@axpecter/lync 2.2.0 → 2.3.1

package/src/internal/Channel.luau

@@ -2,6 +2,10 @@
 --!native
 -- Per-channel buffer state with MSB batch framing, XOR delta, timestamps.
 
+local Base = require(script.Parent.Parent.codec.Base)
+local Buf = require(script.Parent.Parent.util.Buffer)
+local Constants = require(script.Parent.Parent.util.Constants)
+local Log = require(script.Parent.Parent.util.Log)
 local Types = require(script.Parent.Parent.Types)
 local Varint = require(script.Parent.Parent.codec.primitive.Varint)
 
@@ -12,16 +16,29 @@ local TS_FRAME = 1
 local TS_OFFSET = 2
 local TS_FULL = 3
 
-local DEFAULT_MAX = 262144
 local INITIAL_BUF = 1024
-local FRAME_MASK = 0xFF
-local OFFSET_WIN = 65.536
+local HEADER_BYTE = 1
+local FRAME_MSB = Constants.FRAME_MSB
+local U8_MAX = Constants.U8_MAX
+local U16_MAX = Constants.U16_MAX
+local MAX_BATCH_ITEMS = Constants.MAX_BATCH_ITEMS
+
+-- 65.535s window so round((clock % win) * 1000) cannot overflow u16.
+local OFFSET_WIN = 65.535
+
+local TS_BYTES = table.freeze({
+    [TS_NONE] = 0,
+    [TS_FRAME] = 1,
+    [TS_OFFSET] = 2,
+    [TS_FULL] = 8,
+})
 
 -- State ------------------------------------------------------------------
 
-local _maxSize = DEFAULT_MAX
-local _anyTimestamp = false
+local _timestampsEnabled = false
 local _statsEnabled = false
+
+-- Refreshed by updateTimestamp once per flush.
 local _frameCounter = 0
 local _offsetMs = 0
 local _clock = 0.0
@@ -30,50 +47,20 @@ local EMPTY_REFS = table.freeze({}) :: { Instance }
 
 -- Private ----------------------------------------------------------------
 
-local countlz = bit32.countlz
-local lshift = bit32.lshift
+local alloc = Base.alloc
 local band = bit32.band
-local bxor = bit32.bxor
 local bor = bit32.bor
+local bufCopy = buffer.copy
 local writeu8 = buffer.writeu8
 local writeu16 = buffer.writeu16
-local writeu32 = buffer.writeu32
 local writef64 = buffer.writef64
-local readu8 = buffer.readu8
-local readu32 = buffer.readu32
 local round = math.round
-local minN = math.min
+local osClock = os.clock
 
-local function alloc(ch: Types.ChannelState, bytes: number): ()
-    local needed = ch.cursor + bytes
-    if needed <= ch.size then
-        return
-    end
-    if needed > _maxSize then
-        local name = ch.currentPacket
-        if name then
-            error(`[Lync] Channel.alloc("{name}"): buffer overflow ({needed}B, max {_maxSize}B)`)
-        end
-        error(`[Lync] Channel.alloc: buffer overflow ({needed}B, max {_maxSize}B)`)
+local function ensure(ch: Types.ChannelState, n: number): ()
+    if ch.cursor + n > ch.size then
+        alloc(ch, n)
     end
-    local newSize = lshift(1, 32 - countlz(needed - 1))
-    local newBuff = buffer.create(newSize)
-    buffer.copy(newBuff, 0, ch.buff, 0, ch.cursor)
-    ch.buff = newBuff
-    ch.size = newSize
-end
-
-local function tsBytes(mode: number): number
-    if mode == TS_NONE then
-        return 0
-    end
-    if mode == TS_FRAME then
-        return 1
-    end
-    if mode == TS_OFFSET then
-        return 2
-    end
-    return 8
 end
 
 local function writeTimestamp(b: buffer, off: number, mode: number): ()
@@ -86,8 +73,66 @@ local function writeTimestamp(b: buffer, off: number, mode: number): ()
     end
 end
 
