@axpecter/lync 2.2.1 → 2.3.2

package/src/api/Query.luau

@@ -6,38 +6,82 @@ local Players = game:GetService("Players")
 local RunService = game:GetService("RunService")
 
 local Channel = require(script.Parent.Parent.internal.Channel)
+local Log = require(script.Parent.Parent.util.Log)
+local Player = require(script.Parent.Parent.util.Player)
 local Registry = require(script.Parent.Parent.internal.Registry)
 local Transport = require(script.Parent.Parent.internal.Transport)
 local Types = require(script.Parent.Parent.Types)
-local Util = require(script.Parent.Parent.internal.Util)
 
 -- Constants --------------------------------------------------------------
 
 local IS_SERVER = RunService:IsServer()
 local DEFAULT_TIMEOUT = 5
 
+local EMPTY_OPTIONS: Types.QueryOptions = table.freeze({})
+
 -- State ------------------------------------------------------------------
 
 local _nextCorrId = 0
+-- Correlation -> waiting thread / completion closure. Cleared on resolve or timeout.
 local _pending: { [number]: thread } = {}
 local _pendingGather: { [number]: (any) -> () } = {}
 
 -- Private ----------------------------------------------------------------
 
-local isPlayer = Util.isPlayer
+local isPlayer = Player.is
 
 local function nextCorr(): number
     _nextCorrId += 1
     return _nextCorrId
 end
 
