@axpecter/lync 2.3.2 → 3.0.0

package/src/transport/Reader.luau

@@ -1,331 +0,0 @@
---!strict
---!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)
-local Varint = require(script.Parent.Parent.codec.primitive.Varint)
-
--- Constants --------------------------------------------------------------
-
-local KIND_PACKET = Registry.KIND_PACKET
-local KIND_REQUEST = Registry.KIND_REQUEST
-local KIND_RESPONSE = Registry.KIND_RESPONSE
-
-local TS_FRAME = Channel.TS_FRAME
-local TS_OFFSET = Channel.TS_OFFSET
-local TS_FULL = Channel.TS_FULL
-
-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,
-    statsEnabled: boolean,
-    player: Player?,
-    reason: string,
-    value: any
-): ()
-    if statsEnabled then
-        reg.drops += 1
-    end
-    if player then
-        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 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
-        return nil
-    end
-    local b = data :: buffer
-    if buffer.len(b) == 0 then
-        return nil
-    end
-    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
-
-    local statsEnabled = Channel.statsEnabled()
-    local hasRecvHooks = Middleware.hasReceiveHooks()
-    local pos = 0
-
-    while pos < incomingLen do
-        local frameStart = pos
-        local raw = readu8(incoming, pos)
-        pos += 1
-
-        local msb = band(raw, FRAME_MSB) ~= 0
-        local id = band(raw, FRAME_ID_MASK)
-
-        local reg = registryGet(id)
-        if not reg then
-            Log.warn(`unknown packet ID {id} at byte {pos - 1}`)
-            return false
-        end
-
-        local kind = reg.kind
-        if kind == KIND_PACKET then
-            local count: number
-            if msb then
-                count = 1
-            else
-                if pos + 2 > incomingLen then
-                    Log.warn("truncated multi-frame header")
-                    return false
-                end
-                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
-                if pos + 2 > incomingLen then
-                    Log.warn("truncated timestamp")
-                    return false
-                end
-                tsValue = readu16(incoming, pos)
-                pos += 2
-            elseif tsMode == TS_FULL then
-                if pos + 8 > incomingLen then
-                    Log.warn("truncated timestamp")
-                    return false
-                end
-                tsValue = readf64(incoming, pos)
-                pos += 8
-            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
-            -- Lync.nothing reads zero bytes; bypass the pos/consumed gates that assume forward progress.
-            local isZeroSize = sizeMeta == 0
-
-            for _ = 1, count do
-                if not isZeroSize and 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 not isZeroSize and consumed == 0 then
-                    Log.warn(`codec for "{regName}" reported 0 bytes; aborting`)
-                    return false
-                end
-                -- Fixed-size codecs MUST report consumed == _size or `pos` desyncs silently.
-                if sizeMeta and consumed ~= sizeMeta then
-                    Log.warn(
-                        `codec for "{regName}" consumed {consumed} bytes, expected {sizeMeta}; 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 false
-                end
-
-                if
-                    doGate
-                    and not gateValue(reg, regCodec, value, player :: Player, statsEnabled, true)
-                then
-                    continue
-                end
-
-                if hasRecvHooks then
-                    value = runReceive(value, regName, player)
-                end
-
-                if statsEnabled then
-                    reg.recvFires += 1
-                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 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
-                if statsEnabled then
-                    reg.recvFires += 1
-                    reg.bytesReceived += (pos - frameStart)
-                end
-                reg.signal:fire(nil, player, corrId)
-            else
-                local regCodec = reg.codec
-                -- Mirror the packet path: 0-byte response codecs (Lync.nothing) bypass the gates.
-                local qIsZeroSize = regCodec._size == 0
-                if not qIsZeroSize and pos >= incomingLen then
-                    Log.warn(`query "{reg.name}" body missing; aborting`)
-                    return false
-                end
-                local value, consumed = regCodec.read(incoming, pos, refs)
-                if not qIsZeroSize and consumed == 0 then
-                    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
-
-                --[[
-                    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 = runReceive(value, reg.name, player)
-                end
-
-                if statsEnabled then
-                    reg.recvFires += 1
-                    reg.bytesReceived += (pos - frameStart)
-                end
-                reg.signal:fire(value, player, corrId)
-            end
-        end
-    end
-    return true
-end
-
-Reader.setSilent = Log.setSilent
-Reader.reset = Log.reset
-
-return table.freeze(Reader)

package/src/transport/Server.luau

@@ -1,211 +0,0 @@
---!strict
---!optimize 2
--- Server transport: per-player channels, broadcast, flush.
-
-local Players = game:GetService("Players")
-local ReplicatedStorage = game:GetService("ReplicatedStorage")
-
-local Baseline = require(script.Parent.Parent.internal.Baseline)
-local Bridge = require(script.Parent.Parent.transport.Bridge)
-local Channel = require(script.Parent.Parent.internal.Channel)
-local Gate = require(script.Parent.Parent.transport.Gate)
-local Pool = require(script.Parent.Parent.internal.Pool)
-local Reader = require(script.Parent.Parent.transport.Reader)
-local Types = require(script.Parent.Parent.Types)
-
--- Constants --------------------------------------------------------------
-
-local CONTAINER_NAME = "LyncRemotes"
-
--- State ------------------------------------------------------------------
-
-local _reliableChannels: { [Player]: Types.ChannelState } = {}
-local _unreliableChannels: { [Player]: Types.ChannelState } = {}
-local _playerStats: { [Player]: Types.PlayerStats } = {}
-local _prevIncoming: { [Player]: buffer } = {}
-local _prevIncomingLen: { [Player]: number } = {}
-
--- 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
-): Types.ChannelState
-    local ch = map[player]
-    if not ch then
-        ch = Pool.acquire()
-        map[player] = ch
-    end
-    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 = sealAndDump(rCh)
-    local xored = xorApply(snapshot, byteLen, rCh.prevDump, rCh.prevDumpLen)
-    rCh.prevDump = snapshot
-    rCh.prevDumpLen = byteLen
-
-    Bridge.fireClient(player, xored, refs)
-    resetCh(rCh)
-    addStat(player, "bytesSent", byteLen)
-end
-
-local function flushUnreliable(player: Player): ()
-    local uCh = _unreliableChannels[player]
-    if not uCh or uCh.cursor == 0 then
-        return
-    end
-
-    local snapshot, refs, byteLen = sealAndDump(uCh)
-    Bridge.fireClientUnreliable(player, snapshot, refs)
-    resetCh(uCh)
-    addStat(player, "bytesSent", byteLen)
-end
-
-local function flushPlayer(player: Player): ()
-    flushReliable(player)
-    flushUnreliable(player)
-end
-
-local function handleIncomingReliable(player: Player, data: any, refs: any?): ()
-    local incoming = Reader.decodeIncoming(data)
-    if not incoming then
-        return
-    end
-
-    local incomingLen = buffer.len(incoming)
-    if not Gate.checkBandwidth(player, incomingLen) then
-        return
-    end
-
-    local prev = _prevIncoming[player]
-    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?): ()
-    local incoming = Reader.decodeIncoming(data)
-    if not incoming then
-        return
-    end
-
-    local incomingLen = buffer.len(incoming)
-    Reader.process(incoming, incomingLen, refs, player, true)
-    addStat(player, "bytesReceived", incomingLen)
-end
-
-local function clearPlayerState(player: Player): ()
-    local rCh = _reliableChannels[player]
-    if rCh then
-        _reliableChannels[player] = nil
-        Pool.release(rCh)
-    end
-    local uCh = _unreliableChannels[player]
-    if uCh then
-        _unreliableChannels[player] = nil
-        Pool.release(uCh)
-    end
-
-    _playerStats[player] = nil
-    _prevIncoming[player] = nil
-    _prevIncomingLen[player] = nil
-
-    Gate.clearPlayer(player)
-    Baseline.clearPlayer(player)
-end
-
--- Public -----------------------------------------------------------------
-
-local Server = {}
-
-function Server.getChannel(player: Player, isUnreliable: boolean): Types.ChannelState
-    return getOrCreateChannel(
-        if isUnreliable then _unreliableChannels else _reliableChannels,
-        player
-    )
-end
-
-function Server.flush(): ()
-    if Channel.hasTimestamps() then
-        Channel.updateTimestamp()
-    end
-    for _, player in Players:GetPlayers() do
-        flushPlayer(player)
-    end
-end
-
-Server.flushPlayer = flushPlayer
-
-function Server.start(): ()
-    local container = Instance.new("Folder")
-    container.Name = CONTAINER_NAME
-    container.Parent = ReplicatedStorage
-
-    Bridge.setup(container)
-
-    Bridge.reliable().OnServerEvent:Connect(handleIncomingReliable)
-    Bridge.unreliable().OnServerEvent:Connect(handleIncomingUnreliable)
-
-    Players.PlayerAdded:Connect(function(player: Player)
-        if statsEnabled() then
-            _playerStats[player] = { bytesSent = 0, bytesReceived = 0 }
-        end
-    end)
-    Players.PlayerRemoving:Connect(clearPlayerState)
-
-    -- 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.getPlayerStats(player: Player): Types.PlayerStats?
-    return _playerStats[player]
-end
-
-function Server.resetStats(): ()
-    for _, ps in _playerStats do
-        ps.bytesSent = 0
-        ps.bytesReceived = 0
-    end
-end
-
-return table.freeze(Server)

package/src/util/Array.luau

@@ -1,18 +0,0 @@
---!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

@@ -1,90 +0,0 @@
---!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, srcOff: number?): buffer
-    local out = bufCreate(len)
-    bufCopy(out, 0, src, srcOff or 0, len)
-    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)

package/src/util/Constants.luau

@@ -1,30 +0,0 @@
---!strict
---!optimize 2
--- Wire-format constants and integer limits shared across codecs.
-
--- Public -----------------------------------------------------------------
-
-local Constants = {}
-
-Constants.U8_MAX = 0xFF
-Constants.U16_MAX = 0xFFFF
-Constants.U32_MAX = 0xFFFFFFFF
-
-Constants.I8_MIN = -0x80
-Constants.I8_MAX = 0x7F
-Constants.I16_MIN = -0x8000
-Constants.I16_MAX = 0x7FFF
-Constants.I32_MIN = -0x80000000
-Constants.I32_MAX = 0x7FFFFFFF
-
---[[
-    Frame header byte: MSB = single-item (no count cell); cleared = multi-item
-    (u16 count follows). Low 7 bits = registration id (caps registry at 128).
-]]
-Constants.FRAME_MSB = 0x80
-Constants.FRAME_ID_MASK = 0x7F
-
--- u16 count cell.
-Constants.MAX_BATCH_ITEMS = 0xFFFF
-
-return table.freeze(Constants)