@axpecter/lync 2.2.1 → 2.3.1

package/src/transport/Reader.luau

@@ -1,10 +1,12 @@
 --!strict
---!optimize 2
--- Deserializes incoming buffers with MSB batch dispatch.
+--!native
+-- Inbound buffer parser. Returns false on malformed wire so the transport can drop its XOR baseline.
 
 local Baseline = require(script.Parent.Parent.internal.Baseline)
 local Channel = require(script.Parent.Parent.internal.Channel)
+local Constants = require(script.Parent.Parent.util.Constants)
 local Gate = require(script.Parent.Parent.transport.Gate)
+local Log = require(script.Parent.Parent.util.Log)
 local Middleware = require(script.Parent.Parent.internal.Middleware)
 local Registry = require(script.Parent.Parent.internal.Registry)
 local Types = require(script.Parent.Parent.Types)
@@ -20,12 +22,22 @@ local TS_FRAME = Channel.TS_FRAME
 local TS_OFFSET = Channel.TS_OFFSET
 local TS_FULL = Channel.TS_FULL
 
-local MAX_ITEMS_PER_FRAME = 0xFFFF
+local FRAME_MSB = Constants.FRAME_MSB
+local FRAME_ID_MASK = Constants.FRAME_ID_MASK
 
 -- Private ----------------------------------------------------------------
 
 local band = bit32.band
 local readu8 = buffer.readu8
