@axpecter/lync 2.2.0 → 2.3.1

package/src/api/Packet.luau

@@ -7,67 +7,77 @@ 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 -----------------------------------------------------------
 
-export type PacketHandle = {
-    send: (self: PacketHandle, data: any, target: any?) -> (),
-    on: (self: PacketHandle, fn: (...any) -> ()) -> Types.Connection,
-    once: (self: PacketHandle, fn: (...any) -> ()) -> Types.Connection,
-    wait: (self: PacketHandle) -> ...any,
-    name: (self: PacketHandle) -> string,
-    stats: (self: PacketHandle) -> Types.PacketStats,
+export type PacketHandle<T> = {
+    send: (self: PacketHandle<T>, data: T, target: any?) -> (),
+    on: (
+        self: PacketHandle<T>,
+        fn: (data: T, sender: Player?, timestamp: number?) -> ()
+    ) -> Types.Connection,
+    once: (
+        self: PacketHandle<T>,
+        fn: (data: T, sender: Player?, timestamp: number?) -> ()
+    ) -> Types.Connection,
+    wait: (self: PacketHandle<T>) -> (T, Player?, number?),
+    name: (self: PacketHandle<T>) -> string,
+    stats: (self: PacketHandle<T>) -> Types.PacketStats,
 }
 
 -- Public -----------------------------------------------------------------
 
 local Packet = {}
 
-function Packet.define(
+function Packet.define<T>(
     name: string,
-    codec: Types.InternalCodec<any>,
+    codec: Types.InternalCodec<T>,
     options: Types.PacketOptions?
-): PacketHandle
-    local opts = options or ({} :: Types.PacketOptions)
+): PacketHandle<T>
+    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
@@ -103,26 +113,34 @@ function Packet.define(
         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)
@@ -131,57 +149,59 @@ function Packet.define(
         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)
@@ -189,8 +209,11 @@ function Packet.define(
         bumpFires()
     end
 
+    type Self = PacketHandle<T>
+    type Listener = (data: T, sender: Player?, timestamp: number?) -> ()
+
     local handle = {
-        send = function(_self: PacketHandle, data: any, target: any?): ()
+        send = function(_self: Self, data: T, target: any?): ()
             if IS_SERVER then
                 sendFromServer(data, target)
             else
@@ -198,11 +221,11 @@ function Packet.define(
             end
         end,
 
-        on = function(_self: PacketHandle, fn: (...any) -> ()): Types.Connection
-            return reg.signal:connect(fn)
+        on = function(_self: Self, fn: Listener): Types.Connection
+            return reg.signal:connect(fn :: any)
         end,
 
-        once = function(_self: PacketHandle, fn: (...any) -> ()): Types.Connection
+        once = function(_self: Self, fn: Listener): Types.Connection
             local conn: Types.Connection
             conn = reg.signal:connect(function(...: any)
                 conn:disconnect()
@@ -211,15 +234,15 @@ function Packet.define(
             return conn
         end,
 
-        wait = function(_self: PacketHandle): ...any
+        wait = function(_self: Self): (T, Player?, number?)
             return reg.signal:wait()
         end,
 
-        name = function(_self: PacketHandle): string
+        name = function(_self: Self): string
             return reg.name
         end,
 
-        stats = function(_self: PacketHandle): Types.PacketStats
+        stats = function(_self: Self): Types.PacketStats
             return {
                 bytesSent = reg.bytesSent,
                 bytesReceived = reg.bytesReceived,
@@ -230,7 +253,7 @@ function Packet.define(
         end,
     }
 
-    return table.freeze(handle) :: PacketHandle
+    return table.freeze(handle) :: PacketHandle<T>
 end
 
 return table.freeze(Packet)

package/src/api/Query.luau

@@ -6,54 +6,108 @@ 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 -----------------------------------------------------------
 
-export type QueryHandle = {
-    handle: (self: QueryHandle, fn: (request: any, player: Player?) -> any) -> Types.Connection,
-    request: (self: QueryHandle, data: any, target: any?) -> any,
-    name: (self: QueryHandle) -> string,
-    stats: (self: QueryHandle) -> Types.PacketStats,
+--[[
+    Server `request(data, target)` returns `Resp?` for a Player target and
+    `{ [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: (
+        self: QueryHandle<Req, Resp>,
+        fn: (request: Req, player: Player?) -> Resp?
+    ) -> Types.Connection,
+    request: (self: QueryHandle<Req, Resp>, data: Req, target: any?) -> Resp?,
+    name: (self: QueryHandle<Req, Resp>) -> string,
+    stats: (self: QueryHandle<Req, Resp>) -> Types.PacketStats,
 }
 
 -- Public -----------------------------------------------------------------
 
 local Query = {}
 
-function Query.define(
+function Query.define<Req, Resp>(
     name: string,
-    requestCodec: Types.InternalCodec<any>,
-    responseCodec: Types.InternalCodec<any>,
+    requestCodec: Types.InternalCodec<Req>,
+    responseCodec: Types.InternalCodec<Resp>,
     options: Types.QueryOptions?
-): QueryHandle
-    local opts = options or ({} :: Types.QueryOptions)
+): QueryHandle<Req, Resp>
+    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)
 
@@ -89,6 +143,7 @@ function Query.define(
 
     reqReg.partner = respReg.id
 
+    -- Single active handler; replacing it disconnects the prior one via handlerToken.
     local activeHandler: ((any, Player?) -> any)? = nil
     local handlerToken = 0
 
@@ -113,18 +168,22 @@ function Query.define(
         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
@@ -134,10 +193,10 @@ function Query.define(
         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
@@ -146,30 +205,41 @@ function Query.define(
     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
@@ -183,85 +253,64 @@ function Query.define(
         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: QueryHandle,
-            fn: (request: any, player: Player?) -> any
+            _self: Self,
+            fn: (request: Req, player: Player?) -> Resp?
         ): Types.Connection
             handlerToken += 1
             local myToken = handlerToken
-            activeHandler = fn
-
-            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
+            activeHandler = fn :: any
+
+            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: QueryHandle, data: any, target: any?): any
+        request = function(_self: Self, data: Req, target: any?): Resp?
             if IS_SERVER then
                 return requestFromServer(data, target)
             end
             return requestFromClient(data)
         end,
 
-        name = function(_self: QueryHandle): string
+        name = function(_self: Self): string
             return name
         end,
 
-        stats = function(_self: QueryHandle): Types.PacketStats
+        stats = function(_self: Self): Types.PacketStats
             return {
                 bytesSent = reqReg.bytesSent + respReg.bytesSent,
                 bytesReceived = reqReg.bytesReceived + respReg.bytesReceived,
@@ -272,7 +321,7 @@ function Query.define(
         end,
     }
 
-    return table.freeze(handle) :: QueryHandle
+    return table.freeze(handle) :: QueryHandle<Req, Resp>
 end
 
 function Query.pendingCount(): number