@axpecter/lync 2.2.1 → 2.3.1

package/src/transport/Gate.luau

@@ -2,6 +2,7 @@
 --!native
 -- Schema-aware validation and rate limiting.
 
+local Log = require(script.Parent.Parent.util.Log)
 local Types = require(script.Parent.Parent.Types)
 
 -- Constants --------------------------------------------------------------
@@ -9,6 +10,9 @@ local Types = require(script.Parent.Parent.Types)
 local DEFAULT_DEPTH = 16
 local STRIKE_DECAY_SEC = 5
 
+local VEC2_AXES = table.freeze({ "X", "Y" })
+local VEC3_AXES = table.freeze({ "X", "Y", "Z" })
+
 -- State ------------------------------------------------------------------
 
 local _depth = DEFAULT_DEPTH
@@ -27,17 +31,20 @@ local floor = math.floor
 local clock = os.clock
 local minN = math.min
 
-local function checkScalarBounds(value: number, minV: number?, maxV: number?): (boolean, string?)
+-- Validators return string?: nil = accepted, non-nil = rejection reason.
+local validateWithCodec -- forward decl (recursive)
+
+local function checkScalarBounds(value: number, minV: number?, maxV: number?): string?
     if not isfinite(value) then
-        return false, "non-finite"
+        return "non-finite"
     end
     if minV and value < minV then
-        return false, `below min {minV}`
+        return `below min {minV}`
     end
     if maxV and value > maxV then
-        return false, `above max {maxV}`
+        return `above max {maxV}`
     end
-    return true, nil
+    return nil
 end
 
 local function checkVectorComponents(
@@ -45,22 +52,24 @@ local function checkVectorComponents(
     components: { string },
     minV: number,
     maxV: number
-): (boolean, string?)
+): string?
     for _, axis in components do
         local v = value[axis]
         if not isfinite(v) then
-            return false, `component {axis} non-finite`
+            return `component {axis} non-finite`
         end
         if v < minV or v > maxV then
-            return false, `component {axis} ({v}) out of [{minV}, {maxV}]`
+            return `component {axis} ({v}) out of [{minV}, {maxV}]`
         end
     end
-    return true, nil
+    return nil
 end
 
-local VEC2_AXES = table.freeze({ "X", "Y" })
-local VEC3_AXES = table.freeze({ "X", "Y", "Z" })
-
+--[[
+    Untyped fallback NaN/inf scan. Used when a codec lacks specific metadata
+    (e.g. user custom codec) and as the last step of validateWithCodec.
+    Bounded by `depth` so a self-referential table can't recurse forever.
+]]
 local function scanValue(value: any, depth: number): boolean
     if depth <= 0 then
         return true
@@ -125,168 +134,228 @@ local function scanValue(value: any, depth: number): boolean
     return true
 end
 
-local function validateWithCodec(
-    value: any,
-    codec: Types.InternalCodec<any>,
-    depth: number
-): (boolean, string?)
-    if depth <= 0 then
-        return true, nil
+local function validateString(value: any, codec: Types.InternalCodec<any>): string?
+    local maxLen = codec._maxStringLength
+    if maxLen and #(value :: string) > maxLen then
+        return `string length {#value} exceeds max {maxLen}`
+    end
+    return nil
+end
+
+local function validateEnum(value: any, codec: Types.InternalCodec<any>): string?
+    local valid = codec._enumValues
+    if valid and valid[value] == nil then
+        return `not a valid enum value: "{value}"`
+    end
+    return nil
+end
+
+local function validateInteger(value: any, codec: Types.InternalCodec<any>): string?
+    if not isfinite(value) then
+        return "non-finite"
+    end
+    if floor(value) ~= value then
+        return "non-integer"
+    end
+    return checkScalarBounds(value, codec._min, codec._max)
+end
+
+local function validateTagged(value: any, codec: Types.InternalCodec<any>, depth: number): string?
+    if typeof(value) ~= "table" then
+        return "expected table for tagged variant"
+    end
+    local tagField = codec._tagField :: string
+    local tagName = value[tagField]
+    if tagName == nil then
+        return `missing tagField "{tagField}"`
+    end
+    local variants = codec._variants :: { [string]: Types.InternalCodec<any> }
+    local variant = variants[tagName]
+    if not variant then
+        return `unknown variant "{tagName}"`
     end
