@axpecter/lync 1.5.1 → 2.0.0

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)

package/src/transport/Client.luau

@@ -12,6 +12,7 @@ local Types = require(script.Parent.Parent.Types)
 
 type ChannelState = Types.ChannelState
 type Codec<T> = Types.Codec<T>
+type Registration = Types.Registration
 
 -- State ---------------------------------------------------------------
 
@@ -22,6 +23,16 @@ local _unreliable = nil :: ChannelState?
 local _prevRecv = nil :: buffer?
 local _isStarted = false
 
+-- Flush control
+local _flushRate = 60
+local _flushInterval = 1 / 60
+local _useAccumulator = false
+local _flushAccum = 0
+local _flushedThisFrame = false
+
+-- Timestamp
+local _frameCounter: number = 0
+
 -- Private -------------------------------------------------------------
 
 local function receive(data: any, refs: any, applyXor: boolean): ()
@@ -64,6 +75,11 @@ local function flushChannel(remote: any, ch: ChannelState, applyXor: boolean): (
 end
 
 local function flush(): ()
+    if Channel.hasTimestamps() then
+        _frameCounter = (_frameCounter + 1) % 256
+        Channel.updateTimestamp(_frameCounter, 0, os.clock())
+    end
+
     flushChannel(Bridge.reliable, _reliable :: ChannelState, true)
     flushChannel(Bridge.unreliable, _unreliable :: ChannelState, false)
 end
@@ -89,23 +105,39 @@ function Client.start(): ()
     Bridge.unreliable.OnClientEvent:Connect(function(data: any, refs: any): ()
         receive(data, refs, false)
     end)
-    RunService.Heartbeat:Connect(flush)
+
+    if _useAccumulator then
+        RunService.Heartbeat:Connect(function(dt: number)
+            if _flushedThisFrame then
+                _flushedThisFrame = false
+                return
+            end
+            _flushAccum += dt
+            if _flushAccum < _flushInterval then
+                return
+            end
+            _flushAccum -= _flushInterval
+            flush()
+        end)
+    else
+        RunService.Heartbeat:Connect(function()
+            if _flushedThisFrame then
+                _flushedThisFrame = false
+                return
+            end
+            flush()
+        end)
+    end
 end
 
-function Client.write(
-    id: number,
-    name: string,
-    codec: Codec<any>,
-    data: any,
-    isUnreliable: boolean
-): ()
+function Client.write(reg: Registration, data: any, isUnreliable: boolean): ()
     if not _isStarted then
         error(NOT_STARTED)
     end
 
     local final: any
     if Middleware.hasSend then
-        final = Middleware.runSend(data, name, nil)
+        final = Middleware.runSend(data, reg.name, nil)
         if final == nil then
             return
         end
@@ -114,10 +146,16 @@ function Client.write(
     end
 
     local ch = if isUnreliable then _unreliable :: ChannelState else _reliable :: ChannelState
-    Channel.writeBatch(ch, id, name, codec, final)
+    if Channel.statsEnabled() then
+        local before = ch.cursor
+        Channel.writeBatch(ch, reg, final)
+        reg.bytesSent += ch.cursor - before
+        reg.fires += 1
+    else
+        Channel.writeBatch(ch, reg, final)
+    end
 end
 
--- Shared for both query requests and responses(identical wire format).
 function Client.writeQuery(
     id: number,
     name: string,
@@ -149,4 +187,20 @@ function Client.writeQueryNil(id: number, name: string, correlationId: number):
     Channel.writeQuery(_reliable :: ChannelState, id, name, correlationId, nil, nil)
 end
 
+function Client.flush(): ()
+    _flushAccum = 0
+    _flushedThisFrame = true
+    flush()
+end
+
+function Client.setFlushRate(hz: number): ()
+    _flushRate = math.clamp(hz, 1, 60)
+    _flushInterval = 1 / _flushRate
+    _useAccumulator = _flushRate < 60
+end
+
+function Client.getFlushRate(): number
+    return _flushRate
+end
+
 return table.freeze(Client)

package/src/transport/Gate.luau

@@ -162,11 +162,17 @@ end
 
 function Gate.check(value: any, reg: Registration, player: Player): boolean
     if not checkRate(player, reg) then
+        if reg.drops then
+            reg.drops += 1
+        end
         fireDrop(player, "rate", reg.name, nil)
         return false
     end
 
     if not isClean(value, 1) then
+        if reg.drops then
+            reg.drops += 1
+        end
         fireDrop(player, "nan", reg.name, value)
         return false
     end
@@ -175,6 +181,9 @@ function Gate.check(value: any, reg: Registration, player: Player): boolean
     if validate then
         local ok, reason = validate(value, player)
         if not ok then
+            if reg.drops then
+                reg.drops += 1
+            end
             fireDrop(player, reason or "validate", reg.name, value)
             return false
         end

package/src/transport/Reader.luau

@@ -3,9 +3,11 @@
 -- Deserializes incoming buffers and routes by registration kind.
 
 local Baseline = require(script.Parent.Parent.internal.Baseline)
+local Channel = require(script.Parent.Parent.internal.Channel)
 local Gate = require(script.Parent.Gate)
 local Middleware = require(script.Parent.Parent.internal.Middleware)
 local Registry = require(script.Parent.Parent.internal.Registry)
+local Varint = require(script.Parent.Parent.codec.primitive.Varint)
 
 local registryGet = Registry.get
 local gateCheck = Gate.check
@@ -16,8 +18,14 @@ local gateReportDrop = Gate.reportDrop
 local KIND_PACKET = Registry.KIND_PACKET
 local KIND_REQUEST = Registry.KIND_REQUEST
 
+local TS_FRAME = Channel.TS_FRAME
+local TS_OFFSET = Channel.TS_OFFSET
+local TS_FULL = Channel.TS_FULL
+
 local MAX_INCOMING = 65536
 
+local floor = math.floor
+
 -- Public --------------------------------------------------------------
 
 local Reader = {}
@@ -47,9 +55,9 @@ function Reader.process(
         Baseline.setReadKey(player or false)
     end
 
-    -- Cache flags once per frame-buffer, not per packet
     local hasReceiveMiddleware = Middleware.hasReceive
     local isServer = player ~= nil
+    local statsOn = Channel.statsEnabled()
 
     while pos < length do
         local id = buffer.readu8(incoming, pos)
@@ -80,21 +88,62 @@ function Reader.process(
             local batchStart = pos
             local maxBytes = reg.maxPayloadBytes
 
+            -- Timestamp is per-batch, read once after count
+            local timestamp: number? = nil
+            local tsMode = reg.timestampMode
+            if tsMode == TS_FRAME then
+                timestamp = buffer.readu8(incoming, pos)
+                pos += 1
+            elseif tsMode == TS_OFFSET then
+                timestamp = buffer.readu16(incoming, pos)
+                pos += 2
+            elseif tsMode == TS_FULL then
+                timestamp = buffer.readf64(incoming, pos)
+                pos += 8
+            end
+
+            -- Cap count for fixed-size codecs to prevent wasted iterations
+            local fixedSize = (codec :: any)._size
+            if fixedSize and fixedSize > 0 then
+                local maxItems = floor((length - pos) / fixedSize)
+                if count > maxItems then
+                    count = maxItems
+                end
+            end
+
             -- Hot path: no gate, no middleware, no byte budget
             if not (isServer and reg.needsGate) and not hasReceiveMiddleware and not maxBytes then
-                for _ = 1, count do
-                    if pos >= length then
-                        break
+                if statsOn then
+                    local batchBytes = 0
+                    for _ = 1, count do
+                        if pos >= length then
+                            break
+                        end
+
+                        local value, consumed = codec.read(incoming, pos, refs)
+                        pos += consumed
+                        batchBytes += consumed
+                        signal:fire(value, player, timestamp)
                     end
+                    reg.bytesReceived += batchBytes
+                    reg.recvFires += count
+                else
+                    for _ = 1, count do
+                        if pos >= length then
+                            break
+                        end
 
-                    local value, consumed = codec.read(incoming, pos, refs)
-                    pos += consumed
-                    signal:fire(value, player)
+                        local value, consumed = codec.read(incoming, pos, refs)
+                        pos += consumed
+                        signal:fire(value, player, timestamp)
+                    end
                 end
             else
                 -- Cold path: gate and/or middleware and/or byte budget active
                 local baseName = reg.baseName
                 local needsGate = isServer and reg.needsGate
+                local batchBytes = if statsOn then 0 else nil
+                local recvCount = if statsOn then 0 else nil
 
                 for _ = 1, count do
                     if pos >= length then
@@ -109,6 +158,11 @@ function Reader.process(
                     local value, consumed = codec.read(incoming, pos, refs)
                     pos += consumed
 
+                    if batchBytes then
+                        batchBytes += consumed
+                        recvCount += 1
+                    end
+
                     if needsGate and not gateCheck(value, reg, player :: Player) then
                         continue
                     end
@@ -118,31 +172,32 @@ function Reader.process(
                         if final == nil then
                             continue
                         end
-                        signal:fire(final, player)
+                        signal:fire(final, player, timestamp)
                     else
-                        signal:fire(value, player)
+                        signal:fire(value, player, timestamp)
                     end
                 end
+                if batchBytes then
+                    reg.bytesReceived += batchBytes
+                    reg.recvFires += recvCount :: number
+                end
             end
         else
-            -- Query frame: id(u8, already read) + correlationId(u16) + status(u8) = 3 more bytes
-            if pos + 3 > length then
+            -- Query frame: id(u8, already read) + correlationId(varint) + status(u8)
+            if pos + 2 > length then
                 break
             end
 
             local queryCodec = reg.codec
             local querySignal = reg.signal
 
-            local correlationId = buffer.readu16(incoming, pos)
-            local status = buffer.readu8(incoming, pos + 2)
-            pos += 3
+            local correlationId, corrBytes = Varint.read(incoming, pos)
+            pos += corrBytes
+            local status = buffer.readu8(incoming, pos)
+            pos += 1
 
             if status == 1 then
-                if kind == KIND_REQUEST then
-                    querySignal:fire(nil, player, correlationId)
-                else
-                    querySignal:fire(nil, correlationId)
-                end
+                querySignal:fire(nil, player, correlationId)
                 continue
             end
 
@@ -163,11 +218,7 @@ function Reader.process(
                 final = value
             end
 
-            if kind == KIND_REQUEST then
-                querySignal:fire(final, player, correlationId)
-            else
-                querySignal:fire(final, correlationId)
-            end
+            querySignal:fire(final, player, correlationId)
         end
     end
 end