@axpecter/lync 2.3.2 → 3.0.0

package/api/Query.luau

@@ -0,0 +1,149 @@
+--!strict
+--!optimize 2
+-- The query handle: one responder a side, and a request that answers rather than throws or hangs.
+
+local Base = require (script.Parent.Parent.codec.Base)
+local Define = require (script.Parent.Define)
+local Handles = require (script.Parent.Parent.runtime.Handles)
+local Serial = require (script.Parent.Parent.shape.Serial)
+local Types = require (script.Parent.Parent.Types)
+
+local Query = {}
+Query.__index = Query
+
+-- Private -------------------------------------------------------------
+
+-- The one responder this side gets, held until there is a dispatch to hand it to.
+local function answers (self: any, said: string, fn: (...any) -> any)
+    local live = self.live
+    local under = Define.naming (live, said)
+
+    local session = live.session
+    if session ~= nil and session.started then
+        Define.refuse (`{said} after {under} started, and start seals responders`, under)
+    end
+
+    if self.answering ~= nil then
+        Define.refuse (`{under} already has a responder, and a query has one`, under)
+    end
+
+    self.answering = fn
+    Handles.waiting (live, function (session) session:respond (live.id :: number, under, fn) end)
+end
+
+--[[
+    A client's request, which yields until it is answered or told why it will not be. A third
+    argument is the server form's completion and the client form has no third, so a call carrying
+    one is the server's made on the wrong machine. The lookup below cannot refuse, the caller
+    having branched on the side it tests, and what it is called for is the session.
+]]
+local function asked (
+    self: any,
+    value: any,
+    timeout: number?,
+    complete: any
+): (boolean, any, Types.OutcomeData?)
+    local session = Define.asking (self.live, "request")
+    if complete ~= nil then
+        Define.refuse (
+            "request with a completion is the server's call, and this is a client",
+            Define.naming (self.live, "request")
+        )
+    end
+
+    local settled = false
+    local parked: thread? = nil
+
+    local ok: boolean
+    local result: any
+    local data: Types.OutcomeData?
+
+    session:ask (self.live.def, nil, value, timeout, function (answered, gave, about)
+        ok, result, data = answered, gave, about
+        settled = true
+
+        local held = parked
+        if held ~= nil then task.spawn (held) end
+    end)
+
+    if not settled then
+        parked = coroutine.running ()
+        coroutine.yield ()
+    end
+
+    return ok, result, data
+end
+
+-- Public --------------------------------------------------------------
+
+--[[
+    Two builds and one handle, because a request and its reply are one agreement between two
+    machines, and they share one definition and two consecutive ids.
+]]
+function Query.new <Q, R>(of: Types.Codec<Q>, reply: Types.Codec<R>): Types.Query<Q, R>
+    --[[
+        Level two is the caller rather than this frame, so a schema refused at start points at the
+        declaration instead of the start that caught it.
+    ]]
+    local file, line = debug.info (2, "sl")
+    local self = {
+        kind = "query" :: "query",
+        of = of,
+        reply = reply,
+        at = { file = file, line = line },
+        live = Handles.live (),
+        answering = nil :: ((...any) -> any)?,
+    }
+
+    return (setmetatable (self, Query) :: any) :: Types.Query<Q, R>
+end
+
+--[[
+    The responder, on whichever side is answering.
+
+    Two names for one registration, because what a responder is handed differs between the sides
+    and what it is registered as does not.
+]]
+function Query.onServer (self: any, fn: (any, Player) -> any) answers (self, "onServer", fn) end
+
+function Query.onClient (self: any, fn: (any) -> any) answers (self, "onClient", fn) end
+
+--[[
+    One request, in whichever of its two forms this machine has. Which form comes off the machine
+    and never off the arguments, so a call before start names the namespace that has not opened
+    rather than an argument. What the arguments say afterwards is whether the caller made the other
+    side's call, which is the one mistake here that used to answer with somebody else's error.
+]]
+function Query.request (self: any, first: any, second: any, third: any, fourth: any): ...any
+    if self.live.isServer then
+        --[[
+            The server form carries a completion and the client form has no third argument, so a
+            call reaching here without one is the client's. The lookup below cannot refuse, the
+            branch above having settled the side before it is asked, and what it is called for is
+            the session and the namespace it names when there is none.
+        ]]
+        local session = Define.serving (self.live, "request")
+        if typeof (third) ~= "function" then
+            Define.refuse (
+                "request without a completion is a client's call, and this is the server",
+                Define.naming (self.live, "request")
+            )
+        end
+
+        session:ask (self.live.def, first, second, fourth, third)
+        return
+    end
+
+    return asked (self, first, second, third)
+end
+
+-- The schema as text, which is the wording a refused request is answered with.
+function Query.describe (self: any): string
+    return Serial.frame ({
+        kind = "query",
+        of = { cell = Base.cell (self.of) },
+        reply = { cell = Base.cell (self.reply) },
+    })
+end
+
+return table.freeze (Query)

