@axpecter/lync 2.2.1 → 2.3.2

package/src/codec/primitive/Varint.luau

@@ -1,28 +1,41 @@
 --!strict
 --!native
--- Dense prefix varint. Single-branch decode, range up to 2^32 - 1.
+-- Dense prefix varint over [0, 2^32 - 1]. Single-branch decode.
 
 local Base = require(script.Parent.Parent.Base)
+local Constants = require(script.Parent.Parent.Parent.util.Constants)
+local Log = require(script.Parent.Parent.Parent.util.Log)
 local Types = require(script.Parent.Parent.Parent.Types)
 
 -- Constants --------------------------------------------------------------
 
 --[[
-    Wire layout (first byte determines length):
-      0x00..0xBF  1 byte   value = b0                         [0..191]
-      0xC0..0xDF  2 bytes  value = (b0 & 0x1F)<<8 | b1 + 192  [192..8383]
-      0xE0..0xEF  3 bytes  value = (b0 & 0x0F)<<16 | u16 + 8384 [8384..1056959]
-      0xF0..0xFF  5 bytes  value = u32                        [..0xFFFFFFFF]
+    Wire layout (first byte tag selects length):
+      0x00..0xBF  1 byte   value = b0                            [0..191]
+      0xC0..0xDF  2 bytes  value = (b0 & 0x1F)<<8 | b1 + 192     [192..8383]
+      0xE0..0xEF  3 bytes  value = (b0 & 0x0F)<<16 | u16 + 8384  [8384..1056959]
+      0xF0..0xFF  5 bytes  value = u32                           [..0xFFFFFFFF]
 ]]
 local INLINE_MAX = 0xBF
+local TWO_TAG = 0xC0
+local TWO_END = 0xDF
+local TWO_MASK = 0x1F
+local THREE_TAG = 0xE0
+local THREE_END = 0xEF
+local THREE_MASK = 0x0F
+local FIVE_TAG = 0xF0
 local TWO_MAX = 8383
 local THREE_MAX = 1056959
 local TWO_BIAS = 192
 local THREE_BIAS = 8384
 
+local U8_MAX = Constants.U8_MAX
+local U16_MAX = Constants.U16_MAX
+local U32_MAX = Constants.U32_MAX
+
 -- Private ----------------------------------------------------------------
 
-local alloc = Base.alloc
+local ensure = Base.ensure
 local band = bit32.band
 local bor = bit32.bor
 local rshift = bit32.rshift
@@ -39,85 +52,109 @@ local Varint = {}
 
 Varint.INLINE_MAX = INLINE_MAX
 
-function Varint.write(ch: Types.ChannelState, value: number): ()
-    if value < 0 or value > 0xFFFFFFFF or value % 1 ~= 0 then
-        error(`[Lync] Varint.write: value must be an integer in [0, 4294967295], got {value}`)
+-- Wire byte count for a value, without encoding it. Used by cost heuristics.
+function Varint.length(value: number): number
+    if value <= INLINE_MAX then
+        return 1
+    elseif value <= TWO_MAX then
+        return 2
+    elseif value <= THREE_MAX then
+        return 3
     end
+    return 5
+end
 
-    local cursor = ch.cursor
+function Varint.write(ch: Types.ChannelState, value: number): ()
+    if value < 0 or value > U32_MAX or value % 1 ~= 0 then
+        Log.error(`value must be an integer in [0, {U32_MAX}], got {value}`)
+    end
 
     if value <= INLINE_MAX then
-        if cursor + 1 > ch.size then
-            alloc(ch, 1)
-        end
+        ensure(ch, 1)
+        local cursor = ch.cursor
         writeu8(ch.buff, cursor, value)
         ch.cursor = cursor + 1
         return
     end
 
     if value <= TWO_MAX then
-        if cursor + 2 > ch.size then
-            alloc(ch, 2)
-        end
+        ensure(ch, 2)
+        local cursor = ch.cursor
         local adjusted = value - TWO_BIAS
         local b = ch.buff
-        writeu8(b, cursor, bor(0xC0, rshift(adjusted, 8)))
-        writeu8(b, cursor + 1, band(adjusted, 0xFF))
+        writeu8(b, cursor, bor(TWO_TAG, rshift(adjusted, 8)))
+        writeu8(b, cursor + 1, band(adjusted, U8_MAX))
         ch.cursor = cursor + 2
         return
     end
 
     if value <= THREE_MAX then
-        if cursor + 3 > ch.size then
-            alloc(ch, 3)
-        end
+        ensure(ch, 3)
+        local cursor = ch.cursor
         local adjusted = value - THREE_BIAS
         local b = ch.buff
-        writeu8(b, cursor, bor(0xE0, rshift(adjusted, 16)))
-        writeu16(b, cursor + 1, band(adjusted, 0xFFFF))
+        writeu8(b, cursor, bor(THREE_TAG, rshift(adjusted, 16)))
+        writeu16(b, cursor + 1, band(adjusted, U16_MAX))
         ch.cursor = cursor + 3
         return
     end
 
-    if cursor + 5 > ch.size then
-        alloc(ch, 5)
-    end
+    ensure(ch, 5)
+    local cursor = ch.cursor
     local b = ch.buff
-    writeu8(b, cursor, 0xF0)
+    writeu8(b, cursor, FIVE_TAG)
     writeu32(b, cursor + 1, value)
     ch.cursor = cursor + 5
 end
 
+--[[
+    Returns (value, bytesConsumed). On insufficient bytes returns (0, 0) so
+    the transport can abort the frame instead of letting the buffer access
+    raise — required for recovery from truncated/desynced incoming buffers.
+]]
 function Varint.read(src: buffer, pos: number): (number, number)