+    return validateWithCodec(value, variant, depth - 1)
+end
+
+local function validateArray(value: any, codec: Types.InternalCodec<any>, depth: number): string?
+    if typeof(value) ~= "table" then
+        return "expected array"
+    end
+    local maxCount = codec._maxCount
+    local len = #value
+    if maxCount and len > maxCount then
+        return `array length {len} exceeds max {maxCount}`
+    end
+    local element = codec._element :: Types.InternalCodec<any>
+    local nextDepth = depth - 1
+    for i = 1, len do
+        local reason = validateWithCodec(value[i], element, nextDepth)
+        if reason then
+            return `[{i}]: {reason}`
+        end
+    end
+    return nil
+end
 
-    -- Optional: branch on nil before any other check.
-    if codec._isOptional then
+local function validateMap(value: any, codec: Types.InternalCodec<any>, depth: number): string?
+    if typeof(value) ~= "table" then
+        return "expected map"
+    end
+    local maxCount = codec._maxCount
+    local keyCodec = codec._keyCodec :: Types.InternalCodec<any>
+    local valCodec = codec._valueCodec :: Types.InternalCodec<any>
+    local nextDepth = depth - 1
+    local count = 0
+    for k, v in value do
+        count += 1
+        if maxCount and count > maxCount then
+            return `map size exceeds max {maxCount}`
+        end
+        local reason = validateWithCodec(k, keyCodec, nextDepth)
+        if reason then
+            return `key: {reason}`
+        end
+        reason = validateWithCodec(v, valCodec, nextDepth)
+        if reason then
+            return `value at key "{tostring(k)}": {reason}`
+        end
+    end
+    return nil
+end
+
+local function validateTuple(value: any, codec: Types.InternalCodec<any>, depth: number): string?
+    if typeof(value) ~= "table" then
+        return "expected tuple"
+    end
+    local elements = codec._elements :: { Types.InternalCodec<any> }
+    local nextDepth = depth - 1
+    for i = 1, #elements do
+        local reason = validateWithCodec(value[i], elements[i], nextDepth)
+        if reason then
+            return `[{i}]: {reason}`
+        end
+    end
+    return nil
+end
+
+local function validateStruct(value: any, codec: Types.InternalCodec<any>, depth: number): string?
+    if typeof(value) ~= "table" then
+        return "expected table for struct"
+    end
+    local nextDepth = depth - 1
+    for key, fieldCodec in codec._schema :: { [string]: Types.InternalCodec<any> } do
+        local fieldVal = value[key]
+        -- Bool fields default to false when missing; everything else must be present.
+        if fieldVal == nil and not fieldCodec._isBool then
+            return `missing field "{key}"`
+        end
+        local reason = validateWithCodec(fieldVal, fieldCodec, nextDepth)
+        if reason then
+            return `field "{key}": {reason}`
+        end
+    end
+    return nil
+end
+
+function validateWithCodec(value: any, codec: Types.InternalCodec<any>, depth: number): string?
+    -- Peel Optional layers in a loop so optional(optional(X)) chains stay flat.
+    while codec._isOptional do
+        if depth <= 0 then
+            return nil
+        end
         if value == nil then
-            return true, nil
+            return nil
         end
-        local inner = codec._inner :: Types.InternalCodec<any>
-        return validateWithCodec(value, inner, depth - 1)
+        codec = codec._inner :: Types.InternalCodec<any>
+        depth -= 1
+    end
+    if depth <= 0 then
+        return nil
     end
 
-    -- typeCheck (cheap fail-fast for non-composite codecs).
     local typeCheck = codec._typeCheck
     if typeCheck and typeof(value) ~= typeCheck then
-        return false, `expected {typeCheck}, got {typeof(value)}`
+        return `expected {typeCheck}, got {typeof(value)}`
     end
 
-    if codec._isBool then
-        return true, nil
+    if typeCheck == "string" then
+        local reason = validateString(value, codec)
+        if reason then
+            return reason
+        end
     end
 
-    -- Enum: value is a string (typeCheck already validated typeof);
-    -- decoded enums are guaranteed to be in the value set, but on
-    -- send-side a caller may pass an arbitrary string.
+    if codec._isBool then
+        return nil
+    end
     if codec._isEnum then
-        local valid = codec._enumValues
-        if valid and valid[value] == nil then
-            return false, `not a valid enum value: "{value}"`
-        end
-        return true, nil
+        return validateEnum(value, codec)
     end
-
     if codec._isInteger then
