@axpecter/lync 2.2.0 → 2.3.1

package/src/codec/primitive/Signed.luau

@@ -1,7 +1,6 @@
 --!strict
 --!native
--- Signed integer buffer helpers. Reads use FASTCALL2 readi*; writes
--- emulate via writeu* + two's complement (writei* is not FASTCALL).
+-- Signed integer writers via writeu* + two's complement (writei* is not FASTCALL).
 
 -- Private ----------------------------------------------------------------
 
@@ -25,6 +24,7 @@ function Signed.writeI32(b: buffer, off: number, value: number): ()
     writeu32(b, off, if value < 0 then value + 0x100000000 else value)
 end
 
+-- Reads stay on buffer.readi* (already FASTCALL).
 Signed.readI8 = buffer.readi8
 Signed.readI16 = buffer.readi16
 Signed.readI32 = buffer.readi32

package/src/codec/primitive/Varint.luau

@@ -1,25 +1,38 @@
 --!strict
 --!native
--- Dense prefix varint. Single-branch decode, range up to 2^32 - 1.
+-- Dense prefix varint over [0, 2^32 - 1]. Single-branch decode.
 
 local Base = require(script.Parent.Parent.Base)
+local Constants = require(script.Parent.Parent.Parent.util.Constants)
+local Log = require(script.Parent.Parent.Parent.util.Log)
 local Types = require(script.Parent.Parent.Parent.Types)
 
 -- Constants --------------------------------------------------------------
 
 --[[
-    Wire layout (first byte determines length):
-      0x00..0xBF  1 byte   value = b0                         [0..191]
-      0xC0..0xDF  2 bytes  value = (b0 & 0x1F)<<8 | b1 + 192  [192..8383]
-      0xE0..0xEF  3 bytes  value = (b0 & 0x0F)<<16 | u16 + 8384 [8384..1056959]
-      0xF0..0xFF  5 bytes  value = u32                        [..0xFFFFFFFF]
+    Wire layout (first byte tag selects length):
+      0x00..0xBF  1 byte   value = b0                            [0..191]
+      0xC0..0xDF  2 bytes  value = (b0 & 0x1F)<<8 | b1 + 192     [192..8383]
+      0xE0..0xEF  3 bytes  value = (b0 & 0x0F)<<16 | u16 + 8384  [8384..1056959]
+      0xF0..0xFF  5 bytes  value = u32                           [..0xFFFFFFFF]
 ]]
 local INLINE_MAX = 0xBF
+local TWO_TAG = 0xC0
+local TWO_END = 0xDF
+local TWO_MASK = 0x1F
+local THREE_TAG = 0xE0
+local THREE_END = 0xEF
+local THREE_MASK = 0x0F
+local FIVE_TAG = 0xF0
 local TWO_MAX = 8383
 local THREE_MAX = 1056959
 local TWO_BIAS = 192
 local THREE_BIAS = 8384
 
+local U8_MAX = Constants.U8_MAX
+local U16_MAX = Constants.U16_MAX
+local U32_MAX = Constants.U32_MAX
+
 -- Private ----------------------------------------------------------------
 
 local alloc = Base.alloc
@@ -33,6 +46,12 @@ local readu8 = buffer.readu8
 local readu16 = buffer.readu16
 local readu32 = buffer.readu32
 
+local function ensure(ch: Types.ChannelState, n: number): ()
+    if ch.cursor + n > ch.size then
+        alloc(ch, n)
+    end
+end
+
 -- Public -----------------------------------------------------------------
 
 local Varint = {}
@@ -40,84 +59,96 @@ local Varint = {}
 Varint.INLINE_MAX = INLINE_MAX
 
 function Varint.write(ch: Types.ChannelState, value: number): ()
-    if value < 0 or value > 0xFFFFFFFF or value % 1 ~= 0 then
-        error(`[Lync] Varint.write: value must be an integer in [0, 4294967295], got {value}`)
+    if value < 0 or value > U32_MAX or value % 1 ~= 0 then
+        Log.error(`value must be an integer in [0, {U32_MAX}], got {value}`)
     end
 
-    local cursor = ch.cursor
-
     if value <= INLINE_MAX then