package/api/Set.luau

@@ -0,0 +1,189 @@
+--!strict
+--!optimize 2
+-- The set handle: the server's records, the client's view of them, and the one key that splits.
+
+local Base = require (script.Parent.Parent.codec.Base)
+local Define = require (script.Parent.Define)
+local Handles = require (script.Parent.Parent.runtime.Handles)
+local Serial = require (script.Parent.Parent.shape.Serial)
+local Sync = require (script.Parent.Parent.state.Sync)
+local Types = require (script.Parent.Parent.Types)
+
+local Set = {}
+Set.__index = Set
+
+-- Private -------------------------------------------------------------
+
+-- The set this handle mutates, which only the server has records in.
+local function owning (self: any, said: string): Sync.Sync
+    local live = self.live
+    return Define.serving (live, said):set (live.id :: number)
+end
+
+--[[
+    The set this handle reads, or nothing where its namespace has not opened one.
+
+    Nothing rather than a refusal, because a read is what a caller does to find out whether there is
+    anything there, and a set before start holds nothing in exactly the way an empty one does.
+]]
+local function viewing (self: any): Sync.Sync?
+    local live = self.live
+    local session = live.session
+    if session == nil then return nil end
+
+    return session:set (live.id :: number)
+end
+
+-- A walk over nothing, which is what a set that has not opened has to walk.
+local function barren (): (number?, any) return nil end
+
+--[[
+    A callback, attached whenever the caller liked.
+
+    Set callbacks attach at any time for the reason listeners do, and the one that most needs it is
+    `onAdded`: a client attaching after start would miss the seeding its own join asked for.
+]]
+local function watches (
+    self: any,
+    attach: (Sync.Sync, any) -> Types.Connection,
+    fn: any
+): Types.Connection
+    local live = self.live
+    return Handles.later (
+        live,
+        function (session) return attach (session:set (live.id :: number), fn) end
+    )
+end
+
+-- Public --------------------------------------------------------------
+
+-- What clears an optional field, since nothing else can.
+Set.NONE = Sync.NONE
+
+--[[
+    The key is not here. A set is split by a field a caller names afterwards, and until they do the
+    whole set goes to everybody, which is the declaration this makes on its own.
+]]
+function Set.new <T>(of: Types.Codec<T>): Types.Set<T>
+    --[[
+        Level two is the caller, so a set refused at start is named against the line that declared
+        it rather than against the start that did the refusing.
+    ]]
+    local file, line = debug.info (2, "sl")
+    local self = {
+        kind = "set" :: "set",
+        of = of,
+        keyField = nil :: string?,
+        at = { file = file, line = line },
+        live = Handles.live (),
+    }
+
+    return (setmetatable (self, Set) :: any) :: Types.Set<T>
+end
+
+--[[
+    The field records are split by, which is what gives a key an audience to be assigned one.
+
+    Whether the field exists and whether its codec can be a key is settled at start against the
+    compiled record rather than here against the declaration, which has no record to look in yet.
+]]
+function Set.keyBy (self: any, field: string): any
+    Define.declaring (self.live, "keyBy")
+    self.keyField = field
+    return self
+end
+
+-- The full record, under an id nothing else in this set holds.
+function Set.add (self: any, id: number, record: any)
+    local of = owning (self, "add")
+    Sync.add (of, id, record)
+end
+
+-- Only the fields named, and only to whoever can already see the record they are on.
+function Set.update (self: any, id: number, fields: any)
+    local of = owning (self, "update")
+    Sync.update (of, id, fields)
+end
+
+function Set.remove (self: any, id: number)
+    local of = owning (self, "remove")
+    Sync.remove (of, id)
+end
+
+--[[
+    Everything at once, which goes out as one marker per partition rather than a removal per id.
+    A listener is still told once per record, under a cause that says a clear was what did it.
+]]
+function Set.clear (self: any)
+    local of = owning (self, "clear")
+    Sync.clear (of)
+end
+
+--[[
+    Who sees the records under one key, which an unkeyed set has nobody to say it about.
+
+    Refused rather than ignored: an audience on a set that goes to everybody is a caller who
+    believes they have restricted something and has not.
+]]
+function Set.audience (self: any, key: any, to: Types.Recipient)
+    local of = owning (self, "audience")
+    if self.keyField == nil then
+        Define.refuse (
+            "audience is for a set split by keyBy, and this one goes to everybody",
+            Define.naming (self.live, "audience")
+        )
+    end
+
+    Sync.audience (of, key, to)
+end
+
+--[[
+    The live record under an id, borrowed rather than copied.
+
+    Nothing where this machine holds no record under it, which on a client is every id its audiences
+    do not reach as well as every id nobody has added.
+]]
+function Set.get (self: any, id: number): any?
+    local of = viewing (self)
+    if of == nil then return nil end
+
+    return Sync.get (of, id)
+end
+
+function Set.__len (self: any): number
+    local of = viewing (self)
+    if of == nil then return 0 end
+
+    return Sync.size (of)
+end
+
+-- Every record this machine holds, in no order a caller may rely on.
+function Set.__iter (self: any): (any, any, any)
+    local of = viewing (self)
+    if of == nil then return barren, self, nil end
+
+    return Sync.walk (of), self, nil
+end
+
+function Set.onAdded (self: any, fn: (number, any) -> ()): Types.Connection
+    return watches (self, Sync.onAdded, fn)
+end
+
+function Set.onChanged (self: any, fn: (number, any, any?) -> ()): Types.Connection
+    return watches (self, Sync.onChanged, fn)
+end
+
+function Set.onRemoved (self: any, fn: (number, Types.Cause) -> ()): Types.Connection
+    return watches (self, Sync.onRemoved, fn)
+end
+
+-- The schema as text, which is how a record turned away on arrival is described back.
+function Set.describe (self: any): string
+    return Serial.frame ({
+        kind = "set",
+        of = { cell = Base.cell (self.of) },
+        keyField = self.keyField,
+    })
+end
+
+return table.freeze (Set)