+--[[
+    Single -> multi upgrade. Patches the previously-emitted single-item
+    header, splices a 2-byte count cell after the timestamp, and shifts the
+    payload right. Hot only when a packet fires twice in a row to the same
+    channel without an intervening flush.
+]]
+local function upgradeSingleToMulti(ch: Types.ChannelState, regId: number, headerSize: number): ()
+    local headerPos = ch.singlePos
+    writeu8(ch.buff, headerPos, regId)
+
+    local afterTs = headerPos + headerSize
+    local cursor = ch.cursor
+    local payloadLen = cursor - afterTs
+    ensure(ch, 2)
+    -- Re-bind: ensure() may have realloced the buffer.
+    local b = ch.buff
+
+    if payloadLen > 0 then
+        bufCopy(b, afterTs + 2, b, afterTs, payloadLen)
+    end
+
+    ch.countPos = afterTs
+    writeu16(b, afterTs, 0)
+    ch.cursor = cursor + 2
+    ch.singleMode = false
+end
+
+--[[
+    Two writeBatch implementations, swapped at startup by enableStats(). For
+    high-rate channels this saves ~1 register read + 1 compare + 1 jump per
+    item versus branching on `_statsEnabled` inside the loop.
+]]
+local writeBatchPlain: (Types.ChannelState, Types.Registration, any) -> ()
+local writeBatchStats: (Types.ChannelState, Types.Registration, any) -> ()
+
+writeBatchPlain = function(ch: Types.ChannelState, reg: Types.Registration, data: any): ()
+    if reg.id ~= ch.lastId or ch.itemCount >= MAX_BATCH_ITEMS then
+        reg._openFn(ch, reg.id)
+    elseif ch.singleMode then
+        upgradeSingleToMulti(ch, reg.id, reg.headerSize)
+    end
+    ch.itemCount += 1
+    reg.codec.write(ch, data)
+end
+
+writeBatchStats = function(ch: Types.ChannelState, reg: Types.Registration, data: any): ()
+    if reg.id ~= ch.lastId or ch.itemCount >= MAX_BATCH_ITEMS then
+        reg._openFn(ch, reg.id)
+    elseif ch.singleMode then
+        upgradeSingleToMulti(ch, reg.id, reg.headerSize)
+    end
+    ch.itemCount += 1
+    local before = ch.cursor
+    reg.codec.write(ch, data)
+    reg.bytesSent += ch.cursor - before
+end
+
 -- Public -----------------------------------------------------------------
 
+-- Module table is intentionally unfrozen: enableStats() hot-swaps writeBatch.
 local Channel = {}
 
 Channel.TS_NONE = TS_NONE
@@ -114,36 +159,19 @@ function Channel.create(): Types.ChannelState
     }
 end
 
-function Channel.alloc(ch: Types.ChannelState, bytes: number): ()
-    if bytes > 0 then
-        alloc(ch, bytes)
-    end
-end
-
---[[
-    Write a single byte at the cursor and advance. Centralizes the
-    ubiquitous `if cursor + 1 > size then alloc(ch, 1) end; writeu8(...);
-    cursor += 1` pattern.
-]]
 function Channel.writeByte(ch: Types.ChannelState, byte: number): ()
     local cursor = ch.cursor
-    if cursor + 1 > ch.size then
-        alloc(ch, 1)
+    if cursor + HEADER_BYTE > ch.size then
+        alloc(ch, HEADER_BYTE)
     end
     writeu8(ch.buff, cursor, byte)
-    ch.cursor = cursor + 1
+    ch.cursor = cursor + HEADER_BYTE
 end
 
---[[
-    Push `value` into the channel's sidecar refs array, write its
-    1-based index as a u16 to the buffer, advance cursor. Returns the
-    index. Used by the Instance and Unknown codecs.
-]]
-function Channel.pushRef(ch: Types.ChannelState, value: any): number
+-- Append `value` to the sidecar refs, write its 1-based u16 index.
+function Channel.pushRef(ch: Types.ChannelState, value: any): ()
     local idx = ch.refCount + 1
-    if idx > 0xFFFF then
-        error("[Lync] Channel.pushRef: ref overflow (>65535)")
-    end
+    Log.assert(idx <= U16_MAX, "ref overflow, max 65535")
     ch.refs[idx] = value
     ch.refCount = idx
 
