@axpecter/lync 2.3.2 → 3.0.0

package/kernel/Heap.luau

@@ -0,0 +1,80 @@
+--!strict
+--!optimize 2
+-- The one binary min-heap, over parallel key and value arrays.
+
+local Heap = {}
+
+-- Types ---------------------------------------------------------------
+
+--[[
+    `count` is the truth, not `#keys`. A pop leaves the arrays at the size they reached, so a heap
+    draining at frame rate stops allocating and whatever sits past `count` is gone.
+]]
+export type Heap = {
+    keys: { number },
+    values: { number },
+    count: number,
+}
+
+-- Public --------------------------------------------------------------
+
+function Heap.new (): Heap return { keys = {}, values = {}, count = 0 } end
+
+-- The parent moves down into the vacated place, so a climb of n levels costs n moves, not three.
+function Heap.push (heap: Heap, key: number, value: number)
+    local keys, values = heap.keys, heap.values
+
+    local at = heap.count + 1
+    heap.count = at
+
+    while at > 1 do
+        local parent = at // 2
+        if keys[parent] <= key then break end
+
+        keys[at], values[at] = keys[parent], values[parent]
+        at = parent
+    end
+
+    keys[at], values[at] = key, value
+end
+
+function Heap.peek (heap: Heap): (number?, number?)
+    if heap.count == 0 then return nil, nil end
+    return heap.keys[1], heap.values[1]
+end
+
+--[[
+    Moving rather than swapping for the reason `push` gives climbing. The walk stops at the last
+    node with a child, which is half of what is left.
+]]
+function Heap.pop (heap: Heap): (number?, number?)
+    local count = heap.count
+    if count == 0 then return nil, nil end
+
+    local keys, values = heap.keys, heap.values
+    local key, value = keys[1], values[1]
+
+    local size = count - 1
+    heap.count = size
+    if size == 0 then return key, value end
+
+    local moved, movedValue = keys[count], values[count]
+    local at = 1
+    local half = size // 2
+
+    while at <= half do
+        local child = at * 2
+        if child < size and keys[child + 1] < keys[child] then
+            child += 1
+        end
+        if keys[child] >= moved then break end
+
+        keys[at], values[at] = keys[child], values[child]
+        at = child
+    end
+
+    keys[at], values[at] = moved, movedValue
+    return key, value
+end
+
+return table.freeze (Heap)

package/kernel/Listeners.luau

@@ -0,0 +1,95 @@
+--!strict
+--!optimize 2
+-- The connection a registration hands back, and the fan that reaches every one still live.
+
+local Listeners = {}
+
+-- Types ---------------------------------------------------------------
+
+--[[
+    `connected` and `disconnect` are exactly what `Types.Connection` names, so a link is handed back
+    as the connection itself and the two cannot drift apart.
+]]
+export type Link<A...> = {
+    connected: boolean,
+    disconnect: (self: any) -> (),
+    fn: (A...) -> (),
+}
+
+-- How a listener is reached, which is the one thing about a fan that is not this module's.
+export type Run<A...> = (fn: (A...) -> (),A...) -> ()
+
+export type List<A...> = {
+    links: { Link<A...> },
+    live: number,
+    fanning: number,
+    run: Run<A...>,
+}
+
+-- Private -------------------------------------------------------------
+
+-- The links that are no longer connected, taken out in place, once nothing is walking them.
+local function swept (of: List<...any>)
+    local links = of.links
+    local held = #links
+    if of.fanning > 0 or held == of.live then return end
+
+    local at = 1
+    for index = 1, held do
+        local link = links[index]
+        if link.connected then
+            links[at] = link
+            at += 1
+        end
+    end
+    for index = held, at, -1 do
+        links[index] = nil
+    end
+end
+
+-- Public --------------------------------------------------------------
+
+function Listeners.list <A...>(run: Run<A...>): List<A...>
+    return { links = {}, live = 0, fanning = 0, run = run }
+end
+
+-- At the end of the order, which is the order a fan walks.
+function Listeners.connect <A...>(of: List<A...>, fn: (A...) -> ()): Link<A...>
+    local link: Link<A...> = {
+        connected = true,
+        fn = fn,
+        disconnect = function (self: any)
+            if not self.connected then return end
+            self.connected = false
+
+            of.live -= 1
+            swept (of)
+        end,
+    }
+
+    table.insert (of.links, link)
+    of.live += 1
+    return link
+end
+
+--[[
+    Everything still listening, in the order it was registered, each on a thread of its own.
+
+    The count is read once before the walk, so a listener attached by a listener is reached by the
+    next fan and not this one. A walk over a list still growing would have no end it could name.
+]]
+function Listeners.fan <A...>(of: List<A...>, ...: A...)
+    local links, run = of.links, of.run
+    local held = #links
+
+    of.fanning += 1
+    for index = 1, held do
+        local link = links[index]
+        if link.connected then run (link.fn, ...) end
+    end
+    of.fanning -= 1
+
+    swept (of)
+end
+
+return table.freeze (Listeners)