-        if cursor + 1 > ch.size then
-            alloc(ch, 1)
-        end
+        ensure(ch, 1)
+        local cursor = ch.cursor
         writeu8(ch.buff, cursor, value)
         ch.cursor = cursor + 1
         return
     end
 
     if value <= TWO_MAX then
-        if cursor + 2 > ch.size then
-            alloc(ch, 2)
-        end
+        ensure(ch, 2)
+        local cursor = ch.cursor
         local adjusted = value - TWO_BIAS
         local b = ch.buff
-        writeu8(b, cursor, bor(0xC0, rshift(adjusted, 8)))
-        writeu8(b, cursor + 1, band(adjusted, 0xFF))
+        writeu8(b, cursor, bor(TWO_TAG, rshift(adjusted, 8)))
+        writeu8(b, cursor + 1, band(adjusted, U8_MAX))
         ch.cursor = cursor + 2
         return
     end
 
     if value <= THREE_MAX then
-        if cursor + 3 > ch.size then
-            alloc(ch, 3)
-        end
+        ensure(ch, 3)
+        local cursor = ch.cursor
         local adjusted = value - THREE_BIAS
         local b = ch.buff
-        writeu8(b, cursor, bor(0xE0, rshift(adjusted, 16)))
-        writeu16(b, cursor + 1, band(adjusted, 0xFFFF))
+        writeu8(b, cursor, bor(THREE_TAG, rshift(adjusted, 16)))
+        writeu16(b, cursor + 1, band(adjusted, U16_MAX))
         ch.cursor = cursor + 3
         return
     end
 
-    if cursor + 5 > ch.size then
-        alloc(ch, 5)
-    end
+    ensure(ch, 5)
+    local cursor = ch.cursor
     local b = ch.buff
-    writeu8(b, cursor, 0xF0)
+    writeu8(b, cursor, FIVE_TAG)
     writeu32(b, cursor + 1, value)
     ch.cursor = cursor + 5
 end
 
+--[[
+    Returns (value, bytesConsumed). On insufficient bytes returns (0, 0) so
+    the transport can abort the frame instead of letting the buffer access
+    raise — required for recovery from truncated/desynced incoming buffers.
+]]
 function Varint.read(src: buffer, pos: number): (number, number)
+    local available = buffer.len(src) - pos
+    if available < 1 then
+        return 0, 0
+    end
     local b0 = readu8(src, pos)
     if b0 <= INLINE_MAX then
         return b0, 1
     end
-    if b0 <= 0xDF then
-        return band(b0, 0x1F) * 256 + readu8(src, pos + 1) + TWO_BIAS, 2
+    if b0 <= TWO_END then
+        if available < 2 then
+            return 0, 0
+        end
+        return band(b0, TWO_MASK) * 256 + readu8(src, pos + 1) + TWO_BIAS, 2
     end
-    if b0 <= 0xEF then
-        return band(b0, 0x0F) * 65536 + readu16(src, pos + 1) + THREE_BIAS, 3
+    if b0 <= THREE_END then
+        if available < 3 then
+            return 0, 0
+        end
+        return band(b0, THREE_MASK) * 65536 + readu16(src, pos + 1) + THREE_BIAS, 3
+    end
+    if available < 5 then
+        return 0, 0
     end
     return readu32(src, pos + 1), 5
 end
 
--- Encode a value already known to fit in INLINE_MAX (single byte).
+-- Caller-asserted: value is known to fit in INLINE_MAX.
 function Varint.writeInline(ch: Types.ChannelState, value: number): ()
+    ensure(ch, 1)
     local cursor = ch.cursor
-    if cursor + 1 > ch.size then
-        alloc(ch, 1)
-    end
     writeu8(ch.buff, cursor, value)
     ch.cursor = cursor + 1
 end
 
 --[[
-    Decode a length prefix that uses the single-byte fast path for
-    lengths in [0, INLINE_MAX] and the full varint encoding above that.
-    Used by Buffer, String, and Auto's string branch.
+    Length-prefix decode that fast-paths the [0, INLINE_MAX] single-byte form
+    before falling through to full varint. Used by Buffer, String, and Auto.
 ]]
 function Varint.readLengthPrefix(src: buffer, pos: number): (number, number)
+    if buffer.len(src) - pos < 1 then
+        return 0, 0
+    end
     local b0 = readu8(src, pos)
     if b0 <= INLINE_MAX then
         return b0, 1