@@ -153,9 +181,12 @@ function Channel.pushRef(ch: Types.ChannelState, value: any): number
     end
     writeu16(ch.buff, cursor, idx)
     ch.cursor = cursor + 2
-    return idx
 end
 
+--[[
+    Per-flush reset. Preserves prevDump/prevDumpLen (XOR baseline) and
+    ch.deltas (delta caches): both must outlive flushes for the same owner.
+]]
 function Channel.reset(ch: Types.ChannelState): ()
     ch.cursor = 0
     ch.lastId = -1
@@ -170,20 +201,34 @@ function Channel.reset(ch: Types.ChannelState): ()
     end
 end
 
+--[[
+    Full reset including XOR baseline and delta caches. Pool.acquire calls
+    this so a recycled state cannot leak the previous owner's baseline.
+]]
+function Channel.fullReset(ch: Types.ChannelState): ()
+    Channel.reset(ch)
+    ch.prevDump = nil
+    ch.prevDumpLen = 0
+    table.clear(ch.deltas)
+end
+
 --[[
     Resolve the batch-open closure for a given timestamp mode and packet
-    name. The returned function:
-      - seals the previous batch (writing the deferred multi-mode count),
-      - writes the single-mode header [0x80 | id] + optional timestamp,
-      - records cursor position so writeBatch can upgrade single->multi later.
+    name. Returned function seals the prior batch, writes the single-mode
+    header [0x80 | id] + optional timestamp, and records the cursor so
+    writeBatch can upgrade single -> multi later.
 ]]
 function Channel.resolveOpenFn(
     timestampMode: number,
     name: string
 ): (ch: Types.ChannelState, id: number) -> ()
-    local headerLen = 1 + tsBytes(timestampMode)
+    local headerLen = HEADER_BYTE + TS_BYTES[timestampMode]
 
     return function(ch: Types.ChannelState, id: number): ()
+        --[[
+            Inline sealCount: this is the only call site that can take the
+            multi-mode branch on a non-fresh channel.
+        ]]
         if ch.lastId >= 0 and not ch.singleMode then
             writeu16(ch.buff, ch.countPos, ch.itemCount)
         end