package/channel/Blocks.luau

@@ -0,0 +1,124 @@
+--!strict
+--!optimize 2
+-- One block of a frame: the bytes a producer laid down, and how many places still hold them.
+
+local Bytes = require (script.Parent.Parent.wire.Bytes)
+
+local Blocks = {}
+
+-- Constants -----------------------------------------------------------
+
+--[[
+    The five classes a reliable frame's blocks drain in, which is that drain order as the buckets a
+    queue has.
+]]
+const RESPONSE = 1
+const REQUEST = RESPONSE + 1
+const PACKET = REQUEST + 1
+const ESTABLISH = PACKET + 1
+const DELTA = ESTABLISH + 1
+
+-- What a block on the lossy lane is classed as, which is nothing.
+const LOOSE = 0
+
+-- What a released block points at until its next build, so a pooled record pins no bytes.
+const EMPTY = buffer.create (0)
+
+-- Types ---------------------------------------------------------------
+
+-- One block, queued and copied and eventually let go.
+export type Block = {
+    buf: buffer,
+    len: number,
+    class: number,
+    seq: number,
+    refs: { Instance }?,
+    rc: number,
+}
+
+-- State ---------------------------------------------------------------
+
+-- Blocks nobody holds any more, kept for the next build rather than collected.
+local free: { Block } = {}
+
+-- Public --------------------------------------------------------------
+
+Blocks.RESPONSE = RESPONSE
+Blocks.REQUEST = REQUEST
+Blocks.PACKET = PACKET
+Blocks.ESTABLISH = ESTABLISH
+Blocks.DELTA = DELTA
+Blocks.LOOSE = LOOSE
+
+-- How many classes there are, which is the number of buckets a reliable queue keeps.
+Blocks.CLASSES = DELTA
+
+-- What a caller runs to fill one block, which is everything this layer refuses to know.
+export type Produce = (b: buffer, pos: number) -> number
+
+--[[
+    One block over bytes already in scratch, sealed at a length rather than run from a producer,
+    because a planner writes a section to decide whether it fits and the frame has moved on by the
+    time the block is wanted. What is sealed is exactly the bytes written, so a frame is the sum of
+    its blocks, and `refs` is copied because the array it came from is about to be refilled.
+]]
+function Blocks.sealed (
+    into: buffer,
+    len: number,
+    class: number,
+    seq: number,
+    refs: { Instance }?
+): Block
+    local held = if refs == nil then nil else table.clone (refs)
+    local sealed = Bytes.seal (into, len)
+
+    local of = table.remove (free)
+    if of == nil then
+        return { buf = sealed, len = len, class = class, seq = seq, refs = held, rc = 1 }
+    end
+
+    of.buf = sealed
+    of.len = len
+    of.class = class
+    of.seq = seq
+    of.refs = held
+    of.rc = 1
+    return of
+end
+
+-- One block, built by running a producer into scratch and sealing what it wrote.
+function Blocks.build (
+    into: buffer,
+    class: number,
+    seq: number,
+    refs: { Instance }?,
+    produce: Produce
+): Block
+    return Blocks.sealed (into, produce (into, 0), class, seq, refs)
+end
+
+-- One more hold, taken by whatever is about to keep a block past the call that handed it over.
+function Blocks.retain (of: Block)
+    of.rc += 1
+end
+
+-- One hold fewer, and the pool where the last one leaves it.
+function Blocks.release (of: Block)
+    of.rc -= 1
+    if of.rc > 0 then return end
+
+    of.buf = EMPTY
+    of.len = 0
+    of.refs = nil
+    table.insert (free, of)
+end
+
+-- Every block in a list let go, and the list emptied.
+function Blocks.drain (held: { Block })
+    for _, of in held do
+        Blocks.release (of)
+    end
+    table.clear (held)
+end
+
+return table.freeze (Blocks)