package/kernel/Log.luau

@@ -0,0 +1,197 @@
+--!strict
+--!optimize 2
+-- The one record channel: everything the library says about itself, and who is listening.
+
+local Catalog = require (script.Parent.Catalog)
+local Listeners = require (script.Parent.Listeners)
+local Threads = require (script.Parent.Threads)
+local Types = require (script.Parent.Parent.Types)
+
+local Log = {}
+
+-- Constants -----------------------------------------------------------
+
+-- Shared by every record whose site handed over nothing else, since one empty table is enough.
+const NO_FACTS = table.freeze ({} :: Facts)
+
+-- A name in braces, which is the whole of what a template can hold.
+const HELD = "{(%w+)}"
+
+-- Types ---------------------------------------------------------------
+
+--[[
+    Every key reaches the record's `data` under its own name, so a site and a caller hold one
+    vocabulary and there is no mapping between them to keep in step.
+]]
+export type Facts = { [string]: unknown }
+
+-- A raise on its way to the boundary that catches it.
+export type Rejection = {
+    read code: Catalog.Code,
+    read facts: Facts,
+}
+
+-- State ---------------------------------------------------------------
+
+--[[
+    One list for the process, so a caller wires `onLog` once and hears everything. Two namespaces in
+    one place are not two things anybody watching logs subscribes to separately.
+]]
+local records: Listeners.List<Types.LogKind, string, Types.LogData> = Listeners.list (Threads.spawn)
+
+-- Private -------------------------------------------------------------
+
+--[[
+    The position comes from whoever calls in, the useful line being a caller's declaration site and
+    never this one. Nothing is frozen, so a listener that keeps a record has to copy it.
+]]
+local function said (kind: Types.LogKind, message: string, facts: Facts, file: string, line: number)
+    local data = table.clone (facts) :: any
+    data.file = file
+    data.line = line
+
+    Listeners.fan (records, kind, message, data :: Types.LogData)
+end
+
+--[[
+    Taken where the call raised, since a handler runs on the raising thread with the stack still
+    standing under it, which is the only moment a line inside a caller's listener can be read.
+]]
+local function traced (thrown: any): string return debug.traceback (tostring (thrown), 2) end
+
+-- Public --------------------------------------------------------------
+
+--[[
+    A call run with its answer, and a raise turned into a record rather than the engine's report.
+    The trace is the message, the library having no idea what the caller was doing. The answer is
+    why this is not `contained`: nobody waits on a listener, and a responder's return is the
+    reply.
+]]
+function Log.caught (call: (...any) -> ...any, ...: any): (boolean, any)
+    local ok, held = xpcall (call, traced, ...)
+    if ok then return true, held end
+
+    local file, line = debug.info (call, "sl")
+    said ("error", held, NO_FACTS, file, line)
+    return false, nil
+end
+
+--[[
+    A call on a thread of its own, with whatever it raises reported rather than propagated. Every
+    listener list is fanned through it, so a mistake in one cannot reach the caller who fired.
+]]
+function Log.contained <A...>(call: (A...) -> (), ...: A...)
+    Threads.spawn (Log.caught :: any, call :: any, ...)
+end
+
+--[[
+    Something the library dropped and moved past. A caller reads these to learn what their schema or
+    somebody else's client is doing, so a warning is never a fault and never a throw to come.
+]]
+function Log.warn (message: string, facts: Facts?)
+    local file, line = debug.info (2, "sl")
+    said ("warn", message, facts or NO_FACTS, file, line)
+end
+
+--[[
+    A fault the library contained, and then the throw. Both, since a caller watching the channel and
+    one reading a stack are two people and the record is all the first ever sees.
+]]
+function Log.error (message: string, facts: Facts?): never
+    local file, line = debug.info (2, "sl")
+    said ("error", message, facts or NO_FACTS, file, line)
+
+    return error (message, 0)
+end
+
+-- Gated on a global a release build folds away, so a shipped place composes none of this.
+function Log.debug (message: string, facts: Facts?)
+do return end
+    
+local file, line = debug.info (2, "sl")
+    said ("debug", message, facts or NO_FACTS, file, line)
+end
+
+-- A caller turned away, raised where they asked and recorded nowhere.
+function Log.refuse (message: string): never return error (message, 0) end
+
+--[[
+    A rejection for the boundary above. It carries a code and facts and no line, composing one being
+    a walk of a template on a path a hostile client decides how often to reach.
+]]
+function Log.reject (code: Catalog.Code, facts: Facts?): never
+    return error (table.freeze ({ code = code, facts = facts or NO_FACTS }) :: Rejection, 0)
+end
+
+--[[
+    A name with no fact behind it is left in its braces: a line saying `{path}` is a defect a reader
+    reports, where one saying nothing at all is one they work around.
+]]
+function Log.line (code: Catalog.Code, facts: Facts): string
+    local out = string.gsub (Catalog.entries[code].template, HELD, function (name: string): string
+        local held = facts[name]
+        return if held == nil then `{"{"}{name}{"}"}` else tostring (held)
+    end)
+    return out
+end
+
+-- Whatever the boundary caught, as the record a drop is.
+function Log.dropped (thrown: unknown, about: Facts, kind: Types.LogKind?)
+    local rejection = if typeof (thrown) == "table" then thrown :: Rejection else nil
+    local entry = if rejection == nil then nil else Catalog.entries[rejection.code]
+
+    local code: Catalog.Code = if entry == nil
+        then Catalog.BOUNDS
+        else (rejection :: Rejection).code
+    local raised: Facts = if entry == nil
+        then { said = tostring (thrown) }
+        else (rejection :: Rejection).facts
+
+    --[[
+        A copy, since what follows merges the raise in and the facts are the caller's table. A
+        record that wrote into its own argument is a promise this cannot make.
+    ]]
+    local facts = table.clone (about)
+    for name, value in raised do
+        facts[name] = value
+    end
+    facts.code = code
+
+    --[[
+        A frame that failed before naming a definition has no declaration site to point at, and a
+        record is promised a file and a line, so the library's own name stands there.
+    ]]
+    local file = if typeof (facts.file) == "string" then facts.file :: string else "Lync"
+    local line = if typeof (facts.line) == "number" then facts.line :: number else 1
+
+    said (kind or "warn", Log.line (code, facts), facts, file, line)
+end
+
+--[[
+    A listener, and the connection that ends it. Every registration on the channel goes through the
+    same list the printer sits in, so a caller who takes the printer keeps the records.
+]]
+function Log.onLog (
+    fn: (kind: Types.LogKind, message: string, data: Types.LogData) -> ()
+): Types.Connection
+    return Listeners.connect (records, fn)
+end
+
+--[[
+    The printer, handed over rather than registered. It is a listener like any other and is first in
+    the order because it is attached as this file loads, and a caller who wants to format records
+    themselves disconnects it and attaches their own.
+]]
+Log.console = Listeners.connect (
+    records,
+    function (kind: Types.LogKind, message: string, data: Types.LogData)
+        local at = `{data.file}:{data.line}`
+        if kind == "debug" then
+            print (`[lync] {at} {message}`)
+            return
+        end
+        warn (`[lync] {at} {message}`)
+    end
+)
+
+return table.freeze (Log)

