@axpecter/lync 1.3.0

package/src/api/Namespace.luau

@@ -0,0 +1,226 @@
+--!strict
+--!optimize 2
+-- Scoped packet/query groups with batch ops and local middleware.
+
+local Middleware = require (script.Parent.Parent.internal.Middleware)
+local Packet = require (script.Parent.Packet)
+local Query = require (script.Parent.Query)
+local Types = require (script.Parent.Parent.Types)
+
+type Connection = Types.Connection
+type PacketConfig<T> = Types.PacketConfig<T>
+type QueryConfig<R, S> = Types.QueryConfig<R, S>
+
+-- Constants --------------------------------------------------------------
+
+local MAX_NAMESPACES = 64
+
+-- State ------------------------------------------------------------------
+
+local _registered = {} :: { [string]: true }
+local _count = 0
+
+-- Private ----------------------------------------------------------------
+
+type NamespaceConfig = {
+    packets: { [string]: PacketConfig<any> }?,
+    queries: { [string]: QueryConfig<any, any> }?,
+}
+
+local function prefixName (nsName: string, name: string): string
+    return `{nsName}.{name}`
+end
+
+-- Wraps a middleware handler so it only fires for packets in this namespace.
+local function scopedHandler (
+    nsName: string,
+    handler: (data: any, name: string, player: Player?) -> any?
+): (data: any, name: string, player: Player?) -> any?
+    local prefix = nsName .. "."
+    local prefixLen = #prefix
+
+    return function (data: any, name: string, player: Player?): any?
+        if string.sub (name, 1, prefixLen) ~= prefix then
+            return data
+        end
+        return handler (data, name, player)
+    end
+end
+
+-- Namespace --------------------------------------------------------------
+
+local NamespaceImpl = {}
+NamespaceImpl.__index = NamespaceImpl
+
+-- Listens on every packet in this namespace. Returns a Connection.
+function NamespaceImpl.listenAll (
+    self: any,
+    callback: (name: string, data: any, sender: Player?) -> ()
+): Connection
+    local connections = {} :: { Connection }
+    local prefix = self._name .. "."
+    local prefixLen = #prefix
+
+    for fullName, packet in self._packets do
+        local shortName = string.sub (fullName, prefixLen + 1)
+        local conn = packet:listen (function (data: any, sender: Player?): ()
+            callback (shortName, data, sender)
+        end)
+        table.insert (connections, conn)
+        table.insert (self._tracked, conn)
+    end
+
+    local bundle = {
+        connected = true,
+        disconnect = function (conn: Connection): ()
+            if not conn.connected then
+                return
+            end
+            conn.connected = false
+
+            for _, inner in connections do
+                if inner.connected then
+                    inner:disconnect ()
+                end
+            end
+        end,
+    }
+
+    return bundle :: any
+end
+
+-- Disconnects every listenAll connection. Does not remove scoped middleware.
+function NamespaceImpl.disconnectAll (self: any): ()
+    for _, conn in self._tracked do
+        if conn.connected then
+            conn:disconnect ()
+        end
+    end
+    table.clear (self._tracked)
+end
+
+-- Registers send middleware scoped to this namespace. Returns a remover.
+function NamespaceImpl.onSend (
+    self: any,
+    handler: (data: any, name: string, player: Player?) -> any?
+): () -> ()
+    local wrapped = scopedHandler (self._name, handler)
+    local remover = Middleware.addSend (wrapped)
+    table.insert (self._removers, remover)
+
+    return function (): ()
+        remover ()
+        local idx = table.find (self._removers, remover)
+        if idx then
+            table.remove (self._removers, idx)
+        end
+    end
+end
+
+-- Registers receive middleware scoped to this namespace. Returns a remover.
+function NamespaceImpl.onReceive (
+    self: any,
+    handler: (data: any, name: string, player: Player?) -> any?
+): () -> ()
+    local wrapped = scopedHandler (self._name, handler)
+    local remover = Middleware.addReceive (wrapped)
+    table.insert (self._removers, remover)
+
+    return function (): ()
+        remover ()
+        local idx = table.find (self._removers, remover)
+        if idx then
+            table.remove (self._removers, idx)
+        end
+    end
+end
+
+-- Kills all listeners and removes all scoped middleware. Full cleanup.
+function NamespaceImpl.destroy (self: any): ()
+    self:disconnectAll ()
+
+    for _, remover in self._removers do
+        remover ()
+    end
+    table.clear (self._removers)
+end
+
+-- Returns every packet name (without prefix) in this namespace.
+function NamespaceImpl.packetNames (self: any): { string }
+    local result = {} :: { string }
+    local prefix = self._name .. "."
+    local prefixLen = #prefix
+
+    for fullName in self._packets do
+        table.insert (result, string.sub (fullName, prefixLen + 1))
+    end
+
+    table.sort (result)
+    return result
+end
+
+-- Returns every query name (without prefix) in this namespace.
+function NamespaceImpl.queryNames (self: any): { string }
+    local result = {} :: { string }
+    local prefix = self._name .. "."
+    local prefixLen = #prefix
+
+    for fullName in self._queries do
+        table.insert (result, string.sub (fullName, prefixLen + 1))
+    end
+
+    table.sort (result)
+    return result
+end
+
+-- Public -----------------------------------------------------------------
+
+local Namespace = {}
+
+-- Defines a namespace. Names are auto-prefixed to prevent collisions.
+function Namespace.define (name: string, config: NamespaceConfig): any
+    if #name == 0 then
+        error ("[Lync] Namespace name must not be empty")
+    end
+    if _registered[name] then
+        error (`[Lync] Duplicate namespace: "{name}"`)
+    end
+    if _count >= MAX_NAMESPACES then
+        error (`[Lync] Namespace limit reached: {MAX_NAMESPACES}`)
+    end
+
+    _count += 1
+    _registered[name] = true
+
+    local packets = {} :: { [string]: any }
+    local queries = {} :: { [string]: any }
+    local fields = {} :: { [string]: any }
+
+    fields._name = name
+    fields._packets = packets
+    fields._queries = queries
+    fields._tracked = {} :: { Connection }
+    fields._removers = {} :: { () -> () }
+
+    if config.packets then
+        for shortName, packetConfig in config.packets do
+            local fullName = prefixName (name, shortName)
+            local packet = Packet.define (fullName, packetConfig)
+            packets[fullName] = packet
+            fields[shortName] = packet
+        end
+    end
+
+    if config.queries then
+        for shortName, queryConfig in config.queries do
+            local fullName = prefixName (name, shortName)
+            local query = Query.define (fullName, queryConfig)
+            queries[fullName] = query
+            fields[shortName] = query
+        end
+    end
+
+    return setmetatable (fields, NamespaceImpl)
+end
+
+return table.freeze (Namespace)

