@axpecter/lync 1.5.2 → 2.0.0

package/src/codec/composite/Struct.luau

@@ -47,6 +47,14 @@ function Struct.struct(schema: { [string]: Codec<any> }): Codec<any>
     local boolByteCount = ceil(boolCount / 8)
     local hasBools = boolCount > 0
 
+    local hasUnknown = false
+    for _, fieldCodec in schema do
+        if (fieldCodec :: any)._hasUnknown then
+            hasUnknown = true
+            break
+        end
+    end
+
     local canDirect = true
     local fixedSize = boolByteCount
     local isAllFixed = true
@@ -126,6 +134,7 @@ function Struct.struct(schema: { [string]: Codec<any> }): Codec<any>
             _size = fixedSize,
             _directWrite = directWriteBody,
             _directRead = directReadBody,
+            _hasUnknown = hasUnknown or nil,
 
             write = function(ch: ChannelState, value: any): ()
                 local c = ch.cursor
@@ -152,6 +161,7 @@ function Struct.struct(schema: { [string]: Codec<any> }): Codec<any>
 
     return table.freeze({
         _size = if isAllFixed then fixedSize else nil,
+        _hasUnknown = hasUnknown or nil,
 
         write = function(ch: ChannelState, value: any): ()
             if isAllFixed then
@@ -195,6 +205,14 @@ function Struct.deltaStruct(schema: { [string]: Codec<any> }): Codec<any>
     local bitmaskBytes = ceil(segCount / 8)
     local deltaId = Shared.allocDeltaId()
 
+    local hasUnknown = false
+    for _, fieldCodec in schema do
+        if (fieldCodec :: any)._hasUnknown then
+            hasUnknown = true
+            break
+        end
+    end
+
     -- Scratch bounds reused every frame(only cloned into cache)
     local _scratchBounds = table.create(segCount + 1) :: { number }
     _scratchBounds[1] = 0
@@ -237,6 +255,7 @@ function Struct.deltaStruct(schema: { [string]: Codec<any> }): Codec<any>
 
     return table.freeze({
         _isDelta = true,
+        _hasUnknown = hasUnknown or nil,
 
         write = function(ch: ChannelState, value: any): ()
             local cache = ch.deltas[deltaId] :: DeltaCache?
@@ -413,7 +432,10 @@ function Struct.deltaStruct(schema: { [string]: Codec<any> }): Codec<any>
             end
 
             local cache = Baseline.getCache(deltaId) :: any
-            local result = if cache then table.clone(cache) else {}
+            if not cache then
+                error("[Lync] Delta frame without baseline")
+            end
+            local result = table.clone(cache)
 
             local maskStart = absPos
             absPos += bitmaskBytes

package/src/codec/composite/Tagged.luau

@@ -71,6 +71,14 @@ function Tagged.define(tagField: string, variants: { [string]: Codec<any> }): Co
         end
     end
 
+    local hasUnknown = false
+    for i = 1, count do
+        if (tagCodecs[i] :: any)._hasUnknown then
+            hasUnknown = true
+            break
+        end
+    end
+
     table.freeze(nameToTag)
     table.freeze(tagCodecs)
     table.freeze(tagNames)
@@ -86,6 +94,7 @@ function Tagged.define(tagField: string, variants: { [string]: Codec<any> }): Co
         if fixedSize then
             return table.freeze({
                 _size = fixedSize,
+                _hasUnknown = hasUnknown or nil,
                 _directWrite = function(b: buffer, offset: number, value: any): ()
                     local tag = nameToTag[value[tagField]]
                     if not tag then
@@ -141,6 +150,7 @@ function Tagged.define(tagField: string, variants: { [string]: Codec<any> }): Co
 
         return table.freeze({
             _size = nil,
+            _hasUnknown = hasUnknown or nil,
             write = function(ch: ChannelState, value: any): ()
                 local tag = nameToTag[value[tagField]]
                 if not tag then
@@ -183,6 +193,7 @@ function Tagged.define(tagField: string, variants: { [string]: Codec<any> }): Co
 
     return table.freeze({
         _size = fixedSize,
+        _hasUnknown = hasUnknown or nil,
         write = function(ch: ChannelState, value: any): ()
             local tag = nameToTag[value[tagField]]
             if not tag then

package/src/codec/composite/Tuple.luau

@@ -24,6 +24,14 @@ function Tuple.define(...: Codec<any>): Codec<{ any }>
 
     table.freeze(codecs)
 
+    local hasUnknown = false
+    for i = 1, count do
+        if (codecs[i] :: any)._hasUnknown then
+            hasUnknown = true
+            break
+        end
+    end
+
     local canDirect = true
     local totalSize: number = 0
     local directWrites = table.create(count) :: { any }
@@ -92,6 +100,7 @@ function Tuple.define(...: Codec<any>): Codec<{ any }>
             _size = totalSize,
             _directWrite = directWriteBody,
             _directRead = directReadBody,
+            _hasUnknown = hasUnknown or nil,
             write = function(ch: ChannelState, value: { any }): ()
                 local c = ch.cursor
                 if c + totalSize > ch.size then
@@ -119,6 +128,7 @@ function Tuple.define(...: Codec<any>): Codec<{ any }>
 
     return table.freeze({
         _size = totalSize,
+        _hasUnknown = hasUnknown or nil,
         write = function(ch: ChannelState, value: { any }): ()
             if hasFixedTotal then
                 alloc(ch, totalSize :: number)

package/src/codec/datatype/Instance.luau

@@ -41,6 +41,9 @@ InstanceCodec.inst = table.freeze({
         if not inst then
             error(`[Lync] Instance ref index out of bounds: {idx}`)
         end
+        if typeof(inst) ~= "Instance" then
+            error("[Lync] Invalid ref: expected Instance")
+        end
 
         return inst, 2
     end,

package/src/codec/meta/Unknown.luau

@@ -11,6 +11,7 @@ local alloc = Channel.alloc
 
 return table.freeze({
     unknown = table.freeze({
+        _hasUnknown = true,
         write = function(ch: ChannelState, value: any): ()
             local refs = ch.refs
             local idx = #refs + 1

package/src/index.d.ts

@@ -100,9 +100,9 @@ export type Target = Player | AllTarget | ExceptTarget | GroupObject | Player[];
 
 export interface Scope {
     add(this: Scope, conn: Connection | RBXScriptConnection): void;
-    listen<T>(this: Scope, source: Packet<T>, callback: (data: T, sender: Player | undefined) => void): void;
-    once<T>(this: Scope, source: Packet<T>, callback: (data: T, sender: Player | undefined) => void): void;
-    listenAll(this: Scope, namespace: Namespace, callback: (name: string, data: unknown, sender: Player | undefined) => void): void;
+    listen<T>(this: Scope, source: Packet<T>, callback: (data: T, sender: Player | undefined, timestamp: number | undefined) => void): void;
+    once<T>(this: Scope, source: Packet<T>, callback: (data: T, sender: Player | undefined, timestamp: number | undefined) => void): void;
+    listenAll(this: Scope, namespace: Namespace, callback: (name: string, data: unknown, sender: Player | undefined, timestamp: number | undefined) => void): void;
     destroy(this: Scope): void;
 }
 
@@ -120,14 +120,26 @@ export interface PacketConfig<T> {
     rateLimit?: RateLimitConfig;
     validate?: (data: T, player: Player) => LuaTuple<[boolean, string?]>;
     maxPayloadBytes?: number;
+    timestamp?: "frame" | "offset" | "full";
+}
+
+export interface PlayerStats {
+    bytesSent: number;
+    bytesReceived: number;
 }
 
 export interface Packet<T> {
     send(this: Packet<T>, data: T, target?: Target): void;
-    listen(this: Packet<T>, callback: (data: T, sender: Player | undefined) => void): Connection;
-    once(this: Packet<T>, callback: (data: T, sender: Player | undefined) => void): Connection;
+    listen(this: Packet<T>, callback: (data: T, sender: Player | undefined, timestamp: number | undefined) => void): Connection;
+    once(this: Packet<T>, callback: (data: T, sender: Player | undefined, timestamp: number | undefined) => void): Connection;
     wait(this: Packet<T>): LuaTuple<[T, Player | undefined]>;
     disconnectAll(this: Packet<T>): void;
+
+    getBytesSent(this: Packet<T>): number;
+    getBytesReceived(this: Packet<T>): number;
+    getFires(this: Packet<T>): number;
+    getRecvFires(this: Packet<T>): number;
+    getDrops(this: Packet<T>): number;
 }
 
 // -- Query -------------------------------------------------------------
@@ -182,7 +194,7 @@ export interface Namespace {
     readonly queries: Record<string, Query<unknown, unknown>>;
     listenAll(
         this: Namespace,
-        callback: (name: string, data: unknown, sender: Player | undefined) => void,
+        callback: (name: string, data: unknown, sender: Player | undefined, timestamp: number | undefined) => void,
     ): Connection;
     onSend(
         this: Namespace,
@@ -306,13 +318,30 @@ declare namespace Lync {
     // Scope
     export function scope(): Scope;
 
-    // Configuration
+    // Configuration (call before start)
     export function setChannelMaxSize(bytes: number): void;
     export function setValidationDepth(depth: number): void;
     export function setPoolSize(count: number): void;
 
+    // Runtime configuration
+    export function flush(): void;
+    export function setFlushRate(hz: number): void;
+
+    // Stats (default off; call enableStats() to activate)
+    export function enableStats(): void;
+    export function getPlayerStats(player: Player): PlayerStats | undefined;
+    export function resetStats(): void;
+
+    // Security (server-only)
+    export function setBandwidthLimit(softLimit: number, maxStrikes: number): void;
+
     // Introspection
     export function queryPendingCount(): number;
+
+    // Packet capture (server-only, debug)
+    export function startCapture(label?: string): void;
+    export function stopCapture(): void;
+    export function dumpCaptures(): void;
 }
 
 export default Lync;

package/src/init.luau

@@ -103,8 +103,38 @@ end
 
 -- Public --------------------------------------------------------------
 
+local IS_SERVER = RunService:IsServer()
+
+local function flush(): ()
+    if IS_SERVER then
+        Server.flush()
+    else
+        Client.flush()
+    end
+end
+
+local function setFlushRate(hz: number): ()
+    if IS_SERVER then
+        Server.setFlushRate(hz)
+    else
+        Client.setFlushRate(hz)
+    end
+end
+
+local function getPlayerStats(player: Player): any?
+    return Server.getPlayerStats(player)
+end
+
+local function resetStats(): ()
+    Server.resetStats()
+end
+
+local function setBandwidthLimit(softLimit: number, maxStrikes: number): ()
+    Server.setBandwidthLimit(softLimit, maxStrikes)
+end
+
 local Lync = {
-    VERSION = "1.5.2",
+    VERSION = "2.0.0",
 
     -- Lifecycle
     start = start,
@@ -187,13 +217,30 @@ local Lync = {
     -- Scope
     scope = ScopeModule.create,
 
-    -- Configuration(call before start)
+    -- Configuration (call before start)
     setChannelMaxSize = Channel.setMaxSize,
     setValidationDepth = Gate.setMaxDepth,
     setPoolSize = Pool.setMaxSize,
 
+    -- Runtime configuration
+    flush = flush,
+    setFlushRate = setFlushRate,
+
+    -- Stats (default off; call enableStats() to activate)
+    enableStats = Channel.enableStats,
+    getPlayerStats = getPlayerStats,
+    resetStats = resetStats,
+
+    -- Security (server-only)
+    setBandwidthLimit = setBandwidthLimit,
+
     -- Introspection
     queryPendingCount = QueryModule.pendingCount,
+
+    -- Packet capture (server-only, debug)
+    startCapture = if IS_SERVER then Server.startCapture else nil,
+    stopCapture = if IS_SERVER then Server.stopCapture else nil,
+    dumpCaptures = if IS_SERVER then Server.dumpCaptures else nil,
 }
 
 Lync.default = Lync

package/src/internal/Channel.luau

@@ -17,23 +17,35 @@ local bxor = bit32.bxor
 local band32 = bit32.band
 local countlz = bit32.countlz
 local lshift = bit32.lshift
+local bor = bit32.bor
+local rshift = bit32.rshift
+
+local TS_NONE = 0
+local TS_FRAME = 1
+local TS_OFFSET = 2
+local TS_FULL = 3
 
 -- State ---------------------------------------------------------------
 
 local _maxSize = MAX_SIZE
-
--- Packet name for overflow diagnostics. Not coroutine-safe: concurrent
--- serializers may overwrite before the error fires.
 local _currentPacket = ""
 
+-- Timestamp state updated once per flush via updateTimestamp().
+local _frameCounter: number = 0
+local _offsetMs: number = 0
+local _clockTime: number = 0
+local _anyTimestamp = false
+
+-- Stats gating. Default off; set via Lync.enableStats().
+local _statsEnabled = false
+
 -- Public --------------------------------------------------------------
 
 local Channel = {}
 
--- Override the maximum buffer size. Call before start(). Range: 4096–1048576.
 function Channel.setMaxSize(bytes: number): ()
     if bytes < 4096 or bytes > 1048576 then
-        error(`[Lync] Channel max size must be 4096–1048576, got {bytes}`)
+        error(`[Lync] Channel max size must be 4096-1048576, got {bytes}`)
     end
     _maxSize = bytes
 end
@@ -56,7 +68,6 @@ function Channel.create(): ChannelState
     }
 end
 
--- Grows the channel buffer to fit the requested bytes. Power-of-two sizing.
 function Channel.alloc(ch: ChannelState, bytes: number): ()
     local needed = ch.cursor + bytes
     if needed <= ch.size then
@@ -95,52 +106,126 @@ function Channel.sealAndDump(ch: ChannelState): (buffer, { Instance })
     return out, if #refs > 0 then table.clone(refs) else {}
 end
 
--- Sets the packet name for overflow diagnostics.
 function Channel.setCurrentPacket(name: string): ()
     _currentPacket = name
 end
 
--- Writes a single value into the batch. Opens a new header on ID change or overflow.
-function Channel.writeBatch(ch: ChannelState, id: number, name: string, codec: any, data: any): ()
-    if id ~= ch.lastId or ch.itemCount >= MAX_BATCH then
-        if ch.lastId >= 0 then
-            buffer.writeu16(ch.buff, ch.countPos, ch.itemCount)
-        end
+function Channel.updateTimestamp(frameCounter: number, offsetMs: number, clockTime: number): ()
+    _frameCounter = frameCounter
+    _offsetMs = offsetMs
+    _clockTime = clockTime
+end
 
-        _currentPacket = name
-        alloc(ch, 3)
-        local c = ch.cursor
-        buffer.writeu8(ch.buff, c, id)
-        ch.countPos = c + 1
-        ch.cursor = c + 3
-        ch.lastId = id
-        ch.itemCount = 0
+function Channel.enableTimestamps(): ()
+    _anyTimestamp = true
+end
+
+function Channel.hasTimestamps(): boolean
+    return _anyTimestamp
+end
+
+function Channel.enableStats(): ()
+    _statsEnabled = true
+end
+
+function Channel.statsEnabled(): boolean
+    return _statsEnabled
+end
+
+-- Batch opener: no timestamp variant. Resolved at define time via reg._openFn (#2)
+local function openBatchPlain(ch: ChannelState, id: number, name: string): ()
+    if ch.lastId >= 0 then
+        buffer.writeu16(ch.buff, ch.countPos, ch.itemCount)
+    end
+    _currentPacket = name
+    alloc(ch, 3)
+    local c = ch.cursor
+    buffer.writeu8(ch.buff, c, id)
+    ch.countPos = c + 1
+    ch.cursor = c + 3
+    ch.lastId = id
+    ch.itemCount = 0
+end
+
+local function openBatchFrame(ch: ChannelState, id: number, name: string): ()
+    if ch.lastId >= 0 then
+        buffer.writeu16(ch.buff, ch.countPos, ch.itemCount)
+    end
+    _currentPacket = name
+    alloc(ch, 4)
+    local c = ch.cursor
+    buffer.writeu8(ch.buff, c, id)
+    ch.countPos = c + 1
+    buffer.writeu8(ch.buff, c + 3, _frameCounter)
+    ch.cursor = c + 4
+    ch.lastId = id
+    ch.itemCount = 0
+end
+
+local function openBatchOffset(ch: ChannelState, id: number, name: string): ()
+    if ch.lastId >= 0 then
+        buffer.writeu16(ch.buff, ch.countPos, ch.itemCount)
+    end
+    _currentPacket = name
+    alloc(ch, 5)
+    local c = ch.cursor
+    buffer.writeu8(ch.buff, c, id)
+    ch.countPos = c + 1
+    buffer.writeu16(ch.buff, c + 3, _offsetMs)
+    ch.cursor = c + 5
+    ch.lastId = id
+    ch.itemCount = 0
+end
+
+local function openBatchFull(ch: ChannelState, id: number, name: string): ()
+    if ch.lastId >= 0 then
+        buffer.writeu16(ch.buff, ch.countPos, ch.itemCount)
+    end
+    _currentPacket = name
+    alloc(ch, 11)
+    local c = ch.cursor
+    buffer.writeu8(ch.buff, c, id)
+    ch.countPos = c + 1
+    buffer.writef64(ch.buff, c + 3, _clockTime)
+    ch.cursor = c + 11
+    ch.lastId = id
+    ch.itemCount = 0
+end
+
+-- Returns the correct openBatch function for a given timestamp mode.
+function Channel.resolveOpenFn(tsMode: number): (ch: ChannelState, id: number, name: string) -> ()
+    if tsMode == TS_FRAME then
+        return openBatchFrame
+    elseif tsMode == TS_OFFSET then
+        return openBatchOffset
+    elseif tsMode == TS_FULL then
+        return openBatchFull
+    end
+    return openBatchPlain
+end
+
+-- Writes a single value into the batch. Zero branching on the hot path.
+function Channel.writeBatch(ch: ChannelState, reg: any, data: any): ()
+    local id = reg.id
+    if id ~= ch.lastId or ch.itemCount >= MAX_BATCH then
+        reg._openFn(ch, id, reg.name)
     end
 
     ch.itemCount += 1
-    codec.write(ch, data)
+    reg.codec.write(ch, data)
 end
 
 -- Appends pre-serialized bytes into a batch. Used by broadcast fan-out.
 function Channel.writeBatchRaw(
     ch: ChannelState,
-    id: number,
+    reg: any,
     src: buffer,
     srcLen: number,
     srcRefs: { Instance }?
 ): ()
+    local id = reg.id
     if id ~= ch.lastId or ch.itemCount >= MAX_BATCH then
-        if ch.lastId >= 0 then
-            buffer.writeu16(ch.buff, ch.countPos, ch.itemCount)
-        end
-
-        alloc(ch, 3)
-        local c = ch.cursor
-        buffer.writeu8(ch.buff, c, id)
-        ch.countPos = c + 1
-        ch.cursor = c + 3
-        ch.lastId = id
-        ch.itemCount = 0
+        reg._openFn(ch, id, reg.name)
     end
 
     ch.itemCount += 1
@@ -168,7 +253,7 @@ end
 
 --[[
     Writes a query frame. Seals any open batch, then writes:
-        id(u8) + correlationId(u16) + status(u8)
+        id(u8) + correlationId(varint) + status(u8)
     Status 0 = payload follows. Status 1 = nil response.
 ]]
 function Channel.writeQuery(
@@ -182,18 +267,39 @@ function Channel.writeQuery(
     _currentPacket = name
     sealOpen(ch)
 
-    alloc(ch, 4)
+    alloc(ch, 2)
     local c = ch.cursor
     buffer.writeu8(ch.buff, c, id)
-    buffer.writeu16(ch.buff, c + 1, correlationId)
+    ch.cursor = c + 1
+
+    -- Inline varint write to avoid circular dependency (Varint requires Channel)
+    local v = correlationId
+    if v < 0x80 then
+        alloc(ch, 1)
+        buffer.writeu8(ch.buff, ch.cursor, v)
+        ch.cursor += 1
+    else
+        alloc(ch, 5)
+        local b = ch.buff
+        local vc = ch.cursor
+        while v >= 0x80 do
+            buffer.writeu8(b, vc, bor(band32(v, 0x7F), 0x80))
+            v = rshift(v, 7)
+            vc += 1
+        end
+        buffer.writeu8(b, vc, v)
+        ch.cursor = vc + 1
+    end
 
+    local c2 = ch.cursor
+    alloc(ch, 1)
     if codec then
-        buffer.writeu8(ch.buff, c + 3, 0)
-        ch.cursor = c + 4
+        buffer.writeu8(ch.buff, c2, 0)
+        ch.cursor = c2 + 1
         codec.write(ch, data)
     else
-        buffer.writeu8(ch.buff, c + 3, 1)
-        ch.cursor = c + 4
+        buffer.writeu8(ch.buff, c2, 1)
+        ch.cursor = c2 + 1
     end
 end
 
@@ -229,12 +335,36 @@ function Channel.xorApply(current: buffer, previous: buffer?): buffer
     return result
 end
 
+-- Conditional refs clear (#6)
 function Channel.reset(ch: ChannelState): ()
     ch.cursor = 0
     ch.lastId = -1
     ch.countPos = 0
     ch.itemCount = 0
-    table.clear(ch.refs)
+    if #ch.refs > 0 then
+        table.clear(ch.refs)
+    end
+end
+
+-- Test helper: builds a minimal reg-like object for writeBatch.
+function Channel.mockReg(id: number, name: string, codec: any): any
+    return {
+        id = id,
+        name = name,
+        codec = codec,
+        timestampMode = 0,
+        _openFn = openBatchPlain,
+        drops = 0,
+        bytesSent = 0,
+        bytesReceived = 0,
+        fires = 0,
+        recvFires = 0,
+    }
 end
 
+Channel.TS_NONE = TS_NONE
+Channel.TS_FRAME = TS_FRAME
+Channel.TS_OFFSET = TS_OFFSET
+Channel.TS_FULL = TS_FULL
+
 return table.freeze(Channel)

package/src/internal/Registry.luau

@@ -2,6 +2,7 @@
 --!optimize 2
 -- Deterministic ID assignment for packets and queries.
 
+local Channel = require(script.Parent.Channel)
 local Types = require(script.Parent.Parent.Types)
 
 type Codec<T> = Types.Codec<T>
@@ -32,7 +33,8 @@ local function assign(
     signal: any,
     rateLimit: RateLimitConfig?,
     validate: ((data: any, player: Player) -> (boolean, string?))?,
-    maxPayloadBytes: number?
+    maxPayloadBytes: number?,
+    timestampMode: number?
 ): Registration
     if _names[name] then
         error(`[Lync] Duplicate registration: "{name}"`)
@@ -70,6 +72,13 @@ local function assign(
         validate = validate,
         needsGate = rateLimit ~= nil or validate ~= nil,
         maxPayloadBytes = maxPayloadBytes,
+        timestampMode = timestampMode or 0,
+        _openFn = Channel.resolveOpenFn(timestampMode or 0),
+        bytesSent = 0,
+        bytesReceived = 0,
+        fires = 0,
+        recvFires = 0,
+        drops = 0,
     }
 
     _entries[id] = reg
@@ -92,7 +101,8 @@ function Registry.register(
     signal: any,
     rateLimit: RateLimitConfig?,
     validate: ((data: any, player: Player) -> (boolean, string?))?,
-    maxPayloadBytes: number?
+    maxPayloadBytes: number?,
+    timestampMode: number?
 ): Registration
     return assign(
         name,
@@ -103,7 +113,8 @@ function Registry.register(
         signal,
         rateLimit,
         validate,
-        maxPayloadBytes
+        maxPayloadBytes,
+        timestampMode
     )
 end
 
@@ -143,4 +154,10 @@ function Registry.getByName(name: string): Registration?
     return if id then _entries[id] else nil
 end
 
+function Registry.forEach(fn: (reg: Registration) -> ()): ()
+    for _, reg in _entries do
+        fn(reg)
+    end
+end
+
 return table.freeze(Registry)