@axpecter/lync 2.1.2 → 2.2.0

package/src/internal/Channel.luau

@@ -1,10 +1,11 @@
 --!strict
 --!native
--- Per-channel buffer state with MSB batch framing, XOR, timestamps.
+-- Per-channel buffer state with MSB batch framing, XOR delta, timestamps.
 
 local Types = require(script.Parent.Parent.Types)
+local Varint = require(script.Parent.Parent.codec.primitive.Varint)
 
--- Constants -----------------------------------------------------------
+-- Constants --------------------------------------------------------------
 
 local TS_NONE = 0
 local TS_FRAME = 1
@@ -12,9 +13,11 @@ local TS_OFFSET = 2
 local TS_FULL = 3
 
 local DEFAULT_MAX = 262144
-local EMPTY_REFS = table.freeze({})
+local INITIAL_BUF = 1024
+local FRAME_MASK = 0xFF
+local OFFSET_WIN = 65.536
 
--- State ---------------------------------------------------------------
+-- State ------------------------------------------------------------------
 
 local _maxSize = DEFAULT_MAX
 local _anyTimestamp = false
@@ -23,20 +26,23 @@ local _frameCounter = 0
 local _offsetMs = 0
 local _clock = 0.0
 
--- Private -------------------------------------------------------------
+local EMPTY_REFS = table.freeze({}) :: { Instance }
+
+-- Private ----------------------------------------------------------------
 
 local countlz = bit32.countlz
 local lshift = bit32.lshift
+local band = bit32.band
 local bxor = bit32.bxor
 local bor = bit32.bor
-local band = bit32.band
 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 min = math.min
+local minN = math.min
 
 local function alloc(ch: Types.ChannelState, bytes: number): ()
     local needed = ch.cursor + bytes
@@ -44,11 +50,11 @@ local function alloc(ch: Types.ChannelState, bytes: number): ()
         return
     end
     if needed > _maxSize then
