@axpecter/lync 1.3.0

package/src/transport/Client.luau

@@ -0,0 +1,151 @@
+--!strict
+--!optimize 2
+-- Client-side transport with batching, frame XOR on reliable.
+
+local RunService = game:GetService ("RunService")
+
+local Bridge = require (script.Parent.Bridge)
+local Channel = require (script.Parent.Parent.internal.Channel)
+local Middleware = require (script.Parent.Parent.internal.Middleware)
+local Reader = require (script.Parent.Reader)
+local Types = require (script.Parent.Parent.Types)
+
+type ChannelState = Types.ChannelState
+type Codec<T> = Types.Codec<T>
+
+-- State ------------------------------------------------------------------
+
+local NOT_STARTED = "[Lync] Client not started. Call Lync.start() before sending"
+local _reliable = nil :: ChannelState?
+local _unreliable = nil :: ChannelState?
+local _prevRecv = nil :: buffer?
+local _isStarted = false
+
+-- Private ----------------------------------------------------------------
+
+local function receive (data: any, refs: any, applyXor: boolean): ()
+    local buf = Reader.decodeIncoming (data)
+    if not buf then
+        return
+    end
+
+    local raw: buffer
+    if applyXor then
+        raw = Channel.xorApply (buf, _prevRecv)
+        _prevRecv = raw
+    else
+        raw = buf
+    end
+
+    local safeRefs: { Instance }? = if typeof (refs) == "table" then refs else nil
+    local ok, err = pcall (Reader.process, raw, safeRefs, nil, 0)
+    if not ok then
+        warn (`[Lync] Read failed: {err}`)
+    end
+end
+
+local function flushChannel (remote: any, ch: ChannelState, applyXor: boolean): ()
+    if ch.cursor == 0 then
+        return
+    end
+
+    local raw, refs = Channel.sealAndDump (ch)
+
+    if applyXor then
+        local xored = Channel.xorApply (raw, ch.prevDump)
+        ch.prevDump = raw
+        remote:FireServer (xored, refs)
+    else
+        remote:FireServer (raw, refs)
+    end
+
+    Channel.reset (ch)
+end
+
+local function flush (): ()
+    flushChannel (Bridge.reliable, _reliable :: ChannelState, true)
+    flushChannel (Bridge.unreliable, _unreliable :: ChannelState, false)
+end
+
+-- Public -----------------------------------------------------------------
+
+local Client = {}
+
+function Client.start (): ()
+    if _isStarted then
+        return
+    end
+    _isStarted = true
+
+    Bridge.setup ()
+
+    _reliable = Channel.create ()
+    _unreliable = Channel.create ()
+
+    Bridge.reliable.OnClientEvent:Connect (function (data: any, refs: any): ()
+        receive (data, refs, true)
+    end)
+    Bridge.unreliable.OnClientEvent:Connect (function (data: any, refs: any): ()
+        receive (data, refs, false)
+    end)
+    RunService.Heartbeat:Connect (flush)
+end
+
+function Client.write (
+    id: number,
+    name: string,
+    codec: Codec<any>,
+    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)
+        if final == nil then
+            return
+        end
+    else
+        final = data
+    end
+
+    local ch = if isUnreliable then _unreliable :: ChannelState else _reliable :: ChannelState
+    Channel.writeBatch (ch, id, name, codec, final)
+end
+
+-- Shared for both query requests and responses (identical wire format).
+function Client.writeQuery (
+    id: number,
+    name: string,
+    correlationId: number,
+    codec: Codec<any>,
+    data: any
+): ()
+    if not _isStarted then
+        error (NOT_STARTED)
+    end
+
+    local final: any
+    if Middleware.hasSend then
+        final = Middleware.runSend (data, name, nil)
+        if final == nil then
+            return
+        end
+    else
+        final = data
+    end
+
+    Channel.writeQuery (_reliable :: ChannelState, id, name, correlationId, codec, final)
+end
+
+function Client.writeQueryNil (id: number, name: string, correlationId: number): ()
+    if not _isStarted then
+        error (NOT_STARTED)
+    end
+    Channel.writeQuery (_reliable :: ChannelState, id, name, correlationId, nil, nil)
+end
+
+return table.freeze (Client)

package/src/transport/Gate.luau

