@axpecter/lync 2.0.0 → 2.1.0

package/src/init.luau

@@ -1,247 +1,359 @@
 --!strict
 --!optimize 2
--- Public API.
+-- Lync: buffer networking for Roblox.
 
 local RunService = game:GetService("RunService")
 
--- Codec: primitive
-local BoolCodec = require(script.codec.primitive.Bool)
-local Float16 = require(script.codec.primitive.Float16)
-local NumberCodec = require(script.codec.primitive.Number)
-
--- Codec: datatype
-local BufferCodec = require(script.codec.datatype.Buffer)
-local CFrameCodec = require(script.codec.datatype.CFrame)
-local ColorCodec = require(script.codec.datatype.Color)
-local InstanceCodec = require(script.codec.datatype.Instance)
-local IntVectorCodec = require(script.codec.datatype.IntVector)
-local NumberRangeCodec = require(script.codec.datatype.NumberRange)
-local RayCodec = require(script.codec.datatype.Ray)
-local RectCodec = require(script.codec.datatype.Rect)
-local RegionCodec = require(script.codec.datatype.Region)
-local SequenceCodec = require(script.codec.datatype.Sequence)
-local StringCodec = require(script.codec.datatype.String)
-local UDimCodec = require(script.codec.datatype.UDim)
-local VectorCodec = require(script.codec.datatype.Vector)
-
--- Codec: composite
-local Array = require(script.codec.composite.Array)
-local Map = require(script.codec.composite.Map)
-local Optional = require(script.codec.composite.Optional)
-local Struct = require(script.codec.composite.Struct)
-local Tagged = require(script.codec.composite.Tagged)
-local Tuple = require(script.codec.composite.Tuple)
-
--- Codec: meta
-local Auto = require(script.codec.meta.Auto)
-local Bitfield = require(script.codec.meta.Bitfield)
-local Custom = require(script.codec.meta.Custom)
-local EnumCodec = require(script.codec.meta.Enum)
-local Nothing = require(script.codec.meta.Nothing)
-local Quantized = require(script.codec.meta.Quantized)
-local Unknown = require(script.codec.meta.Unknown)
-
--- Internal
+local Base = require(script.codec.Base)
 local Channel = require(script.internal.Channel)
+local Gate = require(script.transport.Gate)
+local Group = require(script.api.Group)
 local Middleware = require(script.internal.Middleware)
+local Packet = require(script.api.Packet)
 local Pool = require(script.internal.Pool)
-
--- Transport
-local Client = require(script.transport.Client)
-local Gate = require(script.transport.Gate)
-local Server = require(script.transport.Server)
-
--- API
-local GroupModule = require(script.api.Group)
-local NamespaceModule = require(script.api.Namespace)
-local PacketModule = require(script.api.Packet)
-local QueryModule = require(script.api.Query)
-local ScopeModule = require(script.api.Scope)
-local SignalModule = require(script.api.Signal)
-
--- Type re-exports -----------------------------------------------------
-
+local Query = require(script.api.Query)
+local Registry = require(script.internal.Registry)
+local Scope = require(script.api.Scope)
 local Types = require(script.Types)
 