package/src/api/Packet.luau

@@ -0,0 +1,147 @@
+--!strict
+--!optimize 2
+-- Packet definition and send/listen API.
+
+local RunService = game:GetService ("RunService")
+
+local Client = require (script.Parent.Parent.transport.Client)
+local Registry = require (script.Parent.Parent.internal.Registry)
+local Server = require (script.Parent.Parent.transport.Server)
+local Signal = require (script.Parent.Signal)
+local Types = require (script.Parent.Parent.Types)
+
+type Connection = Types.Connection
+type PacketConfig<T> = Types.PacketConfig<T>
+
+-- Constants --------------------------------------------------------------
+
+local IS_SERVER = RunService:IsServer ()
+
+local serverWriteTo = Server.writeTo
+local serverWriteToAll = Server.writeToAll
+local serverWriteToList = Server.writeToList
+local serverWriteToAllExcept = Server.writeToAllExcept
+local serverWriteToGroup = Server.writeToGroup
+local clientWrite = Client.write
+
+-- Private ----------------------------------------------------------------
+
+-- Shared methods (both contexts)
+local SharedImpl = {}
+
+function SharedImpl.listen (self: any, callback: (...any) -> ()): Connection
+    return self._signal:connect (callback)
+end
+
+function SharedImpl.once (self: any, callback: (...any) -> ()): Connection
+    return self._signal:once (callback)
+end
+
+function SharedImpl.wait (self: any): ...any
+    return self._signal:wait ()
+end
+
+function SharedImpl.disconnectAll (self: any): ()
+    self._signal:disconnectAll ()
+end
+
+-- Server-only metatable . Has sendTo/sendToAll, no send().
+local ServerImpl = setmetatable ({}, { __index = SharedImpl })
+ServerImpl.__index = ServerImpl
+
+local DELTA_TARGETED = 1
+local DELTA_BROADCAST = 2
+
+local function checkDeltaMode (self: any, mode: number): ()
+    if not self._isDelta then
+        return
+    end
+    local current = self._deltaMode
+    if current == 0 then
+        self._deltaMode = mode
+    elseif current ~= mode then
+        error (`[Lync] Delta packet cannot mix targeted and broadcast: "{self._name}"`)
+    end
+end
+
+function ServerImpl.sendTo (self: any, data: any, player: Player): ()
+    checkDeltaMode (self, DELTA_TARGETED)
+    serverWriteTo (player, self._id, self._name, self._codec, data, self._isUnreliable)
+end
+
+function ServerImpl.sendToAll (self: any, data: any): ()
+    checkDeltaMode (self, DELTA_BROADCAST)
+    serverWriteToAll (self._id, self._name, self._codec, data, self._isUnreliable)
+end
+
+function ServerImpl.sendToList (self: any, data: any, players: { Player }): ()
+    checkDeltaMode (self, DELTA_TARGETED)
+    serverWriteToList (players, self._id, self._name, self._codec, data, self._isUnreliable)
+end
+
+function ServerImpl.sendToAllExcept (self: any, data: any, except: Player): ()
+    checkDeltaMode (self, DELTA_BROADCAST)
+    serverWriteToAllExcept (except, self._id, self._name, self._codec, data, self._isUnreliable)
+end
+
+function ServerImpl.sendToGroup (self: any, data: any, groupName: string): ()
+    checkDeltaMode (self, DELTA_BROADCAST)
+    serverWriteToGroup (groupName, self._id, self._name, self._codec, data, self._isUnreliable)
+end
+
+table.freeze (ServerImpl)
+
+-- Client-only metatable . Has send(), no sendTo/sendToAll
+local ClientImpl = setmetatable ({}, { __index = SharedImpl })
+ClientImpl.__index = ClientImpl
+
+function ClientImpl.send (self: any, data: any): ()
+    clientWrite (self._id, self._name, self._codec, data, self._isUnreliable)
+end
+
+table.freeze (ClientImpl)
+
+-- Public -----------------------------------------------------------------
+
+local Packet = {}
+
+function Packet.define (name: string, config: PacketConfig<any>): any
+    if #name == 0 then
+        error ("[Lync] Packet name must not be empty")
+    end
+    if not config.value then
+        error (`[Lync] Packet requires a value codec: "{name}"`)
+    end
+
+    local isUnreliable = config.unreliable or false
+
+    if (config.value :: any)._isDelta and isUnreliable then
+        error (`[Lync] Delta codec requires reliable delivery: "{name}"`)
+    end
+
+    local signal = Signal.create ()
+
+    local reg = Registry.register (
+        name,
+        config.value,
+        isUnreliable,
+        signal,
+        config.rateLimit,
+        config.validate,
+        config.maxPayloadBytes
+    )
+
+    local isDelta = (config.value :: any)._isDelta == true
+
+    return setmetatable ({
+        _id = reg.id,
+        _name = reg.name,
+        _codec = reg.codec,
+        _isUnreliable = isUnreliable,
+        _isDelta = isDelta,
+        _deltaMode = 0,
+        _signal = signal,
+    }, if IS_SERVER then ServerImpl else ClientImpl)
+end
+
+return table.freeze (Packet)

