@axpecter/lync 2.3.3 → 3.0.0

package/wire/Bytes.luau

@@ -0,0 +1,118 @@
+--!strict
+--!optimize 2
+-- How a buffer holds things: a field at a bit, the order two ranges compare in, and a seal.
+
+local Protocol = require (script.Parent.Protocol)
+local Wide = require (script.Parent.Parent.kernel.Wide)
+
+local Bytes = {}
+
+-- Constants -----------------------------------------------------------
+
+-- Bytes in the wide word, whichever of its two carriers this build got.
+const STRIDE = 8
+
+const BYTE = Protocol.BYTE_BITS
+
+-- Public --------------------------------------------------------------
+
+-- A run of bits as the whole bytes that hold it, rounded up.
+function Bytes.whole (bits: number): number return math.ceil (bits / BYTE) end
+
+-- One value of `width` bits at a bit offset, and the offset past it.
+function Bytes.put (b: buffer, at: number, width: number, value: number): number
+    local held = at
+    local left = width
+    local of = value
+
+    while left > 0 do
+        local byte = held // BYTE
+        local shift = held % BYTE
+        local room = BYTE - shift
+        local step = if left < room then left else room
+
+        local was = if shift == 0 then 0 else buffer.readu8 (b, byte)
+        local piece = bit32.lshift (bit32.extract (of, 0, step), shift)
+        buffer.writeu8 (b, byte, bit32.bor (was, piece))
+
+        of = bit32.rshift (of, step)
+        held += step
+        left -= step
+    end
+
+    return at + width
+end
+
+--[[
+    The same value back, and the offset past it. A width of nothing is a value of nothing, which is
+    what a ranged int over one possibility is, and it reads no byte at all.
+]]
+function Bytes.take (b: buffer, at: number, width: number): (number, number)
+    local of = 0
+    local held = at
+    local left = width
+    local got = 0
+
+    while left > 0 do
+        local byte = held // BYTE
+        local shift = held % BYTE
+        local room = BYTE - shift
+        local step = if left < room then left else room
+
+        local piece = bit32.extract (buffer.readu8 (b, byte), shift, step)
+        of = bit32.bor (of, bit32.lshift (piece, got))
+
+        got += step
+        held += step
+        left -= step
+    end
+
+    return of, at + width
+end
+
+-- The byte a bit run ends on, and whether what it left above itself is zero.
+function Bytes.aligned (b: buffer, at: number): (number, boolean)
+    local over = at % BYTE
+    if over == 0 then return at // BYTE, true end
+
+    local pad = bit32.rshift (buffer.readu8 (b, at // BYTE), over)
+    return at // BYTE + 1, pad == 0
+end
+
+--[[
+    The swap makes the word compare a byte compare: a read takes the first byte as the least of the
+    word, and reversing it spells the magnitude the bytes read as. A word is taken only where a
+    whole one remains inside the shorter range, because the bytes past it are not ours. Never
+    through a float, where plus and minus zero are equal and one NaN payload is unequal.
+]]
+@native
+function Bytes.rangeLess (b: buffer, atA: number, lenA: number, atB: number, lenB: number): boolean
+    local shared = math.min (lenA, lenB)
+    local words = shared - shared % STRIDE
+    local at = 0
+
+    while at < words do
+        local wordA = Wide.ordered (b, atA + at)
+        local wordB = Wide.ordered (b, atB + at)
+        if not Wide.same (wordA, wordB) then return Wide.below (wordA, wordB) end
+        at += STRIDE
+    end
+
+    while at < shared do
+        local byteA = buffer.readu8 (b, atA + at)
+        local byteB = buffer.readu8 (b, atB + at)
+        if byteA ~= byteB then return byteA < byteB end
+        at += 1
+    end
+
+    return lenA < lenB
+end
+
+-- A copy rather than the scratch, because the next block encodes into that same scratch.
+function Bytes.seal (scratch: buffer, length: number): buffer
+    local sealed = buffer.create (length)
+    buffer.copy (sealed, 0, scratch, 0, length)
+    return sealed
+end
+
+return table.freeze (Bytes)

package/wire/Clock.luau

@@ -0,0 +1,37 @@
+--!strict
+--!optimize 2
+-- Milliseconds against an epoch, the field they wrap into, and the instant one is unwrapped to.
+
+local Protocol = require (script.Parent.Protocol)
+
+local Clock = {}
+
+-- Constants -----------------------------------------------------------
+
+const RATE = Protocol.STAMP_RATE
+const SPAN = 2 ^ Protocol.STAMP_BITS
+
+-- Public --------------------------------------------------------------
+
+--[[
+    Floored rather than rounded, so a count never runs ahead of the clock it read, and negative
+    where the reading is behind the epoch: a client's shared clock sits there for a moment after
+    start and clamping would move its stamps.
+]]
+function Clock.elapsed (now: number, epoch: number): number
+    local since = now - epoch
+    return math.floor (since * RATE)
+end
+
+-- The remainder follows the divisor, so a negative count lands inside the field, not below it.
+function Clock.stamp (elapsed: number): number return elapsed % SPAN end
+
+--[[
+    The instant carrying this stamp nearest the estimate. At exactly half a space the two candidates
+    tie and the rounding takes the one further from the stamp, which is arbitrary and pinned.
+]]
+function Clock.unwrap (stamp: number, elapsed: number): number
+    return stamp + math.round ((elapsed - stamp) / SPAN) * SPAN
+end
+
+return table.freeze (Clock)

package/wire/Protocol.luau

@@ -0,0 +1,110 @@
+--!strict
+--!optimize 2
+-- The one home of every wire constant. Nothing else in the repository may state one.
+
+local Protocol = {}
+
+-- What both machines have to agree on before either spends a byte on the other's schema.
+Protocol.VERSION = 4
+
+--[[
+    The handshake lane's whole grammar: what each of the two messages weighs, where a verdict keeps
+    its one field, what a verdict says first, and the whole of what one can say.
+]]
+Protocol.HELLO_BYTES = 8
+Protocol.VERDICT_BYTES = 9
+Protocol.VERDICT_FIELD = 1
+Protocol.VERDICT_REJECT = 0
+Protocol.VERDICT_ACCEPT = 1
+
+-- How a bit is addressed, which is the whole of what a byte means to this format.
+Protocol.BYTE_BITS = 8
+
+--[[
+    The number domain. A signed varint folds its sign into the value it carries, so it reaches half
+    as far in each direction and its edge sits a bit below the one a double counts exactly to.
+]]
+Protocol.EXACT = 9007199254740992
+Protocol.VLI_EDGE = 4503599627370495
+Protocol.VARINT_GROUPS = 8
+Protocol.BIT_CEILING = 24
+
+--[[
+    A varint group: the bit that says another follows, the seven under it, and half of those.
+
+    The format's own and not the encoder's, since a reader who has the bytes and not the source
+    has to be able to take one apart, and half a group is where a signed value's sign folds.
+]]
+Protocol.VARINT_BITS = 7
+Protocol.VARINT_MORE = 0x80
+Protocol.VARINT_GROUP = 0x7F
+Protocol.VARINT_HALF = 0x40
+
+-- Schema legality.
+Protocol.MAX_FIELDS = 64
+
+--[[
+    The unreliable lane. The margin is not measured and carries no date, because nothing has
+    measured it: zero is the documented engine threshold taken at its word, and a margin above it
+    is a number somebody would have to put a real network behind before writing down.
+]]
+Protocol.UNRELIABLE_CEILING = 1000
+Protocol.UNRELIABLE_MARGIN = 0
+Protocol.UNRELIABLE_CAP = Protocol.UNRELIABLE_CEILING - Protocol.UNRELIABLE_MARGIN
+Protocol.MAX_FIRE = 1000000
+
+-- Budgets, in bytes, and the detector window in seconds.
+Protocol.BUDGET_RATE = 32768
+Protocol.BUDGET_FLOOR = 1024
+Protocol.SECTION_BYTES = Protocol.BUDGET_FLOOR
+Protocol.DETECTOR_WINDOW = 1
+
+-- Queries, the timeout in seconds.
+Protocol.QUERY_TIMEOUT = 10
+Protocol.QUERY_CAP = 32768
+
+-- Sequences and stamps.
+Protocol.NEWEST_WINDOW = 32768
+Protocol.NEWEST_GENS = 4
+Protocol.STAMP_BITS = 32
+Protocol.STAMP_RATE = 1000
+
+-- A packed colour's channel widths, least significant first.
+Protocol.RGB565_RED = 5
+Protocol.RGB565_GREEN = 6
+Protocol.RGB565_BLUE = 5
+
+--[[
+    Which component a turn left behind, in the order they are counted. The tag a frame carries is
+    one of these four, which is also why it is two bits wide.
+]]
+Protocol.QUAT_X = 0
+Protocol.QUAT_Y = 1
+Protocol.QUAT_Z = 2
+Protocol.QUAT_W = 3
+
+--[[
+    How far one component of the octahedral fold runs, in degrees, which is what a precision stated
+    for one is read against.
+]]
+Protocol.QUARTER_TURN = 90
+
+--[[
+    How far the three that were kept can reach, which is the root of a half. The tag names the one
+    left out and it is the largest, so a kept component is no larger than that one and the two of
+    them squared cannot pass one, which puts both at this exactly where they are equal.
+]]
+Protocol.QUAT_BOUND = 0.7071067811865476
+-- The response header's outcome, which is one bit and decides whether a payload follows it.
+
+Protocol.OUTCOME_BITS = 1
+
+-- What a section header says it is, and how it names the fields it carries.
+Protocol.SECTION_KEYFRAME = 0
+Protocol.SECTION_DELTA = 1
+Protocol.SECTION_REMOVAL = 2
+Protocol.SECTION_CLEAR = 3
+Protocol.FIELDSET_LIST = 0
+Protocol.FIELDSET_MASK = 1
+
+return table.freeze (Protocol)

package/wire/Sequence.luau

@@ -0,0 +1,40 @@
+--!strict
+--!optimize 2
+-- The u16 ring an unreliable stream is ordered by, and the rate gate over it.
+
+local Protocol = require (script.Parent.Protocol)
+
+local Sequence = {}
+
+-- Constants -----------------------------------------------------------
+
+const WINDOW = Protocol.NEWEST_WINDOW
+
+-- The ring a sequence counts round, which is the window doubled.
+const SPACE = WINDOW * 2
+
+-- Public --------------------------------------------------------------
+
+function Sequence.next (n: number): number return (n + 1) % SPACE end
+
+--[[
+    Newer is a distance under the window, so exactly half the space apart ranks neither way and a
+    sequence is never newer than itself. The subtraction goes negative and the remainder follows the
+    divisor, which is what carries it round the ring.
+]]
+function Sequence.isNewer (a: number, b: number): boolean
+    local apart = (a - b) % SPACE
+    return apart > 0 and apart < WINDOW
+end
+
+--[[
+    The interval runs from the last transmission, never from a division of the clock: a gate reading
+    the clock in buckets delivers the same rate and lets two flushes a bucket apart both through.
+    Two in one instant are one transmission.
+]]
+function Sequence.opened (now: number, last: number?, hz: number?): boolean
+    if last == nil or hz == nil then return true end
+    return now - last >= 1 / hz
+end
+
+return table.freeze (Sequence)

package/wire/Varint.luau

@@ -0,0 +1,124 @@
+--!strict
+--!optimize 2
+-- The two variable-length forms, `vlq` and `vli`.
+
+local Log = require (script.Parent.Parent.kernel.Log)
+local Protocol = require (script.Parent.Protocol)
+
+local Varint = {}
+
+-- Constants -----------------------------------------------------------
+
+-- The continuation bit, the seven bits under it, and half a group, which the format owns.
+const MORE = Protocol.VARINT_MORE
+const GROUP = Protocol.VARINT_GROUP
+const HALF = Protocol.VARINT_HALF
+
+const EXACT = Protocol.EXACT
+const GROUPS = Protocol.VARINT_GROUPS
+
+-- Private -------------------------------------------------------------
+
+--[[
+    A value is carried as a head group and the rest, never as one number: the zigzag of the widest
+    signed value wants fifty-four bits and a double holds fifty-three, and neither part wants more
+    than fifty-three. That is why nothing here reaches the integer domain.
+]]
+@native
+local function laid (out: buffer, at: number, head: number, tail: number): number
+    while tail > 0 do
+        buffer.writeu8 (out, at, head + MORE)
+        at += 1
+        head, tail = tail % MORE, tail // MORE
+    end
+
+    buffer.writeu8 (out, at, head)
+    return at + 1
+end
+
+@native
+local function taken (b: buffer, at: number): (number, number, number)
+    local head = buffer.readu8 (b, at)
+    at += 1
+    if head < MORE then return head, 0, at end
+    head -= MORE
+
+    local tail, shift = 0, 1
+    for _ = 2, GROUPS do
+        local byte = buffer.readu8 (b, at)
+        at += 1
+        if byte < MORE then return head, tail + byte * shift, at end
+
+        tail += (byte - MORE) * shift
+        shift *= MORE
+    end
+
+    -- Raised bare: this answers three numbers, where a call answering `never` reads as a fall thro
+    error (`a varint ran past {GROUPS} groups`, 0)
+end
+
+-- Public --------------------------------------------------------------
+
+--[[
+    Answers the offset past what it wrote, and refuses a value the exact domain has no place for.
+    A varint carries a whole number and the domain is what a double holds exactly, so what is
+    turned away here is a caller's own value rather than anything a frame could have carried.
+]]
+@native
+function Varint.write (out: buffer, at: number, value: number): number
+    if value < 0 or value >= EXACT then
+        Log.refuse (`a varint carries none to {EXACT - 1}, not {value}`)
+    end
+    return laid (out, at, value % MORE, value // MORE)
+end
+
+--[[
+    Answers the value and the offset past it, and refuses bytes that spell a number past the exact
+    domain. Refused rather than answered, because a value a double cannot hold exactly is a value
+    the two machines would disagree about the moment either did arithmetic on it.
+]]
+@native
+function Varint.read (b: buffer, at: number): (number, number)
+    local head, tail, after = taken (b, at)
+
+    local value = head + tail * MORE
+    if value >= EXACT then Log.refuse (`a varint read {value}, past the exact ceiling`) end
+    return value, after
+end
+
+--[[
+    Taken off the magnitude rather than the doubled value. A negative one sitting on a group
+    boundary has nothing left in its head, so the head carries the whole group and the rest gives
+    one up, which is the one place the two branches differ.
+]]
+@native
+function Varint.writeSigned (out: buffer, at: number, value: number): number
+    if value <= -EXACT or value >= EXACT then
+        Log.refuse (`a signed varint carries {1 - EXACT} to {EXACT - 1}, not {value}`)
+    end
+    if value >= 0 then return laid (out, at, (value % HALF) * 2, value // HALF) end
+
+    local magnitude = -value
+    local head = magnitude % HALF
+    if head == 0 then return laid (out, at, GROUP, magnitude // HALF - 1) end
+    return laid (out, at, head * 2 - 1, magnitude // HALF)
+end
+
+--[[
+    The same pair for the signed form, refused at both ends of the domain rather than at one. A
+    reader that checked only the top would take a magnitude one past the bottom and answer a number
+    no encoder could have written.
+]]
+@native
+function Varint.readSigned (b: buffer, at: number): (number, number)
+    local head, tail, after = taken (b, at)
+
+    local rest = tail * HALF
+    local value = if head % 2 == 0 then head / 2 + rest else -((head + 1) / 2 + rest)
+    if value <= -EXACT or value >= EXACT then
+        Log.refuse (`a signed varint read {value}, past the exact ceiling`)
+    end
+    return value, after
+end
+
+return table.freeze (Varint)

package/src/Types.luau

@@ -1,180 +0,0 @@
---!strict
--- Shared type definitions for the Lync networking library.
-
-export type ChannelState = {
-    buff: buffer,
-    cursor: number,
-    size: number,
-    refs: { Instance },
-    refCount: number,
-    lastId: number,
-    countPos: number,
-    itemCount: number,
-    singleMode: boolean,
-    singlePos: number,
-    --[[
-        Per-codec write-side delta state, keyed by deltaId. Shape is opaque
-        and codec-internal: deltaStruct stores `{raw, len, segOff, segLen}`,
-        deltaArray stores `{perIdx, length}`, deltaMap stores `{perKey}`,
-        delta scalars store quantized previous values.
-    ]]
-    deltas: { [number]: any },
-    prevDump: buffer?,
-    prevDumpLen: number,
-    currentPacket: string?,
-}
-
-export type Codec<T> = {
-    write: (ch: ChannelState, value: T) -> (),
-    read: (src: buffer, pos: number, refs: { Instance }?) -> (T, number),
-}
-
---[[
-    Optional metadata used by Gate (validation), Reader (max-item bound),
-    Auto (type dispatch), and composite codecs (direct write/read fast path).
-]]
-export type InternalCodec<T> = {
-    write: (ch: ChannelState, value: T) -> (),
-    read: (src: buffer, pos: number, refs: { Instance }?) -> (T, number),
-    _size: number?,
-    _directWrite: ((b: buffer, offset: number, value: T) -> ())?,
-    _directRead: ((b: buffer, offset: number) -> T)?,
-    _isDelta: boolean?,
-    --[[
-        True if any nested codec is delta. Lets the broadcast hot path skip
-        encode-once when delta state would diverge per-receiver.
-    ]]
-    _hasDelta: boolean?,
-    _isBool: boolean?,
-    _hasUnknown: boolean?,
-    _min: number?,
-    _max: number?,
-    _isInteger: boolean?,
-    _schema: { [string]: InternalCodec<T> }?,
-    _typeCheck: string?,
-    --[[
-        Composite metadata: lets Gate recurse element/variant validation
-        instead of falling through to the generic NaN/inf scan.
-    ]]
-    _isOptional: boolean?,
-    _inner: InternalCodec<T>?,
-    _isTagged: boolean?,
-    _variants: { [string]: InternalCodec<T> }?,
-    _tagField: string?,
-    _isArray: boolean?,
-    _element: InternalCodec<T>?,
-    _maxCount: number?,
-    _isMap: boolean?,
-    _keyCodec: InternalCodec<T>?,
-    _valueCodec: InternalCodec<T>?,
-    _isTuple: boolean?,
-    _elements: { InternalCodec<T> }?,
-    _isEnum: boolean?,
-    _enumValues: { [string]: number }?,
-    _maxStringLength: number?,
-}
-
-export type RateLimitState = {
-    tokens: number,
-    lastRefill: number,
-    lastAccepted: number,
-}
-
---[[
-    Token-bucket (maxPerSecond + optional burst) or cooldown (cooldown
-    seconds between accepts). Mixing both forms is undefined behavior.
-]]
-export type RateLimitConfig = {
-    maxPerSecond: number?,
-    burst: number?,
-    cooldown: number?,
-}
-
---[[
-    User-supplied per-packet validator. Returns (true, nil) on accept;
-    (false, reason) on reject — the reason is forwarded to onDrop hooks.
-]]
-export type ValidateFn = (data: any, player: Player) -> (boolean, string?)
-
-export type PacketOptions = {
-    unreliable: boolean?,
-    rateLimit: RateLimitConfig?,
-    validate: ValidateFn?,
-    maxPayloadBytes: number?,
-    timestamp: ("frame" | "offset" | "full")?,
-}
-
-export type QueryOptions = {
-    timeout: number?,
-    rateLimit: RateLimitConfig?,
-    validate: ValidateFn?,
-}
-
-export type Registration = {
-    id: number,
-    name: string,
-    kind: number,
-    codec: InternalCodec<any>,
-    isUnreliable: boolean,
-    -- Response registration id; set on REQUEST regs only.
-    partner: number?,
-    signal: SignalLike,
-    rateLimit: RateLimitConfig?,
-    validate: ValidateFn?,
-    needsGate: boolean,
-    maxPayloadBytes: number?,
-    timestampMode: number,
-    headerSize: number,
-    _openFn: (ch: ChannelState, id: number) -> (),
-    bytesSent: number,
-    bytesReceived: number,
-    fires: number,
-    recvFires: number,
-    drops: number,
-}
-
-export type SignalLike = {
-    fire: (self: SignalLike, ...any) -> (),
-    fireSync: (self: SignalLike, ...any) -> (),
-    connect: (self: SignalLike, callback: (...any) -> ()) -> Connection,
-    once: (self: SignalLike, callback: (...any) -> ()) -> Connection,
-    wait: (self: SignalLike) -> ...any,
-    count: (self: SignalLike) -> number,
-    hasListeners: (self: SignalLike) -> boolean,
-}
-
-export type Connection = {
-    connected: boolean,
-    disconnect: (self: Connection) -> (),
-}
-
-export type ConfigureOptions = {
-    channelMaxSize: number?,
-    validationDepth: number?,
-    poolSize: number?,
-    bandwidthLimit: { softLimit: number, maxStrikes: number }?,
-    globalRateLimit: { maxPerSecond: number }?,
-    stats: boolean?,
-}
-
-export type PacketStats = {
-    bytesSent: number,
-    bytesReceived: number,
-    fires: number,
-    recvFires: number,
-    drops: number,
-}
-
-export type PlayerStats = {
-    bytesSent: number,
-    bytesReceived: number,
-}
-
---[[
-    Server keys baselines per Player; client uses `false` since booleans are
-    valid table keys but Players never collide with that.
-]]
-export type BaselineKey = Player | false
-
--- Type-only module: runtime table is empty so re-requires are cheap.
-return table.freeze({})