@shapeshift-labs/frontier-realtime-server

v0.1.0

Published

2 months ago

Authoritative room, tick, command validation, rate-limit, and snapshot-history runtime for Frontier realtime.

0High
0Medium
0Low

shapeshift-labs

frontier realtime server authoritative multiplayer tick snapshot

Frontier Realtime Server

Authoritative room, tick, command validation, rate-limit, and snapshot-history runtime for Frontier realtime.

This package sits above @shapeshift-labs/frontier-realtime. It owns server-side room state, queued command processing, authoritative ticks, command validation boundaries, bounded snapshot history, and rate-limit helpers. It does not own WebSocket transport, CRDT collaboration sync, physics, rendering, persistence, or game/entity framework APIs.

npm: @shapeshift-labs/frontier-realtime-server
source: siliconjungle/-shapeshift-labs-frontier-realtime-server
license: MIT

Related Packages

The published Frontier package family is generated from one shared package catalog so READMEs stay in sync across packages:

@shapeshift-labs/frontier: Core JSON diff/apply, compact patch tuples, JSON Pointer, equality, clone, validation, Unicode helpers.
@shapeshift-labs/frontier-query: Shared query-key, selector path, condition, entity identity, and table-shape primitives.
@shapeshift-labs/frontier-codec: Patch serialization, binary frames, canonical JSON, and patch-history codecs.
@shapeshift-labs/frontier-engine: Stateful planned diff engine, adaptive profiles, schema plans, and engine-level history helpers.
@shapeshift-labs/frontier-state: Patch-routed app-state subscriptions, owned commits, maintained views, and path mapping.
@shapeshift-labs/frontier-state-cache: Normalized query-result cache with entity/query watchers, persistence, change logs, optimistic layers, and mutation bridge.
@shapeshift-labs/frontier-state-cache-idb: IndexedDB persistence adapter for Frontier state-cache snapshots.
@shapeshift-labs/frontier-state-cache-file: Structured file persistence adapter for Frontier state-cache snapshots and change logs.
@shapeshift-labs/frontier-state-cache-sql: SQL persistence adapter for Frontier state-cache snapshots and change logs.
@shapeshift-labs/frontier-schema: JSON Schema validation, Frontier profile generation, CloudEvent envelopes, and query/table schema helpers.
@shapeshift-labs/frontier-event-log: Bounded event logs, replay cursors, consumer acknowledgements, keyed compaction, checkpoints, and Frontier patch event records.
@shapeshift-labs/frontier-scheduler: Deterministic work scheduling, lanes, cancellation, backpressure, frame policies, replay snapshots, and work graphs.
@shapeshift-labs/frontier-logging: Opt-in structured logging, browser telemetry, file sinks, exporters, benchmark traces, and Frontier patch/update summaries.
@shapeshift-labs/frontier-mutation: Explicit mutation and selector plans compiled to Frontier patches or CRDT operations.
@shapeshift-labs/frontier-virtual: DOM-neutral virtualization, layout providers, range materialization, grids, spatial culling, frustum culling, and serializable layout state.
@shapeshift-labs/frontier-dom: Patch-native DOM and host renderer bindings, manifest hydration, JSX runtime/compiler helpers, SSR, devtools, and logging bridges.
@shapeshift-labs/frontier-crdt: Native CRDT documents, update tooling, awareness, branches, conflict introspection, version frames, and undo.
@shapeshift-labs/frontier-crdt-sync: CRDT sync endpoints, repo/storage/provider contracts, document URLs, local networks, model checking, forensics, and text binding contracts.
@shapeshift-labs/frontier-crdt-websocket: WebSocket client/server transports for Frontier CRDT sync providers.
@shapeshift-labs/frontier-react: React external-store hooks and adapters for Frontier state, cache, and CRDT surfaces.
@shapeshift-labs/frontier-richtext: Rich text Delta normalization/application, marks, embeds, ranges, and cursor/selection transforms for local editor integrations.
@shapeshift-labs/frontier-realtime: Shared realtime command, tick, snapshot, prediction, reconciliation, interpolation, rollback, message, and delta primitives.
@shapeshift-labs/frontier-realtime-websocket: WebSocket client, wire, and Node room-server transport for Frontier realtime.
@shapeshift-labs/frontier-game: Game-facing entity, component, player, room, ownership, spatial interest, rollback, physics, and replication helpers above realtime.

Package source repositories:

Install

npm install @shapeshift-labs/frontier-realtime @shapeshift-labs/frontier-realtime-server

Usage

import { createCommandSource } from '@shapeshift-labs/frontier-realtime';
import { createRealtimeRoom } from '@shapeshift-labs/frontier-realtime-server';

