@axpecter/lync 1.5.2 → 2.1.0

package/src/api/Packet.luau

@@ -1,200 +1,234 @@
 --!strict
 --!optimize 2
--- Packet definition and send/listen API.
+-- Packet definition, send, on, once, wait, stats.
 
+local Players = game:GetService("Players")
 local RunService = game:GetService("RunService")
 
-local Client = require(script.Parent.Parent.transport.Client)
+local Baseline = require(script.Parent.Parent.internal.Baseline)
+local Channel = require(script.Parent.Parent.internal.Channel)
+local Middleware = require(script.Parent.Parent.internal.Middleware)
 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 Codec<T> = Types.Codec<T>
-type InternalCodec<T> = Types.InternalCodec<T>
-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 serverWriteToSet = Server.writeToSet
-local clientWrite = Client.write
-
-local DELTA_TARGETED = 1
-local DELTA_BROADCAST = 2
-
 -- Private -------------------------------------------------------------
 
-type PacketFields = {
-    _id: number,
-    _name: string,
-    _codec: Codec<any>,
-    _isUnreliable: boolean,
-    _isDelta: boolean,
-    _deltaMode: number,
-    _signal: Signal.Signal,
-}
-
--- Server-only metatable. Single send() dispatches on target type.
-local ServerImpl = {}
-ServerImpl.__index = ServerImpl
-
-export type Packet = typeof(setmetatable({} :: PacketFields, ServerImpl))
-
-function ServerImpl.listen(self: Packet, callback: (...any) -> ()): Connection
-    return self._signal:connect(callback)
-end
-
-function ServerImpl.once(self: Packet, callback: (...any) -> ()): Connection
-    return self._signal:once(callback)
-end
-
-function ServerImpl.wait(self: Packet): ...any
-    return self._signal:wait()
-end
-
-function ServerImpl.disconnectAll(self: Packet): ()
-    self._signal:disconnectAll()
-end
-
-local function checkDeltaMode(self: Packet, 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}"`)
+local function resolveTimestampMode(ts: string?): (number, number)
+    if ts == "frame" then
+        Channel.enableTimestamps()
+        return Channel.TS_FRAME, 2
+    elseif ts == "offset" then
+        Channel.enableTimestamps()
+        return Channel.TS_OFFSET, 3
+    elseif ts == "full" then
+        Channel.enableTimestamps()
+        return Channel.TS_FULL, 9
     end
+    return Channel.TS_NONE, 1
 end
 
-function ServerImpl.send(self: Packet, data: any, target: any?): ()
-    if target == nil then
-        error("[Lync] Server packet:send requires a target")
-    end
+-- Public --------------------------------------------------------------
 
-    local id = self._id
-    local name = self._name
-    local codec = self._codec
-    local isUnreliable = self._isUnreliable
+local Packet = {}
 
-    -- Single player
-    if typeof(target) == "Instance" then
-        checkDeltaMode(self, DELTA_TARGETED)
-        serverWriteTo(target :: Player, id, name, codec, data, isUnreliable)
-        return
-    end
+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,
+}
 
-    -- Must be a table from here
-    local tag = target._tag
+function Packet.define(
+    name: string,
+    codec: Types.InternalCodec<any>,
+    options: Types.PacketOptions?
+): PacketHandle
+    local opts = options or {} :: Types.PacketOptions
+    local isUnreliable = opts.unreliable or false
 
-    -- Lync.all sentinel
-    if tag == "all" then
-        checkDeltaMode(self, DELTA_BROADCAST)
-        serverWriteToAll(id, name, codec, data, isUnreliable)
-        return
+    if isUnreliable and (codec :: any)._isDelta then
+        error(`[Lync] Lync.packet: "{name}" cannot use delta codecs with unreliable transport`)
     end
 
-    -- Lync.except(player, ...) descriptor
-    if tag == "except" then
-        checkDeltaMode(self, DELTA_BROADCAST)
-        serverWriteToAllExcept(target._set, id, name, codec, data, isUnreliable)
-        return
+    if (codec :: any)._hasUnknown and not opts.validate then
+        warn(
+            `[Lync] Lync.packet: "{name}" uses unknown codec without validate — data bypasses schema validation`
+        )
     end
 
-    -- Group object
-    if tag == "group" then
-        checkDeltaMode(self, DELTA_BROADCAST)
-        serverWriteToSet(target:getSet(), id, name, codec, data, isUnreliable)
-        return
+    if (codec :: any)._isDelta then
+        Baseline.markHasDelta()
     end
 
-    -- Player list(array)
-    checkDeltaMode(self, DELTA_TARGETED)
-    serverWriteToList(target :: { Player }, id, name, codec, data, isUnreliable)
-end
-
-table.freeze(ServerImpl)
+    local tsMode, headerSize = resolveTimestampMode(opts.timestamp)
+    local needsGate = IS_SERVER
 
--- Client-only metatable. Has send(), no target needed.
-local ClientImpl = {}
-ClientImpl.__index = ClientImpl
+    local openFn = Channel.resolveOpenFn(tsMode, name)
 
-function ClientImpl.listen(self: Packet, callback: (...any) -> ()): Connection
-    return self._signal:connect(callback)
-end
-
-function ClientImpl.once(self: Packet, callback: (...any) -> ()): Connection
-    return self._signal:once(callback)
-end
-
-function ClientImpl.wait(self: Packet): ...any
-    return self._signal:wait()
-end
-
-function ClientImpl.disconnectAll(self: Packet): ()
-    self._signal:disconnectAll()
-end
-
-function ClientImpl.send(self: Packet, data: any): ()
-    clientWrite(self._id, self._name, self._codec, data, self._isUnreliable)
-end
-
-table.freeze(ClientImpl)
-
--- Public --------------------------------------------------------------
+    local reg = Registry.register(
+        name,
+        Registry.KIND_PACKET,
+        codec,
+        isUnreliable,
+        nil,
+        needsGate,
+        headerSize,
+        tsMode,
+        openFn,
+        opts.rateLimit,
+        opts.validate,
+        opts.maxPayloadBytes
+    )
 