@@ -197,7 +242,7 @@ function Channel.resolveOpenFn(
             alloc(ch, headerLen)
         end
         local b = ch.buff
-        writeu8(b, cursor, bor(0x80, id))
+        writeu8(b, cursor, bor(FRAME_MSB, id))
         writeTimestamp(b, cursor + 1, timestampMode)
 
         ch.singleMode = true
@@ -206,95 +251,31 @@ function Channel.resolveOpenFn(
     end
 end
 
+Channel.writeBatch = writeBatchPlain
+
 --[[
-    Write one item into the current batch. Handles single->multi mode
-    upgrade when a second item lands on the same packet ID: clears the
-    header byte's MSB, then memmoves payload right by 2 to insert the
-    deferred u16 count between the timestamp and first payload.
+    Every caller (Server.flushReliable / flushUnreliable, Client.flush)
+    pre-checks `ch.cursor > 0`, so cursor here is always positive.
 ]]
-function Channel.writeBatch(ch: Types.ChannelState, reg: Types.Registration, data: any): ()
-    if reg.id ~= ch.lastId or ch.itemCount >= 0xFFFF then
-        reg._openFn(ch, reg.id)
-    elseif ch.singleMode then
-        local headerPos = ch.singlePos
-        local b = ch.buff
-        writeu8(b, headerPos, reg.id)
-
-        local afterTs = headerPos + reg.headerSize
-        local cursor = ch.cursor
-        local payloadLen = cursor - afterTs
-        if cursor + 2 > ch.size then
-            alloc(ch, 2)
-        end
-        local b2 = ch.buff
-
-        if payloadLen > 0 then
-            buffer.copy(b2, afterTs + 2, b2, afterTs, payloadLen)
-        end
-
-        ch.countPos = afterTs
-        writeu16(b2, afterTs, 0)
-        ch.cursor = cursor + 2
-        ch.singleMode = false
-    end
-
-    ch.itemCount += 1
-    reg.codec.write(ch, data)
-end
-
 function Channel.sealAndDump(ch: Types.ChannelState): (buffer, { Instance }, number, number)
-    if ch.lastId >= 0 and not ch.singleMode and ch.countPos >= 0 then
+    if ch.lastId >= 0 and not ch.singleMode then
         writeu16(ch.buff, ch.countPos, ch.itemCount)
     end
 
     local cursor = ch.cursor
     local snapshot = buffer.create(cursor)
-    if cursor > 0 then
-        buffer.copy(snapshot, 0, ch.buff, 0, cursor)
-    end
+    bufCopy(snapshot, 0, ch.buff, 0, cursor)
 
     local refCount = ch.refCount
     local refs = if refCount > 0 then table.clone(ch.refs) else EMPTY_REFS
     return snapshot, refs, cursor, refCount
 end
 
---[[
-    XOR `current` against `previous`, returning a fresh buffer of curLen
-    bytes. When `previous` is nil, returns `current` unchanged.
-]]
-function Channel.xorApply(
-    current: buffer,
-    curLen: number,
-    previous: buffer?,
-    prevLen: number
-): buffer
-    if not previous then
-        return current
-    end
-
-    local result = buffer.create(curLen)
-    local overlap = minN(curLen, prevLen)
-    local prev = previous
-
-    local aligned = band(overlap, -4)
-    local i = 0
-    while i < aligned do
-        writeu32(result, i, bxor(readu32(current, i), readu32(prev, i)))
-        i += 4
-    end
-    while i < overlap do
-        writeu8(result, i, bxor(readu8(current, i), readu8(prev, i)))
-        i += 1
-    end
-    if curLen > overlap then
-        buffer.copy(result, overlap, current, overlap, curLen - overlap)
-    end
-    return result
-end
+Channel.xorApply = Buf.xorApply
 
 --[[
-    Write a query frame. MSB on the id byte signals nil response;
-    cleared means a payload follows. Correlation IDs are varint-encoded.
+    Query frame. MSB on the id byte = nil response; cleared = payload follows.
+    Correlation IDs are varint-encoded.
 ]]
 function Channel.writeQuery(
     ch: Types.ChannelState,
@@ -303,14 +284,19 @@ function Channel.writeQuery(
     codec: Types.InternalCodec<any>?,
     data: any
 ): ()
-    if ch.lastId >= 0 and not ch.singleMode and ch.countPos >= 0 then
+    if ch.lastId >= 0 and not ch.singleMode then
         writeu16(ch.buff, ch.countPos, ch.itemCount)
     end
+    --[[
+        lastId = -1 forces the next writeBatch to call _openFn (which resets
+        singleMode). Every other reader of singleMode (writeQuery,
+        sealAndDump) is gated by `lastId >= 0` first, so stamping singleMode
+        here would never be observed before the next reset overwrites it.
+    ]]
     ch.lastId = -1
-    ch.singleMode = false
 
     local hasPayload = codec ~= nil and data ~= nil
-    local headerByte = if hasPayload then id else bor(0x80, id)
+    local headerByte = if hasPayload then id else bor(FRAME_MSB, id)
 
     local cursor = ch.cursor
     if cursor + 1 > ch.size then
@@ -328,29 +314,42 @@ end
 -- Configuration ----------------------------------------------------------
 
 function Channel.setMaxSize(bytes: number): ()
-    _maxSize = bytes
+    Base.setMaxSize(bytes)
 end
 
 function Channel.updateTimestamp(): ()
-    _frameCounter = band(_frameCounter + 1, FRAME_MASK)
-    _offsetMs = round((os.clock() % OFFSET_WIN) * 1000)
-    _clock = os.clock()
+    _frameCounter = band(_frameCounter + 1, U8_MAX)
+    local now = osClock()
+    _offsetMs = round((now % OFFSET_WIN) * 1000)
+    _clock = now
 end
 
 function Channel.enableTimestamps(): ()
-    _anyTimestamp = true
+    _timestampsEnabled = true
 end
 
 function Channel.hasTimestamps(): boolean
-    return _anyTimestamp
+    return _timestampsEnabled
 end
 
 function Channel.enableStats(): ()
     _statsEnabled = true
+    Channel.writeBatch = writeBatchStats
 end
 
 function Channel.statsEnabled(): boolean
     return _statsEnabled
 end
 
-return table.freeze(Channel)
+-- Module-level config + timestamp counters. Distinct from Channel.reset(ch).
+function Channel.resetGlobals(): ()
+    Base.reset()
+    _timestampsEnabled = false
+    _statsEnabled = false
+    _frameCounter = 0
+    _offsetMs = 0
+    _clock = 0.0
+    Channel.writeBatch = writeBatchPlain
+end
+
+return Channel

package/src/internal/Middleware.luau

@@ -13,13 +13,21 @@ local _dropSignal = Signal.create()
 
 -- Private ----------------------------------------------------------------
 
+-- Mirrors Signal's STATE_DISCONNECTED. Entries in this state are mid-fire disconnects.
+local STATE_DISCONNECTED = 0
+
 --[[
-    Walk a transform chain in order. Each callback returns a transformed
-    value or nil to keep the previous value. A fresh snapshot guards
-    against disconnect-during-fire reentry.
+    Snapshot before iterating: a handler can disconnect itself or others,
+    and a fresh chain pull would skip or double-fire entries depending on
+    swap direction. Snapshotting locks the per-frame view.
 ]]
-local function runChain(signal: any, value: any, name: string, player: Player?): any
-    local count = signal._count[1]
+local function runChain(
+    signal: { _count: number, _entries: { any } },
+    value: any,
+    name: string,
+    player: Player?
+): any
+    local count = signal._count
     if count == 0 then
         return value
     end
@@ -31,8 +39,9 @@ local function runChain(signal: any, value: any, name: string, player: Player?):
     local result = value
     for i = 1, count do
         local entry = snapshot[i]
-        if entry._state ~= 0 then
+        if entry._state ~= STATE_DISCONNECTED then
             local returned = entry.fn(result, name, player)
+            -- Hooks return non-nil to replace the value; nil keeps the prior result.
             if returned ~= nil then
                 result = returned
             end
@@ -73,6 +82,7 @@ function Middleware.fireDrop(player: Player, reason: string, name: string, data:
     _dropSignal:fireSync(player, reason, name, data)
 end
 
+-- Hot-path callers gate on these to skip runChain's snapshot allocation.
 function Middleware.hasSendHooks(): boolean
     return _sendSignal:hasListeners()
 end
@@ -81,4 +91,10 @@ function Middleware.hasReceiveHooks(): boolean
     return _receiveSignal:hasListeners()
 end
 
+function Middleware.reset(): ()
+    _sendSignal = Signal.create()
+    _receiveSignal = Signal.create()
+    _dropSignal = Signal.create()
+end
+
 return table.freeze(Middleware)

package/src/internal/Pool.luau

@@ -1,9 +1,9 @@
 --!strict
 --!optimize 2
--- Stack-based ChannelState pool. Reset-on-acquire keeps released
--- channels reusable without per-release reset cost.
+-- ChannelState pool. Acquire fullResets to wipe prior owner state.
 
 local Channel = require(script.Parent.Channel)
+local Log = require(script.Parent.Parent.util.Log)
 local Types = require(script.Parent.Parent.Types)
 
 -- Constants --------------------------------------------------------------
@@ -20,17 +20,19 @@ local _maxSize = DEFAULT_SIZE
 
 local Pool = {}
 
+-- fullReset wipes the prior owner's XOR baseline and delta caches.
 function Pool.acquire(): Types.ChannelState
     if _depth > 0 then
         local ch = _stack[_depth]
         _stack[_depth] = nil
         _depth -= 1
-        Channel.reset(ch)
+        Channel.fullReset(ch)
         return ch
     end
     return Channel.create()
 end
 
+-- Above the cap, drop on the floor; the GC reclaims the buffer.
 function Pool.release(ch: Types.ChannelState): ()
     if _depth >= _maxSize then
         return
@@ -41,7 +43,7 @@ end
 
 function Pool.setMaxSize(size: number): ()
     if size < 0 then
-        error(`[Lync] Pool.setMaxSize: size must be >= 0, got {size}`)
+        Log.error(`size must be non-negative, got {size}`)
     end
     _maxSize = size
     while _depth > _maxSize do
@@ -54,4 +56,10 @@ function Pool.count(): number
     return _depth
 end
 
+function Pool.reset(): ()
+    table.clear(_stack)
+    _depth = 0
+    _maxSize = DEFAULT_SIZE
+end
+
 return table.freeze(Pool)

package/src/internal/Registry.luau

@@ -1,7 +1,8 @@
 --!strict
 --!optimize 2
--- Deterministic packet/query ID assignment. Sequential 7-bit IDs.
+-- Sequential 7-bit packet/query ID assignment.
 
+local Log = require(script.Parent.Parent.util.Log)
 local Signal = require(script.Parent.Parent.api.Signal)
 local Types = require(script.Parent.Parent.Types)
 
@@ -10,13 +11,15 @@ local Types = require(script.Parent.Parent.Types)
 local KIND_PACKET = 0
 local KIND_REQUEST = 1
 local KIND_RESPONSE = 2
+
+-- 7-bit id leaves the MSB free for the frame single/multi flag (see Constants.FRAME_MSB).
 local MAX_ID = 127
 
 -- State ------------------------------------------------------------------
 
 local _nextId = 0
-local _byId: { [number]: Types.Registration } = {}
-local _byName: { [string]: Types.Registration } = {}
+local _registrationsById: { [number]: Types.Registration } = {}
+local _registrationsByName: { [string]: Types.Registration } = {}
 
 -- Public -----------------------------------------------------------------
 
@@ -45,10 +48,14 @@ export type RegisterOptions = {
 function Registry.register(opts: RegisterOptions): Types.Registration
     local nextCandidate = _nextId + 1
     if nextCandidate > MAX_ID then
-        error(`[Lync] Registry.register: ID limit exceeded ({MAX_ID})`)
+        Log.error(`ID limit ({MAX_ID}) exceeded; cannot register "{opts.name}"`)
     end
-    if opts.kind ~= KIND_RESPONSE and _byName[opts.name] then
-        error(`[Lync] Registry.register: duplicate name "{opts.name}"`)
+    --[[
+        RESPONSE entries share their request's name with a "\0resp" suffix; only
+        request/packet names need uniqueness in the by-name index.
+    ]]
+    if opts.kind ~= KIND_RESPONSE and _registrationsByName[opts.name] ~= nil then
+        Log.error(`duplicate name "{opts.name}"`)
     end
 
     _nextId = nextCandidate
@@ -75,36 +82,38 @@ function Registry.register(opts: RegisterOptions): Types.Registration
         drops = 0,
     }
 
-    _byId[nextCandidate] = reg
+    _registrationsById[nextCandidate] = reg
     if opts.kind ~= KIND_RESPONSE then
-        _byName[opts.name] = reg
+        _registrationsByName[opts.name] = reg
     end
     return reg
 end
 
 function Registry.get(id: number): Types.Registration?
-    return _byId[id]
+    return _registrationsById[id]
 end
 
 function Registry.getByName(name: string): Types.Registration?
-    return _byName[name]
+    return _registrationsByName[name]
 end
 
 function Registry.count(): number
     return _nextId
 end
 
+-- IDs are sequential and never freed, so the table has no holes.
 function Registry.all(): { Types.Registration }
     local result = table.create(_nextId)
-    local n = 0
     for i = 1, _nextId do
-        local reg = _byId[i]
-        if reg then
-            n += 1
-            result[n] = reg
-        end
+        result[i] = _registrationsById[i]
     end
     return result
 end
 
+function Registry.reset(): ()
+    table.clear(_registrationsById)
+    table.clear(_registrationsByName)
+    _nextId = 0
+end
+
 return table.freeze(Registry)

package/src/internal/Transport.luau

@@ -1,6 +1,6 @@
 --!strict
 --!optimize 2
--- Lazy-require Server/Client to break the api -> transport import cycle.
+-- Lazy Server/Client require to break the api -> transport import cycle.
 
 -- State ------------------------------------------------------------------