const room = createRealtimeRoom({
  roomId: 'arena-1',
  initialState: { players: { a: { x: 0 } } },
  tickRate: 20,
  applyCommand(state, command) {
    if (command.type !== 'move') return state;
    const player = state.players[command.clientId];
    return {
      players: {
        ...state.players,
        [command.clientId]: { x: player.x + command.payload.dx }
      }
    };
  },
  validateCommand(_state, command) {
    return Math.abs(command.payload.dx) <= 1 || 'move too large';
  }
});

room.join('a');

const commands = createCommandSource({ clientId: 'a' });
room.enqueue(commands.create('move', { dx: 1 }, { roomId: 'arena-1' }));

const result = room.step();
console.log(result.snapshot);

API

import {
  createRateLimiter,
  createRealtimeRoom,
  createRealtimeSessionStore,
  createSnapshotHistory,
  type RealtimeServerRoom
} from '@shapeshift-labs/frontier-realtime-server';

Realtime Rooms

createRealtimeRoom(options) creates an authoritative room that accepts client command envelopes, validates sequence/rate/room boundaries, processes queued commands in deterministic order, advances server ticks, and publishes authoritative snapshots.

const room = createRealtimeRoom({
  roomId: 'room-1',
  initialState,
  applyCommand(state, command, context) {
    return reduce(state, command, context.tick);
  },
  validateCommand(state, command) {
    return canApply(state, command) || 'invalid command';
  }
});

room.join('client-a');
room.enqueue(command);
const step = room.step();

Room steps return accepted command acknowledgements, rejected command records, the authoritative state, an authoritative snapshot, and server messages that can be passed to a transport layer.

Session Resume

Rooms issue sessionId and resumeToken values in welcome messages by default. Passing them back to join(clientId, { sessionId, resumeToken, lastSeenTick }) resumes the client session, preserves the last accepted command sequence, and lets transports reconnect without treating the client as a brand-new participant.

createRealtimeSessionStore() is also exported behind ./session for custom room/session orchestration.

Snapshot History

createSnapshotHistory(options) keeps a bounded tick-sorted snapshot history for replay, debug inspection, and lag-compensation queries.

const history = createSnapshotHistory({ capacity: 128 });
history.push(snapshot);
const rewind = history.atOrBefore(targetTick);

Rate Limits

createRateLimiter(options) provides a small token-bucket limiter for per-client command admission. Realtime rooms also include a per-tick command cap; this helper is for broader session or transport policy.

const limiter = createRateLimiter({ capacity: 20, refillPerSecond: 10 });
if (!limiter.allow(clientId).allowed) {
  // Reject or delay the command at the server edge.
}

Subpath Imports

import { createSnapshotHistory } from '@shapeshift-labs/frontier-realtime-server/history';
import { appendRealtimeStepToEventLog } from '@shapeshift-labs/frontier-realtime-server/event-log';
import { createRateLimiter } from '@shapeshift-labs/frontier-realtime-server/rate-limit';
import { createRealtimeRoom } from '@shapeshift-labs/frontier-realtime-server/room';
import { createRealtimeSessionStore } from '@shapeshift-labs/frontier-realtime-server/session';

Package Scope

This package intentionally owns only server-side realtime primitives:

Authoritative room state and tick stepping.
Command queueing, sequence checks, validation hooks, and rejection records.
Per-tick command caps and standalone token-bucket rate limits.
Bounded authoritative snapshot history.
Session records for reconnect/resume.
Optional frontier-event-log replay helpers behind ./event-log.
Server message records for future transports.

It does not own WebSocket transport, browser clients, CRDT collaboration sync, rendering, physics, durable persistence, entity/component gameplay APIs, or anti-cheat policy beyond command validation hooks. Those belong in higher packages or application code.

TypeScript

The package ships ESM JavaScript plus .d.ts declarations for the root export and public subpaths.

Validation

npm test
npm run fuzz
npm run bench
npm run pack:dry

The package test suite covers root and subpath imports, room join/leave, command queueing, duplicate/unknown/rate-limit/validation rejections, authoritative snapshots, snapshot history lookup, token-bucket limits, TypeScript declarations, randomized room replay, and package export boundaries.

Benchmarks

Run the package-local benchmark:

npm run bench

Latest local package benchmark on Node v26.1.0, darwin arm64, 9 rounds:

| Fixture | Median | p95 | | --- | ---: | ---: | | Room enqueue/process 128 commands | 97.73 us | 98.39 us | | Room idle step | 3.84 us | 4.34 us | | Snapshot history push/query | 8.95 us | 9.42 us | | Token bucket allow 128 commands | 1.87 us | 2.04 us |

These are Frontier-only package measurements, not competitor comparisons.

License

MIT. See LICENSE.