+local function writeQueryTracked(
+    ch: Types.ChannelState,
+    reg: Types.Registration,
+    corrId: number,
+    codec: Types.InternalCodec<any>?,
+    data: any
+): ()
+    if Channel.statsEnabled() then
+        local before = ch.cursor
+        Channel.writeQuery(ch, reg.id, corrId, codec, data)
+        reg.bytesSent += ch.cursor - before
+    else
+        Channel.writeQuery(ch, reg.id, corrId, codec, data)
+    end
+end
+
+local function collectTargets(target: any): { Player }
+    local targets: { Player } = {}
+    if typeof(target) ~= "table" then
+        return targets
+    end
+
+    local kind = target._lyncKind
+    if kind == "all" then
+        for _, p in Players:GetPlayers() do
+            table.insert(targets, p)
+        end
+    elseif kind == "group" then
+        for p in target._members do
+            table.insert(targets, p)
+        end
+    else
+        for _, p in target do
+            if isPlayer(p) then
+                table.insert(targets, p :: Player)
+            end
+        end
+    end
+    return targets
+end
+
 -- Public types -----------------------------------------------------------
 
 --[[
     Server `request(data, target)` returns `Resp?` for a Player target and
-    `{ [Player]: Resp? }` for a multi-target table; Luau doesn't support
-    overloads on table fields, so the type advertises `Resp?` (the common
-    single-target case). Multi-target callers must cast the return.
+    `{ [Player]: Resp? }` for a multi-target table; Luau lacks overloads on
+    table fields, so the type advertises `Resp?` and multi-target callers cast.
 ]]
 export type QueryHandle<Req, Resp> = {
     handle: (
@@ -59,10 +103,11 @@ function Query.define<Req, Resp>(
     responseCodec: Types.InternalCodec<Resp>,
     options: Types.QueryOptions?
 ): QueryHandle<Req, Resp>
-    local opts = options or ({} :: Types.QueryOptions)
+    local opts = options or EMPTY_OPTIONS
     local timeout = opts.timeout or DEFAULT_TIMEOUT
 
     local reqOpenFn = Channel.resolveOpenFn(Channel.TS_NONE, name)
+    -- Embedded "\0resp" suffix stays uniquely paired with the request reg.
     local respName = `{name}\0resp`
     local respOpenFn = Channel.resolveOpenFn(Channel.TS_NONE, respName)
 
@@ -98,6 +143,7 @@ function Query.define<Req, Resp>(
 
     reqReg.partner = respReg.id
 
+    -- Single active handler; replacing it disconnects the prior one via handlerToken.
     local activeHandler: ((any, Player?) -> any)? = nil
     local handlerToken = 0
 
@@ -122,18 +168,22 @@ function Query.define<Req, Resp>(
         end
 
         local ok, response = pcall(handler, value, sender)
+        if not ok then
+            Log.warn(`query "{name}" handler errored: {response}`)
+        end
+        -- pcall failure path returns nil response (writeQuery encodes a nil-MSB header).
         local payloadCodec = if ok then responseCodec else nil
         local payloadData = if ok then response else nil
 
-        local ch = if IS_SERVER and sender
-            then Transport.server().getChannel(sender, false)
-            elseif not IS_SERVER then Transport.client().getChannel(false)
-            else nil
+        local ch: Types.ChannelState? = if IS_SERVER
+            then (if sender then Transport.server().getChannel(sender, false) else nil)
+            else Transport.client().getChannel(false)
         if ch then
-            Channel.writeQuery(ch, respReg.id, corrId, payloadCodec, payloadData)
+            writeQueryTracked(ch, respReg, corrId, payloadCodec, payloadData)
         end
     end)
 
+    -- Resolve the waiting thread with nil after `timeout` seconds.
     local function scheduleSingleTimeout(corrId: number, running: thread): ()
         task.delay(timeout, function()
             if _pending[corrId] == running then
@@ -143,10 +193,10 @@ function Query.define<Req, Resp>(
         end)
     end
 
-    local function requestSingle(target: Player, data: any): any
+    -- Issue a single-target query on `ch` and yield until reply or timeout.
+    local function requestOnChannel(ch: Types.ChannelState, data: any): any
         local corrId = nextCorr()
-        local ch = Transport.server().getChannel(target, false)
-        Channel.writeQuery(ch, reqReg.id, corrId, requestCodec, data)
+        writeQueryTracked(ch, reqReg, corrId, requestCodec, data)
 
         local running = coroutine.running()
         _pending[corrId] = running
@@ -155,30 +205,41 @@ function Query.define<Req, Resp>(
     end
 
     local function requestMulti(targets: { Player }, data: any): { [Player]: any }
-        if #targets == 0 then
+        local targetCount = #targets
+        if targetCount == 0 then
             return {}
         end
 
         local results: { [Player]: any } = {}
-        local remaining = #targets
+        local remaining = targetCount
         local running = coroutine.running()
         local resolved = false
+        local corrIds = table.create(targetCount)
 
+        --[[
+            On timeout, surface the partial result table AND evict every
+            still-pending closure. Without eviction each unanswered closure
+            keeps `results`/`remaining`/`resolveOnce` alive: a slow leak.
+        ]]
         local function resolveOnce(): ()
             if resolved then
                 return
             end
             resolved = true
+            for i = 1, targetCount do
+                _pendingGather[corrIds[i]] = nil
+            end
             task.spawn(running, results)
         end
 
         local Server = Transport.server()
-        for _, player in targets do
+        for i, p in targets do
             local pCorr = nextCorr()
-            local ch = Server.getChannel(player, false)
-            Channel.writeQuery(ch, reqReg.id, pCorr, requestCodec, data)
+            corrIds[i] = pCorr
+            local ch = Server.getChannel(p, false)
+            writeQueryTracked(ch, reqReg, pCorr, requestCodec, data)
 
-            local pRef = player
+            local pRef = p
             _pendingGather[pCorr] = function(response: any)
                 results[pRef] = response
                 remaining -= 1
@@ -192,54 +253,28 @@ function Query.define<Req, Resp>(
         return coroutine.yield()
     end
 
-    local function collectTargets(target: any): { Player }
-        local targets: { Player } = {}
-        if typeof(target) ~= "table" then
-            return targets
-        end
-
-        if target._lyncAll then
-            for _, p in Players:GetPlayers() do
-                table.insert(targets, p)
-            end
-        elseif target._lyncGroup then
-            for player in target._members do
-                table.insert(targets, player)
-            end
-        else
-            for _, p in target do
-                if isPlayer(p) then
-                    table.insert(targets, p :: Player)
-                end
-            end
-        end
-        return targets
-    end
-
     local function requestFromServer(data: any, target: any): any
         if target == nil then
-            error(`[Lync] Query.request: "{name}" server request requires a target`)
+            Log.error(`"{name}" server request requires a target`)
         end
         if isPlayer(target) then
-            return requestSingle(target :: Player, data)
+            return requestOnChannel(Transport.server().getChannel(target :: Player, false), data)
         end
         return requestMulti(collectTargets(target), data)
     end
 
     local function requestFromClient(data: any): any
-        local corrId = nextCorr()
-        local ch = Transport.client().getChannel(false)
-        Channel.writeQuery(ch, reqReg.id, corrId, requestCodec, data)
-
-        local running = coroutine.running()
-        _pending[corrId] = running
-        scheduleSingleTimeout(corrId, running)
-        return coroutine.yield()
+        return requestOnChannel(Transport.client().getChannel(false), data)
     end
 
     type Self = QueryHandle<Req, Resp>
 
     local handle = {
+        --[[
+            Replace the active handler. The returned Connection only clears
+            the active slot if no later :handle has overwritten it: token
+            comparison guards against a stale disconnect wiping a fresh handler.
+        ]]
         handle = function(
             _self: Self,
             fn: (request: Req, player: Player?) -> Resp?
@@ -248,17 +283,20 @@ function Query.define<Req, Resp>(
             local myToken = handlerToken
             activeHandler = fn :: any
 
-            local conn = { connected = true }
-            function conn.disconnect(self): ()
-                if not self.connected then
-                    return
-                end
-                self.connected = false
-                if handlerToken == myToken then
-                    activeHandler = nil
-                end
-            end
-            return conn :: Types.Connection
+            local conn: Types.Connection
+            conn = {
+                connected = true,
+                disconnect = function(self): ()
+                    if not self.connected then
+                        return
+                    end
+                    self.connected = false
+                    if handlerToken == myToken then
+                        activeHandler = nil
+                    end
+                end,
+            }
+            return conn
         end,
 
         request = function(_self: Self, data: Req, target: any?): Resp?

package/src/api/Scope.luau

@@ -1,7 +1,6 @@
 --!strict
 --!optimize 2
--- Batched connection lifecycle. Accepts Lync Connection,
--- RBXScriptConnection, and any object with :disconnect() / :Disconnect().
+-- Batched connection lifecycle for Lync, RBXScriptConnection, and disconnect()-style objects.
 
 local Types = require(script.Parent.Parent.Types)
 
@@ -25,21 +24,29 @@ local function pushConnection(self: Scope, conn: any): ()
     self._connections[idx] = conn
 end
 
+-- Routes :on / :once through `methodName` so both call sites share insert + size bookkeeping.
+local function attach(
+    self: Scope,
+    source: any,
+    fn: (...any) -> (),
+    methodName: string
+): Types.Connection
+    local conn = source[methodName](source, fn)
+    pushConnection(self, conn)
+    return conn
+end
+
 -- Public -----------------------------------------------------------------
 
 local ScopeMeta = {}
 ScopeMeta.__index = ScopeMeta
 
 function ScopeMeta.on(self: Scope, source: any, fn: (...any) -> ()): Types.Connection
-    local conn = source:on(fn)
-    pushConnection(self, conn)
-    return conn
+    return attach(self, source, fn, "on")
 end
 
 function ScopeMeta.once(self: Scope, source: any, fn: (...any) -> ()): Types.Connection
-    local conn = source:once(fn)
-    pushConnection(self, conn)
-    return conn
+    return attach(self, source, fn, "once")
 end
 
 ScopeMeta.add = pushConnection
@@ -48,6 +55,11 @@ function ScopeMeta.size(self: Scope): number
     return self._count
 end
 
+--[[
+    Disconnect every tracked source. The shape sniff handles three kinds:
+    Roblox RBXScriptConnection (:Disconnect), Lync Connection (:disconnect),
+    and tables exposing either capitalization.
+]]
 function ScopeMeta.destroy(self: Scope): ()
     local conns = self._connections
     local count = self._count
@@ -56,8 +68,12 @@ function ScopeMeta.destroy(self: Scope): ()
         conns[i] = nil
         if typeof(conn) == "RBXScriptConnection" then
             (conn :: RBXScriptConnection):Disconnect()
-        elseif typeof(conn) == "table" and conn.disconnect then
-            conn:disconnect()
+        elseif typeof(conn) == "table" then
+            if conn.disconnect then
+                conn:disconnect()
+            elseif conn.Disconnect then
+                conn:Disconnect()
+            end
         end
     end
     self._count = 0

package/src/api/Signal.luau

@@ -1,6 +1,6 @@
 --!strict
 --!optimize 2
--- O(1) disconnect signal system with thread reuse and reentrancy-safe fire.
+-- O(1) disconnect signal with thread reuse and reentrancy-safe fire.
 
 local Types = require(script.Parent.Parent.Types)
 
@@ -12,6 +12,7 @@ local STATE_ONCE = 2
 
 -- State ------------------------------------------------------------------
 
+-- Single recyclable thread for async dispatch; saves coroutine.create per fire.
 local _freeThread: thread? = nil
 
 -- Private ----------------------------------------------------------------
@@ -41,14 +42,19 @@ type Entry = {
     fn: (...any) -> (),
     _state: number,
     connected: boolean,
-    _signalEntries: { Entry },
-    _signalCount: { number },
+    _signal: SignalFields,
     _index: number,
 }
 
+type SignalFields = {
+    _entries: { Entry },
+    _count: number,
+}
+
 local EntryImpl = {}
 EntryImpl.__index = EntryImpl
 
+-- Swap-with-last for O(1) disconnect; the moved entry's _index is patched too.
 local function disconnectEntry(entry: Entry): ()
     if entry._state == STATE_DISCONNECTED then
         return
@@ -57,9 +63,10 @@ local function disconnectEntry(entry: Entry): ()
     entry._state = STATE_DISCONNECTED
     entry.connected = false
 
-    local entries = entry._signalEntries
-    local countRef = entry._signalCount
-    local idx, last = entry._index, countRef[1]
+    local signal = entry._signal
+    local entries = signal._entries
+    local idx = entry._index
+    local last = signal._count
 
     if idx < last then
         local moved = entries[last]
@@ -67,31 +74,40 @@ local function disconnectEntry(entry: Entry): ()
         moved._index = idx
     end
     entries[last] = nil
-    countRef[1] = last - 1
+    signal._count = last - 1
 end
 
 EntryImpl.disconnect = disconnectEntry
 table.freeze(EntryImpl)
 
-type SignalFields = {
-    _entries: { Entry },
-    _count: { number },
-}
+-- Auto-disconnects ONCE entries before invoking; chooses sync vs spawned thread.
+local function invokeEntry(entry: Entry, sync: boolean, ...: any): ()
+    local state = entry._state
+    if state == STATE_DISCONNECTED then
+        return
+    end
+    if state == STATE_ONCE then
+        disconnectEntry(entry)
+    end
+    if sync then
+        entry.fn(...)
+    else
+        spawnCallback(entry.fn, ...)
+    end
+end
 
 local SignalImpl = {}
 SignalImpl.__index = SignalImpl
 
 local function newEntry(self: SignalFields, callback: (...any) -> (), state: number): Entry
-    local countRef = self._count
-    local idx = countRef[1] + 1
-    countRef[1] = idx
+    local idx = self._count + 1
+    self._count = idx
 
     local entry: Entry = setmetatable({
         fn = callback,
         _state = state,
         connected = true,
-        _signalEntries = self._entries,
-        _signalCount = countRef,
+        _signal = self,
         _index = idx,
     }, EntryImpl) :: any
 
@@ -118,53 +134,28 @@ function SignalImpl.wait(self: SignalFields): ...any
 end
 
 local function dispatch(self: SignalFields, sync: boolean, ...: any): ()
-    local count = self._count[1]
+    local count = self._count
     if count == 0 then
         return
     end
 
     local entries = self._entries
 
+    -- Single-listener fast path skips the snapshot allocation.
     if count == 1 then
-        local entry = entries[1]
-        local state = entry._state
-        if state == STATE_ONCE then
-            disconnectEntry(entry)
-            if sync then
-                entry.fn(...)
-            else
-                spawnCallback(entry.fn, ...)
-            end
-        elseif state == STATE_CONNECTED then
-            if sync then
-                entry.fn(...)
-            else
-                spawnCallback(entry.fn, ...)
-            end
-        end
+        invokeEntry(entries[1], sync, ...)
         return
     end
 
+    --[[
+        Re-entrancy: a handler may disconnect or add others mid-fire.
+        Snapshot the entry list so the iteration view is stable.
+    ]]
     local snapshot = table.create(count)
     table.move(entries, 1, count, 1, snapshot)
 
     for i = 1, count do
-        local entry = snapshot[i]
-        local state = entry._state
-        if state == STATE_ONCE then
-            disconnectEntry(entry)
-            if sync then
-                entry.fn(...)
-            else
-                spawnCallback(entry.fn, ...)
-            end
-        elseif state == STATE_CONNECTED then
-            if sync then
-                entry.fn(...)
-            else
-                spawnCallback(entry.fn, ...)
-            end
-        end
+        invokeEntry(snapshot[i], sync, ...)
     end
 end
 
@@ -177,11 +168,11 @@ function SignalImpl.fireSync(self: SignalFields, ...: any): ()
 end
 
 function SignalImpl.count(self: SignalFields): number
-    return self._count[1]
+    return self._count
 end
 
 function SignalImpl.hasListeners(self: SignalFields): boolean
-    return self._count[1] > 0
+    return self._count > 0
 end
 
 table.freeze(SignalImpl)
@@ -191,7 +182,7 @@ table.freeze(SignalImpl)
 local SignalModule = {}
 
 function SignalModule.create(): Types.SignalLike
-    return (setmetatable({ _entries = {}, _count = { 0 } }, SignalImpl) :: any) :: Types.SignalLike
+    return (setmetatable({ _entries = {}, _count = 0 }, SignalImpl) :: any) :: Types.SignalLike
 end
 
 return table.freeze(SignalModule)

package/src/codec/Base.luau

@@ -1,7 +1,8 @@
 --!strict
 --!optimize 2
--- Fixed-size codec factory and channel buffer-grow primitive.
+-- Fixed-size codec factory + channel buffer-grow primitive.
 
+local Log = require(script.Parent.Parent.util.Log)
 local Types = require(script.Parent.Parent.Types)
 
 -- Constants --------------------------------------------------------------
@@ -19,9 +20,9 @@ local countlz = bit32.countlz
 local lshift = bit32.lshift
 
 --[[
-    Grow `ch.buff` so `ch.cursor + bytes` fits. New size is the next
-    power of two >= needed, capped by _maxSize. Caller MUST re-read
-    `ch.buff` after this returns: the buffer reference is replaced.
+    Grow `ch.buff` so cursor + bytes fits. New size is the next power of two
+    >= needed, capped by _maxSize. Callers MUST re-read `ch.buff` after
+    return: the buffer reference is replaced.
 ]]
 local function alloc(ch: Types.ChannelState, bytes: number): ()
     if bytes == 0 then
@@ -36,9 +37,9 @@ local function alloc(ch: Types.ChannelState, bytes: number): ()
     if needed > _maxSize then
         local name = ch.currentPacket
         if name then
-            error(`[Lync] Channel.alloc("{name}"): buffer overflow ({needed}B, max {_maxSize}B)`)
+            Log.error(`packet "{name}" overflowed at {needed}B (max {_maxSize}B)`)
         end
-        error(`[Lync] Channel.alloc: buffer overflow ({needed}B, max {_maxSize}B)`)
+        Log.error(`overflowed at {needed}B (max {_maxSize}B)`)
     end
 
     local newSize = lshift(1, 32 - countlz(needed - 1))
@@ -53,18 +54,31 @@ end
 local Base = {}
 
 Base.INITIAL_BUF = INITIAL_BUF
-
 Base.alloc = alloc
 
+-- Cheap inline guard hoisted into every codec that grows a channel directly.
+function Base.ensure(ch: Types.ChannelState, n: number): ()
+    if ch.cursor + n > ch.size then
+        alloc(ch, n)
+    end
+end
+
+-- Floor is INITIAL_BUF: anything smaller errors on the very first write.
 function Base.setMaxSize(bytes: number): ()
+    if bytes < INITIAL_BUF then
+        Log.error(`bytes ({bytes}) must be >= {INITIAL_BUF}`)
+    end
     _maxSize = bytes
 end
 
+function Base.reset(): ()
+    _maxSize = DEFAULT_MAX
+end
+
 --[[
-    Build a fixed-size codec. The codec exposes channel-level write/read
-    (which handles buffer growth and cursor bookkeeping) plus the raw
-    _directWrite / _directRead primitives composite codecs use in their
-    pre-sized fast paths.
+    Build a fixed-size codec. Exposes channel-level write/read (handles
+    buffer growth + cursor) plus raw _directWrite/_directRead for composite
+    fast paths that pre-size the channel themselves.
 ]]
 function Base.define<T>(
     size: number,
@@ -101,9 +115,9 @@ function Base.define<T>(
 end
 
 --[[
-    Constant codec: zero bytes wire, decode always returns `value`. Used
-    by quantizers when min == max so the wire emits nothing yet decode
-    still produces a type-faithful value.
+    Zero-byte codec: writes nothing, reads always return `value`. Used by
+    quantizers when min == max so the wire emits nothing yet decode produces
+    a type-faithful value.
 ]]
 function Base.constant<T>(value: T): Types.InternalCodec<T>
     return table.freeze({