@@ -0,0 +1,222 @@
+--!strict
+--!optimize 2
+-- Post-deserialization security: NaN/inf, rate limiting, custom validate.
+
+local Types = require (script.Parent.Parent.Types)
+
+type Registration = Types.Registration
+type RateLimitConfig = Types.RateLimitConfig
+
+-- Constants --------------------------------------------------------------
+
+local DEFAULT_MAX_DEPTH = 16
+
+local isfinite = math.isfinite
+local min = math.min
+local clock = os.clock
+
+-- State ------------------------------------------------------------------
+
+type Bucket = {
+    tokens: number,
+    lastRef: number,
+}
+
+local _maxDepth = DEFAULT_MAX_DEPTH
+local _buckets = {} :: { [Player]: { [number]: Bucket } }
+local _dropHandlers =
+    {} :: { (player: Player, reason: string, packetName: string, data: any?) -> () }
+
+-- Private ----------------------------------------------------------------
+
+local function fireDrop (player: Player, reason: string, packetName: string, data: any?): ()
+    for _, handler in _dropHandlers do
+        handler (player, reason, packetName, data)
+    end
+end
+
+@native
+local function isClean (value: any, depth: number): boolean
+    if depth > _maxDepth then
+        return false
+    end
+
+    local t = type (value)
+
+    if t == "number" then
+        return isfinite (value)
+    end
+
+    -- String, boolean, nil are always clean . Exit before table/vector/userdata checks
+    if t == "string" or t == "boolean" or t == "nil" then
+        return true
+    end
+
+    if t == "table" then
+        local deeper = depth + 1
+        for k, v in value do
+            if not isClean (k, deeper) or not isClean (v, deeper) then
+                return false
+            end
+        end
+        return true
+    end
+
+    if t == "vector" then
+        return isfinite (value.X) and isfinite (value.Y) and isfinite (value.Z)
+    end
+
+    if t == "userdata" then
+        local ut = typeof (value)
+
+        if ut == "Vector2" then
+            return isfinite (value.X) and isfinite (value.Y)
+        elseif ut == "Color3" then
+            return isfinite (value.R) and isfinite (value.G) and isfinite (value.B)
+        elseif ut == "CFrame" then
+            local position = value.Position
+            if
+                not isfinite (position.X)
+                or not isfinite (position.Y)
+                or not isfinite (position.Z)
+            then
+                return false
+            end
+            local axis, angle = value:ToAxisAngle ()
+            return isfinite (angle)
+                and isfinite (axis.X)
+                and isfinite (axis.Y)
+                and isfinite (axis.Z)
+        elseif ut == "UDim" then
+            return isfinite (value.Scale)
+        elseif ut == "UDim2" then
+            return isfinite (value.X.Scale) and isfinite (value.Y.Scale)
+        elseif ut == "NumberRange" then
+            return isfinite (value.Min) and isfinite (value.Max)
+        elseif ut == "Rect" then
+            return isfinite (value.Min.X)
+                and isfinite (value.Min.Y)
+                and isfinite (value.Max.X)
+                and isfinite (value.Max.Y)
+        elseif ut == "Ray" then
+            local origin = value.Origin
+            local direction = value.Direction
+            return isfinite (origin.X)
+                and isfinite (origin.Y)
+                and isfinite (origin.Z)
+                and isfinite (direction.X)
+                and isfinite (direction.Y)
+                and isfinite (direction.Z)
+        elseif ut == "Region3" then
+            local position = value.CFrame.Position
+            return isfinite (position.X) and isfinite (position.Y) and isfinite (position.Z)
+        end
+    end
+
+    return true
+end
+
+local function checkRate (player: Player, reg: Registration): boolean
+    local cfg = reg.rateLimit
+    if not cfg then
+        return true
+    end
+
+    local playerBuckets = _buckets[player]
+    if not playerBuckets then
+        return true
+    end
+
+    local id = reg.id
+    local now = clock ()
+    local cap = cfg.burstAllowance or cfg.maxPerSecond
+    local bucket = playerBuckets[id]
+
+    if not bucket then
+        playerBuckets[id] = {
+            tokens = cap - 1,
+            lastRef = now,
+        }
+        return true
+    end
+
+    local elapsed = now - bucket.lastRef
+    bucket.tokens = min (cap, bucket.tokens + elapsed * cfg.maxPerSecond)
+    bucket.lastRef = now
+
+    if bucket.tokens >= 1 then
+        bucket.tokens -= 1
+        return true
+    end
+
+    return false
+end
+
+-- Public -----------------------------------------------------------------
+
+local Gate = {}
+
+-- Override the max recursion depth for NaN/inf scanning. Default 16. Range: 4–32.
+function Gate.setMaxDepth (depth: number): ()
+    if depth < 4 or depth > 32 then
+        error (`[Lync] Gate max depth must be 4–32, got {depth}`)
+    end
+    _maxDepth = depth
+end
+
+function Gate.getMaxDepth (): number
+    return _maxDepth
+end
+
+function Gate.check (value: any, reg: Registration, player: Player): boolean
+    if not checkRate (player, reg) then
+        fireDrop (player, "rate", reg.name, nil)
+        return false
+    end
+
+    if not isClean (value, 1) then
+        fireDrop (player, "nan", reg.name, value)
+        return false
+    end
+
+    local validate = reg.validate
+    if validate then
+        local ok, reason = validate (value, player)
+        if not ok then
+            fireDrop (player, reason or "validate", reg.name, value)
+            return false
+        end
+    end
+
+    return true
+end
+
+function Gate.onDrop (
+    callback: (player: Player, reason: string, packetName: string, data: any?) -> ()
+): () -> ()
+    table.insert (_dropHandlers, callback)
+
+    return function (): ()
+        local idx = table.find (_dropHandlers, callback)
+        if idx then
+            table.remove (_dropHandlers, idx)
+        end
+    end
+end
+
+-- Fires drop handlers without validation. Used by Reader for byte-budget violations.
+function Gate.reportDrop (player: Player?, reason: string, packetName: string, data: any?): ()
+    if player and #_dropHandlers > 0 then
+        fireDrop (player, reason, packetName, data)
+    end
+end
+
+function Gate.onPlayerAdded (player: Player): ()
+    _buckets[player] = {}
+end
+
+function Gate.onPlayerRemoved (player: Player): ()
+    _buckets[player] = nil
+end
+
+return table.freeze (Gate)