-export type Codec<T> = Types.Codec<T>
-export type InternalCodec<T> = Types.InternalCodec<T>
-export type Connection = Types.Connection
-export type RateLimitConfig = Types.RateLimitConfig
-export type PacketConfig<T> = Types.PacketConfig<T>
-export type QueryConfig<R, S> = Types.QueryConfig<R, S>
-
-export type Packet = PacketModule.Packet
-export type Query = QueryModule.Query
-export type Group = GroupModule.Group
-export type Scope = ScopeModule.Scope
-export type Namespace = NamespaceModule.Namespace
-export type Signal = SignalModule.Signal
-export type NamespaceConfig = Types.NamespaceConfig
+-- Codecs
+local ArrayC = require(script.codec.composite.Array)
+local AutoC = require(script.codec.meta.Auto)
+local BitfieldC = require(script.codec.meta.Bitfield)
+local BoolC = require(script.codec.primitive.Bool)
+local BufferC = require(script.codec.datatype.Buffer)
+local CFrameC = require(script.codec.datatype.CFrame)
+local ColorC = require(script.codec.datatype.Color)
+local CustomC = require(script.codec.meta.Custom)
+local EnumC = require(script.codec.meta.Enum)
+local Float16C = require(script.codec.primitive.Float16)
+local FloatC = require(script.codec.meta.Float)
+local IVC = require(script.codec.datatype.IntVector)
+local InstanceC = require(script.codec.datatype.Instance)
+local IntC = require(script.codec.primitive.Int)
+local MapC = require(script.codec.composite.Map)
+local NRC = require(script.codec.datatype.NumberRange)
+local NothingC = require(script.codec.meta.Nothing)
+local NumberC = require(script.codec.primitive.Number)
+local OptionalC = require(script.codec.composite.Optional)
+local RayC = require(script.codec.datatype.Ray)
+local RectC = require(script.codec.datatype.Rect)
+local RegionC = require(script.codec.datatype.Region)
+local SeqC = require(script.codec.datatype.Sequence)
+local StringC = require(script.codec.datatype.String)
+local StructC = require(script.codec.composite.Struct)
+local TaggedC = require(script.codec.composite.Tagged)
+local TupleC = require(script.codec.composite.Tuple)
+local UDimC = require(script.codec.datatype.UDim)
+local UnknownC = require(script.codec.meta.Unknown)
+local VectorC = require(script.codec.datatype.Vector)
 
 -- Constants -----------------------------------------------------------
 
-local ALL = table.freeze({ _tag = "all" })
+local IS_SERVER = RunService:IsServer()
+
+-- State ---------------------------------------------------------------
+
+local _started = false
+local _flushRate = 60
+local _flushAccum = 0
+local _flushConn: RBXScriptConnection? = nil
 
 -- Private -------------------------------------------------------------
 
+local DROP = table.freeze({ _lyncDrop = true })
+local ALL = table.freeze({ _lyncAll = true })
+
 local function except(...: any): any
-    local count = select("#", ...)
-    local set = {} :: { [Player]: true }
-    for i = 1, count do
-        set[select(i, ...)] = true
+    local excluded: { [Player]: boolean } = {}
+
+    for i = 1, select("#", ...) do
+        local arg = select(i, ...)
+        if typeof(arg) == "Instance" and (arg :: Instance):IsA("Player") then
+            excluded[arg :: Player] = true
+        elseif typeof(arg) == "table" and (arg :: any)._lyncGroup then
+            for player in (arg :: any)._members do
+                excluded[player] = true
+            end
+        else
+            error("[Lync] except: argument must be a Player or Group")
+        end
     end
-    return { _tag = "except", _set = set }
+
+    return table.freeze({ _lyncExcept = true, _excluded = excluded })
 end
 
-local function start(): ()
-    if RunService:IsServer() then
-        Server.start()
+local function setupFlush(): ()
+    local flushFn: () -> ()
+
+    if IS_SERVER then
+        local Server = require(script.transport.Server)
+        flushFn = function(): ()
+            Server.flush()
+        end
     else
-        Client.start()
+        local Client = require(script.transport.Client)
+        flushFn = function(): ()
+            Client.flush()
+        end
     end
+
+    _flushConn = RunService.Heartbeat:Connect(function(dt: number)
+        if _flushRate >= 60 then
+            flushFn()
+        else
+            _flushAccum += dt
+            local interval = 1 / _flushRate
+            if _flushAccum >= interval then
+                _flushAccum -= interval
+                -- Prevent drift accumulation
+                if _flushAccum >= interval then
+                    _flushAccum = 0
+                end
+                flushFn()
+            end
+        end
+    end)
 end
 
 -- Public --------------------------------------------------------------
 
-local IS_SERVER = RunService:IsServer()
+local Lync: any = {}
 
