@axpecter/lync 2.2.1 → 2.3.1

package/src/api/Packet.luau

@@ -7,34 +7,37 @@ local RunService = game:GetService("RunService")
 
 local Baseline = require(script.Parent.Parent.internal.Baseline)
 local Channel = require(script.Parent.Parent.internal.Channel)
+local Log = require(script.Parent.Parent.util.Log)
 local Middleware = require(script.Parent.Parent.internal.Middleware)
+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()
 
+-- mode: TS_* tag; headerSize: 1 (frame byte) + timestamp bytes (1, 2, or 8).
+local TS_MODES: { [string]: { mode: number, headerSize: number } } = table.freeze({
+    frame = table.freeze({ mode = Channel.TS_FRAME, headerSize = 2 }),
+    offset = table.freeze({ mode = Channel.TS_OFFSET, headerSize = 3 }),
+    full = table.freeze({ mode = Channel.TS_FULL, headerSize = 9 }),
+})
+
+local EMPTY_OPTIONS: Types.PacketOptions = table.freeze({})
+
 -- Private ----------------------------------------------------------------
 
-local isPlayer = Util.isPlayer
+local isPlayer = Player.is
 
 local function resolveTimestampMode(ts: ("frame" | "offset" | "full")?): (number, number)
-    if ts == "frame" then
-        Channel.enableTimestamps()
-        return Channel.TS_FRAME, 2
-    end
-    if ts == "offset" then
-        Channel.enableTimestamps()
-        return Channel.TS_OFFSET, 3
+    if ts == nil then
+        return Channel.TS_NONE, 1
     end
-    if ts == "full" then
-        Channel.enableTimestamps()
-        return Channel.TS_FULL, 9
-    end
-    return Channel.TS_NONE, 1
+    local entry = TS_MODES[ts]
+    Channel.enableTimestamps()
+    return entry.mode, entry.headerSize
 end
 
 -- Public types -----------------------------------------------------------
@@ -63,17 +66,18 @@ function Packet.define<T>(
     codec: Types.InternalCodec<T>,
     options: Types.PacketOptions?
 ): PacketHandle<T>
-    local opts = options or ({} :: Types.PacketOptions)
+    local opts = options or EMPTY_OPTIONS
     local isUnreliable = opts.unreliable or false
 
+    -- Delta + unreliable is unsafe: a dropped frame permanently desyncs the receiver baseline.
     if isUnreliable and codec._isDelta then
-        error(`[Lync] Lync.packet: "{name}" cannot use delta codecs with unreliable transport`)
+        Log.error(
+            `"{name}" delta codecs need reliable transport (lost packets desync the baseline)`
+        )
     end
 
     if codec._hasUnknown and not opts.validate then
-        warn(
-            `[Lync] Lync.packet: "{name}" uses unknown codec without validate; data bypasses schema validation`
-        )
+        Log.warn(`"{name}" uses unknown codec without validate; data bypasses schema validation`)
     end
 
     if codec._isDelta then
@@ -109,26 +113,34 @@ function Packet.define<T>(
         end
     end
 
-    local function applySend(data: any, player: Player?): any?
+    --[[
+        Run the send middleware chain. Returns (dropped, value). A nil value
+        is a legitimate payload (Lync.nothing); only the explicit Lync.DROP
+        sentinel or a hook returning DROP triggers the drop branch.
+    ]]
+    local function applySend(data: any, player: Player?): (boolean, any)
         if not Middleware.hasSendHooks() then
-            return data
+            return false, data
         end
-
         local sendData = Middleware.runSend(data, name, player)
-        if typeof(sendData) == "table" and sendData._lyncDrop then
-            return nil
+        if typeof(sendData) == "table" and sendData._lyncKind == "drop" then
+            return true, nil
         end
-        return sendData
+        return false, sendData
     end
 
-    local function sendFromServer(data: any, target: any): ()
-        if target == nil then
-            error(`[Lync] Packet.send: "{name}" server send requires a target`)
+    -- Caller has already run send middleware once for the broadcast.
+    local function broadcast(players: { Player }, data: any): ()
+        for _, p in players do
+            sendToPlayer(p, data)
         end
+        bumpFires()
+    end
 
+    local function sendToTarget(data: any, target: any): ()
         if isPlayer(target) then
-            local sendData = applySend(data, target :: Player)
-            if sendData == nil then
+            local dropped, sendData = applySend(data, target :: Player)
+            if dropped then
                 return
             end
             sendToPlayer(target :: Player, sendData)
@@ -137,57 +149,59 @@ function Packet.define<T>(
         end
 
         if typeof(target) == "table" then
-            local sendData = applySend(data, nil)
-            if sendData == nil then
+            local dropped, sendData = applySend(data, nil)
+            if dropped then
                 return
             end
 
-            if target._lyncAll then
-                for _, player in Players:GetPlayers() do
-                    sendToPlayer(player, sendData)
-                end
-                bumpFires()
+            local kind = target._lyncKind
+            if kind == "all" then
+                broadcast(Players:GetPlayers(), sendData)
                 return
             end
 
-            if target._lyncExcept then
+            if kind == "except" then
                 local excluded = target._excluded :: { [Player]: boolean }
-                for _, player in Players:GetPlayers() do
-                    if not excluded[player] then
-                        sendToPlayer(player, sendData)
+                for _, p in Players:GetPlayers() do
+                    if not excluded[p] then
+                        sendToPlayer(p, sendData)
                     end
                 end
                 bumpFires()
                 return
             end
 
-            if target._lyncGroup then
-                for player in target._members :: { [Player]: boolean } do
-                    sendToPlayer(player, sendData)
+            if kind == "group" then
+                for p in target._members :: { [Player]: boolean } do
+                    sendToPlayer(p, sendData)
                 end
                 bumpFires()
                 return
             end
 
-            for _, player in target do
-                if isPlayer(player) then
-                    sendToPlayer(player :: Player, sendData)
+            -- Plain { Player } array.
+            for _, p in target do
+                if isPlayer(p) then
+                    sendToPlayer(p :: Player, sendData)
                 end
             end
             bumpFires()
             return
         end
 
-        error(
-            `[Lync] Packet.send: "{name}" expected Player, table, Group, or Lync.all as target, got {typeof(
-                target
-            )}`
-        )
+        Log.error(`"{name}" expected Player, table, Group, or Lync.all, got {typeof(target)}`)
+    end
+
+    local function sendFromServer(data: any, target: any): ()
+        if target == nil then
+            Log.error(`"{name}" server send requires a target`)
+        end
+        sendToTarget(data, target)
     end
 
     local function sendFromClient(data: any): ()
-        local sendData = applySend(data, nil)
-        if sendData == nil then
+        local dropped, sendData = applySend(data, nil)
+        if dropped then
             return
         end
         local ch = Transport.client().getChannel(isUnreliable)

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