+    local available = buffer.len(src) - pos
+    if available < 1 then
+        return 0, 0
+    end
     local b0 = readu8(src, pos)
     if b0 <= INLINE_MAX then
         return b0, 1
     end
-    if b0 <= 0xDF then
-        return band(b0, 0x1F) * 256 + readu8(src, pos + 1) + TWO_BIAS, 2
+    if b0 <= TWO_END then
+        if available < 2 then
+            return 0, 0
+        end
+        return band(b0, TWO_MASK) * 256 + readu8(src, pos + 1) + TWO_BIAS, 2
+    end
+    if b0 <= THREE_END then
+        if available < 3 then
+            return 0, 0
+        end
+        return band(b0, THREE_MASK) * 65536 + readu16(src, pos + 1) + THREE_BIAS, 3
     end
-    if b0 <= 0xEF then
-        return band(b0, 0x0F) * 65536 + readu16(src, pos + 1) + THREE_BIAS, 3
+    if available < 5 then
+        return 0, 0
     end
     return readu32(src, pos + 1), 5
 end
 
--- Encode a value already known to fit in INLINE_MAX (single byte).
+-- Caller-asserted: value is known to fit in INLINE_MAX.
 function Varint.writeInline(ch: Types.ChannelState, value: number): ()
+    ensure(ch, 1)
     local cursor = ch.cursor
-    if cursor + 1 > ch.size then
-        alloc(ch, 1)
-    end
     writeu8(ch.buff, cursor, value)
     ch.cursor = cursor + 1
 end
 
 --[[
-    Decode a length prefix that uses the single-byte fast path for
-    lengths in [0, INLINE_MAX] and the full varint encoding above that.
-    Used by Buffer, String, and Auto's string branch.
+    Length-prefix decode that fast-paths the [0, INLINE_MAX] single-byte form
+    before falling through to full varint. Used by Buffer, String, and Auto.
 ]]
 function Varint.readLengthPrefix(src: buffer, pos: number): (number, number)
+    if buffer.len(src) - pos < 1 then
+        return 0, 0
+    end
     local b0 = readu8(src, pos)
     if b0 <= INLINE_MAX then
         return b0, 1

package/src/codec/primitive/Zint.luau

@@ -0,0 +1,99 @@
+--!strict
+--!native
+-- Signed varint via zigzag mapping. Small magnitudes pack in 1 byte.
+
+local Log = require(script.Parent.Parent.Parent.util.Log)
+local Types = require(script.Parent.Parent.Parent.Types)
+local Varint = require(script.Parent.Parent.primitive.Varint)
+
+-- Constants --------------------------------------------------------------
+
+--[[
+    Zigzag fold maps signed values onto unsigned varint space:
+      n >= 0  -> 2n
+      n < 0   -> -2n - 1
+    Inverse: low bit selects sign, shift down 1 bit.
+
+    Wire ranges (using Varint dense form):
+      1 byte: [-96, 95]
+      2 bytes: [-4192, 4191]
+      3 bytes: [-528480, 528479]
+      5 bytes: full i32
+]]
+local I32_MIN = -0x80000000
+local I32_MAX = 0x7FFFFFFF
+
+-- Private ----------------------------------------------------------------
+
+local floor = math.floor
+local band = bit32.band
+local varintWrite = Varint.write
+local varintRead = Varint.read
+
+-- Signed -> unsigned. Hot path; called per write of every delta scalar.
+local function encode(value: number): number
+    if value >= 0 then
+        return value * 2
+    end
+    return value * -2 - 1
+end
+
+-- Inverse of encode. Even -> n/2; odd -> -((n+1)/2). Branchless on the half.
+local function decode(raw: number): number
+    local low = band(raw, 1)
+    local half = (raw - low) / 2
+    return if low == 1 then -half - 1 else half
+end
+
+-- Public -----------------------------------------------------------------
+
+local Zint = {}
+
+Zint.encode = encode
+Zint.decode = decode
+
+--[[
+    Variable-length signed integer in [I32_MIN, I32_MAX]. Optional [min, max]
+    bounds gate input at write time so out-of-range payloads error early
+    rather than corrupting downstream decoders.
+]]
+function Zint.zint(min: number?, max: number?): Types.InternalCodec<number>
+    local lo = min or I32_MIN
+    local hi = max or I32_MAX
+    if lo > hi then
+        Log.error(`min ({lo}) must be <= max ({hi})`)
+    end
+    if floor(lo) ~= lo or floor(hi) ~= hi then
+        Log.error("bounds must be integers")
+    end
+    if lo < I32_MIN or hi > I32_MAX then
+        Log.error(`range [{lo}, {hi}] exceeds i32 bounds`)
+    end
+
+    return table.freeze({
+        _typeCheck = "number",
+        _isInteger = true,
+        _min = lo,
+        _max = hi,
+
+        write = function(ch: Types.ChannelState, value: number): ()
+            if value < lo or value > hi then
+                Log.error(`value {value} out of range [{lo}, {hi}]`)
+            end
+            if floor(value) ~= value then
+                Log.error(`value {value} must be an integer`)
+            end
+            varintWrite(ch, encode(value))
+        end,
+
+        read = function(src: buffer, pos: number, _refs: { Instance }?): (number, number)
+            local raw, consumed = varintRead(src, pos)
+            if consumed == 0 then
+                Log.error("truncated zint")
+            end
+            return decode(raw), consumed
+        end,
+    }) :: Types.InternalCodec<number>
+end
+
+return table.freeze(Zint)