-local function flush(): ()
-    if IS_SERVER then
-        Server.flush()
-    else
-        Client.flush()
+-- Lifecycle -----------------------------------------------------------
+
+function Lync.configure(options: Types.ConfigureOptions): ()
+    if _started then
+        error("[Lync] Lync.configure: must be called before Lync.start()")
+    end
+
+    if options.channelMaxSize then
+        local size = options.channelMaxSize
+        if size < 4096 or size > 1048576 then
+            error("[Lync] Lync.configure: channelMaxSize must be 4096-1048576")
+        end
+        Channel.setMaxSize(size)
+        Base.setMaxSize(size)
+    end
+
+    if options.validationDepth then
+        local depth = options.validationDepth
+        if depth < 4 or depth > 32 then
+            error("[Lync] Lync.configure: validationDepth must be 4-32")
+        end
+        Gate.setDepth(depth)
+    end
+
+    if options.poolSize then
+        local size = options.poolSize
+        if size < 2 or size > 128 then
+            error("[Lync] Lync.configure: poolSize must be 2-128")
+        end
+        Pool.setMaxSize(size)
+    end
+
+    if options.bandwidthLimit then
+        Gate.configureBandwidth(options.bandwidthLimit.softLimit, options.bandwidthLimit.maxStrikes)
+    end
+
+    if options.globalRateLimit then
+        Gate.configureGlobalRateLimit(options.globalRateLimit.maxPerSecond)
+    end
+
+    if options.stats then
+        Channel.enableStats()
+        if IS_SERVER then
+            local Server = require(script.transport.Server)
+            Server.enableStats()
+        end
     end
 end
 
-local function setFlushRate(hz: number): ()
+function Lync.start(): ()
+    if _started then
+        error("[Lync] Lync.start: already started")
+    end
+    _started = true
+
     if IS_SERVER then
-        Server.setFlushRate(hz)
+        local Server = require(script.transport.Server)
+        Server.start()
     else
-        Client.setFlushRate(hz)
+        local Client = require(script.transport.Client)
+        Client.start()
     end
-end
 
-local function getPlayerStats(player: Player): any?
-    return Server.getPlayerStats(player)
+    setupFlush()
 end
 
-local function resetStats(): ()
-    Server.resetStats()
+-- `Lync.started` is a read-only property backed by _started
+Lync.started = false
+
+-- Definitions ---------------------------------------------------------
+
+Lync.packet = Packet.define
+Lync.query = Query.define
+Lync.group = Group.create
+Lync.scope = Scope.create
+
+-- Targeting -----------------------------------------------------------
+
+Lync.all = ALL
+Lync.except = except
+Lync.DROP = DROP
+
+-- Middleware ----------------------------------------------------------
+
+Lync.onSend = Middleware.onSend
+Lync.onReceive = Middleware.onReceive
+Lync.onDrop = Middleware.onDrop
+
+-- Runtime control -----------------------------------------------------
+
+function Lync.flush(): ()
+    if not _started then
+        error("[Lync] Lync.flush: must call Lync.start() first")
+    end
+
+    if IS_SERVER then
+        local Server = require(script.transport.Server)
+        Server.flush()
+    else
+        local Client = require(script.transport.Client)
+        Client.flush()
+    end
+
+    -- Reset accumulator to prevent double-flush
+    _flushAccum = 0
 end
 
-local function setBandwidthLimit(softLimit: number, maxStrikes: number): ()
-    Server.setBandwidthLimit(softLimit, maxStrikes)
+function Lync.flushRate(hz: number): ()
+    if hz < 1 or hz > 60 then
+        error("[Lync] Lync.flushRate: hz must be 1-60")
+    end
+    _flushRate = hz
+    _flushAccum = 0
 end
 