package/kernel/Tally.luau

@@ -0,0 +1,128 @@
+--!strict
+--!optimize 2
+-- What a namespace has moved, counted where it happens and read as one frozen number set.
+
+local Types = require (script.Parent.Parent.Types)
+
+local Tally = {}
+
+-- Types ---------------------------------------------------------------
+
+export type Row = {
+    sent: number,
+    sentBytes: number,
+    received: number,
+    receivedBytes: number,
+    drops: number,
+}
+
+-- Everything counted, which is the four about the namespace and one line a definition.
+export type Tally = {
+    flushes: number,
+    sentBytes: number,
+    receivedBytes: number,
+    drops: number,
+    definitions: { [string]: Row },
+}
+
+-- Private -------------------------------------------------------------
+
+local function zeroed (): Row
+    return { sent = 0, sentBytes = 0, received = 0, receivedBytes = 0, drops = 0 }
+end
+
+-- The fallback line, for a count about a definition the namespace never compiled.
+local function line (of: Tally, name: string): Row
+    local held = of.definitions[name]
+    if held ~= nil then return held end
+
+    held = zeroed ()
+    of.definitions[name] = held
+    return held
+end
+
+-- Public --------------------------------------------------------------
+
+function Tally.new (names: { string }): Tally
+    local definitions: { [string]: Row } = {}
+    for _, name in names do
+        definitions[name] = zeroed ()
+    end
+
+    return {
+        flushes = 0,
+        sentBytes = 0,
+        receivedBytes = 0,
+        drops = 0,
+        definitions = definitions,
+    }
+end
+
+-- Counted where a block is composed, so one bound for two clients still counts once.
+function Tally.sent (of: Tally, name: string, bytes: number)
+    local held = line (of, name)
+    held.sent += 1
+    held.sentBytes += bytes
+end
+
+-- More bytes against a definition, without a call to go with them.
+function Tally.carried (of: Tally, name: string, bytes: number)
+    line (of, name).sentBytes += bytes
+end
+
+-- Counted off the frame, whatever became of what was inside it.
+function Tally.received (of: Tally, name: string, bytes: number)
+    local held = line (of, name)
+    held.received += 1
+    held.receivedBytes += bytes
+end
+
+-- One drop, against the definition it was about where there is one.
+function Tally.dropped (of: Tally, name: string?)
+    of.drops += 1
+    if name == nil then return end
+
+    line (of, name).drops += 1
+end
+
+-- The engine's own figure, above the blocks inside it, since framing rides outside them.
+function Tally.moved (of: Tally, bytes: number)
+    of.sentBytes += bytes
+end
+
+-- The same figure coming the other way.
+function Tally.took (of: Tally, bytes: number)
+    of.receivedBytes += bytes
+end
+
+function Tally.flushed (of: Tally)
+    of.flushes += 1
+end
+
+--[[
+    Copied and frozen, since the surface says two readings subtract into an exact rate and a caller
+    who kept one is owed the numbers they took.
+]]
+function Tally.reading (of: Tally): Types.Stats
+    local definitions: { [string]: Types.DefinitionStats } = {}
+
+    for name, held in of.definitions do
+        definitions[name] = table.freeze ({
+            sent = held.sent,
+            sentBytes = held.sentBytes,
+            received = held.received,
+            receivedBytes = held.receivedBytes,
+            drops = held.drops,
+        })
+    end
+
+    return table.freeze ({
+        flushes = of.flushes,
+        sentBytes = of.sentBytes,
+        receivedBytes = of.receivedBytes,
+        drops = of.drops,
+        definitions = table.freeze (definitions),
+    })
+end
+
+return table.freeze (Tally)