package/channel/Group.luau

@@ -0,0 +1,118 @@
+--!strict
+--!optimize 2
+-- A membership set a caller mutates and an audience holds, and the sweep that thins one.
+
+local Log = require (script.Parent.Parent.kernel.Log)
+local Types = require (script.Parent.Parent.Types)
+
+local Group = {}
+
+-- Types ---------------------------------------------------------------
+
+--[[
+    A set kept as both an array and the place each member sits in it. The array is what a walk and a
+    count read, and the index is what a membership test and a removal read, and neither is derivable
+    from the other in constant time.
+]]
+type Held = {
+    members: { Player },
+    at: { [Player]: number },
+}
+
+-- Private -------------------------------------------------------------
+
+local Members = {}
+Members.__index = Members
+
+--[[
+    What a group becomes when it is released. Every read and every write goes through a metamethod
+    that raises, so a caller holding a stale reference is told rather than answered: a destroyed
+    group that reported an empty membership would let them fire at nobody forever and never learn
+    why.
+]]
+local Dead = {}
+
+local function gone (): any return Log.refuse ("this group was destroyed") end
+
+Dead.__index = gone
+Dead.__len = gone
+Dead.__iter = gone
+
+-- State ---------------------------------------------------------------
+
+-- Every group that has not been destroyed, which is where a leave sweep finds them.
+local live: { [Held]: true } = {}
+
+-- Public --------------------------------------------------------------
+
+--[[
+    Adding a member twice leaves one and removing an absent one is nothing. A caller adds on every
+    join and removes on every leave from code that has no idea what the group held, so counting
+    duplicates or refusing an absent removal would make each of those sites read it first.
+]]
+function Members.add (self: Held, player: Player)
+    if self.at[player] ~= nil then return end
+
+    table.insert (self.members, player)
+    self.at[player] = #self.members
+end
+
+-- The last member fills the gap, so a removal costs nothing and the order is not one to rely on.
+function Members.remove (self: Held, player: Player)
+    local index = self.at[player]
+    if index == nil then return end
+
+    local last = #self.members
+    local moved = self.members[last]
+
+    self.members[index] = moved
+    self.at[moved] = index
+
+    self.members[last] = nil
+    self.at[player] = nil
+end
+
+function Members.has (self: Held, player: Player): boolean return self.at[player] ~= nil end
+
+--[[
+    Emptied and let go, in that order. The emptying is what releases the members: a group is the
+    only thing holding some of them by the time a caller is done with it, and waiting for the
+    collector to notice is exactly the timing this library never rides.
+]]
+function Members.destroy (self: Held)
+    live[self] = nil
+
+    table.clear (self.members)
+    table.clear (self.at)
+    setmetatable (self :: any, Dead)
+end
+
+function Members.__len (self: Held): number return #self.members end
+
+function Members.__iter (self: Held) return ipairs (self.members) end
+
+function Group.new (): Types.Group
+    local self: Held = setmetatable ({ members = {}, at = {} }, Members) :: any
+    live[self] = true
+
+    return (self :: any) :: Types.Group
+end
+
+--[[
+    Whether a value is a group, which is what a recipient asks before it walks one. A destroyed one
+    never reaches here: every recipient form is told apart by reading a field off it first, and
+    reading any field off a destroyed group is already the raise that says so.
+]]
+function Group.is (value: unknown): boolean return getmetatable (value :: any) == Members end
+
+--[[
+    Every group a departed player was in, thinned. Called once per leave from wherever the removal
+    is heard, which is the same sweep that releases every other structure keyed by them.
+]]
+function Group.dropped (player: Player)
+    for of in live do
+        (of :: any):remove (player)
+    end
+end
+
+return table.freeze (Group)