package/src/transport/Reader.luau

@@ -0,0 +1,175 @@
+--!strict
+--!optimize 2
+-- Deserializes incoming buffers and routes by registration kind.
+
+local Baseline = require (script.Parent.Parent.internal.Baseline)
+local Gate = require (script.Parent.Gate)
+local Middleware = require (script.Parent.Parent.internal.Middleware)
+local Registry = require (script.Parent.Parent.internal.Registry)
+
+local registryGet = Registry.get
+local gateCheck = Gate.check
+local gateReportDrop = Gate.reportDrop
+
+-- Constants --------------------------------------------------------------
+
+local KIND_PACKET = Registry.KIND_PACKET
+local KIND_REQUEST = Registry.KIND_REQUEST
+
+local MAX_INCOMING = 65536
+
+-- Public -----------------------------------------------------------------
+
+local Reader = {}
+
+-- Shared incoming-data validation used by both Client and Server receive.
+function Reader.decodeIncoming (data: any): buffer?
+    if typeof (data) ~= "buffer" then
+        return nil
+    end
+    if buffer.len (data) > MAX_INCOMING then
+        return nil
+    end
+    return data
+end
+
+-- Callers wrap this in pcall. Any throw aborts the entire buffer from this source.
+function Reader.process (
+    incoming: buffer,
+    refs: { Instance }?,
+    player: Player?,
+    startOffset: number
+): ()
+    local length = buffer.len (incoming)
+    local pos = startOffset
+
+    if Baseline.hasDelta then
+        Baseline.setReadKey (player or false)
+    end
+
+    -- Cache flags once per frame-buffer, not per packet
+    local hasReceiveMiddleware = Middleware.hasReceive
+    local isServer = player ~= nil
+
+    while pos < length do
+        local id = buffer.readu8 (incoming, pos)
+        pos += 1
+
+        local reg = registryGet (id)
+        if not reg then
+            warn (`[Lync] Unknown packet ID {id}`)
+            break
+        end
+
+        local kind = reg.kind
+
+        if kind == KIND_PACKET then
+            if pos + 2 > length then
+                break
+            end
+
+            local count = buffer.readu16 (incoming, pos)
+            pos += 2
+
+            if count == 0 then
+                continue
+            end
+
+            local codec = reg.codec
+            local signal = reg.signal
+            local batchStart = pos
+            local maxBytes = reg.maxPayloadBytes
+
+            -- 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
+                    end
+
+                    local value, consumed = codec.read (incoming, pos, refs)
+                    pos += consumed
+                    signal:fire (value, player)
+                end
+            else
+                -- Cold path: gate and/or middleware and/or byte budget active
+                local baseName = reg.baseName
+                local needsGate = isServer and reg.needsGate
+
+                for _ = 1, count do
+                    if pos >= length then
+                        break
+                    end
+
+                    if maxBytes and (pos - batchStart) > maxBytes then
+                        gateReportDrop (player, "size", reg.name, nil)
+                        break
+                    end
+
+                    local value, consumed = codec.read (incoming, pos, refs)
+                    pos += consumed
+
+                    if needsGate and not gateCheck (value, reg, player :: Player) then
+                        continue
+                    end
+
+                    if hasReceiveMiddleware then
+                        local final = Middleware.runReceive (value, baseName, player)
+                        if final == nil then
+                            continue
+                        end
+                        signal:fire (final, player)
+                    else
+                        signal:fire (value, player)
+                    end
+                end
+            end
+        else
+            -- Query frame: id(u8, already read) + correlationId(u16) + status(u8) = 3 more bytes
+            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
+
+            if status == 1 then
+                if kind == KIND_REQUEST then
+                    querySignal:fire (nil, player, correlationId)
+                else
+                    querySignal:fire (nil, correlationId)
+                end
+                continue
+            end
+
+            local value, consumed = queryCodec.read (incoming, pos, refs)
+            pos += consumed
+
+            if isServer and reg.needsGate and not gateCheck (value, reg, player :: Player) then
+                continue
+            end
+
+            local final: any
+            if hasReceiveMiddleware then
+                final = Middleware.runReceive (value, reg.baseName, player)
+                if final == nil then
+                    continue
+                end
+            else
+                final = value
+            end
+
+            if kind == KIND_REQUEST then
+                querySignal:fire (final, player, correlationId)
+            else
+                querySignal:fire (final, correlationId)
+            end
+        end
+    end
+end
+
+return table.freeze (Reader)