-local PacketModule = {}
+    -- Lazy-require Server/Client to avoid circular dependency
+    local _server: any = nil
+    local _client: any = nil
 
-function PacketModule.define(name: string, config: PacketConfig<any>): Packet
-    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}"`)
+    local function getServer(): any
+        if not _server then
+            _server = require(script.Parent.Parent.transport.Server)
+        end
+        return _server
     end
 
-    local isUnreliable = config.unreliable or false
+    local function getClient(): any
+        if not _client then
+            _client = require(script.Parent.Parent.transport.Client)
+        end
+        return _client
+    end
 
-    if (config.value :: InternalCodec<any>)._isDelta and isUnreliable then
-        error(`[Lync] Delta codec requires reliable delivery: "{name}"`)
+    local handle: any = {}
+
+    function handle.send(self: PacketHandle, data: any, target: any?): ()
+        if Middleware.hasSendHooks() then
+            data = Middleware.runSend(data, name, nil)
+            if typeof(data) == "table" and (data :: any)._lyncDrop then
+                return
+            end
+        end
+
+        if IS_SERVER then
+            if target == nil then
+                error(`[Lync] Packet "{name}": server send requires a target`)
+            end
+
+            local Server = getServer()
+
+            if typeof(target) == "Instance" and target:IsA("Player") then
+                local ch = Server.getChannel(target :: Player, isUnreliable)
+                Channel.writeBatch(ch, reg, data)
+                if Channel.statsEnabled() then
+                    reg.fires += 1
+                end
+                return
+            end
+
+            if typeof(target) == "table" then
+                local tbl = target :: any
+
+                if tbl._lyncAll then
+                    for _, player in Players:GetPlayers() do
+                        local ch = Server.getChannel(player, isUnreliable)
+                        Channel.writeBatch(ch, reg, data)
+                    end
+                    if Channel.statsEnabled() then
+                        reg.fires += 1
+                    end
+                    return
+                end
+
+                if tbl._lyncExcept then
+                    local excluded = tbl._excluded :: { [Player]: boolean }
+                    for _, player in Players:GetPlayers() do
+                        if not excluded[player] then
+                            local ch = Server.getChannel(player, isUnreliable)
+                            Channel.writeBatch(ch, reg, data)
+                        end
+                    end
+                    if Channel.statsEnabled() then
+                        reg.fires += 1
+                    end
+                    return
+                end
+
+                if tbl._lyncGroup then
+                    local members = tbl._members :: { [Player]: boolean }
+                    for player in members do
+                        local ch = Server.getChannel(player, isUnreliable)
+                        Channel.writeBatch(ch, reg, data)
+                    end
+                    if Channel.statsEnabled() then
+                        reg.fires += 1
+                    end
+                    return
+                end
+
+                for _, player in tbl do
+                    if typeof(player) == "Instance" and (player :: Instance):IsA("Player") then
+                        local ch = Server.getChannel(player :: Player, isUnreliable)
+                        Channel.writeBatch(ch, reg, data)
+                    end
+                end
+                if Channel.statsEnabled() then
+                    reg.fires += 1
+                end
+                return
+            end
+
+            error(
+                `[Lync] Packet "{name}": expected Player, table, Group, or Lync.all as target, got {typeof(
+                    target
+                )}`
+            )
+        else
+            local Client = getClient()
+            local ch = Client.getChannel(isUnreliable)
+            Channel.writeBatch(ch, reg, data)
+            if Channel.statsEnabled() then
+                reg.fires += 1
+            end
+        end
     end
 
-    local signal = Signal.create()
+    function handle.on(_self: PacketHandle, fn: (...any) -> ()): Types.Connection
+        return reg.signal:connect(fn)
+    end
 
-    local reg = Registry.register(
-        name,
-        config.value,
-        isUnreliable,
-        signal,
-        config.rateLimit,
-        config.validate,
-        config.maxPayloadBytes
-    )
+    function handle.once(_self: PacketHandle, fn: (...any) -> ()): Types.Connection
+        local conn: Types.Connection
+        conn = reg.signal:connect(function(...: any)
+            conn:disconnect()
+            fn(...)
+        end)
+        return conn
+    end
 
-    local isDelta = (config.value :: InternalCodec<any>)._isDelta == true
+    function handle.wait(_self: PacketHandle): ...any
+        return reg.signal:wait()
+    end
 
-    local fields: PacketFields = {
-        _id = reg.id,
-        _name = reg.name,
-        _codec = reg.codec,
-        _isUnreliable = isUnreliable,
-        _isDelta = isDelta,
-        _deltaMode = 0,
-        _signal = signal,
-    }
+    function handle.name(_self: PacketHandle): string
+        return reg.name
+    end
 
-    if IS_SERVER then
-        return setmetatable(fields, ServerImpl)
+    function handle.stats(_self: PacketHandle): Types.PacketStats
+        return {
+            bytesSent = reg.bytesSent,
+            bytesReceived = reg.bytesReceived,
+            fires = reg.fires,
+            recvFires = reg.recvFires,
+            drops = reg.drops,
+        }
     end
-    return setmetatable(fields, ClientImpl) :: Packet
+
+    return table.freeze(handle)
 end
 
-return table.freeze(PacketModule)
+return table.freeze(Packet)