package/src/api/Query.luau

@@ -0,0 +1,295 @@
+--!strict
+--!optimize 2
+-- Bidirectional request-reply over RemoteEvents.
+
+local Players = game:GetService ("Players")
+local RunService = game:GetService ("RunService")
+
+local Client = require (script.Parent.Parent.transport.Client)
+local Group = require (script.Parent.Group)
+local Registry = require (script.Parent.Parent.internal.Registry)
+local Server = require (script.Parent.Parent.transport.Server)
+local Signal = require (script.Parent.Signal)
+local Types = require (script.Parent.Parent.Types)
+
+type Connection = Types.Connection
+type QueryConfig<R, S> = Types.QueryConfig<R, S>
+
+-- Constants --------------------------------------------------------------
+
+local IS_SERVER = RunService:IsServer ()
+
+-- Wire ceiling: correlationId is u16 in Channel.writeQuery / Reader.process.
+local POOL_SIZE = 65536
+
+-- State ------------------------------------------------------------------
+
+type PendingQuery = {
+    thread: thread?,
+    callback: ((data: any) -> ())?,
+    timeout: thread?,
+}
+
+local _pending = {} :: { [number]: PendingQuery }
+local _nextId = 0
+local _activeCount = 0
+
+-- Private ----------------------------------------------------------------
+
+local function allocCorrelation (): number
+    if _activeCount >= POOL_SIZE then
+        error ("[Lync] All 65536 query correlation slots exhausted")
+    end
+
+    local id = _nextId
+
+    -- Skip occupied slots. With 65536 capacity and typical single-digit
+    -- concurrency, this loop body almost never executes.
+    while _pending[id] do
+        id = (id + 1) % POOL_SIZE
+    end
+
+    _nextId = (id + 1) % POOL_SIZE
+    _activeCount += 1
+    return id
+end
+
+local function freeCorrelation (): ()
+    _activeCount -= 1
+end
+
+local function completeQuery (id: number, data: any): ()
+    local entry = _pending[id]
+    if not entry then
+        return
+    end
+
+    _pending[id] = nil
+    freeCorrelation ()
+
+    if entry.timeout then
+        task.cancel (entry.timeout)
+    end
+
+    if entry.callback then
+        entry.callback (data)
+    elseif entry.thread then
+        coroutine.resume (entry.thread :: thread, data)
+    end
+end
+
+local function onTimeout (correlation: number): ()
+    completeQuery (correlation, nil)
+end
+
+-- Query ------------------------------------------------------------------
+
+local QueryImpl = {}
+QueryImpl.__index = QueryImpl
+
+function QueryImpl.listen (self: any, callback: (...any) -> any): Connection
+    local respId = self._respReg.id
+    local respName = self._name
+    local respCodec = self._respReg.codec
+
+    if IS_SERVER then
+        return self._reqReg.signal:connect (
+            function (request: any, player: Player, correlation: number): ()
+                local ok, response = pcall (callback, request, player)
+                if not ok then
+                    warn (`[Lync] Query handler error on "{respName}": {response}`)
+                end
+
+                if ok and response ~= nil then
+                    Server.writeQuery (player, respId, respName, correlation, respCodec, response)
+                else
+                    Server.writeQueryNil (player, respId, respName, correlation)
+                end
+            end
+        )
+    else
+        return self._reqReg.signal:connect (
+            function (request: any, _player: Player?, correlation: number): ()
+                local ok, response = pcall (callback, request)
+                if not ok then
+                    warn (`[Lync] Query handler error on "{respName}": {response}`)
+                end
+
+                if ok and response ~= nil then
+                    Client.writeQuery (respId, respName, correlation, respCodec, response)
+                else
+                    Client.writeQueryNil (respId, respName, correlation)
+                end
+            end
+        )
+    end
+end
+
+function QueryImpl.invoke (self: any, request: any, player: Player?): any
+    if IS_SERVER and not player then
+        error ("[Lync] Query:invoke on server requires a player argument")
+    end
+
+    local correlation = allocCorrelation ()
+    local thread = coroutine.running ()
+
+    local entry: PendingQuery = { thread = thread, timeout = nil }
+    _pending[correlation] = entry
+
+    if IS_SERVER then
+        Server.writeQuery (
+            player :: Player,
+            self._reqReg.id,
+            self._name,
+            correlation,
+            self._reqReg.codec,
+            request
+        )
+    else
+        Client.writeQuery (self._reqReg.id, self._name, correlation, self._reqReg.codec, request)
+    end
+
+    entry.timeout = task.delay (self._timeout, onTimeout, correlation)
+    return coroutine.yield ()
+end
+
+-- Send a query to multiple players and yield. Returns { [Player]: response? }.
+local function invokeMulti (self: any, players: { Player }, request: any): { [Player]: any? }
+    if not IS_SERVER then
+        error ("[Lync] Multi-invoke is server-only")
+    end
+
+    local count = #players
+    if count == 0 then
+        return {}
+    end
+
+    if count == 1 then
+        local result = QueryImpl.invoke (self, request, players[1])
+        return { [players[1]] = result }
+    end
+
+    local thread = coroutine.running ()
+    local results = {} :: { [Player]: any? }
+    local remaining = count
+    local correlations = table.create (count) :: { number }
+    local finished = false
+
+    local reqId = self._reqReg.id
+    local reqName = self._name
+    local reqCodec = self._reqReg.codec
+    local timeout = self._timeout
+
+    for i = 1, count do
+        local player = players[i]
+        local correlation = allocCorrelation ()
+        correlations[i] = correlation
+
+        local entry: PendingQuery = {
+            thread = nil,
+            callback = function (data: any): ()
+                results[player] = data
+                remaining -= 1
+                if remaining == 0 and not finished then
+                    finished = true
+                    task.spawn (thread, results)
+                end
+            end,
+            timeout = nil,
+        }
+
+        _pending[correlation] = entry
+
+        Server.writeQuery (player, reqId, reqName, correlation, reqCodec, request)
+    end
+
+    local timeoutThread = task.delay (timeout, function (): ()
+        if finished then
+            return
+        end
+        finished = true
+
+        for i = 1, count do
+            local cid = correlations[i]
+            local entry = _pending[cid]
+            if entry then
+                _pending[cid] = nil
+                freeCorrelation ()
+            end
+        end
+
+        task.spawn (thread, results)
+    end)
+
+    for i = 1, count do
+        local cid = correlations[i]
+        local entry = _pending[cid]
+        if entry then
+            entry.timeout = timeoutThread
+        end
+    end
+
+    return coroutine.yield ()
+end
+
+function QueryImpl.invokeAll (self: any, request: any): { [Player]: any? }
+    local players = Players:GetPlayers ()
+    return invokeMulti (self, players, request)
+end
+
+function QueryImpl.invokeList (self: any, request: any, players: { Player }): { [Player]: any? }
+    return invokeMulti (self, players, request)
+end
+
+function QueryImpl.invokeGroup (self: any, request: any, groupName: string): { [Player]: any? }
+    local set = Group.getSet (groupName)
+    local players = {} :: { Player }
+    for player in set do
+        table.insert (players, player)
+    end
+    return invokeMulti (self, players, request)
+end
+
+-- Public -----------------------------------------------------------------
+
+local Query = {}
+
+function Query.define (name: string, config: QueryConfig<any, any>): any
+    if not config.request then
+        error (`[Lync] Query requires a request codec: "{name}"`)
+    end
+    if not config.response then
+        error (`[Lync] Query requires a response codec: "{name}"`)
+    end
+
+    local reqSignal = Signal.create ()
+    local respSignal = Signal.create ()
+
+    local reqReg, respReg = Registry.registerQueryPair (
+        name,
+        config.request,
+        config.response,
+        reqSignal,
+        respSignal,
+        config.rateLimit,
+        config.validate
+    )
+
+    respSignal:connect (function (resp: any, correlation: number): ()
+        completeQuery (correlation, resp)
+    end)
+
+    return setmetatable ({
+        _name = name,
+        _reqReg = reqReg,
+        _respReg = respReg,
+        _timeout = config.timeout or 5,
+    }, QueryImpl)
+end
+
+-- Returns the number of queries currently awaiting a response.
+function Query.pendingCount (): number
+    return _activeCount
+end
+
+return table.freeze (Query)