package/kernel/Threads.luau

@@ -0,0 +1,44 @@
+--!strict
+--!optimize 2
+-- Pooled coroutines: a call runs on one immediately, and cannot reach whoever asked for it.
+
+local Threads = {}
+
+-- State ---------------------------------------------------------------
+
+--[[
+    A thread is taken per call and puts itself back when that call returns, so the pile grows to the
+    deepest run of calls ever in flight at one moment and never past it.
+]]
+local idle: { thread } = {}
+
+-- Private -------------------------------------------------------------
+
+local function ran (call: (...any) -> (), ...: any)
+    call (...)
+    table.insert (idle, coroutine.running ())
+end
+
+--[[
+    The first call arrives as this function's own arguments, so a fresh thread is resumed once and
+    not twice. Every call after it arrives out of the yield below.
+]]
+local function cycles (call: (...any) -> (), ...: any)
+    ran (call, ...)
+    while true do
+        ran (coroutine.yield ())
+    end
+end
+
+-- Public --------------------------------------------------------------
+
+function Threads.spawn <A...>(call: (A...) -> (), ...: A...)
+    local held = table.remove (idle)
+    if held == nil then
+        task.spawn (coroutine.create (cycles), call, ...)
+        return
+    end
+    task.spawn (held, call, ...)
+end
+
+return table.freeze (Threads)