@axpecter/lync 2.3.2 → 3.0.0

package/Types.luau

@@ -0,0 +1,215 @@
+--!strict
+--!optimize 2
+-- The public type vocabulary: every type a consumer names, and the inference behind it.
+
+-- Types ---------------------------------------------------------------
+
+export type LogKind = "warn" | "error" | "debug"
+export type Cause = "removed" | "cleared"
+export type OutcomeCode = "timeout" | "unanswered" | "leave" | "shutdown"
+
+--[[
+    The three sentinels. Each carries a phantom field so the checker keeps them apart from one
+    another and from any table a caller might pass instead.
+]]
+export type All = { read _all: true }
+export type Except = { read _except: true }
+export type None = { read _none: true }
+
+export type Recipient = All | Except | Group | Player | { Player }
+
+--[[
+    What `define` takes, keyed by the names the definitions are reached under. Named rather than
+    written inline so a caller assembling a namespace has something to annotate.
+]]
+export type Definition = Packet<any> | Query<any, any> | Set<any>
+export type Definitions = { [string]: Definition }
+
+export type Connection = {
+    read connected: boolean,
+    read disconnect: (self: Connection) -> (),
+}
+
+--[[
+    Reused between decodes, so anything kept from it must be copied. `last` is stamped on every
+    arrival, accepted or not.
+]]
+export type ValidateContext = {
+    read player: Player?,
+    read now: number,
+    read last: number?,
+}
+
+export type LogData = {
+    read file: string,
+    read line: number,
+    read player: Player?,
+    read definition: string?,
+    read [string]: unknown,
+}
+
+export type OutcomeData = {
+    read definition: string,
+    read elapsed: number?,
+}
+
+export type DefinitionStats = {
+    read sent: number,
+    read sentBytes: number,
+    read received: number,
+    read receivedBytes: number,
+    read drops: number,
+}
+
+export type Stats = {
+    read flushes: number,
+    read sentBytes: number,
+    read receivedBytes: number,
+    read drops: number,
+    read definitions: { [string]: DefinitionStats },
+}
+
+--[[
+    The phantom `_T` is the whole inference story: it never exists at run time and Infer reads it
+    back out below. `monotonic` takes any codec because a generic type may not name itself with a
+    different argument. No trend marker sits beside it, an order being derived rather than
+    declared.
+]]
+export type Codec<T> = {
+    read _T: T,
+    read validate: (
+        self: Codec<T>,
+        check: (value: T, ctx: ValidateContext) -> string?
+    ) -> Codec<T>,
+    read as: <U>(self: Codec<T>, to: (value: T) -> U, from: (value: U) -> T) -> Codec<U>,
+    read monotonic: (self: Codec<T>) -> Codec<T>,
+    read newest: (self: Codec<T>, hz: number?) -> Codec<T>,
+}
+
+--[[
+    The value a codec carries. `Infer<Codec<Vector3>>` is `Vector3`, which is what lets a handler
+    signature fall out of the schema with nothing annotated.
+]]
+export type function Infer (codec) return codec:readproperty (types.singleton ("_T")) end
+
+--[[
+    A table of codecs read as the record it describes, mapping each field to the value its codec
+    carries. This is what `struct` returns the codec of.
+]]
+export type function Schema (fields)
+    local record = types.newtable ()
+    for key, property in fields:properties () do
+        local codec = property.read or property.write
+        record:setproperty (key, codec:readproperty (types.singleton ("_T")))
+    end
+    return record
+end
+
+--[[
+    Every field is optional so a caller may omit it, and the clear sentinel is accepted on exactly
+    the fields the record declares optional.
+]]
+export type function Update (record, none)
+    if not (record:is ("table") or record:is ("class")) then return types.any end
+
+    local fields = types.newtable ()
+    for key, property in record:properties () do
+        local field = property.read or property.write
+        local isClearable = false
+        if field:is ("union") then
+            for _, part in field:components () do
+                if part:is ("nil") then isClearable = true end
+            end
+        end
+        local value = if isClearable then types.unionof (field, none) else field
+        fields:setproperty (key, types.optional (value))
+    end
+    return fields
+end
+
+export type Packet<T> = {
+    read unreliable: (self: Packet<T>) -> Packet<T>,
+    read newest: (self: Packet<T>, hz: number?) -> Packet<T>,
+    read timestamped: (self: Packet<T>) -> Packet<T>,
+    read fireServer: (self: Packet<T>, value: T) -> (),
+    read fireClient: (self: Packet<T>, recipient: Recipient, value: T) -> (),
+    read onServer: (
+        self: Packet<T>,
+        fn: (value: T, player: Player, sent: number?) -> ()
+    ) -> Connection,
+    read onClient: (self: Packet<T>, fn: (value: T, sent: number?) -> ()) -> Connection,
+    read describe: (self: Packet<T>) -> string,
+}
+
+--[[
+    The client form yields for the reply. The server form takes a completion callback and never
+    yields. Both answer `(true, reply)` or `(false, code, data)`, so a request never throws and
+    never hangs.
+]]
+export type Outcome<R> = (ok: boolean, result: R | OutcomeCode, data: OutcomeData?) -> ()
+
+export type Query<Q, R> = {
+    read onServer: (self: Query<Q, R>, fn: (value: Q, player: Player) -> R) -> (),
+    read onClient: (self: Query<Q, R>, fn: (value: Q) -> R) -> (),
+    read request: ((
+        self: Query<Q, R>,
+        value: Q,
+        timeout: number?
+    ) -> (boolean, R | OutcomeCode, OutcomeData?)) & ((
+        self: Query<Q, R>,
+        client: Player,
+        value: Q,
+        complete: Outcome<R>,
+        timeout: number?
+    ) -> ()),
+    read describe: (self: Query<Q, R>) -> string,
+}
+
+type SetFields<T> = {
+    read keyBy: (self: Set<T>, field: string) -> Set<T>,
+    read onAdded: (self: Set<T>, fn: (id: number, record: T) -> ()) -> Connection,
+    read onChanged: (self: Set<T>, fn: (id: number, record: T, old: T?) -> ()) -> Connection,
+    read onRemoved: (self: Set<T>, fn: (id: number, cause: Cause) -> ()) -> Connection,
+    read add: (self: Set<T>, id: number, record: T) -> (),
+    read update: (self: Set<T>, id: number, fields: Update<T, None>) -> (),
+    read remove: (self: Set<T>, id: number) -> (),
+    read clear: (self: Set<T>) -> (),
+    read audience: (self: Set<T>, key: unknown, recipient: Recipient) -> (),
+    read get: (self: Set<T>, id: number) -> T?,
+    read describe: (self: Set<T>) -> string,
+}
+
+--[[
+    `#set` counts the local view and `for id, record in set do` walks it, so both reads sit on the
+    metatable rather than the record.
+]]
+type SetMeta<T> = {
+    __len: (self: Set<T>) -> number,
+    __iter: (
+        self: Set<T>
+    ) -> (({ [number]: T }, number) -> (number?, T), { [number]: T }, number),
+}
+
+--[[
+    No key parameter. Luau widens a string argument to `string` rather than its singleton, a
+    declaration inside the define literal has no annotation site, and a generic type may not name
+    itself with a different argument, so a key type could never be carried here. A key on an unkeyed
+    set is a programmer error the runtime throws on.
+]]
+export type Set<T> = typeof(setmetatable ({} :: SetFields<T>, {} :: SetMeta<T>))
+
+type GroupFields = {
+    read add: (self: Group, player: Player) -> (),
+    read remove: (self: Group, player: Player) -> (),
+    read has: (self: Group, player: Player) -> boolean,
+    read destroy: (self: Group) -> (),
+}
+
+type GroupMeta = {
+    __len: (self: Group) -> number,
+    __iter: (self: Group) -> (({ Player }, number) -> (number?, Player), { Player }, number),
+}
+
+export type Group = typeof(setmetatable ({} :: GroupFields, {} :: GroupMeta))
+
+return nil