-        error(
-            if ch.currentPacket
-                then `[Lync] Channel: buffer overflow ({needed}B, max {_maxSize}B) in "{ch.currentPacket}"`
-                else `[Lync] Channel: buffer overflow ({needed}B, max {_maxSize}B)`
-        )
+        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)`)
     end
     local newSize = lshift(1, 32 - countlz(needed - 1))
     local newBuff = buffer.create(newSize)
@@ -57,7 +63,30 @@ local function alloc(ch: Types.ChannelState, bytes: number): ()
     ch.size = newSize
 end
 
--- Public --------------------------------------------------------------
+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): ()
+    if mode == TS_FRAME then
+        writeu8(b, off, _frameCounter)
+    elseif mode == TS_OFFSET then
+        writeu16(b, off, _offsetMs)
+    elseif mode == TS_FULL then
+        writef64(b, off, _clock)
+    end
+end
+
+-- Public -----------------------------------------------------------------
 
 local Channel = {}
 
@@ -68,9 +97,9 @@ Channel.TS_FULL = TS_FULL
 
 function Channel.create(): Types.ChannelState
     return {
-        buff = buffer.create(1024),
+        buff = buffer.create(INITIAL_BUF),
         cursor = 0,
-        size = 1024,
+        size = INITIAL_BUF,
         refs = {},
         refCount = 0,
         lastId = -1,
@@ -86,7 +115,45 @@ function Channel.create(): Types.ChannelState
 end
 
 function Channel.alloc(ch: Types.ChannelState, bytes: number): ()
-    alloc(ch, bytes)
+    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)
+    end
+    writeu8(ch.buff, cursor, byte)
+    ch.cursor = cursor + 1
+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
+    local idx = ch.refCount + 1
+    if idx > 0xFFFF then
+        error("[Lync] Channel.pushRef: ref overflow (>65535)")
+    end
+    ch.refs[idx] = value
+    ch.refCount = idx
+
+    local cursor = ch.cursor
+    if cursor + 2 > ch.size then
+        alloc(ch, 2)
+    end
+    writeu16(ch.buff, cursor, idx)
+    ch.cursor = cursor + 2
+    return idx
 end
 
 function Channel.reset(ch: Types.ChannelState): ()
@@ -104,121 +171,56 @@ function Channel.reset(ch: Types.ChannelState): ()
 end
 
 --[[
-    Resolves the batch-open function for a given timestamp mode.
-    The returned function handles MSB single-item framing:
-      First item: writes [0x80 | id] (single mode, no count).
-      Second item: upgrades to multi mode with u16 count.
+    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.
 ]]
 function Channel.resolveOpenFn(
     timestampMode: number,
     name: string
 ): (ch: Types.ChannelState, id: number) -> ()
-    if timestampMode == TS_NONE then
-        return function(ch: Types.ChannelState, id: number): ()
-            -- Seal previous batch
-            if ch.lastId >= 0 and not ch.singleMode then
-                writeu16(ch.buff, ch.countPos, ch.itemCount)
-            end
-            ch.currentPacket = name
-            ch.lastId = id
-            ch.itemCount = 0
-
-            -- Write single-mode header: [1IIIIIII]
-            local cursor = ch.cursor
-            if cursor + 1 > ch.size then
-                alloc(ch, 1)
-            end
-            writeu8(ch.buff, cursor, bor(0x80, id))
-            ch.singleMode = true
-            ch.singlePos = cursor
-            ch.cursor = cursor + 1
-        end
-    elseif timestampMode == TS_FRAME then
-        return function(ch: Types.ChannelState, id: number): ()
-            if ch.lastId >= 0 and not ch.singleMode then
-                writeu16(ch.buff, ch.countPos, ch.itemCount)
-            end
-            ch.currentPacket = name
-            ch.lastId = id
-            ch.itemCount = 0
-
-            local cursor = ch.cursor
-            if cursor + 2 > ch.size then
-                alloc(ch, 2)
-            end
-            local b = ch.buff
-            writeu8(b, cursor, bor(0x80, id))
-            writeu8(b, cursor + 1, _frameCounter)
-            ch.singleMode = true
-            ch.singlePos = cursor
-            ch.cursor = cursor + 2
-        end
-    elseif timestampMode == TS_OFFSET then
-        return function(ch: Types.ChannelState, id: number): ()
-            if ch.lastId >= 0 and not ch.singleMode then
-                writeu16(ch.buff, ch.countPos, ch.itemCount)
-            end
-            ch.currentPacket = name
-            ch.lastId = id
-            ch.itemCount = 0
-
-            local cursor = ch.cursor
-            if cursor + 3 > ch.size then
-                alloc(ch, 3)
-            end
-            local b = ch.buff
-            writeu8(b, cursor, bor(0x80, id))
-            writeu16(b, cursor + 1, _offsetMs)
-            ch.singleMode = true
-            ch.singlePos = cursor
-            ch.cursor = cursor + 3
+    local headerLen = 1 + tsBytes(timestampMode)
+
+    return function(ch: Types.ChannelState, id: number): ()
+        if ch.lastId >= 0 and not ch.singleMode then
+            writeu16(ch.buff, ch.countPos, ch.itemCount)
         end
-    else -- TS_FULL
-        return function(ch: Types.ChannelState, id: number): ()
-            if ch.lastId >= 0 and not ch.singleMode then
-                writeu16(ch.buff, ch.countPos, ch.itemCount)
-            end
-            ch.currentPacket = name
-            ch.lastId = id
-            ch.itemCount = 0
-
-            local cursor = ch.cursor
-            if cursor + 9 > ch.size then
-                alloc(ch, 9)
-            end
-            local b = ch.buff
-            writeu8(b, cursor, bor(0x80, id))
-            writef64(b, cursor + 1, _clock)
-            ch.singleMode = true
-            ch.singlePos = cursor
-            ch.cursor = cursor + 9
+
+        ch.currentPacket = name
+        ch.lastId = id
+        ch.itemCount = 0
+
+        local cursor = ch.cursor
+        if cursor + headerLen > ch.size then
+            alloc(ch, headerLen)
         end
+        local b = ch.buff
+        writeu8(b, cursor, bor(0x80, id))
+        writeTimestamp(b, cursor + 1, timestampMode)
+
+        ch.singleMode = true
+        ch.singlePos = cursor
+        ch.cursor = cursor + headerLen
     end
 end
 
 --[[
-    Writes one item into a batch. Handles MSB single→multi upgrade.
+    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.
 ]]
 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
-        --[[
-            Second item for same packet: upgrade to multi mode.
-            Rewrite header byte to clear MSB, insert u16 count after.
-        ]]
-        local b = ch.buff
         local headerPos = ch.singlePos
-        writeu8(b, headerPos, reg.id) -- MSB cleared = multi-item mode
-
-        local tsBytes = reg.headerSize - 1
-        local afterTs = headerPos + 1 + tsBytes
+        local b = ch.buff
+        writeu8(b, headerPos, reg.id)
 
-        --[[
-            Upgrading from single→multi requires inserting 2 bytes (u16 count)
-            between the timestamp and the first item's payload, shifting
-            existing data right by 2.
-        ]]
+        local afterTs = headerPos + reg.headerSize
         local cursor = ch.cursor
         local payloadLen = cursor - afterTs
         if cursor + 2 > ch.size then
@@ -231,7 +233,7 @@ function Channel.writeBatch(ch: Types.ChannelState, reg: Types.Registration, dat
         end
 
         ch.countPos = afterTs
-        writeu16(b2, afterTs, 0) -- placeholder u16; sealAndDump writes final count
+        writeu16(b2, afterTs, 0)
         ch.cursor = cursor + 2
         ch.singleMode = false
     end
@@ -240,32 +242,25 @@ function Channel.writeBatch(ch: Types.ChannelState, reg: Types.Registration, dat
     reg.codec.write(ch, data)
 end
 
---[[
-    Seals the current batch and returns a snapshot for transmission.
-]]
 function Channel.sealAndDump(ch: Types.ChannelState): (buffer, { Instance }, number, number)
-    -- Multi-item batches need their count finalized before transmission
     if ch.lastId >= 0 and not ch.singleMode and ch.countPos >= 0 then
         writeu16(ch.buff, ch.countPos, ch.itemCount)
     end
 
     local cursor = ch.cursor
     local snapshot = buffer.create(cursor)
-    buffer.copy(snapshot, 0, ch.buff, 0, cursor)
-
-    local refs: { Instance }
-    local refCount = ch.refCount
-    if refCount > 0 then
-        refs = table.clone(ch.refs)
-    else
-        refs = EMPTY_REFS :: any
+    if cursor > 0 then
+        buffer.copy(snapshot, 0, ch.buff, 0, cursor)
     end
 
+    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 frame against previous for deflate-friendly output.
+    XOR `current` against `previous`, returning a fresh buffer of curLen
+    bytes. When `previous` is nil, returns `current` unchanged.
 ]]
 function Channel.xorApply(
     current: buffer,
@@ -278,34 +273,28 @@ function Channel.xorApply(
     end
 
     local result = buffer.create(curLen)
-    local overlap = min(curLen, prevLen)
-    local prev = previous :: buffer
+    local overlap = minN(curLen, prevLen)
+    local prev = previous
 
-    -- u32 chunks
-    local aligned = overlap - (overlap % 4)
+    local aligned = band(overlap, -4)
     local i = 0
     while i < aligned do
-        buffer.writeu32(result, i, bxor(readu32(current, i), readu32(prev, i)))
+        writeu32(result, i, bxor(readu32(current, i), readu32(prev, i)))
         i += 4
     end
-
-    -- u8 remainder of overlap
     while i < overlap do
         writeu8(result, i, bxor(readu8(current, i), readu8(prev, i)))
         i += 1
     end
-
-    -- Excess bytes (current longer than previous)
     if curLen > overlap then
         buffer.copy(result, overlap, current, overlap, curLen - overlap)
     end
-
     return result
 end
 
 --[[
-    Writes a query frame with MSB encoding for nil-status.
-    MSB set = nil response, MSB clear = payload follows.
+    Write a query frame. MSB on the id byte signals nil response;
+    cleared means a payload follows. Correlation IDs are varint-encoded.
 ]]
 function Channel.writeQuery(
     ch: Types.ChannelState,
@@ -314,95 +303,37 @@ function Channel.writeQuery(
     codec: Types.InternalCodec<any>?,
     data: any
 ): ()
-    -- Queries are standalone frames, so close any open packet batch first
     if ch.lastId >= 0 and not ch.singleMode and ch.countPos >= 0 then
         writeu16(ch.buff, ch.countPos, ch.itemCount)
     end
     ch.lastId = -1
     ch.singleMode = false
 
-    if codec and data ~= nil then
-        local cursor = ch.cursor
-        if cursor + 1 > ch.size then
-            alloc(ch, 1)
-        end
-        writeu8(ch.buff, cursor, id)
-        ch.cursor = cursor + 1
-
-        -- Inlined varint avoids the function call overhead for correlation IDs
-        if correlationId <= 0xBF then
-            local c2 = ch.cursor
-            if c2 + 1 > ch.size then
-                alloc(ch, 1)
-            end
-            writeu8(ch.buff, c2, correlationId)
-            ch.cursor = c2 + 1
-        elseif correlationId <= 8383 then
-            local c2 = ch.cursor
-            if c2 + 2 > ch.size then
-                alloc(ch, 2)
-            end
-            local adjusted = correlationId - 192
-            writeu8(ch.buff, c2, bor(0xC0, band(adjusted // 256, 0x1F)))
-            writeu8(ch.buff, c2 + 1, band(adjusted, 0xFF))
-            ch.cursor = c2 + 2
-        else
-            local c2 = ch.cursor
-            if c2 + 5 > ch.size then
-                alloc(ch, 5)
-            end
-            writeu8(ch.buff, c2, 0xF0)
-            buffer.writeu32(ch.buff, c2 + 1, correlationId)
-            ch.cursor = c2 + 5
-        end
+    local hasPayload = codec ~= nil and data ~= nil
+    local headerByte = if hasPayload then id else bor(0x80, id)
 
-        codec.write(ch, data)
-    else
-        -- MSB set signals nil response to the reader
-        local cursor = ch.cursor
-        if cursor + 1 > ch.size then
-            alloc(ch, 1)
-        end
-        writeu8(ch.buff, cursor, bor(0x80, id))
-        ch.cursor = cursor + 1
-
-        if correlationId <= 0xBF then
-            local c2 = ch.cursor
-            if c2 + 1 > ch.size then
-                alloc(ch, 1)
-            end
-            writeu8(ch.buff, c2, correlationId)
-            ch.cursor = c2 + 1
-        elseif correlationId <= 8383 then
-            local c2 = ch.cursor
-            if c2 + 2 > ch.size then
-                alloc(ch, 2)
-            end
-            local adjusted = correlationId - 192
-            writeu8(ch.buff, c2, bor(0xC0, band(adjusted // 256, 0x1F)))
-            writeu8(ch.buff, c2 + 1, band(adjusted, 0xFF))
-            ch.cursor = c2 + 2
-        else
-            local c2 = ch.cursor
-            if c2 + 5 > ch.size then
-                alloc(ch, 5)
-            end
-            writeu8(ch.buff, c2, 0xF0)
-            buffer.writeu32(ch.buff, c2 + 1, correlationId)
-            ch.cursor = c2 + 5
-        end
+    local cursor = ch.cursor
+    if cursor + 1 > ch.size then
+        alloc(ch, 1)
+    end
+    writeu8(ch.buff, cursor, headerByte)
+    ch.cursor = cursor + 1
+
+    Varint.write(ch, correlationId)
+    if hasPayload then
+        (codec :: Types.InternalCodec<any>).write(ch, data)
     end
 end
 
--- Configuration -------------------------------------------------------
+-- Configuration ----------------------------------------------------------
 
 function Channel.setMaxSize(bytes: number): ()
     _maxSize = bytes
 end
 
 function Channel.updateTimestamp(): ()
-    _frameCounter = (_frameCounter + 1) % 256
-    _offsetMs = round((os.clock() % 65.536) * 1000)
+    _frameCounter = band(_frameCounter + 1, FRAME_MASK)
+    _offsetMs = round((os.clock() % OFFSET_WIN) * 1000)
     _clock = os.clock()
 end
 

package/src/internal/Middleware.luau

@@ -1,17 +1,47 @@
 --!strict
 --!optimize 2
--- Ordered intercept chains returning Connection objects.
+-- Ordered intercept chains for send/receive/drop hooks.
 
 local Signal = require(script.Parent.Parent.api.Signal)
 local Types = require(script.Parent.Parent.Types)
 
--- State ---------------------------------------------------------------
+-- State ------------------------------------------------------------------
 
 local _sendSignal = Signal.create()
 local _receiveSignal = Signal.create()
 local _dropSignal = Signal.create()
 
--- Public --------------------------------------------------------------
+-- Private ----------------------------------------------------------------
+
+--[[
+    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.
+]]
+local function runChain(signal: any, value: any, name: string, player: Player?): any
+    local count = signal._count[1]
+    if count == 0 then
+        return value
+    end
+
+    local entries = signal._entries
+    local snapshot = table.create(count)
+    table.move(entries, 1, count, 1, snapshot)
+
+    local result = value
+    for i = 1, count do
+        local entry = snapshot[i]
+        if entry._state ~= 0 then
+            local returned = entry.fn(result, name, player)
+            if returned ~= nil then
+                result = returned
+            end
+        end
+    end
+    return result
+end
+
+-- Public -----------------------------------------------------------------
 
 local Middleware = {}
 
@@ -31,52 +61,12 @@ function Middleware.onDrop(
     return _dropSignal:connect(fn)
 end
 
---[[
-    Runs send middleware chain. Returns transformed data, or DROP sentinel.
-    If no hooks, returns data unchanged (zero overhead).
-]]
 function Middleware.runSend(data: any, name: string, player: Player?): any
-    local count = _sendSignal._count[1]
-    if count == 0 then
-        return data
-    end
-
-    local entries = _sendSignal._entries
-    local result = data
-
-    for i = 1, count do
-        local entry = entries[i]
-        if entry._state ~= 0 then -- not disconnected
-            local returned = entry.fn(result, name, player)
-            if returned ~= nil then
-                result = returned
-            end
-        end
-    end
-
-    return result
+    return runChain(_sendSignal, data, name, player)
 end
 
 function Middleware.runReceive(data: any, name: string, player: Player?): any
-    local count = _receiveSignal._count[1]
-    if count == 0 then
-        return data
-    end
-
-    local entries = _receiveSignal._entries
-    local result = data
-
-    for i = 1, count do
-        local entry = entries[i]
-        if entry._state ~= 0 then
-            local returned = entry.fn(result, name, player)
-            if returned ~= nil then
-                result = returned
-            end
-        end
-    end
-
-    return result
+    return runChain(_receiveSignal, data, name, player)
 end
 
 function Middleware.fireDrop(player: Player, reason: string, name: string, data: any?): ()
@@ -84,11 +74,11 @@ function Middleware.fireDrop(player: Player, reason: string, name: string, data:
 end
 
 function Middleware.hasSendHooks(): boolean
-    return _sendSignal._count[1] > 0
+    return _sendSignal:hasListeners()
 end
 
 function Middleware.hasReceiveHooks(): boolean
-    return _receiveSignal._count[1] > 0
+    return _receiveSignal:hasListeners()
 end
 
 return table.freeze(Middleware)

package/src/internal/Pool.luau

@@ -1,33 +1,33 @@
 --!strict
 --!optimize 2
--- Stack-based ChannelState pool for per-player channel reuse.
+-- Stack-based ChannelState pool. Reset-on-acquire keeps released
+-- channels reusable without per-release reset cost.
 
 local Channel = require(script.Parent.Channel)
 local Types = require(script.Parent.Parent.Types)
 
--- Constants -----------------------------------------------------------
+-- Constants --------------------------------------------------------------
 
 local DEFAULT_SIZE = 16
 
--- State ---------------------------------------------------------------
+-- State ------------------------------------------------------------------
 
 local _stack: { Types.ChannelState } = {}
 local _depth = 0
 local _maxSize = DEFAULT_SIZE
 
--- Public --------------------------------------------------------------
+-- Public -----------------------------------------------------------------
 
 local Pool = {}
 
 function Pool.acquire(): Types.ChannelState
     if _depth > 0 then
         local ch = _stack[_depth]
-        _stack[_depth] = nil :: any
+        _stack[_depth] = nil
         _depth -= 1
         Channel.reset(ch)
         return ch
     end
-
     return Channel.create()
 end
 
@@ -35,17 +35,17 @@ function Pool.release(ch: Types.ChannelState): ()
     if _depth >= _maxSize then
         return
     end
-
     _depth += 1
     _stack[_depth] = ch
 end
 
 function Pool.setMaxSize(size: number): ()
+    if size < 0 then
+        error(`[Lync] Pool.setMaxSize: size must be >= 0, got {size}`)
+    end
     _maxSize = size
-
-    -- Trim excess
     while _depth > _maxSize do
-        _stack[_depth] = nil :: any
+        _stack[_depth] = nil
         _depth -= 1
     end
 end