@pylonsync/realtime 0.18.1 → 0.19.0

package/dist/connection.d.ts

@@ -1,12 +1,25 @@
 /**
- * A shard connection with no framework: one WebSocket, reconnected with
- * backoff, that decodes frames, applies replication frames to an
- * `EntityTable`, and sends inputs. `useShard` in `@pylonsync/react` and
- * `connectShardGame` build on it.
+ * A shard connection with no framework: one WebSocket or WebTransport
+ * session, reconnected with backoff, that decodes frames, applies
+ * replication frames to an `EntityTable`, and sends inputs. `useShard` in
+ * `@pylonsync/react` and `connectShardGame` build on it.
  */
 import { ShardClock } from "./clock";
 import { EntityTable, type ReplicationSummary } from "./replication";
 import { type ShardInputRejection, type ShardPayloadDecoder } from "./wire";
+/**
+ * How the client reaches the shard.
+ *
+ * - `"websocket"`: a WebSocket (TCP). Works everywhere.
+ * - `"webtransport"`: a WebTransport session (QUIC over UDP). Entity
+ *   updates come as datagrams, so a lost packet delays only itself. Needs
+ *   the browser API and an app that serves WebTransport
+ *   (`PYLON_WEBTRANSPORT_PORT`); fails otherwise.
+ * - `"auto"`: WebTransport when the browser and the app support it, else a
+ *   WebSocket. After a WebTransport session fails to open (UDP blocked, an
+ *   old browser), the client uses WebSockets for the rest of its life.
+ */
+export type ShardTransport = "websocket" | "webtransport" | "auto";
 export interface ShardConnectOptions {
     /** Subscriber ID (usually the logged-in user ID). Required for multiplayer. */
     subscriberId: string;
@@ -39,6 +52,19 @@ export interface ShardConnectOptions {
      * `shard` query parameter is replaced with the new shard.
      */
     wsUrl?: string;
+    /** Default `"websocket"`. See `ShardTransport`. */
+    transport?: ShardTransport;
+    /**
+     * Where to fetch the WebTransport URL and certificate hashes. Default
+     * `/_pylon/shard/webtransport` on `baseUrl` (or the page's host), or on
+     * the host of `wsUrl` when only that is set.
+     */
+    webTransportInfoUrl?: string;
+    /**
+     * How long a WebTransport session may take to open before `"auto"`
+     * falls back to a WebSocket, in ms (default 3000).
+     */
+    webTransportTimeoutMs?: number;
     /** Reconnect on unexpected close (default: true). */
     autoReconnect?: boolean;
     /** First reconnect delay in ms (default 500; doubles to at most 10 000). */
@@ -101,6 +127,8 @@ export interface ShardClient<TSnapshot = unknown, TInput = unknown> {
     send: (input: TInput) => number;
     close: () => void;
     readonly connected: boolean;
+    /** The transport of the open (or last) connection, or null before one opened. */
+    readonly transport: "websocket" | "webtransport" | null;
 }
 /**
  * True when a shard ticket (`v1.<payload>.<signature>`, the payload

package/dist/game.d.ts

@@ -25,12 +25,17 @@
  * ```
  */
 import type { ShardClock } from "./clock";
-import { type ShardClient, type ShardConnectOptions } from "./connection";
+import { type ShardClient, type ShardConnectOptions, type ShardTransport } from "./connection";
 import { type InterpolatedEntity, type InterpolationOptions } from "./interpolation";
 import { Predictor, type PredictorOptions } from "./prediction";
 import type { EntityTable, ReplicationSummary } from "./replication";
 import type { ShardInputRejection } from "./wire";
 export interface ShardGameOptions extends ShardConnectOptions {
+    /**
+     * Default `"auto"`: WebTransport where the browser and the app support
+     * it, else a WebSocket. See `ShardTransport`.
+     */
+    transport?: ShardTransport;
     /**
      * How far behind the shard's estimated current tick entities are drawn,
      * in ms. It must cover the time between frames plus network jitter.

package/dist/replication.d.ts

@@ -23,8 +23,30 @@
  * JavaScript numbers hold integers exactly up to 2^53. Entity ids and
  * quantized positions must stay below that; a frame that exceeds it is
  * refused rather than rounded.
+ *
+ * **Datagrams** (`pylon_replication::datagram`): on WebTransport, spawns,
+ * despawns, and full frames come as frames on the stream, and updates as
+ * datagrams that may be lost, duplicated, or reordered. A datagram update
+ * carries the entity's absolute position and the tick of the stream frame
+ * that spawned it (low 16 bits). {@link EntityTable.applyDatagram} applies
+ * an update only to the entity spawned at that tick and only when it is
+ * newer than the entity's last datagram, and skips it otherwise. Stream
+ * frames must go through `apply(frame, tick)` so the table knows the
+ * ticks; a full frame starts them over.
+ *
+ * ```text
+ * u8      version (2)
+ * varint  frame number, tick, input ack, stream tick (of the last stream
+ *         frame sent by this tick)
+ * f32 LE  precision
+ * varint  parts (datagrams sent for this tick)
+ * varint  update count, per entity (ids ascending, delta-coded): id,
+ *         u16 LE spawn tick, u8 mask, the masked axes (zigzag, absolute),
+ *         components if bit 8
+ * ```
  */
 export declare const REPLICATION_VERSION = 1;
+export declare const DATAGRAM_VERSION = 2;
 export declare class ReplicationError extends Error {
     constructor(message: string);
 }
@@ -41,6 +63,23 @@ export interface ReplicatedEntity {
     /** Component id to bytes, in the game's own encoding. */
     components: Map<number, Uint8Array>;
 }
+/** What one datagram did. */
+export interface DatagramSummary {
+    frame: number;
+    tick: number;
+    ack: number;
+    /** The tick of the last stream frame the server had sent by `tick`. */
+    streamTick: number;
+    /** Datagrams the server sent for `tick`. */
+    parts: number;
+    /** Entities it updated. */
+    updated: number[];
+    /**
+     * Updates it skipped: an unknown entity, another spawn, an older
+     * datagram than the entity's last, or another precision.
+     */
+    skipped: number;
+}
 /** What one frame did. */
 export interface ReplicationSummary {
     full: boolean;
@@ -48,6 +87,11 @@ export interface ReplicationSummary {
     updated: number[];
     despawned: number[];
 }
+/**
+ * A datagram's frame number, tick, and input ack, without applying it.
+ * Throws on bytes that are not a datagram.
+ */
+export declare function readDatagramHeader(datagram: Uint8Array): Omit<DatagramSummary, "updated" | "skipped">;
 /**
  * The entities one subscriber has been told about. Apply every
  * replication frame in order; a frame that fails to apply means the
@@ -58,8 +102,33 @@ export declare class EntityTable {
     readonly entities: Map<number, ReplicatedEntity>;
     /** World units per quantization step, from the last frame. */
     precision: number;
+    /**
+     * The tick of the stream frame that spawned each entity, when frames are
+     * applied with their tick. Datagram updates name it.
+     */
+    readonly spawnTicks: Map<number, number>;
+    /** The last datagram applied to each entity. */
+    readonly datagramFrames: Map<number, number>;
+    /**
+     * The tick of the last frame applied with its tick. A client acks each
+     * datagram with it, so the server knows which spawns it had.
+     */
+    streamTick: number;
     get size(): number;
     get(id: number): ReplicatedEntity | undefined;
+    /** Forget everything. */
     clear(): void;
-    apply(frame: Uint8Array): ReplicationSummary;
+    /**
+     * Apply a replication frame. On a connection that also gets datagrams,
+     * pass the tick from the frame's header: the table records the tick each
+     * entity spawned at and the tick of the last frame, which datagrams and
+     * their acks name. A full frame starts that record over.
+     */
+    apply(frame: Uint8Array, tick?: number): ReplicationSummary;
+    /**
+     * Apply one datagram. It changes nothing it cannot apply exactly (see
+     * `DatagramSummary.skipped`). Throws only on bytes that are not a
+     * datagram.
+     */
+    applyDatagram(datagram: Uint8Array): DatagramSummary;
 }

package/dist/wire.d.ts

@@ -5,7 +5,8 @@
  * message is a binary frame with an 18-byte header:
  *
  *   0   1  frame kind: 1 snapshot, 2 input rejected, 3 entity replication,
- *            4 transfer (JSON `{ shard, ticket }`: the last frame; reconnect there)
+ *            4 transfer (JSON `{ shard, ticket }`: the last frame; reconnect there),
+ *            6 closing (WebTransport only, JSON `{ code, reason }`)
  *   1   1  codec: 0 JSON, 1 MessagePack, 2 bincode, 3 custom, 4 replication
  *   2   8  tick (u64 big-endian)
  *   10  8  ack: highest client_seq the shard processed for this subscriber (0 = none)
@@ -13,6 +14,12 @@
  *
  * Inputs go up as `{ input, client_seq }`: JSON in a text frame, or the
  * shard's codec in a binary frame.
+ *
+ * Over WebTransport (wire version 3 in Rust) the same frames travel on one
+ * bidirectional stream, each after a 4-byte big-endian length, and entity
+ * updates travel as QUIC datagrams (`EntityTable.applyDatagram`). The
+ * client's hello, its inputs, and its datagram acks are described at
+ * `encodeWebTransportHello`, `ShardClientMessage`, and `encodeDatagramAcks`.
  */
 export declare const SHARD_PROTOCOL_VERSION = 2;
 export declare const SHARD_HEADER_LEN = 18;
@@ -26,6 +33,13 @@ export declare const ShardFrameKind: {
      * last frame on the connection.
      */
     readonly Transfer: 4;
+    /** A datagram frame (wire version 3 WebSocket only). */
+    readonly Datagram: 5;
+    /**
+     * WebTransport only: the server is about to close the session, with
+     * JSON `{ code, reason }` (`WEBTRANSPORT_CLOSE`). The client closes it.
+     */
+    readonly Closing: 6;
 };
 /** Where the subscriber went: connect to `shard` with `ticket`. */
 export interface ShardTransferNotice {
@@ -74,3 +88,72 @@ export declare function decodeShardRejection(codec: number, payload: Uint8Array,
  * text, which the server always accepts.
  */
 export declare function encodeShardInput(codec: number | null, input: unknown, clientSeq: number): string | Uint8Array;
+/** Acks one message may carry (the server refuses more). */
+export declare const MAX_ACKS_PER_MESSAGE = 512;
+/**
+ * Type bytes of the client's messages on a WebTransport stream (the first
+ * byte; the rest is the message).
+ */
+export declare const ShardClientMessage: {
+    /** An input envelope in the shard's codec (MessagePack shards). */
+    readonly Input: 0;
+    /** Datagram acks (`encodeDatagramAcks`). */
+    readonly Acks: 1;
+    /** An input envelope as JSON. */
+    readonly JsonInput: 2;
+};
+/** WebTransport session close codes the server uses. */
+export declare const WEBTRANSPORT_CLOSE: {
+    readonly Normal: 0;
+    /** Refused: bad credentials, an unknown shard. */
+    readonly Policy: 1;
+    /** The client broke the protocol. */
+    readonly Protocol: 2;
+    /** Try again: the client was too slow, or the server was busy. */
+    readonly Again: 3;
+};
+/** What `GET /_pylon/shard/webtransport` returns. */
+export interface WebTransportInfo {
+    /** The `https://` URL of the WebTransport endpoint. */
+    url: string;
+    /**
+     * SHA-256 hashes of the server's self-signed certificates, for
+     * `serverCertificateHashes`. Empty when the certificate has a public CA.
+     */
+    certHashes: Uint8Array[];
+}
+/** Parse the body of `GET /_pylon/shard/webtransport`. */
+export declare function decodeWebTransportInfo(body: unknown): WebTransportInfo;
+/**
+ * Datagram acks: the type byte `ShardClientMessage.Acks`, a varint count,
+ * then per ack the datagram's frame number and `EntityTable.streamTick`
+ * when the client applied it, both varints. Sent as a datagram, or on the
+ * stream.
+ */
+export declare function encodeDatagramAcks(acks: ReadonlyArray<readonly [number, number]>): Uint8Array;
+/** A message for a WebTransport stream: a 4-byte big-endian length, then `bytes`. */
+export declare function lengthPrefixed(bytes: Uint8Array): Uint8Array;
+/** The first message on a WebTransport stream: who connects to which shard. */
+export declare function encodeWebTransportHello(hello: {
+    shard: string;
+    sid: string;
+    ticket?: string;
+    token?: string;
+}): Uint8Array;
+/**
+ * An input as a WebTransport stream message: `encodeShardInput`'s output
+ * after its type byte.
+ */
+export declare function encodeWebTransportInput(encoded: string | Uint8Array): Uint8Array;
+/**
+ * Splits a WebTransport stream's bytes into its length-prefixed frames.
+ * Chunks can end anywhere: in a length, in a frame.
+ */
+export declare class StreamFrames {
+    private chunks;
+    private buffered;
+    /** Add a chunk and return the frames it completed. */
+    push(chunk: Uint8Array): ArrayBuffer[];
+    private peek;
+    private take;
+}

package/package.json

@@ -3,7 +3,7 @@
   "publishConfig": {
     "access": "public"
   },
-  "version": "0.18.1",
+  "version": "0.19.0",
   "description": "Pylon realtime shard client pieces with no framework: the wire protocol, codecs, and the entity replication decoder and table.",
   "type": "module",
   "main": "./src/index.ts",