package/api/Define.luau

@@ -0,0 +1,154 @@
+--!strict
+--!optimize 2
+-- A namespace declared: the names under it, and where a handle finds what it was bound to.
+
+local Handles = require (script.Parent.Parent.runtime.Handles)
+local Legality = require (script.Parent.Parent.shape.Legality)
+local Log = require (script.Parent.Parent.kernel.Log)
+local Order = require (script.Parent.Parent.shape.Order)
+local Session = require (script.Parent.Parent.runtime.Session)
+local Types = require (script.Parent.Parent.Types)
+
+local Define = {}
+
+-- Types ---------------------------------------------------------------
+
+--[[
+    The binding a handle carries, named here because this is where a caller's half of it is
+    written. The other half is filled in by a session, which is why the record is not declared
+    here.
+]]
+export type Live = Handles.Live
+
+-- One namespace as declared, before anything has been compiled from it.
+export type Space = {
+    read name: string,
+    read defs: Types.Definitions,
+    read names: { string },
+}
+
+-- State ---------------------------------------------------------------
+
+-- Every namespace this machine has declared, by the name it was declared under.
+local spaces: { [string]: Space } = {}
+local order: { string } = {}
+local sealed = false
+
+-- Private -------------------------------------------------------------
+
+local function refuse (said: string, name: string): never
+    return Log.error (said, { definition = name })
+end
+
+-- What a message calls a definition, which is both halves because either alone names several.
+local function called (of: Live): string return `{of.space}.{of.name}` end
+
+-- Public --------------------------------------------------------------
+
+Define.spaces = spaces
+Define.order = order
+Define.refuse = refuse
+
+-- What this definition is called, which is both halves where it has them.
+function Define.naming (of: Live, said: string): string
+    if of.space == nil then return said end
+    return called (of)
+end
+
+-- A modifier, refused once the namespace it is in has been started.
+function Define.declaring (of: Live, said: string)
+    if of.session == nil then return end
+
+    refuse (
+        `{said} was called after {of.space} started, and a declaration is not a setting`,
+        called (of)
+    )
+end
+
+-- The session a handle talks through, or nothing where it has none yet.
+function Define.reach (of: Live, said: string): Session.Session
+    local session = of.session
+    if session == nil then
+        if of.space == nil then
+            refuse (`{said} before it was named in a namespace, which define is for`, said)
+        end
+        refuse (`{said} before {of.space} was started`, called (of))
+    end
+
+    local held = session :: Session.Session
+    if held.closed then
+        refuse (`{said} after {of.space} was closed, and close lets its remotes go`, called (of))
+    end
+
+    return held
+end
+
+-- A call only the server makes, since the records and the audiences are the server's.
+function Define.serving (of: Live, said: string): Session.Session
+    local session = Define.reach (of, said)
+    if not of.isServer then
+        refuse (`{said} is the server's call, and this is a client`, called (of))
+    end
+
+    return session
+end
+
+-- A call only a client makes, since what it leaves out is the one machine a client can reach.
+function Define.asking (of: Live, said: string): Session.Session
+    local session = Define.reach (of, said)
+    if of.isServer then
+        refuse (`{said} is a client's call, and this is the server`, called (of))
+    end
+
+    return session
+end
+
+-- No more namespaces, which is what start says about the ones it did not find.
+function Define.seal () sealed = true end
+
+--[[
+    A namespace, as the definitions a caller wrote and the name both machines require it under. The
+    table handed over is the one handed back, frozen, so a caller who edited it afterwards cannot
+    leave the two machines agreeing at different times. A name already defined refuses.
+]]
+function Define.define (name: string, defs: Types.Definitions): Types.Definitions
+    if sealed then
+        refuse (`{name} was defined after start, and start opens what there is`, name)
+    end
+    if spaces[name] ~= nil then refuse (`{name} has already been defined`, name) end
+
+    local why = Legality.named (name)
+    if why ~= nil then refuse (`{name} {why}`, name) end
+    if name == "" then refuse ("a namespace with no name cannot be required by anybody", name) end
+
+    local names = Order.names (defs)
+    for _, under in names do
+        --[[
+            Read through a check that the value is a table at all. A caller who wrote a number
+            against a name has made the typo this refusal is for, and reaching into it first turns
+            that into an index of a number, which says nothing about what they got wrong.
+        ]]
+        local one = defs[under] :: any
+        local live = if typeof (one) == "table" then one.live :: Live? else nil
+        if live == nil then refuse (`{name}.{under} is not a packet, a query or a set`, name) end
+
+        local held = live :: Live
+        if held.space ~= nil then
+            refuse (`{name}.{under} is already named in {held.space}`, name)
+        end
+
+        held.space = name
+        held.name = under
+    end
+
+    spaces[name] = table.freeze ({ name = name, defs = defs, names = table.freeze (names) })
+    table.insert (order, name)
+
+    --[[
+        Frozen where it is not already. A caller who froze their own table handed over one that is
+        as unwritable as this asks for, and freezing a frozen table raises rather than agreeing.
+    ]]
+    return if table.isfrozen (defs) then defs else table.freeze (defs)
+end
+
+return table.freeze (Define)

