@axpecter/lync 2.2.1 → 2.3.2

package/src/codec/composite/Struct.luau

@@ -1,10 +1,12 @@
 --!strict
 --!native
--- Struct and deltaStruct codecs.
+-- struct() and deltaStruct(). Bool fields bit-pack into a tail block.
 
 local Base = require(script.Parent.Parent.Base)
+local Baseline = require(script.Parent.Parent.Parent.internal.Baseline)
 local Channel = require(script.Parent.Parent.Parent.internal.Channel)
-local Shared = require(script.Parent.Shared)
+local Log = require(script.Parent.Parent.Parent.util.Log)
+local Shared = require(script.Parent.Parent.composite.Shared)
 local Types = require(script.Parent.Parent.Parent.Types)
 
 -- Private ----------------------------------------------------------------
@@ -12,21 +14,54 @@ local Types = require(script.Parent.Parent.Parent.Types)
 local alloc = Base.alloc
 local writeByte = Channel.writeByte
 local writeu8 = buffer.writeu8
+local writeu16 = buffer.writeu16
+local writeu32 = buffer.writeu32
 local readu8 = buffer.readu8
+local readu16 = buffer.readu16
+local readu32 = buffer.readu32
 local band = bit32.band
 local bor = bit32.bor
 local lshift = bit32.lshift
+local rshift = bit32.rshift
+local countrz = bit32.countrz
+
+-- 1/2/4-byte direct writes; 3-byte case splits into u16 + u8 (no native u24).
+local function writeBitmap(b: buffer, off: number, mask: number, bitmapBytes: number): ()
+    if bitmapBytes == 1 then
+        writeu8(b, off, mask)
+    elseif bitmapBytes == 2 then
+        writeu16(b, off, mask)
+    elseif bitmapBytes == 4 then
+        writeu32(b, off, mask)
+    else
+        writeu16(b, off, band(mask, 0xFFFF))
+        writeu8(b, off + 2, band(rshift(mask, 16), 0xFF))
+    end
+end
+
+local function readBitmap(b: buffer, off: number, bitmapBytes: number): number
+    if bitmapBytes == 1 then
+        return readu8(b, off)
+    elseif bitmapBytes == 2 then
+        return readu16(b, off)
+    elseif bitmapBytes == 4 then
+        return readu32(b, off)
+    end
+    return bor(readu16(b, off), lshift(readu8(b, off + 2), 16))
+end
 
 local extractFields = Shared.extractFields
 local packBools = Shared.packBools
 local unpackBools = Shared.unpackBools
 local rangeEqual = Shared.rangeEqual
 local snapshot = Shared.snapshot
+local refreshCache = Shared.refreshCache
 local acquireScratch = Shared.acquireScratch
 local releaseScratch = Shared.releaseScratch
 local allocDeltaId = Shared.allocDeltaId
 local DELTA_UNCHANGED = Shared.DELTA_UNCHANGED
 local DELTA_FULL_OFFSET = Shared.DELTA_FULL_OFFSET
