@axpecter/lync 1.3.0

package/src/internal/Channel.luau

@@ -0,0 +1,235 @@
+--!strict
+--!native
+-- Per-channel buffer state with batching, delta cache, frame XOR.
+
+local Types = require (script.Parent.Parent.Types)
+
+type ChannelState = Types.ChannelState
+
+-- Constants --------------------------------------------------------------
+
+local INITIAL_SIZE = 1024
+local MAX_SIZE = 262144
+local MAX_BATCH = 65535
+
+local min = math.min
+local bxor = bit32.bxor
+local band32 = bit32.band
+local countlz = bit32.countlz
+local lshift = bit32.lshift
+
+-- State ------------------------------------------------------------------
+
+local _maxSize = MAX_SIZE
+local _currentPacket = ""
+
+-- Public -----------------------------------------------------------------
+
+local Channel = {}
+
+-- Override the maximum buffer size. Call before start(). Range: 4096–1048576.
+function Channel.setMaxSize (bytes: number): ()
+    if bytes < 4096 or bytes > 1048576 then
+        error (`[Lync] Channel max size must be 4096–1048576, got {bytes}`)
+    end
+    _maxSize = bytes
+end
+
+function Channel.getMaxSize (): number
+    return _maxSize
+end
+
+function Channel.create (): ChannelState
+    return {
+        buff = buffer.create (INITIAL_SIZE),
+        cursor = 0,
+        size = INITIAL_SIZE,
+        refs = {},
+        lastId = -1,
+        countPos = 0,
+        itemCount = 0,
+        deltas = {},
+        prevDump = nil,
+    }
+end
+
+-- Grows the channel buffer to fit the requested bytes. Power-of-two sizing.
+function Channel.alloc (ch: ChannelState, bytes: number): ()
+    local needed = ch.cursor + bytes
+    if needed <= ch.size then
+        return
+    end
+    if needed > _maxSize then
+        error (
+            `[Lync] Channel overflow writing "{_currentPacket}": {needed} bytes > {_maxSize} max (call Channel.setMaxSize to raise)`
+        )
+    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 alloc = Channel.alloc
+
+-- Seals the open batch header and returns a snapshot of the buffer + refs.
+function Channel.sealAndDump (ch: ChannelState): (buffer, { Instance })
+    if ch.lastId >= 0 then
+        buffer.writeu16 (ch.buff, ch.countPos, ch.itemCount)
+        ch.lastId = -1
+        ch.countPos = 0
+        ch.itemCount = 0
+    end
+
+    local cur = ch.cursor
+    local out = buffer.create (cur)
+    buffer.copy (out, 0, ch.buff, 0, cur)
+
+    local refs = ch.refs
+    return out, if #refs > 0 then table.clone (refs) else {}
+end
+
+-- Sets the packet name for overflow diagnostics.
+function Channel.setCurrentPacket (name: string): ()
+    _currentPacket = name
+end
+
+-- Writes a single value into the batch. Opens a new header on ID change or overflow.
+function Channel.writeBatch (ch: ChannelState, id: number, name: string, codec: any, data: any): ()
+    if id ~= ch.lastId or ch.itemCount >= MAX_BATCH then
+        if ch.lastId >= 0 then
+            buffer.writeu16 (ch.buff, ch.countPos, ch.itemCount)
+        end
+
+        _currentPacket = name
+        alloc (ch, 3)
+        local c = ch.cursor
+        buffer.writeu8 (ch.buff, c, id)
+        ch.countPos = c + 1
+        ch.cursor = c + 3
+        ch.lastId = id
+        ch.itemCount = 0
+    end
+
+    ch.itemCount += 1
+    codec.write (ch, data)
+end
+
+-- Appends pre-serialized bytes into a batch. Used by broadcast fan-out.
+function Channel.writeBatchRaw (
+    ch: ChannelState,
+    id: number,
+    src: buffer,
+    srcLen: number,
+    srcRefs: { Instance }?
+): ()
+    if id ~= ch.lastId or ch.itemCount >= MAX_BATCH then
+        if ch.lastId >= 0 then
+            buffer.writeu16 (ch.buff, ch.countPos, ch.itemCount)
+        end
+
+        alloc (ch, 3)
+        local c = ch.cursor
+        buffer.writeu8 (ch.buff, c, id)
+        ch.countPos = c + 1
+        ch.cursor = c + 3
+        ch.lastId = id
+        ch.itemCount = 0
+    end
+
+    ch.itemCount += 1
+
+    if srcLen > 0 then
+        alloc (ch, srcLen)
+        buffer.copy (ch.buff, ch.cursor, src, 0, srcLen)
+        ch.cursor += srcLen
+    end
+
+    if srcRefs then
+        local refs = ch.refs
+        table.move (srcRefs, 1, #srcRefs, #refs + 1, refs)
+    end
+end
+
+local function sealOpen (ch: ChannelState): ()
+    if ch.lastId >= 0 then
+        buffer.writeu16 (ch.buff, ch.countPos, ch.itemCount)
+        ch.lastId = -1
+        ch.countPos = 0
+        ch.itemCount = 0
+    end
+end
+
+-- Writes a query frame. Seals any open batch, then writes:
+--     id (u8) + correlationId (u16) + status (u8)
+-- Status 0 = payload follows. Status 1 = nil response.
+function Channel.writeQuery (
+    ch: ChannelState,
+    id: number,
+    name: string,
+    correlationId: number,
+    codec: any?,
+    data: any?
+): ()
+    _currentPacket = name
+    sealOpen (ch)
+
+    alloc (ch, 4)
+    local c = ch.cursor
+    buffer.writeu8 (ch.buff, c, id)
+    buffer.writeu16 (ch.buff, c + 1, correlationId)
+
+    if codec then
+        buffer.writeu8 (ch.buff, c + 3, 0)
+        ch.cursor = c + 4
+        codec.write (ch, data)
+    else
+        buffer.writeu8 (ch.buff, c + 3, 1)
+        ch.cursor = c + 4
+    end
+end
+
+-- XOR current frame against previous. Produces zero-heavy output for deflate.
+function Channel.xorApply (current: buffer, previous: buffer?): buffer
+    local curLen = buffer.len (current)
+    if not previous then
+        return current
+    end
+
+    local prevLen = buffer.len (previous :: buffer)
+    if prevLen == 0 then
+        return current
+    end
+
+    local result = buffer.create (curLen)
+    local overlap = min (curLen, prevLen)
+    local prev = previous :: buffer
+
+    local aligned = band32 (overlap, 0xFFFFFFFC)
+    for i = 0, aligned - 4, 4 do
+        buffer.writeu32 (result, i, bxor (buffer.readu32 (current, i), buffer.readu32 (prev, i)))
+    end
+
+    for i = aligned, overlap - 1 do
+        buffer.writeu8 (result, i, bxor (buffer.readu8 (current, i), buffer.readu8 (prev, i)))
+    end
+
+    if curLen > overlap then
+        buffer.copy (result, overlap, current, overlap, curLen - overlap)
+    end
+
+    return result
+end
+
+function Channel.reset (ch: ChannelState): ()
+    ch.cursor = 0
+    ch.lastId = -1
+    ch.countPos = 0
+    ch.itemCount = 0
+    table.clear (ch.refs)
+end
+
+return table.freeze (Channel)

package/src/internal/Middleware.luau

@@ -0,0 +1,109 @@
+--!strict
+--!optimize 2
+-- Ordered intercept chains for send and receive.
+
+-- State ------------------------------------------------------------------
+
+type Handler = (data: any, name: string, player: Player?) -> any?
+
+type Chain = {
+    handlers: { Handler },
+    snapshot: { Handler }?,
+}
+
+local _send: Chain = { handlers = {}, snapshot = nil }
+local _receive: Chain = { handlers = {}, snapshot = nil }
+
+-- Private ----------------------------------------------------------------
+
+local function runChain (chain: { Handler }, data: any, name: string, player: Player?): any?
+    local current = data
+    for i = 1, #chain do
+        local result = chain[i] (current, name, player)
+        if result == nil then
+            return nil
+        end
+        current = result
+    end
+    return current
+end
+
+local function run (chain: Chain, data: any, name: string, player: Player?): any?
+    local handlers = chain.handlers
+    local count = #handlers
+    if count == 0 then
+        return data
+    end
+
+    local snapshot = chain.snapshot
+    if not snapshot then
+        snapshot = table.clone (handlers)
+        chain.snapshot = snapshot
+    end
+
+    local ok: boolean
+    local result: any
+
+    if count == 1 then
+        ok, result = pcall (snapshot[1], data, name, player)
+    else
+        ok, result = pcall (runChain, snapshot, data, name, player)
+    end
+
+    if not ok then
+        warn (`[Lync] Middleware error on "{name}": {result}`)
+        return nil
+    end
+
+    return result
+end
+
+local function addTo (chain: Chain, fn: Handler): () -> ()
+    table.insert (chain.handlers, fn)
+    chain.snapshot = nil
+
+    return function (): ()
+        local pos = table.find (chain.handlers, fn)
+        if pos then
+            table.remove (chain.handlers, pos)
+            chain.snapshot = nil
+        end
+    end
+end
+
+-- Public -----------------------------------------------------------------
+
+local Middleware = {}
+
+function Middleware.addSend (fn: Handler): () -> ()
+    local remover = addTo (_send, fn)
+    Middleware.hasSend = true
+
+    return function (): ()
+        remover ()
+        Middleware.hasSend = #_send.handlers > 0
+    end
+end
+
+function Middleware.addReceive (fn: Handler): () -> ()
+    local remover = addTo (_receive, fn)
+    Middleware.hasReceive = true
+
+    return function (): ()
+        remover ()
+        Middleware.hasReceive = #_receive.handlers > 0
+    end
+end
+
+function Middleware.runSend (data: any, name: string, player: Player?): any?
+    return run (_send, data, name, player)
+end
+
+function Middleware.runReceive (data: any, name: string, player: Player?): any?
+    return run (_receive, data, name, player)
+end
+
+Middleware.hasSend = false
+Middleware.hasReceive = false
+
+return Middleware

package/src/internal/Pool.luau

@@ -0,0 +1,68 @@
+--!strict
+--!optimize 2
+-- Stack-based ChannelState pool with warmup support.
+
+local Channel = require (script.Parent.Channel)
+local Types = require (script.Parent.Parent.Types)
+
+type ChannelState = Types.ChannelState
+
+-- Constants --------------------------------------------------------------
+
+local DEFAULT_MAX = 16
+
+-- State ------------------------------------------------------------------
+
+local _stack = {} :: { ChannelState }
+local _depth = 0
+local _maxSize = DEFAULT_MAX
+
+-- Public -----------------------------------------------------------------
+
+local Pool = {}
+
+-- Override the max idle ChannelStates in the pool. Default 16. Range: 2–128.
+function Pool.setMaxSize (count: number): ()
+    if count < 2 or count > 128 then
+        error (`[Lync] Pool max size must be 2–128, got {count}`)
+    end
+    _maxSize = count
+end
+
+function Pool.getMaxSize (): number
+    return _maxSize
+end
+
+function Pool.acquire (): ChannelState
+    if _depth > 0 then
+        local ch = _stack[_depth]
+        _stack[_depth] = nil :: any
+        _depth -= 1
+        return ch
+    end
+
+    return Channel.create ()
+end
+
+function Pool.release (ch: ChannelState): ()
+    ch.cursor = 0
+    ch.lastId = -1
+    ch.countPos = 0
+    ch.itemCount = 0
+    table.clear (ch.refs)
+    table.clear (ch.deltas)
+    ch.prevDump = nil
+
+    if _depth >= _maxSize then
+        return -- discard; GC will reclaim
+    end
+
+    _depth += 1
+    _stack[_depth] = ch
+end
+
+function Pool.size (): number
+    return _depth
+end
+
+return table.freeze (Pool)

package/src/internal/Registry.luau

@@ -0,0 +1,146 @@
+--!strict
+--!optimize 2
+-- Deterministic ID assignment for packets and queries.
+
+local Types = require (script.Parent.Parent.Types)
+
+type Codec<T> = Types.Codec<T>
+type Registration = Types.Registration
+type RateLimitConfig = Types.RateLimitConfig
+
+-- Constants --------------------------------------------------------------
+
+local KIND_PACKET = 0
+local KIND_REQUEST = 1
+local KIND_RESPONSE = 2
+local MAX_PACKETS = 255
+
+-- State ------------------------------------------------------------------
+
+local _entries = {} :: { Registration }
+local _names = {} :: { [string]: number }
+local _nextId = 1
+
+-- Private ----------------------------------------------------------------
+
+local function assign (
+    name: string,
+    baseName: string,
+    codec: Codec<any>,
+    isUnreliable: boolean,
+    kind: number,
+    signal: any,
+    rateLimit: RateLimitConfig?,
+    validate: ((data: any, player: Player) -> (boolean, string?))?,
+    maxPayloadBytes: number?
+): Registration
+    if _names[name] then
+        error (`[Lync] Duplicate registration: "{name}"`)
+    end
+    if _nextId > MAX_PACKETS then
+        error (`[Lync] Registration limit reached: {MAX_PACKETS} max`)
+    end
+
+    if rateLimit then
+        if rateLimit.maxPerSecond <= 0 then
+            error (`[Lync] maxPerSecond must be positive: "{name}"`)
+        end
+        if rateLimit.burstAllowance and rateLimit.burstAllowance <= 0 then
+            error (`[Lync] burstAllowance must be positive: "{name}"`)
+        end
+    end
+
+    if maxPayloadBytes and maxPayloadBytes <= 0 then
+        error (`[Lync] maxPayloadBytes must be positive: "{name}"`)
+    end
+
+    local id = _nextId
+    _nextId += 1
+
+    local reg: Registration = {
+        id = id,
+        name = name,
+        baseName = baseName,
+        codec = codec,
+        isUnreliable = isUnreliable,
+        kind = kind,
+        partner = nil,
+        signal = signal,
+        rateLimit = rateLimit,
+        validate = validate,
+        needsGate = rateLimit ~= nil or validate ~= nil,
+        maxPayloadBytes = maxPayloadBytes,
+    }
+
+    _entries[id] = reg
+    _names[name] = id
+    return reg
+end
+
+-- Public -----------------------------------------------------------------
+
+local Registry = {
+    KIND_PACKET = KIND_PACKET,
+    KIND_REQUEST = KIND_REQUEST,
+    KIND_RESPONSE = KIND_RESPONSE,
+}
+
+function Registry.register (
+    name: string,
+    codec: Codec<any>,
+    isUnreliable: boolean,
+    signal: any,
+    rateLimit: RateLimitConfig?,
+    validate: ((data: any, player: Player) -> (boolean, string?))?,
+    maxPayloadBytes: number?
+): Registration
+    return assign (
+        name,
+        name,
+        codec,
+        isUnreliable,
+        KIND_PACKET,
+        signal,
+        rateLimit,
+        validate,
+        maxPayloadBytes
+    )
+end
+
+function Registry.registerQueryPair (
+    name: string,
+    requestCodec: Codec<any>,
+    responseCodec: Codec<any>,
+    requestSignal: any,
+    responseSignal: any,
+    rateLimit: RateLimitConfig?,
+    validate: ((data: any, player: Player) -> (boolean, string?))?
+): (Registration, Registration)
+    local req = assign (
+        `{name}:req`,
+        name,
+        requestCodec,
+        false,
+        KIND_REQUEST,
+        requestSignal,
+        rateLimit,
+        validate
+    )
+    local resp =
+        assign (`{name}:resp`, name, responseCodec, false, KIND_RESPONSE, responseSignal, nil, nil)
+
+    req.partner = resp.id
+    resp.partner = req.id
+    return req, resp
+end
+
+function Registry.get (id: number): Registration?
+    return _entries[id]
+end
+
+function Registry.getByName (name: string): Registration?
+    local id = _names[name]
+    return if id then _entries[id] else nil
+end
+
+return table.freeze (Registry)

package/src/transport/Bridge.luau

@@ -0,0 +1,66 @@
+--!strict
+--!optimize 2
+-- Creates and exposes the network remote instances.
+
+local ReplicatedStorage = game:GetService ("ReplicatedStorage")
+local RunService = game:GetService ("RunService")
+
+-- Constants --------------------------------------------------------------
+
+local FOLDER = "_lync"
+local RELIABLE = "R"
+local UNRELIABLE = "U"
+local TIMEOUT = 10
+
+-- State ------------------------------------------------------------------
+
+local _reliable: RemoteEvent
+local _unreliable: UnreliableRemoteEvent
+
+-- Public -----------------------------------------------------------------
+
+local Bridge = {}
+
+function Bridge.setup (): ()
+    if RunService:IsServer () then
+        local folder = Instance.new ("Folder")
+        folder.Name = FOLDER
+
+        local reliable = Instance.new ("RemoteEvent")
+        reliable.Name = RELIABLE
+        reliable.Parent = folder
+
+        local unreliable = Instance.new ("UnreliableRemoteEvent")
+        unreliable.Name = UNRELIABLE
+        unreliable.Parent = folder
+
+        folder.Parent = ReplicatedStorage
+
+        _reliable = reliable
+        _unreliable = unreliable
+    else
+        local folder = ReplicatedStorage:WaitForChild (FOLDER, TIMEOUT)
+        if not folder then
+            error ("[Lync] Network folder not found, is the server started?")
+        end
+
+        local reliable = folder:WaitForChild (RELIABLE, TIMEOUT)
+        if not reliable then
+            error ("[Lync] Reliable remote not found")
+        end
+
+        local unreliable = folder:WaitForChild (UNRELIABLE, TIMEOUT)
+        if not unreliable then
+            error ("[Lync] Unreliable remote not found")
+        end
+
+        _reliable = reliable :: RemoteEvent
+        _unreliable = unreliable :: UnreliableRemoteEvent
+    end
+
+    Bridge.reliable = _reliable :: any
+    Bridge.unreliable = _unreliable :: any
+    table.freeze (Bridge)
+end
+
+return Bridge