+local readu16 = buffer.readu16
+local readf64 = buffer.readf64
+local registryGet = Registry.get
+local checkGlobal = Gate.checkGlobalRateLimit
+local checkRate = Gate.checkRateLimit
+local validateGate = Gate.validate
+local fireDrop = Middleware.fireDrop
+local runReceive = Middleware.runReceive
+local varintRead = Varint.read
 
 local function recordDrop(
     reg: Types.Registration,
@@ -38,25 +50,60 @@ local function recordDrop(
         reg.drops += 1
     end
     if player then
-        Middleware.fireDrop(player, reason, reg.name, value)
+        fireDrop(player, reason, reg.name, value)
     end
 end
 
+--[[
+    Server gate pipeline. Returns true to deliver, false on rate-limit,
+    schema-validate, or custom-validate rejection. `runGlobal` lets the
+    response path skip the global per-player limit.
+]]
+local function gateValue(
+    reg: Types.Registration,
+    regCodec: Types.InternalCodec<any>,
+    value: any,
+    player: Player,
+    statsEnabled: boolean,
+    runGlobal: boolean
+): boolean
+    -- Both global and per-packet drops use the "rate" reason; collapsed into one branch.
+    if (runGlobal and not checkGlobal(player)) or not checkRate(reg, player) then
+        recordDrop(reg, statsEnabled, player, "rate", value)
+        return false
+    end
+
+    local validateReason = validateGate(value, regCodec)
+    if validateReason then
+        recordDrop(reg, statsEnabled, player, `validation: {validateReason}`, value)
+        return false
+    end
+
+    if reg.validate then
+        local valid, validReason = reg.validate(value, player)
+        if not valid then
+            recordDrop(
+                reg,
+                statsEnabled,
+                player,
+                if validReason then `validate: {validReason}` else "validate",
+                value
+            )
+            return false
+        end
+    end
+    return true
+end
+
 -- Public -----------------------------------------------------------------
 
 local Reader = {}
 
 --[[
-    Sanity-check an inbound RemoteEvent payload. The size cap MUST NOT be
-    tied to the local `Channel.maxSize()` — sender and receiver run in
-    separate Lua VMs with independent module state, so the receiver may
-    not have called Lync.configure with the same channelMaxSize. Coupling
-    them caused server frames larger than the receiver's local default to
-    be silently dropped, which permanently desynced the XOR baseline.
-
-    Roblox enforces a per-RemoteEvent payload ceiling around 1MB; if the
-    payload reached us at all, it's already within Roblox's limit. Trust
-    that and accept anything non-empty.
+    Sanity-check an inbound payload. Size cap is delegated to Roblox's ~1MB
+    RemoteEvent ceiling: the receiver may not have called Lync.configure
+    with the same channelMaxSize as the sender (independent VMs, independent
+    module state), so a local cap here would reject legitimate frames.
 ]]
 function Reader.decodeIncoming(data: any): buffer?
     if typeof(data) ~= "buffer" then
@@ -69,13 +116,19 @@ function Reader.decodeIncoming(data: any): buffer?
     return b
 end
 
+--[[
+    Returns true on full success, false if a malformed frame aborted the
+    parse. Transport callers use this to decide whether to keep the per-peer
+    XOR baseline: false means the buffer is suspect and would permanently
+    desync the channel if reused as the next XOR mask.
+]]
 function Reader.process(
     incoming: buffer,
     incomingLen: number,
     refs: { Instance }?,
     player: Player?,
     isServer: boolean
-): ()
+): boolean
     if Baseline.hasDelta() then
         Baseline.setReadKey(player or false)
     end
@@ -89,115 +142,121 @@ function Reader.process(
         local raw = readu8(incoming, pos)
         pos += 1
 
-        local msb = band(raw, 0x80) ~= 0
-        local id = band(raw, 0x7F)
+        local msb = band(raw, FRAME_MSB) ~= 0
+        local id = band(raw, FRAME_ID_MASK)
 
-        local reg = Registry.get(id)
+        local reg = registryGet(id)
         if not reg then
-            warn(`[Lync] Reader.process: unknown packet ID {id} at byte {pos - 1}`)
-            return
+            Log.warn(`unknown packet ID {id} at byte {pos - 1}`)
+            return false
         end
 
-        if reg.kind == KIND_PACKET then
+        local kind = reg.kind
+        if kind == KIND_PACKET then
             local count: number
             if msb then
                 count = 1
             else
                 if pos + 2 > incomingLen then
-                    warn("[Lync] Reader.process: truncated multi-frame header")
-                    return
+                    Log.warn("truncated multi-frame header")
+                    return false
                 end
-                count = buffer.readu16(incoming, pos)
+                count = readu16(incoming, pos)
                 pos += 2
             end
 
             local tsMode = reg.timestampMode
             local tsValue: number? = nil
             if tsMode == TS_FRAME then
+                if pos + 1 > incomingLen then
+                    Log.warn("truncated timestamp")
+                    return false
+                end
                 tsValue = readu8(incoming, pos)
                 pos += 1
             elseif tsMode == TS_OFFSET then
-                tsValue = buffer.readu16(incoming, pos)
+                if pos + 2 > incomingLen then
+                    Log.warn("truncated timestamp")
+                    return false
+                end
+                tsValue = readu16(incoming, pos)
                 pos += 2
             elseif tsMode == TS_FULL then
-                tsValue = buffer.readf64(incoming, pos)
+                if pos + 8 > incomingLen then
+                    Log.warn("truncated timestamp")
+                    return false
+                end
+                tsValue = readf64(incoming, pos)
                 pos += 8
             end
 
-            if count > MAX_ITEMS_PER_FRAME then
-                count = MAX_ITEMS_PER_FRAME
-            end
-            local sizeMeta = reg.codec._size
-            if sizeMeta then
-                local maxBySize = (incomingLen - pos) // sizeMeta
-                if count > maxBySize then
-                    count = maxBySize
-                end
+            --[[
+                Fixed-size codec: a count exceeding remaining bytes is
+                unambiguously corrupt. Abort to keep the cursor on a frame
+                boundary so the transport can reset cleanly.
+            ]]
+            local regCodec = reg.codec
+            local sizeMeta = regCodec._size
+            if sizeMeta and count * sizeMeta > incomingLen - pos then
+                Log.warn(`"{reg.name}" count {count} exceeds remaining bytes; aborting`)
+                return false
             end
 
             local maxPayload = reg.maxPayloadBytes
             local payloadStart = pos
+            local doGate = isServer and reg.needsGate and player ~= nil
+            local regSignal = reg.signal
+            local regName = reg.name
 
             for _ = 1, count do
-                local value, consumed = reg.codec.read(incoming, pos, refs)
+                if pos >= incomingLen then
+                    Log.warn(`codec for "{regName}" ran past frame end; aborting`)
+                    return false
+                end
+                local value, consumed = regCodec.read(incoming, pos, refs)
                 if consumed == 0 then
-                    warn(
-                        `[Lync] Reader.process: codec for "{reg.name}" reported 0 bytes; aborting frame`
-                    )
-                    return
+                    Log.warn(`codec for "{regName}" reported 0 bytes; aborting`)
+                    return false
                 end
                 pos += consumed
+                if pos > incomingLen then
+                    Log.warn(`codec for "{regName}" overran frame end; aborting`)
+                    return false
+                end
 
                 if maxPayload and (pos - payloadStart) > maxPayload then
                     recordDrop(reg, statsEnabled, player, "maxPayloadBytes", value)
-                    return
+                    return false
                 end
 
-                if isServer and reg.needsGate then
-                    if player and not Gate.checkGlobalRateLimit(player) then
-                        recordDrop(reg, statsEnabled, player, "rate", value)
-                        continue
-                    end
-                    if player and not Gate.checkRateLimit(reg, player) then
-                        recordDrop(reg, statsEnabled, player, "rate", value)
-                        continue
-                    end
-
-                    local ok = Gate.validate(value, reg.codec)
-                    if not ok then
-                        recordDrop(reg, statsEnabled, player, "validation", value)
-                        continue
-                    end
-
-                    if reg.validate and player then
-                        local valid, validReason = reg.validate(value, player)
-                        if not valid then
-                            recordDrop(reg, statsEnabled, player, validReason or "validate", value)
-                            continue
-                        end
-                    end
+                if
+                    doGate
+                    and not gateValue(reg, regCodec, value, player :: Player, statsEnabled, true)
+                then
+                    continue
                 end
 
                 if hasRecvHooks then
-                    value = Middleware.runReceive(value, reg.name, player)
+                    value = runReceive(value, regName, player)
                 end
 
                 if statsEnabled then
                     reg.recvFires += 1
                 end
 
-                if tsValue ~= nil then
-                    reg.signal:fire(value, player, tsValue)
-                else
-                    reg.signal:fire(value, player)
-                end
+                -- tsValue is nil when mode == TS_NONE; pass through to skip a per-item branch.
+                regSignal:fire(value, player, tsValue)
             end
 
             if statsEnabled then
                 reg.bytesReceived += (pos - frameStart)
             end
-        elseif reg.kind == KIND_REQUEST or reg.kind == KIND_RESPONSE then
-            local corrId, corrBytes = Varint.read(incoming, pos)
+        elseif kind == KIND_REQUEST or kind == KIND_RESPONSE then
+            local corrId, corrBytes = varintRead(incoming, pos)
+            if corrBytes == 0 then
+                Log.warn(`truncated correlation id for "{reg.name}"; aborting`)
+                return false
+            end
             pos += corrBytes
 
             if msb then
@@ -207,47 +266,41 @@ function Reader.process(
                 end
                 reg.signal:fire(nil, player, corrId)
             else
-                local value, consumed = reg.codec.read(incoming, pos, refs)
+                if pos >= incomingLen then
+                    Log.warn(`query "{reg.name}" body missing; aborting`)
+                    return false
+                end
+                local regCodec = reg.codec
+                local value, consumed = regCodec.read(incoming, pos, refs)
                 if consumed == 0 then
-                    warn(
-                        `[Lync] Reader.process: query codec for "{reg.name}" reported 0 bytes; aborting frame`
-                    )
-                    return
+                    Log.warn(`query codec for "{reg.name}" reported 0 bytes; aborting`)
+                    return false
                 end
                 pos += consumed
+                if pos > incomingLen then
+                    Log.warn(`query "{reg.name}" overran frame end; aborting`)
+                    return false
+                end
 
-                if isServer and reg.needsGate and reg.kind == KIND_REQUEST then
-                    if player and not Gate.checkRateLimit(reg, player) then
-                        recordDrop(reg, statsEnabled, player, "rate", value)
-                        if statsEnabled then
-                            reg.bytesReceived += (pos - frameStart)
-                        end
-                        continue
-                    end
-
-                    local ok = Gate.validate(value, reg.codec)
-                    if not ok then
-                        recordDrop(reg, statsEnabled, player, "validation", value)
-                        if statsEnabled then
-                            reg.bytesReceived += (pos - frameStart)
-                        end
-                        continue
-                    end
-
-                    if reg.validate and player then
-                        local valid, validReason = reg.validate(value, player)
-                        if not valid then
-                            recordDrop(reg, statsEnabled, player, validReason or "validate", value)
-                            if statsEnabled then
-                                reg.bytesReceived += (pos - frameStart)
-                            end
-                            continue
-                        end
+                --[[
+                    Server gates REQUEST and RESPONSE frames opted into
+                    needsGate so a malicious client can't bypass via the
+                    response channel.
+                ]]
+                if
+                    isServer
+                    and reg.needsGate
+                    and player
+                    and not gateValue(reg, regCodec, value, player, statsEnabled, false)
+                then
+                    if statsEnabled then
+                        reg.bytesReceived += (pos - frameStart)
                     end
+                    continue
                 end
 
                 if hasRecvHooks then
-                    value = Middleware.runReceive(value, reg.name, player)
+                    value = runReceive(value, reg.name, player)
                 end
 
                 if statsEnabled then
@@ -258,6 +311,10 @@ function Reader.process(
             end
         end
     end
+    return true
 end
 
+Reader.setSilent = Log.setSilent
+Reader.reset = Log.reset
+
 return table.freeze(Reader)

package/src/transport/Server.luau

@@ -1,7 +1,6 @@
 --!strict
 --!optimize 2
--- Server-side transport: per-player channels, broadcast, flush.
--- Decodes inbound XOR delta against a per-player baseline.
+-- Server transport: per-player channels, broadcast, flush.
 
 local Players = game:GetService("Players")
 local ReplicatedStorage = game:GetService("ReplicatedStorage")
@@ -26,10 +25,15 @@ local _playerStats: { [Player]: Types.PlayerStats } = {}
 local _prevIncoming: { [Player]: buffer } = {}
 local _prevIncomingLen: { [Player]: number } = {}
 
-local _statsEnabled = false
-
 -- Private ----------------------------------------------------------------
 
+local statsEnabled = Channel.statsEnabled
+local xorApply = Channel.xorApply
+local sealAndDump = Channel.sealAndDump
+local resetCh = Channel.reset
+
+type StatsField = "bytesSent" | "bytesReceived"
+
 local function getOrCreateChannel(
     map: { [Player]: Types.ChannelState },
     player: Player
@@ -42,26 +46,30 @@ local function getOrCreateChannel(
     return ch
 end
 
+-- Skip the table read when stats are off; the hot path needs no branch.
+local function addStat(player: Player, field: StatsField, byteLen: number): ()
+    if statsEnabled() then
+        local ps = _playerStats[player]
+        if ps then
+            ps[field] += byteLen
+        end
+    end
+end
+
 local function flushReliable(player: Player): ()
     local rCh = _reliableChannels[player]
     if not rCh or rCh.cursor == 0 then
         return
     end
 
-    local snapshot, refs, byteLen = Channel.sealAndDump(rCh)
-    local xored = Channel.xorApply(snapshot, byteLen, rCh.prevDump, rCh.prevDumpLen)
+    local snapshot, refs, byteLen = sealAndDump(rCh)
+    local xored = xorApply(snapshot, byteLen, rCh.prevDump, rCh.prevDumpLen)
     rCh.prevDump = snapshot
     rCh.prevDumpLen = byteLen
 
     Bridge.fireClient(player, xored, refs)
-    Channel.reset(rCh)
-
-    if _statsEnabled then
-        local ps = _playerStats[player]
-        if ps then
-            ps.bytesSent += byteLen
-        end
-    end
+    resetCh(rCh)
+    addStat(player, "bytesSent", byteLen)
 end
 
 local function flushUnreliable(player: Player): ()
@@ -70,16 +78,10 @@ local function flushUnreliable(player: Player): ()
         return
     end
 
-    local snapshot, refs, byteLen = Channel.sealAndDump(uCh)
+    local snapshot, refs, byteLen = sealAndDump(uCh)
     Bridge.fireClientUnreliable(player, snapshot, refs)
-    Channel.reset(uCh)
-
-    if _statsEnabled then
-        local ps = _playerStats[player]
-        if ps then
-            ps.bytesSent += byteLen
-        end
-    end
+    resetCh(uCh)
+    addStat(player, "bytesSent", byteLen)
 end
 
 local function flushPlayer(player: Player): ()
@@ -99,23 +101,22 @@ local function handleIncomingReliable(player: Player, data: any, refs: any?): ()
     end
 
     local prev = _prevIncoming[player]
-    local decoded = if prev
-        then Channel.xorApply(incoming, incomingLen, prev, _prevIncomingLen[player])
-        else incoming
-    _prevIncoming[player] = decoded
-    _prevIncomingLen[player] = incomingLen
-
-    local ok, err = pcall(Reader.process, decoded, incomingLen, refs, player, true)
-    if not ok then
-        warn(`[Lync] Server.receive: {player.Name}: {err}`)
-    end
-
-    if _statsEnabled then
-        local ps = _playerStats[player]
-        if ps then
-            ps.bytesReceived += incomingLen
-        end
-    end
+    local decoded = xorApply(incoming, incomingLen, prev, _prevIncomingLen[player])
+
+    --[[
+        Only adopt `decoded` as the next XOR baseline on success. A failed
+        parse means the wire is suspect; reusing it would poison every
+        subsequent packet.
+    ]]
+    if Reader.process(decoded, incomingLen, refs, player, true) then
+        _prevIncoming[player] = decoded
+        _prevIncomingLen[player] = incomingLen
+    else
+        _prevIncoming[player] = nil
+        _prevIncomingLen[player] = nil
+    end
+
+    addStat(player, "bytesReceived", incomingLen)
 end
 
 local function handleIncomingUnreliable(player: Player, data: any, refs: any?): ()
@@ -125,17 +126,8 @@ local function handleIncomingUnreliable(player: Player, data: any, refs: any?):
     end
 
     local incomingLen = buffer.len(incoming)
-    local ok, err = pcall(Reader.process, incoming, incomingLen, refs, player, true)
-    if not ok then
-        warn(`[Lync] Server.receiveUnreliable: {player.Name}: {err}`)
-    end
-
-    if _statsEnabled then
-        local ps = _playerStats[player]
-        if ps then
-            ps.bytesReceived += incomingLen
-        end
-    end
+    Reader.process(incoming, incomingLen, refs, player, true)
+    addStat(player, "bytesReceived", incomingLen)
 end
 
 local function clearPlayerState(player: Player): ()
@@ -191,23 +183,20 @@ function Server.start(): ()
     Bridge.unreliable().OnServerEvent:Connect(handleIncomingUnreliable)
 
     Players.PlayerAdded:Connect(function(player: Player)
-        if _statsEnabled then
+        if statsEnabled() then
             _playerStats[player] = { bytesSent = 0, bytesReceived = 0 }
         end
     end)
     Players.PlayerRemoving:Connect(clearPlayerState)
 
-    if _statsEnabled then
+    -- Catch players who joined before Lync.start.
+    if statsEnabled() then
         for _, player in Players:GetPlayers() do
             _playerStats[player] = { bytesSent = 0, bytesReceived = 0 }
         end
     end
 end
 
-function Server.enableStats(): ()
-    _statsEnabled = true
-end
-
 function Server.getPlayerStats(player: Player): Types.PlayerStats?
     return _playerStats[player]
 end

package/src/util/Array.luau

@@ -0,0 +1,18 @@
+--!strict
+--!optimize 2
+-- O(1) array swap-remove. Breaks insertion order.
+
+-- Public -----------------------------------------------------------------
+
+local Array = {}
+
+-- Reorders. Caller-tracked counts must decrement separately.
+function Array.swapRemove<T>(arr: { T }, idx: number): ()
+    local last = #arr
+    if idx ~= last then
+        arr[idx] = arr[last]
+    end
+    arr[last] = nil
+end
+
+return table.freeze(Array)

package/src/util/Buffer.luau

@@ -0,0 +1,92 @@
+--!strict
+--!native
+-- Word-aligned XOR and equality helpers for Channel and composite deltas.
+
+-- Private ----------------------------------------------------------------
+
+local band = bit32.band
+local bxor = bit32.bxor
+local readu8 = buffer.readu8
+local readu32 = buffer.readu32
+local writeu8 = buffer.writeu8
+local writeu32 = buffer.writeu32
+local bufCopy = buffer.copy
+local bufCreate = buffer.create
+local minN = math.min
+
+-- Public -----------------------------------------------------------------
+
+local Buf = {}
+
+-- 8-byte unrolled compare; 4-byte step then byte tail for remainder.
+function Buf.rangeEqual(a: buffer, offA: number, b: buffer, offB: number, len: number): boolean
+    local aligned8 = band(len, -8)
+    local i = 0
+    while i < aligned8 do
+        if
+            readu32(a, offA + i) ~= readu32(b, offB + i)
+            or readu32(a, offA + i + 4) ~= readu32(b, offB + i + 4)
+        then
+            return false
+        end
+        i += 8
+    end
+    if i + 4 <= len then
+        if readu32(a, offA + i) ~= readu32(b, offB + i) then
+            return false
+        end
+        i += 4
+    end
+    while i < len do
+        if readu8(a, offA + i) ~= readu8(b, offB + i) then
+            return false
+        end
+        i += 1
+    end
+    return true
+end
+
+function Buf.snapshot(src: buffer, len: number): buffer
+    local out = bufCreate(len)
+    if len > 0 then
+        bufCopy(out, 0, src, 0, len)
+    end
+    return out
+end
+
+--[[
+    XOR `current` against `previous` into a fresh curLen buffer. Returns
+    `current` unchanged when previous is nil so first-frame callers don't
+    branch. Overlap is 8-byte unrolled; tail is bulk-copied.
+]]
+function Buf.xorApply(current: buffer, curLen: number, previous: buffer?, prevLen: number?): buffer
+    if not previous then
+        return current
+    end
+    local pLen = prevLen or 0
+
+    local result = bufCreate(curLen)
+    local overlap = minN(curLen, pLen)
+
+    local aligned8 = band(overlap, -8)
+    local i = 0
+    while i < aligned8 do
+        writeu32(result, i, bxor(readu32(current, i), readu32(previous, i)))
+        writeu32(result, i + 4, bxor(readu32(current, i + 4), readu32(previous, i + 4)))
+        i += 8
+    end
+    if i + 4 <= overlap then
+        writeu32(result, i, bxor(readu32(current, i), readu32(previous, i)))
+        i += 4
+    end
+    while i < overlap do
+        writeu8(result, i, bxor(readu8(current, i), readu8(previous, i)))
+        i += 1
+    end
+    if curLen > overlap then
+        bufCopy(result, overlap, current, overlap, curLen - overlap)
+    end
+    return result
+end
+
+return table.freeze(Buf)