+local DELTA_MULTI_OFFSET = Shared.DELTA_MULTI_OFFSET
 
 local function buildFrozenSchema(
     dataKeys: { string },
@@ -53,16 +88,27 @@ function Struct.struct(schema: { [string]: Types.InternalCodec<any> }): Types.In
     local dataKeys, dataCodecs, boolKeys = extractFields(schema)
     local dataCount = #dataKeys
     local boolCount = #boolKeys
-    local boolBytes = (boolCount + 7) // 8
+    local boolBytes = Shared.boolBytes(boolCount)
 
+    -- Single pass: detect all-direct fast-write path + propagate _hasUnknown / _hasDelta.
     local allDirect, fixedSize = true, 0
+    local hasUnknown = false
+    local hasDelta = false
     for i = 1, dataCount do
         local c = dataCodecs[i]
-        if not c._size or not c._directWrite or not c._directRead then
-            allDirect = false
-            break
+        if c._hasUnknown then
+            hasUnknown = true
+        end
+        if Shared.containsDelta(c) then
+            hasDelta = true
+        end
+        if allDirect then
+            if c._size and c._directWrite and c._directRead then
+                fixedSize += c._size
+            else
+                allDirect = false
+            end
         end
-        fixedSize += c._size
     end
 
     local totalFixed = fixedSize + boolBytes
@@ -72,19 +118,19 @@ function Struct.struct(schema: { [string]: Types.InternalCodec<any> }): Types.In
         local offsets = table.create(dataCount)
         local directWrites = table.create(dataCount)
         local directReads = table.create(dataCount)
-        local cursor = 0
+        local runningOffset = 0
         for i = 1, dataCount do
             local c = dataCodecs[i]
-            offsets[i] = cursor
+            offsets[i] = runningOffset
             directWrites[i] = c._directWrite
             directReads[i] = c._directRead
-            cursor += c._size :: number
+            runningOffset += c._size :: number
         end
         table.freeze(offsets)
         table.freeze(directWrites)
         table.freeze(directReads)
 
-        return table.freeze({
+        local codec: Types.InternalCodec<any> = {
             _size = totalFixed,
             _schema = frozenSchema,
 
@@ -96,6 +142,7 @@ function Struct.struct(schema: { [string]: Types.InternalCodec<any> }): Types.In
                     return
                 end
 
+                -- Inline bool packing to avoid the cursor-based packBools call.
                 local boolOff = off + fixedSize
                 local idx = 1
                 for byteIdx = 0, boolBytes - 1 do
@@ -124,15 +171,15 @@ function Struct.struct(schema: { [string]: Types.InternalCodec<any> }): Types.In
             end,
 
             write = function(ch: Types.ChannelState, value: any): ()
-                local c = ch.cursor
-                if c + totalFixed > ch.size then
+                local cursor = ch.cursor
+                if cursor + totalFixed > ch.size then
                     alloc(ch, totalFixed)
                 end
                 local b = ch.buff
                 for i = 1, dataCount do
-                    directWrites[i](b, c + offsets[i], value[dataKeys[i]])
+                    directWrites[i](b, cursor + offsets[i], value[dataKeys[i]])
                 end
-                ch.cursor = c + fixedSize
+                ch.cursor = cursor + fixedSize
                 if boolCount > 0 then
                     packBools(ch, value, boolKeys, boolCount)
                 end
@@ -148,10 +195,17 @@ function Struct.struct(schema: { [string]: Types.InternalCodec<any> }): Types.In
                 end
                 return result, totalFixed
             end,
-        }) :: Types.InternalCodec<any>
+        }
+        if hasUnknown then
+            codec._hasUnknown = true
+        end
+        if hasDelta then
+            codec._hasDelta = true
+        end
+        return table.freeze(codec)
     end
 
-    return table.freeze({
+    local codec: Types.InternalCodec<any> = {
         _schema = frozenSchema,
 
         write = function(ch: Types.ChannelState, value: any): ()
@@ -176,66 +230,263 @@ function Struct.struct(schema: { [string]: Types.InternalCodec<any> }): Types.In
             end
             return result, total
         end,
-    }) :: Types.InternalCodec<any>
+    }
+    if hasUnknown then
+        codec._hasUnknown = true
+    end
+    if hasDelta then
+        codec._hasDelta = true
+    end
+    return table.freeze(codec)
 end
 
+--[[
+    Per-field delta encoder. Splits a struct into segments (one per data
+    field, plus one for the packed-bool block if any) and emits only changed
+    segments. Wire flag byte:
+      0                              UNCHANGED (reuse cache)
+      [1 .. segCount]                single segment k changed
+      segCount + DELTA_FULL_OFFSET   FULL payload
+      segCount + DELTA_MULTI_OFFSET  MULTI: bitmap + dirty segs in order
+]]
 function Struct.deltaStruct(
     schema: { [string]: Types.InternalCodec<any> }
 ): Types.InternalCodec<any>
-    local dataKeys, _dataCodecs, boolKeys = extractFields(schema)
-    local segCount = #dataKeys + (if #boolKeys > 0 then 1 else 0)
+    local dataKeys, dataCodecs, boolKeys = extractFields(schema)
+    local dataCount = #dataKeys
+    local boolCount = #boolKeys
+    local hasBoolSeg = boolCount > 0
+    local segCount = dataCount + (if hasBoolSeg then 1 else 0)
     local FLAG_FULL = segCount + DELTA_FULL_OFFSET
+    local FLAG_MULTI = segCount + DELTA_MULTI_OFFSET
+    local boolSegIdx = segCount
+
+    if FLAG_MULTI > 0xFF then
+        Log.error(`too many segments ({segCount}); flag byte would overflow`)
+    end
+    if segCount > 32 then
+        Log.error(`dirty bitmask is u32, segCount {segCount} exceeds 32`)
+    end
+
     local deltaId = allocDeltaId()
-    local frozenSchema = buildFrozenSchema(dataKeys, boolKeys, schema)
     local innerStruct = Struct.struct(schema)
+    -- Reuse innerStruct's frozen schema; avoids a second buildFrozenSchema.
+    local frozenSchema = innerStruct._schema :: { [string]: Types.InternalCodec<any> }
+
+    -- All-direct + fixed-size: segment offsets/lengths are statically known.
+    local allDirect = dataCount > 0
+    local fixedSize = 0
+    for i = 1, dataCount do
+        local c = dataCodecs[i]
+        if not c._size or not c._directWrite or not c._directRead then
+            allDirect = false
+            break
+        end
+        fixedSize += c._size :: number
+    end
+
+    local boolBytes = Shared.boolBytes(boolCount)
+    local bitmapBytes = Shared.boolBytes(segCount)
+
+    local staticSegOff: { number }? = nil
+    local staticSegLen: { number }? = nil
+    if allDirect then
+        local off = 0
+        local segOff = table.create(segCount)
+        local segLen = table.create(segCount)
+        for i = 1, dataCount do
+            segOff[i] = off
+            segLen[i] = dataCodecs[i]._size :: number
+            off += dataCodecs[i]._size :: number
+        end
+        if hasBoolSeg then
+            segOff[boolSegIdx] = off
+            segLen[boolSegIdx] = boolBytes
+        end
+        staticSegOff = table.freeze(segOff)
+        staticSegLen = table.freeze(segLen)
+    end
+
+    -- Apply one segment's bytes onto `target`. Returns bytes consumed.
+    local function applySegmentRead(
+        target: { [string]: any },
+        segIdx: number,
+        src: buffer,
+        pos: number,
+        refs: { Instance }?
+    ): number
+        if hasBoolSeg and segIdx == boolSegIdx then
+            return unpackBools(src, pos, boolKeys, boolCount, target)
+        end
+        local v, consumed = dataCodecs[segIdx].read(src, pos, refs)
+        target[dataKeys[segIdx]] = v
+        return consumed
+    end
+
+    -- Splice `src[srcOff..srcOff+len)` into the channel's main buffer.
+    local function writeBytes(ch: Types.ChannelState, src: buffer, srcOff: number, len: number): ()
+        if len == 0 then
+            return
+        end
+        local cursor = ch.cursor
+        if cursor + len > ch.size then
+            alloc(ch, len)
+        end
+        buffer.copy(ch.buff, cursor, src, srcOff, len)
+        ch.cursor = cursor + len
+    end
 
     return table.freeze({
         _isDelta = true,
         _schema = frozenSchema,
 
         write = function(ch: Types.ChannelState, value: any): ()
+            local scratch = acquireScratch()
+            local segOff: { number }, segLen: { number }
+
+            if staticSegOff then
+                -- Bulk write via innerStruct, constant offsets.
+                innerStruct.write(scratch, value)
+                segOff = staticSegOff :: { number }
+                segLen = staticSegLen :: { number }
+            else
+                segOff = table.create(segCount)
+                segLen = table.create(segCount)
+                local prev = 0
+                for i = 1, dataCount do
+                    dataCodecs[i].write(scratch, value[dataKeys[i]])
+                    local cur = scratch.cursor
+                    segOff[i] = prev
+                    segLen[i] = cur - prev
+                    prev = cur
+                end
+                if hasBoolSeg then
+                    packBools(scratch, value, boolKeys, boolCount)
+                    segOff[boolSegIdx] = prev
+                    segLen[boolSegIdx] = scratch.cursor - prev
+                end
+            end
+
+            local scratchLen = scratch.cursor
             local cache = ch.deltas[deltaId]
 
             if not cache then
                 writeByte(ch, FLAG_FULL)
-
-                local scratch = acquireScratch()
-                innerStruct.write(scratch, value)
-                local snapLen = scratch.cursor
-
-                ch.deltas[deltaId] = { raw = snapshot(scratch.buff, snapLen), len = snapLen }
-                innerStruct.write(ch, value)
+                writeBytes(ch, scratch.buff, 0, scratchLen)
+                --[[
+                    Variable-size case stores fresh segOff/segLen by ref;
+                    static case stores the module-level frozen tables.
+                ]]
+                ch.deltas[deltaId] = {
+                    raw = snapshot(scratch.buff, scratchLen),
+                    len = scratchLen,
+                    segOff = segOff,
+                    segLen = segLen,
+                } :: any
                 releaseScratch()
                 return
             end
 
-            local scratch = acquireScratch()
-            innerStruct.write(scratch, value)
-            local scratchLen = scratch.cursor
+            local cacheRaw = cache.raw
+            local cacheOff = (cache :: any).segOff :: { number }
+            local cacheLen = (cache :: any).segLen :: { number }
+
+            local dirtyMask = 0
+            local dirtyCount = 0
+            for i = 1, segCount do
+                local newLen = segLen[i]
+                if
+                    newLen ~= cacheLen[i]
+                    or not rangeEqual(scratch.buff, segOff[i], cacheRaw, cacheOff[i], newLen)
+                then
+                    dirtyMask = bor(dirtyMask, lshift(1, i - 1))
+                    dirtyCount += 1
+                end
+            end
 
-            if
-                scratchLen == cache.len
-                and rangeEqual(scratch.buff, 0, cache.raw, 0, scratchLen)
-            then
+            if dirtyCount == 0 then
                 writeByte(ch, DELTA_UNCHANGED)
                 releaseScratch()
                 return
             end
 
-            writeByte(ch, FLAG_FULL)
-            innerStruct.write(ch, value)
+            if dirtyCount == segCount then
+                writeByte(ch, FLAG_FULL)
+                writeBytes(ch, scratch.buff, 0, scratchLen)
+            elseif dirtyCount == 1 then
+                local segIdx = countrz(dirtyMask) + 1
+                writeByte(ch, segIdx)
+                writeBytes(ch, scratch.buff, segOff[segIdx], segLen[segIdx])
+            else
+                writeByte(ch, FLAG_MULTI)
+                local cursor = ch.cursor
+                if cursor + bitmapBytes > ch.size then
+                    alloc(ch, bitmapBytes)
+                end
+                writeBitmap(ch.buff, cursor, dirtyMask, bitmapBytes)
+                ch.cursor = cursor + bitmapBytes
+                for i = 1, segCount do
+                    if band(dirtyMask, lshift(1, i - 1)) ~= 0 then
+                        writeBytes(ch, scratch.buff, segOff[i], segLen[i])
+                    end
+                end
+            end
 
-            cache.raw = snapshot(scratch.buff, scratchLen)
-            cache.len = scratchLen
+            refreshCache(cache, scratch.buff, scratchLen);
+            (cache :: any).segOff = segOff;
+            (cache :: any).segLen = segLen
             releaseScratch()
         end,
 
         read = function(src: buffer, pos: number, refs: { Instance }?): (any, number)
-            if readu8(src, pos) == DELTA_UNCHANGED then
-                return nil, 1
+            local flag = readu8(src, pos)
+
+            if flag == DELTA_UNCHANGED then
+                local cached = Baseline.getCache(deltaId)
+                if not cached then
+                    Log.error("UNCHANGED flag before any FULL frame; baseline missing")
+                end
+                return cached, 1
+            end
+
+            if flag == FLAG_FULL then
+                local value, consumed = innerStruct.read(src, pos + 1, refs)
+                Baseline.setCache(deltaId, value)
+                return value, 1 + consumed
+            end
+
+            if flag <= segCount then
+                local cached = Baseline.getCache(deltaId)
+                if cached == nil then
+                    Log.error(
+                        `per-field update (seg {flag}) before any FULL frame; baseline missing`
+                    )
+                end
+                local newValue = table.clone(cached)
+                local consumed = applySegmentRead(newValue, flag, src, pos + 1, refs)
+                Baseline.setCache(deltaId, newValue)
+                return newValue, 1 + consumed
+            end
+
+            if flag == FLAG_MULTI then
+                local cached = Baseline.getCache(deltaId)
+                if not cached then
+                    Log.error("multi-field update before any FULL frame")
+                end
+                local newValue = table.clone(cached)
+                local mask = readBitmap(src, pos + 1, bitmapBytes)
+                local total = 1 + bitmapBytes
+                for i = 1, segCount do
+                    if band(mask, lshift(1, i - 1)) ~= 0 then
+                        local consumed = applySegmentRead(newValue, i, src, pos + total, refs)
+                        total += consumed
+                    end
+                end
+                Baseline.setCache(deltaId, newValue)
+                return newValue, total
             end
-            local value, consumed = innerStruct.read(src, pos + 1, refs)
-            return value, 1 + consumed
+
+            Log.error(`invalid delta flag {flag}`)
         end,
     }) :: Types.InternalCodec<any>
 end

package/src/codec/composite/Tagged.luau

@@ -1,8 +1,10 @@
 --!strict
---!optimize 2
+--!native
 -- Discriminated union codec. u8 variant tag + variant payload.
 
 local Channel = require(script.Parent.Parent.Parent.internal.Channel)
+local Log = require(script.Parent.Parent.Parent.util.Log)
+local Shared = require(script.Parent.Parent.composite.Shared)
 local Types = require(script.Parent.Parent.Parent.Types)
 
 -- Private ----------------------------------------------------------------
@@ -18,10 +20,9 @@ function Tagged.define(
     tagField: string,
     variants: { [string]: Types.InternalCodec<any> }
 ): Types.InternalCodec<any>
-    if tagField == "" then
-        error("[Lync] Lync.tagged: tagField cannot be empty")
-    end
+    Log.assert(tagField ~= "", "tagField cannot be empty")
 
+    -- Sort variant names so the wire-form tag id is stable across runs.
     local names: { string } = {}
     for name in variants do
         table.insert(names, name)
@@ -29,32 +30,32 @@ function Tagged.define(
     table.sort(names)
 
     local variantCount = #names
-    if variantCount == 0 then
-        error("[Lync] Lync.tagged: requires at least one variant")
-    end
+    Log.assert(variantCount > 0, "requires at least one variant")
     if variantCount > 256 then
-        error("[Lync] Lync.tagged: exceeds 256 variants")
+        Log.error(`exceeds 256 variants ({variantCount})`)
     end
 
     local nameToTag: { [string]: number } = {}
     local tagToCodec = table.create(variantCount)
-    local tagToName = table.create(variantCount)
     local hasUnknown = false
+    local hasDelta = false
 
     for i = 1, variantCount do
         local name = names[i]
         local codec = variants[name]
         nameToTag[name] = i - 1
         tagToCodec[i] = codec
-        tagToName[i] = name
         if codec._hasUnknown then
             hasUnknown = true
         end
+        if Shared.containsDelta(codec) then
+            hasDelta = true
+        end
     end
 
+    table.freeze(names)
     table.freeze(nameToTag)
     table.freeze(tagToCodec)
-    table.freeze(tagToName)
 
     local codec: Types.InternalCodec<any> = {
         _isTagged = true,
@@ -64,11 +65,11 @@ function Tagged.define(
         write = function(ch: Types.ChannelState, value: any): ()
             local name = value[tagField]
             if name == nil then
-                error(`[Lync] Tagged.write: missing tagField "{tagField}"`)
+                Log.error(`missing tagField "{tagField}"`)
             end
             local tag = nameToTag[name]
             if tag == nil then
-                error(`[Lync] Tagged.write: unknown variant "{name}"`)
+                Log.error(`unknown variant "{name}"`)
             end
 
             writeByte(ch, tag)
@@ -79,12 +80,13 @@ function Tagged.define(
             local tag = readu8(src, pos)
             local varCodec = tagToCodec[tag + 1]
             if not varCodec then
-                error(`[Lync] Tagged.read: unknown tag {tag}`)
+                Log.error(`unknown tag {tag}`)
             end
 
             local data, consumed = varCodec.read(src, pos + 1, refs)
-            if type(data) == "table" then
-                data[tagField] = tagToName[tag + 1]
+            -- Re-attach the discriminator so callers can dispatch on it.
+            if typeof(data) == "table" then
+                data[tagField] = names[tag + 1]
             end
             return data, 1 + consumed
         end,
@@ -92,6 +94,9 @@ function Tagged.define(
     if hasUnknown then
         codec._hasUnknown = true
     end
+    if hasDelta then
+        codec._hasDelta = true
+    end
     return table.freeze(codec)
 end
 

package/src/codec/composite/Tuple.luau

@@ -1,8 +1,10 @@
 --!strict
---!optimize 2
+--!native
 -- Positional ordered codec. Like struct but indexed.
 
 local Base = require(script.Parent.Parent.Base)
+local Log = require(script.Parent.Parent.Parent.util.Log)
+local Shared = require(script.Parent.Parent.composite.Shared)
 local Types = require(script.Parent.Parent.Parent.Types)
 
 -- Private ----------------------------------------------------------------
@@ -16,36 +18,42 @@ local Tuple = {}
 function Tuple.define(...: Types.InternalCodec<any>): Types.InternalCodec<any>
     local codecs = { ... }
     local count = #codecs
-    if count == 0 then
-        error("[Lync] Lync.tuple: requires at least one codec")
-    end
+    Log.assert(count > 0, "requires at least one codec")
 
+    -- Single pass: detect all-direct fast path + propagate _hasUnknown / _hasDelta.
     local allDirect, totalSize, hasUnknown = true, 0, false
+    local hasDelta = false
     for i = 1, count do
         local c = codecs[i]
         if c._hasUnknown then
             hasUnknown = true
         end
-        if not c._size or not c._directWrite or not c._directRead then
-            allDirect = false
-        elseif allDirect then
-            totalSize += c._size
+        if Shared.containsDelta(c) then
+            hasDelta = true
+        end
+        if allDirect then
+            if c._size and c._directWrite and c._directRead then
+                totalSize += c._size
+            else
+                allDirect = false
+            end
         end
     end
     table.freeze(codecs)
 
+    -- All-direct: pre-compute offsets so write/read avoids the cursor dance per element.
     if allDirect then
         local offsets = table.create(count)
         local directWrites = table.create(count)
         local directReads = table.create(count)
-        local cursor = 0
+        local runningOffset = 0
 
         for i = 1, count do
             local c = codecs[i]
-            offsets[i] = cursor
+            offsets[i] = runningOffset
             directWrites[i] = c._directWrite
             directReads[i] = c._directRead
-            cursor += c._size :: number
+            runningOffset += c._size :: number
         end
         table.freeze(offsets)
         table.freeze(directWrites)
@@ -71,15 +79,15 @@ function Tuple.define(...: Types.InternalCodec<any>): Types.InternalCodec<any>
             end,
 
             write = function(ch: Types.ChannelState, value: any): ()
-                local c = ch.cursor
-                if c + totalSize > ch.size then
+                local cursor = ch.cursor
+                if cursor + totalSize > ch.size then
                     alloc(ch, totalSize)
                 end
                 local b = ch.buff
                 for i = 1, count do
-                    directWrites[i](b, c + offsets[i], value[i])
+                    directWrites[i](b, cursor + offsets[i], value[i])
                 end
-                ch.cursor = c + totalSize
+                ch.cursor = cursor + totalSize
             end,
 
             read = function(src: buffer, pos: number, _refs: { Instance }?): (any, number)
@@ -93,6 +101,9 @@ function Tuple.define(...: Types.InternalCodec<any>): Types.InternalCodec<any>
         if hasUnknown then
             codec._hasUnknown = true
         end
+        if hasDelta then
+            codec._hasDelta = true
+        end
         return table.freeze(codec)
     end
 
@@ -111,6 +122,9 @@ function Tuple.define(...: Types.InternalCodec<any>): Types.InternalCodec<any>
             local total = 0
             for i = 1, count do
                 local v, consumed = codecs[i].read(src, pos + total, refs)
+                if consumed == 0 then
+                    Log.error(`element codec consumed 0 bytes at index {i}`)
+                end
                 result[i] = v
                 total += consumed
             end
@@ -120,6 +134,9 @@ function Tuple.define(...: Types.InternalCodec<any>): Types.InternalCodec<any>
     if hasUnknown then
         codec._hasUnknown = true
     end
+    if hasDelta then
+        codec._hasDelta = true
+    end
     return table.freeze(codec)
 end