package/api/Lifecycle.luau

@@ -0,0 +1,119 @@
+--!strict
+--!optimize 2
+-- The place's lifecycle: the one start, the flushes that send, and the close that lets go.
+
+local Define = require (script.Parent.Define)
+local Log = require (script.Parent.Parent.kernel.Log)
+local Session = require (script.Parent.Parent.runtime.Session)
+local Transport = require (script.Parent.Parent.channel.Transport)
+local Types = require (script.Parent.Parent.Types)
+
+local Lifecycle = {}
+
+-- State ---------------------------------------------------------------
+
+--[[
+    Every namespace that has been opened, under the name it was declared with.
+
+    Module state for the reason the namespace table is: a place starts once, whatever number of
+    scripts declared into it, and every call here is about all of them or about one by name.
+]]
+local sessions: { [string]: Session.Session } = {}
+local started = false
+
+-- Private -------------------------------------------------------------
+
+-- Who is here, as the three things a namespace asks and no more.
+local function rostered (): Session.Roster
+    local players = game:GetService ("Players")
+
+    return {
+        all = function (): { Player } return players:GetPlayers () end,
+        onAdded = function (_, take: (Player) -> ()): () -> ()
+            local held = players.PlayerAdded:Connect (take)
+            return function () held:Disconnect () end
+        end,
+        -- Wrapped, unlike the one above it, because this event hands over a reason as well.
+        onRemoving = function (_, take: (Player) -> ()): () -> ()
+            local held = players.PlayerRemoving:Connect (function (who: Player) take (who) end)
+            return function () held:Disconnect () end
+        end,
+    }
+end
+
+-- The namespace a name reaches, refused where it reaches none.
+local function opened (name: string, said: string): Session.Session
+    local session = sessions[name]
+    if session == nil then
+        Log.error (`{said} named {name}, which is no namespace this place defined`, {
+            definition = name,
+        })
+    end
+
+    return session :: Session.Session
+end
+
+-- Nothing here is about a definition, so a refusal about the place itself names none.
+local function running (said: string)
+    if started then return end
+
+    Log.error (`{said} before start, and nothing is open until a place starts`)
+end
+
+-- Public --------------------------------------------------------------
+
+-- Every namespace declared, compiled, bound to its handles, and opened.
+function Lifecycle.start ()
+    if started then Log.error ("start has already run, and a place starts once") end
+    started = true
+    Define.seal ()
+
+    local side: Transport.Side = if game:GetService ("RunService"):IsServer ()
+        then "server"
+        else "client"
+    local roster = rostered ()
+
+    for _, name in Define.order do
+        local space = Define.spaces[name]
+        local transport = Transport.new (name, side)
+        local session = Session.new (name, space.defs, transport, roster, side)
+
+        sessions[name] = session
+        session:start ()
+    end
+end
+
+-- Everything buffered since the last flush, out, for every namespace or for one by name.
+function Lifecycle.flush (first: (string | number)?, second: number?)
+    running ("flush")
+
+    if type (first) == "string" then
+        opened (first, "flush"):flush (second)
+        return
+    end
+
+    for _, name in Define.order do
+        sessions[name]:flush (first)
+    end
+end
+
+--[[
+    Every namespace closed, in the order they were declared. A second call is not a fault: what
+    close promises is that the remotes are let go and nothing is left waiting, and both are true
+    the second time.
+]]
+function Lifecycle.close ()
+    running ("close")
+
+    for _, name in Define.order do
+        sessions[name]:close ()
+    end
+end
+
+-- One namespace's counters, as the frozen reading two of which subtract into a rate.
+function Lifecycle.stats (name: string): Types.Stats
+    running ("stats")
+    return opened (name, "stats"):stats ()
+end
+
+return table.freeze (Lifecycle)