-        if not isfinite(value) then
-            return false, "non-finite"
-        end
-        if floor(value) ~= value then
-            return false, "non-integer"
-        end
-        return checkScalarBounds(value, codec._min, codec._max)
+        return validateInteger(value, codec)
     end
 
-    -- Vector quantized: per-component range check.
     if (typeCheck == "Vector2" or typeCheck == "Vector3") and codec._min and codec._max then
         local axes = if typeCheck == "Vector2" then VEC2_AXES else VEC3_AXES
         return checkVectorComponents(value, axes, codec._min, codec._max)
     end
-
-    -- Scalar quantized float (number with explicit range).
     if typeCheck == "number" and codec._min ~= nil and codec._max ~= nil then
         return checkScalarBounds(value, codec._min, codec._max)
     end
 
     if codec._isTagged then
-        if typeof(value) ~= "table" then
-            return false, "expected table for tagged variant"
-        end
-        local tagField = codec._tagField :: string
-        local tagName = value[tagField]
-        if tagName == nil then
-            return false, `missing tagField "{tagField}"`
-        end
-        local variants = codec._variants :: { [string]: Types.InternalCodec<any> }
-        local variant = variants[tagName]
-        if not variant then
-            return false, `unknown variant "{tagName}"`
-        end
-        return validateWithCodec(value, variant, depth - 1)
+        return validateTagged(value, codec, depth)
     end
-
     if codec._isArray then
-        if typeof(value) ~= "table" then
-            return false, "expected array"
-        end
-        local maxCount = codec._maxCount
-        local len = #value
-        if maxCount and len > maxCount then
-            return false, `array length {len} exceeds max {maxCount}`
-        end
-        local element = codec._element :: Types.InternalCodec<any>
-        local nextDepth = depth - 1
-        for i = 1, len do
-            local ok, reason = validateWithCodec(value[i], element, nextDepth)
-            if not ok then
-                return false, `[{i}]: {reason}`
-            end
-        end
-        return true, nil
+        return validateArray(value, codec, depth)
     end
-
     if codec._isMap then
-        if typeof(value) ~= "table" then
-            return false, "expected map"
-        end
-        local maxCount = codec._maxCount
-        local keyCodec = codec._keyCodec :: Types.InternalCodec<any>
-        local valCodec = codec._valueCodec :: Types.InternalCodec<any>
-        local nextDepth = depth - 1
-        local count = 0
-        for k, v in value do
-            count += 1
-            if maxCount and count > maxCount then
-                return false, `map size exceeds max {maxCount}`
-            end
-            local ok, reason = validateWithCodec(k, keyCodec, nextDepth)
-            if not ok then
-                return false, `key: {reason}`
-            end
-            ok, reason = validateWithCodec(v, valCodec, nextDepth)
-            if not ok then
-                return false, `value at key "{tostring(k)}": {reason}`
-            end
-        end
-        return true, nil
+        return validateMap(value, codec, depth)
     end
-
     if codec._isTuple then
-        if typeof(value) ~= "table" then
-            return false, "expected tuple"
-        end
-        local elements = codec._elements :: { Types.InternalCodec<any> }
-        local nextDepth = depth - 1
-        for i = 1, #elements do
-            local ok, reason = validateWithCodec(value[i], elements[i], nextDepth)
-            if not ok then
-                return false, `[{i}]: {reason}`
-            end
-        end
-        return true, nil
+        return validateTuple(value, codec, depth)
     end
-
     if codec._schema then
-        if typeof(value) ~= "table" then
-            return false, "expected table for struct"
-        end
-        local nextDepth = depth - 1
-        for key, fieldCodec in codec._schema do
-            local fieldVal = value[key]
-            if fieldVal == nil and not fieldCodec._isBool then
-                return false, `missing field "{key}"`
-            end
-            local ok, reason = validateWithCodec(fieldVal, fieldCodec, nextDepth)
-            if not ok then
-                return false, `field "{key}": {reason}`
-            end
-        end
-        return true, nil
+        return validateStruct(value, codec, depth)
     end
 
-    -- Fallback: NaN/inf scan for codecs without specific metadata
-    -- (raw f32/f64, untagged Roblox types, buffer, etc.).
+    -- No specific metadata: fall back to a depth-bounded NaN/inf scan.
     if not scanValue(value, depth) then