package/src/index.d.ts

@@ -1,8 +1,13 @@
 /// <reference types="@rbxts/types" />
 
 declare namespace Lync {
-    // ── Core Types ──────────────────────────────────────────────────
+    // ── Core types ──────────────────────────────────────────────────────
 
+    /**
+     * Opaque codec brand. The `_nominal_codec` field never exists at
+     * runtime; it ties the generic parameter to a unique nominal type so
+     * `Codec<number>` and `Codec<string>` can't be assigned to each other.
+     */
     interface Codec<T> {
         /** @hidden */ readonly _nominal_codec: T;
     }
@@ -25,17 +30,26 @@ declare namespace Lync {
         bytesReceived: number;
     }
 
-    // ── Packet ──────────────────────────────────────────────────────
+    type RateLimitConfig =
+        | { maxPerSecond: number; burst?: number }
+        | { cooldown: number };
+
+    // ── Packet ──────────────────────────────────────────────────────────
 
     interface PacketOptions<T> {
         unreliable?: boolean;
-        rateLimit?: { maxPerSecond?: number; burst?: number } | { cooldown: number };
+        rateLimit?: RateLimitConfig;
         validate?: (data: T, player: Player) => LuaTuple<[boolean, string?]>;
         maxPayloadBytes?: number;
         timestamp?: "frame" | "offset" | "full";
     }
 
     interface Packet<T> {
+        /**
+         * Server: target is required (single Player, array, Group, or sentinel).
+         * Client: target is omitted; the second arg is ignored at runtime.
+         * The signature unions both forms.
+         */
         send(this: Packet<T>, data: T, target?: Target): void;
         on(this: Packet<T>, fn: (data: T, sender?: Player, timestamp?: number) => void): Connection;
         once(this: Packet<T>, fn: (data: T, sender?: Player, timestamp?: number) => void): Connection;
@@ -44,55 +58,80 @@ declare namespace Lync {
         stats(this: Packet<T>): PacketStats;
     }
 
-    // ── Query ───────────────────────────────────────────────────────
+    // ── Query ───────────────────────────────────────────────────────────
 
     interface QueryOptions<Req> {
         timeout?: number;
-        rateLimit?: { maxPerSecond?: number; burst?: number };
+        rateLimit?: RateLimitConfig;
         validate?: (data: Req, player: Player) => LuaTuple<[boolean, string?]>;
     }
 
     interface Query<Req, Resp> {
-        handle(this: Query<Req, Resp>, fn: (request: Req, player?: Player) => Resp | undefined): Connection;
+        handle(
+            this: Query<Req, Resp>,
+            fn: (request: Req, player?: Player) => Resp | undefined,
+        ): Connection;
+
+        /** Client: yields until reply or timeout; nil on timeout. */
         request(this: Query<Req, Resp>, data: Req): Resp | undefined;
+        /** Server, single-Player target. */
         request(this: Query<Req, Resp>, data: Req, target: Player): Resp | undefined;
+        /** Server, multi-target (Group, array, all, except). */
         request(this: Query<Req, Resp>, data: Req, target: Target): Map<Player, Resp | undefined>;
+
         name(this: Query<Req, Resp>): string;
         stats(this: Query<Req, Resp>): PacketStats;
     }
 
-    // ── Group ───────────────────────────────────────────────────────
+    // ── Group ───────────────────────────────────────────────────────────
 
     interface Group extends Iterable<Player> {
+        /** Returns true if membership changed (idempotent). */
         add(this: Group, player: Player): boolean;
         remove(this: Group, player: Player): boolean;
         has(this: Group, player: Player): boolean;
         count(this: Group): number;
+        /** Clear members and free the name. */
         destroy(this: Group): void;
     }
 
-    // ── Scope ───────────────────────────────────────────────────────
+    // ── Scope ───────────────────────────────────────────────────────────
 
     interface Scope {
-        on<T>(this: Scope, source: Packet<T>, fn: (data: T, sender?: Player, timestamp?: number) => void): Connection;
-        once<T>(this: Scope, source: Packet<T>, fn: (data: T, sender?: Player, timestamp?: number) => void): Connection;
+        on<T>(
+            this: Scope,
+            source: Packet<T>,
+            fn: (data: T, sender?: Player, timestamp?: number) => void,
+        ): Connection;
+        once<T>(
+            this: Scope,
+            source: Packet<T>,
+            fn: (data: T, sender?: Player, timestamp?: number) => void,
+        ): Connection;
         add(this: Scope, connection: Connection | RBXScriptConnection): void;
         destroy(this: Scope): void;
     }
 
-    // ── Targets ─────────────────────────────────────────────────────
+    // ── Targets ─────────────────────────────────────────────────────────
 
     type Target = Player | Player[] | Group | AllTarget | ExceptTarget;
 
+    /** Branded sentinel returned by `Lync.all`. */
     interface AllTarget {
-        /** @hidden */ readonly _lyncAll: true;
+        /** @hidden */ readonly _lyncKind: "all";
     }
 
+    /** Branded sentinel returned by `Lync.except(...)`. */
     interface ExceptTarget {
-        /** @hidden */ readonly _lyncExcept: true;
+        /** @hidden */ readonly _lyncKind: "except";
     }
 
-    // ── Codec Inference ─────────────────────────────────────────────
+    /** Branded sentinel exposed as `Lync.DROP`. Return from `onSend` to discard. */
+    interface DropSentinel {
+        /** @hidden */ readonly _lyncKind: "drop";
+    }
+
+    // ── Codec inference ─────────────────────────────────────────────────
 
     type InferCodec<C> = C extends Codec<infer T> ? T : never;
 
@@ -100,25 +139,36 @@ declare namespace Lync {
         [K in keyof S]: InferCodec<S[K]>;
     };
 
-    // ── Callable Codecs ─────────────────────────────────────────────
+    // ── Callable codec brands (function-call form for variants) ─────────
 
     interface StringCodec extends Codec<string> {
+        /** Bounded variant; rejects on read if length exceeds maxLength. */
         (maxLength: number): Codec<string>;
     }
 
     interface Vec2Codec extends Codec<Vector2> {
+        /** Quantized per-component variant. 2/4/8 bytes. */
         (min: number, max: number, precision: number): Codec<Vector2>;
     }
 
     interface Vec3Codec extends Codec<Vector3> {
+        /** Quantized per-component variant. 3/6/12 bytes. */
         (min: number, max: number, precision: number): Codec<Vector3>;
     }
 
     interface CFrameCodec extends Codec<CFrame> {
+        /** Smallest-three-quaternion variant. 16 bytes; ≤ 0.16° rotation error. */
         (): Codec<CFrame>;
     }
 
-    // ── Configure ───────────────────────────────────────────────────
+    // ── Bitfield schema ─────────────────────────────────────────────────
+
+    type BitfieldField =
+        | { type: "bool" }
+        | { type: "uint"; width: number }
+        | { type: "int"; width: number };
+
+    // ── Configure ───────────────────────────────────────────────────────
 
     interface ConfigureOptions {
         channelMaxSize?: number;
@@ -129,23 +179,35 @@ declare namespace Lync {
         stats?: boolean;
     }
 
-    // ── Drop Sentinel ───────────────────────────────────────────────
+    // ── Registration debug shape ────────────────────────────────────────
 
-    interface DropSentinel {
-        /** @hidden */ readonly _lyncDrop: true;
+    interface RegistrationInfo {
+        name: string;
+        id: number;
+        kind: number;
+        isUnreliable: boolean;
     }
 }
 
 interface LyncModule {
-    // ── Lifecycle ────────────────────────────────────────────────────
+    // ── Lifecycle ───────────────────────────────────────────────────────
 
     configure(this: void, options: Lync.ConfigureOptions): void;
     start(this: void): void;
     isStarted(this: void): boolean;
+    flush(this: void): void;
+    flushRate(this: void, hz: number): void;
+    /** Restore module state to post-require defaults. For tests / hot reload. */
+    reset(this: void): void;
 
-    // ── Definitions ─────────────────────────────────────────────────
+    // ── Definitions ─────────────────────────────────────────────────────
 
-    packet<T>(this: void, name: string, codec: Lync.Codec<T>, options?: Lync.PacketOptions<T>): Lync.Packet<T>;
+    packet<T>(
+        this: void,
+        name: string,
+        codec: Lync.Codec<T>,
+        options?: Lync.PacketOptions<T>,
+    ): Lync.Packet<T>;
 
     query<Req, Resp>(
         this: void,
@@ -158,46 +220,49 @@ interface LyncModule {
     group(this: void, name: string): Lync.Group;
     scope(this: void): Lync.Scope;
 
-    // ── Targeting ───────────────────────────────────────────────────
+    // ── Targeting ───────────────────────────────────────────────────────
 
     readonly all: Lync.AllTarget;
     except(this: void, ...args: Array<Player | Lync.Group>): Lync.ExceptTarget;
     readonly DROP: Lync.DropSentinel;
 
-    // ── Middleware ───────────────────────────────────────────────────
-
-    onSend(this: void, fn: (data: unknown, name: string, player?: Player) => unknown): Lync.Connection;
-    onReceive(this: void, fn: (data: unknown, name: string, player?: Player) => unknown): Lync.Connection;
-    onDrop(this: void, fn: (player: Player, reason: string, name: string, data?: unknown) => void): Lync.Connection;
+    // ── Middleware ──────────────────────────────────────────────────────
 
-    // ── Runtime Control ─────────────────────────────────────────────
-
-    flush(this: void): void;
-    flushRate(this: void, hz: number): void;
+    onSend(
+        this: void,
+        fn: (data: unknown, name: string, player?: Player) => unknown,
+    ): Lync.Connection;
+    onReceive(
+        this: void,
+        fn: (data: unknown, name: string, player?: Player) => unknown,
+    ): Lync.Connection;
+    onDrop(
+        this: void,
+        fn: (player: Player, reason: string, name: string, data?: unknown) => void,
+    ): Lync.Connection;
 
-    // ── Stats ───────────────────────────────────────────────────────
+    // ── Stats ───────────────────────────────────────────────────────────
 
     readonly stats: {
+        /** Server-only; returns undefined on client or before stats=true. */
         player(this: void, player: Player): Lync.PlayerStats | undefined;
         reset(this: void): void;
     };
 
-    // ── Debug ───────────────────────────────────────────────────────
+    // ── Debug ───────────────────────────────────────────────────────────
 
     readonly debug: {
+        /** Reserved no-op for capture/replay tooling. */
         capture(this: void, label?: string): void;
+        /** Reserved no-op for capture/replay tooling. */
         stop(this: void): void;
+        /** Reserved no-op for capture/replay tooling. */
         dump(this: void): void;
         pending(this: void): number;
-        registrations(this: void): ReadonlyArray<{
-            name: string;
-            id: number;
-            kind: number;
-            isUnreliable: boolean;
-        }>;
+        registrations(this: void): ReadonlyArray<Lync.RegistrationInfo>;
     };
 
-    // ── Number Codecs ───────────────────────────────────────────────
+    // ── Number codecs ───────────────────────────────────────────────────
 
     int(this: void, min: number, max: number): Lync.Codec<number>;
     float(this: void, min: number, max: number, precision: number): Lync.Codec<number>;
@@ -206,12 +271,12 @@ interface LyncModule {
     readonly f64: Lync.Codec<number>;
     readonly bool: Lync.Codec<boolean>;
 
-    // ── String & Buffer ─────────────────────────────────────────────
+    // ── String & buffer ─────────────────────────────────────────────────
 
     readonly string: Lync.StringCodec;
     readonly buff: Lync.Codec<buffer>;
 
-    // ── Vectors & Spatial ───────────────────────────────────────────
+    // ── Vectors & spatial ───────────────────────────────────────────────
 
     readonly vec2: Lync.Vec2Codec;
     readonly vec3: Lync.Vec3Codec;
@@ -223,7 +288,7 @@ interface LyncModule {
     readonly vec2int16: Lync.Codec<Vector2int16>;
     readonly vec3int16: Lync.Codec<Vector3int16>;
 
-    // ── Roblox Types ────────────────────────────────────────────────
+    // ── Roblox types ────────────────────────────────────────────────────
 
     readonly color3: Lync.Codec<Color3>;
     readonly inst: Lync.Codec<Instance>;
@@ -233,26 +298,65 @@ interface LyncModule {
     readonly numberSequence: Lync.Codec<NumberSequence>;
     readonly colorSequence: Lync.Codec<ColorSequence>;
 
-    // ── Composites ──────────────────────────────────────────────────
+    // ── Composites ──────────────────────────────────────────────────────
+
+    struct<S extends Record<string, Lync.Codec<unknown>>>(
+        this: void,
+        schema: S,
+    ): Lync.Codec<Lync.InferSchema<S>>;
+
+    /** Reliable transport only; rejected at definition time on `unreliable`. */
+    deltaStruct<S extends Record<string, Lync.Codec<unknown>>>(
+        this: void,
+        schema: S,
+    ): Lync.Codec<Lync.InferSchema<S>>;
 
-    struct<S extends Record<string, Lync.Codec<unknown>>>(this: void, schema: S): Lync.Codec<Lync.InferSchema<S>>;
-    deltaStruct<S extends Record<string, Lync.Codec<unknown>>>(this: void, schema: S): Lync.Codec<Lync.InferSchema<S>>;
     array<T>(this: void, element: Lync.Codec<T>, maxCount?: number): Lync.Codec<T[]>;
+    /** Reliable transport only. */
     deltaArray<T>(this: void, element: Lync.Codec<T>, maxCount?: number): Lync.Codec<T[]>;
-    map<K, V>(this: void, keyCodec: Lync.Codec<K>, valueCodec: Lync.Codec<V>, maxCount?: number): Lync.Codec<Map<K, V>>;
-    deltaMap<K, V>(this: void, keyCodec: Lync.Codec<K>, valueCodec: Lync.Codec<V>, maxCount?: number): Lync.Codec<Map<K, V>>;
+
+    map<K, V>(
+        this: void,
+        keyCodec: Lync.Codec<K>,
+        valueCodec: Lync.Codec<V>,
+        maxCount?: number,
+    ): Lync.Codec<Map<K, V>>;
+    /** Reliable transport only. */
+    deltaMap<K, V>(
+        this: void,
+        keyCodec: Lync.Codec<K>,
+        valueCodec: Lync.Codec<V>,
+        maxCount?: number,
+    ): Lync.Codec<Map<K, V>>;
+
     optional<T>(this: void, codec: Lync.Codec<T>): Lync.Codec<T | undefined>;
-    tuple<T extends Lync.Codec<unknown>[]>(this: void, ...codecs: T): Lync.Codec<{ [K in keyof T]: Lync.InferCodec<T[K]> }>;
+
+    tuple<T extends Lync.Codec<unknown>[]>(
+        this: void,
+        ...codecs: T
+    ): Lync.Codec<{ [K in keyof T]: Lync.InferCodec<T[K]> }>;
+
+    /**
+     * Discriminated union with a string tag field. Up to 256 variants;
+     * each variant is a struct codec keyed by name.
+     */
     tagged<Tag extends string, V extends Record<string, Lync.Codec<unknown>>>(
         this: void,
         tagField: Tag,
         variants: V,
-    ): Lync.Codec<{ [K in keyof V & string]: { [F in Tag]: K } & Lync.InferCodec<V[K]> }[keyof V & string]>;
+    ): Lync.Codec<
+        { [K in keyof V & string]: { [F in Tag]: K } & Lync.InferCodec<V[K]> }[keyof V & string]
+    >;
 
-    // ── Meta ────────────────────────────────────────────────────────
+    // ── Meta ────────────────────────────────────────────────────────────
 
     enum<T extends string[]>(this: void, ...values: T): Lync.Codec<T[number]>;
-    bitfield(this: void, schema: Record<string, { type: "bool" } | { type: "uint"; width: number } | { type: "int"; width: number }>): Lync.Codec<Record<string, boolean | number>>;
+
+    bitfield(
+        this: void,
+        schema: Record<string, Lync.BitfieldField>,
+    ): Lync.Codec<Record<string, boolean | number>>;
+
     custom<T>(
         this: void,
         size: number,
@@ -260,8 +364,12 @@ interface LyncModule {
         read: (b: buffer, offset: number) => T,
         typeCheck?: string,
     ): Lync.Codec<T>;
+
+    /** 0-byte codec; reads `undefined`. Use for fire-and-forget signals. */
     readonly nothing: Lync.Codec<undefined>;
+    /** Bypasses serialization through the channel sidecar. Pair with `validate`. */
     readonly unknown: Lync.Codec<unknown>;
+    /** Self-describing; nil/bool/numbers/strings/buffers/Roblox datatypes. */
     readonly auto: Lync.Codec<unknown>;
 }