-local Lync = {
-    VERSION = "2.0.0",
-
-    -- Lifecycle
-    start = start,
-
-    -- Definition
-    definePacket = PacketModule.define,
-    defineQuery = QueryModule.define,
-    defineNamespace = NamespaceModule.define,
-
-    -- Primitives
-    u8 = NumberCodec.u8,
-    u16 = NumberCodec.u16,
-    u32 = NumberCodec.u32,
-    i8 = NumberCodec.i8,
-    i16 = NumberCodec.i16,
-    i32 = NumberCodec.i32,
-    f32 = NumberCodec.f32,
-    f64 = NumberCodec.f64,
-    bool = BoolCodec.bool,
-    f16 = Float16.f16,
-
-    -- Datatypes
-    string = StringCodec.string,
-    boundedString = StringCodec.bounded,
-    vec2 = VectorCodec.vec2,
-    vec3 = VectorCodec.vec3,
-    cframe = CFrameCodec.cframe,
-    color3 = ColorCodec.color3,
-    inst = InstanceCodec.inst,
-    buff = BufferCodec.buff,
-    udim = UDimCodec.udim,
-    udim2 = UDimCodec.udim2,
-    numberRange = NumberRangeCodec.numberRange,
-    rect = RectCodec.rect,
-    vec2int16 = IntVectorCodec.vec2int16,
-    vec3int16 = IntVectorCodec.vec3int16,
-    region3 = RegionCodec.region3,
-    region3int16 = RegionCodec.region3int16,
-    ray = RayCodec.ray,
-    numberSequence = SequenceCodec.numberSequence,
-    colorSequence = SequenceCodec.colorSequence,
-
-    -- Composites
-    struct = Struct.struct,
-    deltaStruct = Struct.deltaStruct,
-    deltaArray = Array.deltaArray,
-    deltaMap = Map.deltaMap,
-    array = Array.array,
-    map = Map.map,
-    optional = Optional.optional,
-    tuple = Tuple.define,
-    tagged = Tagged.define,
-
-    -- Meta
-    enum = EnumCodec.define,
-    quantizedFloat = Quantized.float,
-    quantizedVec3 = Quantized.vec3,
-    bitfield = Bitfield.define,
-    custom = Custom.define,
-
-    nothing = Nothing.nothing,
-    unknown = Unknown.unknown,
-    auto = Auto.auto,
-
-    -- Hooks
-    onDrop = Gate.onDrop,
-    onSend = Middleware.addSend,
-    onReceive = Middleware.addReceive,
-
-    -- Target descriptors
-    all = ALL,
-    except = except,
-
-    -- Middleware sentinel
-    DROP = Middleware.DROP,
-
-    -- Groups
-    createGroup = GroupModule.create,
-
-    -- Scope
-    scope = ScopeModule.create,
-
-    -- Configuration (call before start)
-    setChannelMaxSize = Channel.setMaxSize,
-    setValidationDepth = Gate.setMaxDepth,
-    setPoolSize = Pool.setMaxSize,
-
-    -- Runtime configuration
-    flush = flush,
-    setFlushRate = setFlushRate,
-
-    -- Stats (default off; call enableStats() to activate)
-    enableStats = Channel.enableStats,
-    getPlayerStats = getPlayerStats,
-    resetStats = resetStats,
-
-    -- Security (server-only)
-    setBandwidthLimit = setBandwidthLimit,
-
-    -- Introspection
-    queryPendingCount = QueryModule.pendingCount,
-
-    -- Packet capture (server-only, debug)
-    startCapture = if IS_SERVER then Server.startCapture else nil,
-    stopCapture = if IS_SERVER then Server.stopCapture else nil,
-    dumpCaptures = if IS_SERVER then Server.dumpCaptures else nil,
-}
-
-Lync.default = Lync
-return table.freeze(Lync)
+-- Stats ---------------------------------------------------------------
+
+Lync.stats = table.freeze({
+    player = function(player: Player): Types.PlayerStats?
+        if not IS_SERVER then
+            return nil
+        end
+        local Server = require(script.transport.Server)
+        return Server.getPlayerStats(player)
+    end,
+
+    reset = function(): ()
+        if IS_SERVER then
+            local Server = require(script.transport.Server)
+            Server.resetStats()
+        end
+
+        -- Reset per-registration stats
+        for _, reg in Registry.all() do
+            reg.bytesSent = 0
+            reg.bytesReceived = 0
+            reg.fires = 0
+            reg.recvFires = 0
+            reg.drops = 0
+        end
+    end,
+})
+
+-- Debug ---------------------------------------------------------------
+
+Lync.debug = table.freeze({
+    capture = function(_label: string?): ()
+        -- TODO: Implement capture recording
+    end,
+
+    stop = function(): ()
+        -- TODO: Implement capture stop
+    end,
+
+    dump = function(): ()
+        -- TODO: Implement capture dump
+    end,
+
+    pending = function(): number
+        return Query.pendingCount()
+    end,
+
+    registrations = function(): { any }
+        local regs = Registry.all()
+        local result = table.create(#regs)
+
+        for i, reg in regs do
+            result[i] = table.freeze({
+                name = reg.name,
+                id = reg.id,
+                kind = reg.kind,
+                isUnreliable = reg.isUnreliable,
+            })
+        end
+
+        return table.freeze(result)
+    end,
+})
+
+-- Codecs --------------------------------------------------------------
+
+Lync.int = IntC.int
+Lync.float = FloatC.float
+Lync.f16 = Float16C.f16
+Lync.f32 = NumberC.f32
+Lync.f64 = NumberC.f64
+Lync.bool = BoolC.bool
+Lync.string = StringC
+Lync.buff = BufferC.buff
+Lync.vec2 = VectorC.vec2
+Lync.vec3 = VectorC.vec3
+Lync.cframe = CFrameC.cframe
+Lync.color3 = ColorC.color3
+Lync.inst = InstanceC.inst
+Lync.udim = UDimC.udim
+Lync.udim2 = UDimC.udim2
+Lync.numberRange = NRC.numberRange
+Lync.rect = RectC.rect
+Lync.ray = RayC.ray
+Lync.region3 = RegionC.region3
+Lync.region3int16 = RegionC.region3int16
+Lync.vec2int16 = IVC.vec2int16
+Lync.vec3int16 = IVC.vec3int16
+Lync.numberSequence = SeqC.numberSequence
+Lync.colorSequence = SeqC.colorSequence
+Lync.struct = StructC.struct
+Lync.deltaStruct = StructC.deltaStruct
+Lync.array = ArrayC.array
+Lync.deltaArray = ArrayC.deltaArray
+Lync.map = MapC.map
+Lync.deltaMap = MapC.deltaMap
+Lync.optional = OptionalC.optional
+Lync.tuple = TupleC.define
+Lync.tagged = TaggedC.define
+Lync.enum = EnumC.define
+Lync.bitfield = BitfieldC.define
+Lync.custom = CustomC.define
+Lync.nothing = NothingC.nothing
+Lync.unknown = UnknownC.unknown
+Lync.auto = AutoC.auto
+
+-- Wrap in metatable for `Lync.started` property -----------------------
+
+local LyncProxy = setmetatable({}, {
+    __index = function(_self: any, key: string): any
+        if key == "started" then
+            return _started
+        end
+        return Lync[key]
+    end,
+
+    __newindex = function(): ()
+        error("[Lync] Lync: module table is read-only")
+    end,
+})
+
+return LyncProxy

package/src/internal/Baseline.luau

@@ -1,45 +1,50 @@
 --!strict
 --!optimize 2
--- Read-side baseline cache keyed by source(player or client sentinel).
+-- Read-side delta cache for delta codecs.
 
 -- State ---------------------------------------------------------------
 
-local _readKey = false :: any
-local _readCaches = {} :: { [any]: { [number]: any } }
+local _caches: { [number]: { [any]: any } } = {}
+local _currentKey: any = false
+local _hasDelta = false
 
 -- Public --------------------------------------------------------------
 
 local Baseline = {}
 
--- One-way latch: set to true on first delta write, never reset. This
--- avoids a setReadKey call on every non-delta frame at the cost of a
--- cheap branch once deltas are first used in the session.
-Baseline.hasDelta = false
-
 function Baseline.setReadKey(key: any): ()
-    _readKey = key
+    _currentKey = key
 end
 
-function Baseline.getCache(deltaId: number): any
-    local map = _readCaches[_readKey]
-    return map and map[deltaId]
+function Baseline.getCache(deltaId: number): any?
+    local perPlayer = _caches[deltaId]
+    if not perPlayer then
+        return nil
+    end
+    return perPlayer[_currentKey]
 end
 
-function Baseline.setCache(deltaId: number, data: any): ()
-    if not Baseline.hasDelta then
-        Baseline.hasDelta = true
+function Baseline.setCache(deltaId: number, value: any): ()
+    local perPlayer = _caches[deltaId]
+    if not perPlayer then
+        perPlayer = {}
+        _caches[deltaId] = perPlayer
     end
-    local map = _readCaches[_readKey]
-    if not map then
-        map = {}
-        _readCaches[_readKey] = map
+    perPlayer[_currentKey] = value
+end
+
+function Baseline.clearPlayer(key: any): ()
+    for _, perPlayer in _caches do
+        perPlayer[key] = nil
     end
-    map[deltaId] = data
 end
 
-function Baseline.clearSource(key: any): ()
-    _readCaches[key] = nil
+function Baseline.markHasDelta(): ()
+    _hasDelta = true
+end
+
+function Baseline.hasDelta(): boolean
+    return _hasDelta
 end
 
--- Not frozen: hasDelta is mutated at runtime by setCache.
-return Baseline
+return table.freeze(Baseline)