@axpecter/lync 2.3.2 → 3.0.0

package/kernel/Wide.luau

@@ -0,0 +1,267 @@
+--!strict
+--!optimize 2
+-- Sixty-four bits: the platform's own where it has them, and two halves where it has not.
+
+local Bits = require (script.Parent.Bits)
+
+local Wide = {}
+
+-- Constants -----------------------------------------------------------
+
+-- Whether this platform carries a sixty-four bit integer.
+local carried: any = integer
+const NATIVE = carried ~= nil
+
+--[[
+    The piece a half is cut into for a multiply, what a piece and a word count to, and how wide a
+    half is.
+]]
+const PIECE = 16
+const PLACE = 65536
+const WORD = PLACE * PLACE
+const HALF = Bits.width (WORD - 1)
+
+-- Where the low half of a word sits in the eight bytes it is written as, and where the high half.
+const LOW = 0
+const HIGH = 4
+
+-- The base a word is spelled in, and how many of those digits one half spells.
+const BASE = 16
+const DIGITS = 8
+
+-- The spelling itself, so the width a half is written to and the width one is read back at agree.
+const SPELLING = `%0{DIGITS}X%0{DIGITS}X`
+
+-- Types ---------------------------------------------------------------
+
+-- A sixty-four bit word, which is one thing to every caller and two to this module.
+export type Word = any
+
+-- One carrier: every operation on a word, in the vocabulary this library asks them in.
+export type Carrier = {
+    read NONE: Word,
+    read bit: (place: number) -> Word,
+    read union: (a: Word, b: Word) -> Word,
+    read meets: (a: Word, b: Word) -> boolean,
+    read any: (of: Word) -> boolean,
+    read lowest: (of: Word) -> number,
+    read without: (of: Word) -> Word,
+    read bxor: (a: Word, b: Word) -> Word,
+    read mul: (a: Word, b: Word) -> Word,
+    read of: (value: number) -> Word,
+    read parse: (digits: string) -> Word,
+    read same: (a: Word, b: Word) -> boolean,
+    read below: (a: Word, b: Word) -> boolean,
+    read read: (b: buffer, at: number) -> Word,
+    read write: (b: buffer, at: number, of: Word) -> number,
+    read ordered: (b: buffer, at: number) -> Word,
+    read text: (of: Word) -> string,
+}
+
+-- Private -------------------------------------------------------------
+
+-- The platform's own, which is every operation straight through.
+local SPLIT = if NATIVE then carried.create (HALF) else nil
+local NOTHING = if NATIVE then carried.create (0) else nil
+
+local held: Carrier = {
+    NONE = NOTHING,
+
+    bit = function (place: number): Word
+        return carried.lshift (carried.create (1), carried.create (place - 1))
+    end,
+
+    union = function (a: Word, b: Word): Word return carried.bor (a, b) end,
+    meets = function (a: Word, b: Word): boolean return carried.btest (a, b) end,
+    any = function (of: Word): boolean return carried.btest (of) end,
+    lowest = function (of: Word): number return carried.tonumber (carried.countrz (of)) + 1 end,
+
+    without = function (of: Word): Word
+        return carried.band (of, carried.sub (of, carried.create (1)))
+    end,
+
+    bxor = function (a: Word, b: Word): Word return carried.bxor (a, b) end,
+    mul = function (a: Word, b: Word): Word return carried.mul (a, b) end,
+    of = function (value: number): Word return carried.create (value) end,
+    parse = function (digits: string): Word return carried.fromstring (digits, BASE) end,
+    same = function (a: Word, b: Word): boolean return a == b end,
+    below = function (a: Word, b: Word): boolean return carried.ult (a, b) end,
+    read = function (b: buffer, at: number): Word return buffer.readinteger (b, at) end,
+
+    write = function (b: buffer, at: number, of: Word): number
+        buffer.writeinteger (b, at, of)
+        return at + HIGH + HIGH
+    end,
+
+    ordered = function (b: buffer, at: number): Word
+        return carried.bswap (buffer.readinteger (b, at))
+    end,
+
+    text = function (of: Word): string
+        return string.format (
+            SPELLING,
+            carried.tonumber (carried.extract (of, SPLIT, SPLIT)),
+            carried.tonumber (carried.extract (of, NOTHING, SPLIT))
+        )
+    end,
+}
+
+-- Two halves, each a `bit32` word, most significant first.
+local halved: Carrier = {
+    NONE = table.freeze ({ 0, 0 }),
+
+    bit = function (place: number): Word
+        local value = 2 ^ (place - 1)
+        if value < WORD then return table.freeze ({ 0, value }) end
+
+        return table.freeze ({ value / WORD, 0 })
+    end,
+
+    union = function (a: Word, b: Word): Word
+        return { bit32.bor (a[1], b[1]), bit32.bor (a[2], b[2]) }
+    end,
+
+    meets = function (a: Word, b: Word): boolean
+        return bit32.btest (a[1], b[1]) or bit32.btest (a[2], b[2])
+    end,
+
+    any = function (of: Word): boolean return of[1] ~= 0 or of[2] ~= 0 end,
+
+    lowest = function (of: Word): number
+        if of[2] ~= 0 then return bit32.countrz (of[2]) + 1 end
+        return bit32.countrz (of[1]) + HALF + 1
+    end,
+
+    -- The lowest set bit cleared, which is the one place a half borrows from nothing.
+    without = function (of: Word): Word
+        if of[2] ~= 0 then return { of[1], bit32.band (of[2], of[2] - 1) } end
+        return { bit32.band (of[1], of[1] - 1), 0 }
+    end,
+
+    bxor = function (a: Word, b: Word): Word
+        return { bit32.bxor (a[1], b[1]), bit32.bxor (a[2], b[2]) }
+    end,
+
+    -- A product modulo 2^64, in four sixteen bit pieces.
+    mul = function (a: Word, b: Word): Word
+        local a0 = bit32.band (a[2], PLACE - 1)
+        local a1 = bit32.rshift (a[2], PIECE)
+        local a2 = bit32.band (a[1], PLACE - 1)
+        local a3 = bit32.rshift (a[1], PIECE)
+
+        local b0 = bit32.band (b[2], PLACE - 1)
+        local b1 = bit32.rshift (b[2], PIECE)
+        local b2 = bit32.band (b[1], PLACE - 1)
+        local b3 = bit32.rshift (b[1], PIECE)
+
+        local c0 = a0 * b0
+        local c1 = a0 * b1 + a1 * b0
+        local c2 = a0 * b2 + a1 * b1 + a2 * b0
+        local c3 = a0 * b3 + a1 * b2 + a2 * b1 + a3 * b0
+
+        local r0 = c0 % PLACE
+        local up = (c0 - r0) / PLACE + c1
+
+        local r1 = up % PLACE
+        up = (up - r1) / PLACE + c2
+
+        local r2 = up % PLACE
+        up = (up - r2) / PLACE + c3
+
+        local r3 = up % PLACE
+        return { r3 * PLACE + r2, r1 * PLACE + r0 }
+    end,
+
+    of = function (value: number): Word return { 0, value } end,
+
+    parse = function (digits: string): Word
+        local high = tonumber (string.sub (digits, 1, #digits - DIGITS), BASE)
+        local low = tonumber (string.sub (digits, #digits - DIGITS + 1), BASE)
+
+        return { high or 0, low or 0 }
+    end,
+
+    same = function (a: Word, b: Word): boolean return a[1] == b[1] and a[2] == b[2] end,
+
+    below = function (a: Word, b: Word): boolean
+        if a[1] ~= b[1] then return a[1] < b[1] end
+        return a[2] < b[2]
+    end,
+
+    -- The low half first, which is where a little endian sixty-four bit read finds it.
+    read = function (b: buffer, at: number): Word
+        return { buffer.readu32 (b, at + HIGH), buffer.readu32 (b, at + LOW) }
+    end,
+
+    write = function (b: buffer, at: number, of: Word): number
+        buffer.writeu32 (b, at + LOW, of[2])
+        buffer.writeu32 (b, at + HIGH, of[1])
+        return at + HIGH + HIGH
+    end,
+
+    -- The first byte most significant, which is what a bytewise order compares.
+    ordered = function (b: buffer, at: number): Word
+        return {
+            bit32.byteswap (buffer.readu32 (b, at + LOW)),
+            bit32.byteswap (buffer.readu32 (b, at + HIGH)),
+        }
+    end,
+
+    text = function (of: Word): string return string.format (SPELLING, of[1], of[2]) end,
+}
+
+local chosen = if NATIVE then held else halved
+
+-- Every bit that has been asked for, made once.
+local bits: { Word } = {}
+
+-- Public --------------------------------------------------------------
+
+--[[
+    Which carrier this build got. Reported so a place can say so, and read by the suites that hold
+    the two to each other wherever both exist.
+]]
+Wide.native = NATIVE
+
+-- Both carriers, under names, where this build has both.
+local both: { [string]: Carrier } = { halves = halved }
+if NATIVE then both.own = held end
+
+Wide.carriers = table.freeze (both)
+
+-- A word of no bits, which is what a mask starts as and what an empty union comes to.
+Wide.NONE = chosen.NONE
+
+-- Everything a word is asked, in the vocabulary the library asks it in rather than the platform's.
+Wide.union = chosen.union
+Wide.meets = chosen.meets
+Wide.any = chosen.any
+Wide.lowest = chosen.lowest
+Wide.without = chosen.without
+Wide.bxor = chosen.bxor
+Wide.mul = chosen.mul
+Wide.of = chosen.of
+Wide.parse = chosen.parse
+Wide.same = chosen.same
+Wide.below = chosen.below
+Wide.read = chosen.read
+Wide.write = chosen.write
+Wide.ordered = chosen.ordered
+Wide.text = chosen.text
+
+--[[
+    One bit at a place, counted from one the way a field index is.
+
+    Answered from the pile above where it has been asked for before, which is every ask after the
+    first for any place a schema actually names.
+]]
+function Wide.bit (place: number): Word
+    local found = bits[place]
+    if found ~= nil then return found end
+
+    found = chosen.bit (place)
+    bits[place] = found
+    return found
+end
+
+return table.freeze (Wide)

package/package.json

@@ -1,39 +1,22 @@
 {
     "name": "@axpecter/lync",
-    "version": "2.3.2",
-    "description": "Buffer networking for Roblox. Delta compression, XOR framing, built-in security",
-    "main": "src/init.luau",
-    "types": "src/index.d.ts",
-    "module": "commonjs",
-    "author": "Axp3cter",
-    "license": "MIT",
-    "repository": {
-        "type": "git",
-        "url": "git+https://github.com/Axp3cter/Lync.git"
-    },
+    "version": "3.0.0",
+    "description": "Typed buffer networking for Roblox: packets, queries, and replicated sets.",
+    "keywords": ["roblox", "roblox-ts", "luau", "networking", "buffer", "packets", "replication"],
     "homepage": "https://github.com/Axp3cter/Lync",
-    "bugs": {
-        "url": "https://github.com/Axp3cter/Lync/issues"
-    },
-    "publishConfig": {
-        "access": "public"
-    },
-    "keywords": [
-        "roblox",
-        "networking",
-        "buffer",
-        "delta",
-        "compression",
-        "roblox-ts",
-        "luau"
-    ],
-    "files": [
-        "src",
-        "README.md"
-    ],
+    "bugs": { "url": "https://github.com/Axp3cter/Lync/issues" },
+    "repository": { "type": "git", "url": "git+https://github.com/Axp3cter/Lync.git" },
+    "license": "MIT",
+    "author": "Axp3cter",
+    "main": "init.luau",
+    "types": "index.d.ts",
+    "files": ["**/*.luau", "index.d.ts"],
+    "scripts": { "check": "tsc" },
+    "publishConfig": { "access": "public" },
+    "peerDependencies": { "@rbxts/types": "^1.0.0" },
     "devDependencies": {
         "@rbxts/compiler-types": "^3.0.0-types.0",
-        "@rbxts/types": "^1.0.0",
-        "typescript": "^5.6.0"
+        "@rbxts/types": "^1.0.941",
+        "typescript": "5.5.3"
     }
 }

package/runtime/Boundary.luau

@@ -0,0 +1,180 @@
+--!strict
+--!optimize 2
+-- The trust split: bytes from a client are hostile, bytes from the server are this library's own.
+
+local Catalog = require (script.Parent.Parent.kernel.Catalog)
+local Compile = require (script.Parent.Parent.shape.Compile)
+local Log = require (script.Parent.Parent.kernel.Log)
+local Serial = require (script.Parent.Parent.shape.Serial)
+local Tally = require (script.Parent.Parent.kernel.Tally)
+local Types = require (script.Parent.Parent.Types)
+
+local Boundary = {}
+
+-- Constants -----------------------------------------------------------
+
+-- What a drop is on each lane, which is the whole of what the trust split comes to afterwards.
+const HOSTILE: Types.LogKind = "warn"
+const TRUSTED: Types.LogKind = "error"
+
+-- Types ---------------------------------------------------------------
+
+-- What a validate is handed, as the record this module keeps rather than the read one it is.
+export type Context = {
+    player: Player?,
+    now: number,
+    last: number?,
+}
+
+-- The two tables a rejection's numbers are read back through.
+export type Names = {
+    read paths: Serial.Interner,
+    read expected: Serial.Interner,
+}
+
+-- One link's boundary: the two contexts, the arrival stamps, and whether this frame has a cursor.
+export type Boundary = {
+    read name: string,
+    read tally: Tally.Tally,
+    read hostile: Context,
+    read trusted: Context,
+    read stamps: { [Player]: { [number]: number } },
+    read heard: { [number]: number },
+    ctx: Context,
+    live: boolean,
+    took: boolean,
+}
+
+-- Private -------------------------------------------------------------
+
+-- An empty context, which is what a link holds two of for as long as it is open.
+local function context (): Context return { player = nil, now = 0, last = nil } end
+
+-- What one sender's definitions were last heard at, made the first time they are heard at all.
+local function marks (of: Boundary, from: Player): { [number]: number }
+    local held = of.stamps[from]
+    if held ~= nil then return held end
+
+    held = {}
+    of.stamps[from] = held
+    return held
+end
+
+-- Where the reader got to, for a failure that can be asked.
+local function resumed (thrown: unknown): number?
+    if typeof (thrown) ~= "table" then return nil end
+
+    local rejection = thrown :: Log.Rejection
+    if rejection.code ~= Catalog.VALIDATE then return nil end
+
+    local at = rejection.facts.at
+    return if typeof (at) == "number" then at else nil
+end
+
+-- A rejection's numbers as the words they were interned from.
+local function diagnosed (thrown: unknown, names: Names, about: Log.Facts)
+    if typeof (thrown) ~= "table" then return end
+
+    local facts = (thrown :: Log.Rejection).facts
+    local path = facts.pathId
+    local expected = facts.expectId
+
+    if typeof (path) == "number" then about.path = names.paths.texts[path] end
+    if typeof (expected) == "number" then about.expected = names.expected.texts[expected] end
+end
+
+-- Public --------------------------------------------------------------
+
+-- One link's boundary, before anything has arrived.
+function Boundary.new (name: string, tally: Tally.Tally): Boundary
+    local hostile = context ()
+
+    return {
+        name = name,
+        tally = tally,
+        hostile = hostile,
+        trusted = context (),
+        stamps = {},
+        heard = {},
+        ctx = hostile,
+        live = true,
+        took = false,
+    }
+end
+
+-- A frame arriving, and the context every payload in it is read under.
+function Boundary.opened (of: Boundary, from: Player?, now: number)
+    local ctx = if from == nil then of.trusted else of.hostile
+
+    ctx.player = from
+    ctx.now = now
+    ctx.last = nil
+
+    of.ctx = ctx
+    of.live = true
+end
+
+-- One definition heard from one sender, stamped whether or not what follows decodes.
+function Boundary.stamped (of: Boundary, from: Player?, id: number, now: number)
+    local held = if from == nil then of.heard else marks (of, from)
+
+    of.ctx.last = held[id]
+    held[id] = now
+end
+
+-- One payload or one entry, decoded under containment, and the byte past it.
+function Boundary.ran (
+    of: Boundary,
+    def: Compile.Def,
+    names: Names,
+    take: (buffer, number, Types.ValidateContext) -> (number, any),
+    b: buffer,
+    pos: number
+): (number?, any)
+    local ok, at, value = pcall (take, b, pos, of.ctx)
+    if ok then
+        of.took = true
+        return at, value
+    end
+
+    of.took = false
+
+    local ends = resumed (at)
+    if ends == nil then of.live = false end
+
+    local about: Log.Facts = {
+        definition = def.name,
+        file = def.file,
+        line = def.line,
+        player = of.ctx.player,
+    }
+
+    diagnosed (at, names, about)
+    Log.dropped (at, about, if of.ctx.player == nil then TRUSTED else HOSTILE)
+    Tally.dropped (of.tally, def.name)
+
+    return ends, nil
+end
+
+-- A failure about the frame rather than about anything in it, which closes it.
+function Boundary.lost (of: Boundary, code: Catalog.Code, facts: Log.Facts)
+    of.live = false
+
+    local raised = { code = code, facts = facts }
+    Log.dropped (
+        raised,
+        { player = of.ctx.player },
+        if of.ctx.player == nil then TRUSTED else HOSTILE
+    )
+
+    --[[
+        Against the namespace and no definition, which is what a count with no name to charge is
+        for. What went wrong here is exactly which definition the frame said it was.
+    ]]
+    Tally.dropped (of.tally, nil)
+end
+
+-- A sender gone, and the stamps that were only ever about them.
+function Boundary.left (of: Boundary, who: Player) of.stamps[who] = nil end
+
+return table.freeze (Boundary)

package/runtime/Dispatch.luau

@@ -0,0 +1,91 @@
+--!strict
+--!optimize 2
+-- Where a decoded definition goes: the listeners on one, its lone responder, and neither's mistake.
+
+local Listeners = require (script.Parent.Parent.kernel.Listeners)
+local Log = require (script.Parent.Parent.kernel.Log)
+local Types = require (script.Parent.Parent.Types)
+
+local Dispatch = {}
+
+-- Types ---------------------------------------------------------------
+
+--[[
+    A query's one answer. What it is handed is its side's business and not this module's: a server
+    responder reads a value and a player, a client responder reads a value, and a dispatch that knew
+    which would be a second home for a rule the surface already states twice.
+]]
+export type Responder = (...any) -> any
+
+--[[
+    Everything a machine has attached, keyed by the id the wire names. Held by whoever owns the
+    namespace rather than here, because two namespaces in one place are two of these and a module
+    keeping them itself would be state that depends on which of them loaded first.
+]]
+export type Wiring = {
+    heard: { [number]: Listeners.List<...any> },
+    answering: { [number]: Responder },
+}
+
+-- Private -------------------------------------------------------------
+
+-- A definition nothing on this machine listens for.
+local function unheard (name: string)
+    local said = `nothing on this machine listens for {name}`
+    local facts: Log.Facts = { definition = name }
+--[[
+        Not two reports but two builds. The raise never returns, so a place being worked on stops
+        on the mistake, and the line under it is what a shipped one does with the same fact.
+    ]]    
+
+
+Log.warn (said, facts)
+end
+
+-- Public --------------------------------------------------------------
+
+function Dispatch.wiring (): Wiring return { heard = {}, answering = {} } end
+
+-- One more listener on a definition, at the end of the order, and the connection that ends it.
+function Dispatch.listen (of: Wiring, id: number, fn: (...any) -> ()): Types.Connection
+    local heard = of.heard[id]
+    if heard == nil then
+        heard = Listeners.list (Log.contained :: Listeners.Run<...any>)
+        of.heard[id] = heard
+    end
+
+    return Listeners.connect (heard :: Listeners.List<...any>, fn)
+end
+
+--[[
+    The one responder a query gets, and a second is refused at once: by reply time both exist, and
+    whichever was picked would be right half the time and silent about the rest.
+]]
+function Dispatch.respond (of: Wiring, id: number, name: string, fn: Responder)
+    if of.answering[id] ~= nil then
+        Log.error (`{name} already has a responder, and a query has one`, { definition = name })
+    end
+
+    of.answering[id] = fn
+end
+
+-- A decoded packet, to everything attached, in the order it was attached.
+function Dispatch.packet (of: Wiring, id: number, name: string, ...: any)
+    local heard = of.heard[id]
+    if heard == nil or heard.live == 0 then
+        unheard (name)
+        return
+    end
+
+    Listeners.fan (heard, ...)
+end
+
+-- A decoded request, run, and whether there is anything to send back.
+function Dispatch.request (of: Wiring, id: number, ...: any): (boolean, any)
+    local fn = of.answering[id]
+    if fn == nil then return false, nil end
+
+    return Log.caught (fn, ...)
+end
+
+return table.freeze (Dispatch)