-        return false, "NaN/inf detected"
+        return "NaN/inf detected"
+    end
+    return nil
+end
+
+local function getOrCreateBucket(
+    map: { [Player]: Types.RateLimitState },
+    player: Player,
+    burst: number,
+    now: number
+): Types.RateLimitState
+    local state = map[player]
+    if not state then
+        state = { tokens = burst, lastRefill = now, lastAccepted = 0 }
+        map[player] = state
     end
-    return true, nil
+    return state
+end
+
+local function consumeToken(
+    state: Types.RateLimitState,
+    now: number,
+    capacity: number,
+    rate: number
+): boolean
+    local elapsed = now - state.lastRefill
+    state.lastRefill = now
+    state.tokens = minN(capacity, state.tokens + elapsed * rate)
+
+    if state.tokens >= 1 then
+        state.tokens -= 1
+        state.lastAccepted = now
+        return true
+    end
+    return false
 end
 
 -- Public -----------------------------------------------------------------
@@ -295,12 +364,12 @@ local Gate = {}
 
 function Gate.setDepth(depth: number): ()
     if depth < 1 then
-        error(`[Lync] Gate.setDepth: depth must be >= 1, got {depth}`)
+        Log.error(`depth must be >= 1, got {depth}`)
     end
     _depth = depth
 end
 
-function Gate.validate(value: any, codec: Types.InternalCodec<any>): (boolean, string?)
+function Gate.validate(value: any, codec: Types.InternalCodec<any>): string?
     return validateWithCodec(value, codec, _depth)
 end
 
@@ -322,12 +391,10 @@ function Gate.checkRateLimit(reg: Types.Registration, player: Player): boolean
         _rateLimits[reg.id] = perPacket
     end
 
-    local state = perPacket[player]
-    if not state then
-        state = { tokens = config.burst or 1, lastRefill = now, lastAccepted = 0 }
-        perPacket[player] = state
-    end
+    local burst = config.burst or 1
+    local state = getOrCreateBucket(perPacket, player, burst, now)
 
+    -- Cooldown form: reject anything within `cooldown` seconds of the last accept.
     if config.cooldown then
         if now - state.lastAccepted < config.cooldown then
             return false
@@ -340,17 +407,7 @@ function Gate.checkRateLimit(reg: Types.Registration, player: Player): boolean
     if not maxPerSecond then
         return true
     end
-
-    local elapsed = now - state.lastRefill
-    state.lastRefill = now
-    state.tokens = minN(config.burst or 1, state.tokens + elapsed * maxPerSecond)
-
-    if state.tokens >= 1 then
-        state.tokens -= 1
-        state.lastAccepted = now
-        return true
-    end
-    return false
+    return consumeToken(state, now, burst, maxPerSecond)
 end
 
 function Gate.checkGlobalRateLimit(player: Player): boolean
@@ -360,27 +417,14 @@ function Gate.checkGlobalRateLimit(player: Player): boolean
     end
 
     local now = clock()
-    local state = _globalLimits[player]
-    if not state then
-        state = { tokens = maxPS, lastRefill = now, lastAccepted = 0 }
-        _globalLimits[player] = state
-    end
-
-    local elapsed = now - state.lastRefill
-    state.lastRefill = now
-    state.tokens = minN(maxPS, state.tokens + elapsed * maxPS)
-
-    if state.tokens >= 1 then
-        state.tokens -= 1
-        return true
-    end
-    return false
+    local state = getOrCreateBucket(_globalLimits, player, maxPS, now)
+    return consumeToken(state, now, maxPS, maxPS)
 end
 
 --[[
-    Bandwidth check: frames at or below softLimit refund a strike;
-    over-soft frames add one. Strikes also decay with idle time so a
-    quiet player isn't penalized indefinitely.
+    Bandwidth check. Frames at or below softLimit refund a strike; frames
+    above add one. Strikes decay with idle time so a quiet player isn't
+    penalized indefinitely after a noisy burst.
 ]]
 function Gate.checkBandwidth(player: Player, bytes: number): boolean
     if not _bandwidthSoftLimit then
@@ -430,4 +474,15 @@ function Gate.clearPlayer(player: Player): ()
     end
 end
 
+function Gate.reset(): ()
+    _depth = DEFAULT_DEPTH
+    _globalMaxPerSecond = nil
+    _bandwidthSoftLimit = nil
+    _bandwidthMaxStrikes = 10
+    table.clear(_rateLimits)
+    table.clear(_globalLimits)
+    table.clear(_bandwidthStrikes)
+    table.clear(_bandwidthLastSeen)
+end
+
 return table.freeze(Gate)