package/api/Packet.luau

@@ -0,0 +1,108 @@
+--!strict
+--!optimize 2
+-- The packet handle: what a caller declares before start, and what they fire and hear after it.
+
+local Base = require (script.Parent.Parent.codec.Base)
+local Define = require (script.Parent.Define)
+local Handles = require (script.Parent.Parent.runtime.Handles)
+local Legality = require (script.Parent.Parent.shape.Legality)
+local Serial = require (script.Parent.Parent.shape.Serial)
+local Types = require (script.Parent.Parent.Types)
+
+local Packet = {}
+Packet.__index = Packet
+
+-- Private -------------------------------------------------------------
+
+local function hears (self: any, fn: (...any) -> ()): Types.Connection
+    local live = self.live
+
+    -- The id is read inside, because a handle attached before it was bound has none yet.
+    return Handles.later (live, function (of) return of:listen (live.id :: number, fn) end)
+end
+
+-- Public --------------------------------------------------------------
+
+function Packet.new <T>(of: Types.Codec<T>): Types.Packet<T>
+    --[[
+        Level two is the caller, so a schema refused at start names the line a caller declared on
+        rather than the line that found the fault.
+    ]]
+    local file, line = debug.info (2, "sl")
+    local self = {
+        kind = "packet" :: "packet",
+        of = of,
+        isUnreliable = false,
+        isNewest = false,
+        hz = nil :: number?,
+        isTimestamped = false,
+        at = { file = file, line = line },
+        live = Handles.live (),
+    }
+
+    return (setmetatable (self, Packet) :: any) :: Types.Packet<T>
+end
+
+-- Lossy and unordered, and every fire still goes out.
+function Packet.unreliable (self: any): any
+    Define.declaring (self.live, "unreliable")
+    self.isUnreliable = true
+    return self
+end
+
+-- Lossy, latest wins, and rate capped where a rate is named.
+function Packet.newest (self: any, hz: number?): any
+    Define.declaring (self.live, "newest")
+    self.isNewest = true
+    self.hz = hz
+    return self
+end
+
+-- Stamped with the instant it was fired, which is comparable across clients.
+function Packet.timestamped (self: any): any
+    Define.declaring (self.live, "timestamped")
+    self.isTimestamped = true
+    return self
+end
+
+--[[
+    One fire at the server, which is the only place a client can reach.
+
+    No recipient, because there is one. That asymmetry is the surface's own and is not composed
+    here: a client naming who to send to would be naming the machine it is already talking to.
+]]
+function Packet.fireServer (self: any, value: any)
+    local session = Define.asking (self.live, "fireServer")
+    session:fire (self.live.def, nil, value)
+end
+
+-- One fire at whoever the recipient names, which only a server has anybody to name.
+function Packet.fireClient (self: any, to: Types.Recipient, value: any)
+    local session = Define.serving (self.live, "fireClient")
+    session:fire (self.live.def, to, value)
+end
+
+--[[
+    The number both listeners take last is the instant of the fire, and it arrives only where the
+    packet was declared stamped. Every other fire hands the listener nothing in its place.
+]]
+function Packet.onServer (self: any, fn: (any, Player, number?) -> ()): Types.Connection
+    return hears (self, fn)
+end
+
+function Packet.onClient (self: any, fn: (any, number?) -> ()): Types.Connection
+    return hears (self, fn)
+end
+
+-- The schema as text, which is what a report quotes back when a decode is refused.
+function Packet.describe (self: any): string
+    return Serial.frame ({
+        kind = "packet",
+        of = { cell = Base.cell (self.of) },
+        delivery = Legality.delivery (self),
+        hz = self.hz,
+        timestamped = self.isTimestamped,
+    })
+end
+
+return table.freeze (Packet)