@axpecter/lync 2.3.2 → 3.0.0

package/channel/Link.luau

@@ -0,0 +1,135 @@
+--!strict
+--!optimize 2
+-- One namespace's endpoint: the buffers it reuses, the clients it may reach, and what is queued.
+
+local Blocks = require (script.Parent.Blocks)
+local Recipients = require (script.Parent.Recipients)
+local Tally = require (script.Parent.Parent.kernel.Tally)
+local Transport = require (script.Parent.Transport)
+
+local Link = {}
+
+-- Types ---------------------------------------------------------------
+
+--[[
+    A namespace's outbound state, as a record rather than a handle, because everything here is read
+    by an assembler that walks the buckets and sums the lengths and a class would put a method in
+    front of every one of those reads. Four lists, since a frame is assembled per client and two of
+    them are the part that is the same for all, and the lossy pair has no classes.
+]]
+export type Link = {
+    read name: string,
+    read isServer: boolean,
+    read transport: Transport.Transport,
+    read tally: Tally.Tally,
+    read scratch: buffer,
+    seq: number,
+    epoch: number,
+    sending: boolean,
+    read audience: { Player },
+    read ready: Recipients.Ready,
+    read shared: { { Blocks.Block } },
+    read divergent: { [Player]: { { Blocks.Block } } },
+    read sharedLossy: { Blocks.Block },
+    read divergentLossy: { [Player]: { Blocks.Block } },
+}
+
+-- Private -------------------------------------------------------------
+
+-- One bucket per class, which is what a reliable queue is on either side of the shared line.
+local function buckets (): { { Blocks.Block } }
+    local out = table.create (Blocks.CLASSES) :: { { Blocks.Block } }
+    for index = 1, Blocks.CLASSES do
+        out[index] = {}
+    end
+    return out
+end
+
+-- Public --------------------------------------------------------------
+
+-- An endpoint, before its remotes exist.
+function Link.new (
+    name: string,
+    side: Transport.Side,
+    room: number,
+    transport: Transport.Transport,
+    tally: Tally.Tally
+): Link
+    return {
+        name = name,
+        isServer = side == "server",
+        transport = transport,
+        tally = tally,
+        scratch = buffer.create (room),
+        seq = 0,
+        epoch = 0,
+        sending = side == "server",
+        audience = {},
+        ready = {},
+        shared = buckets (),
+        divergent = {},
+        sharedLossy = {},
+        divergentLossy = {},
+    }
+end
+
+function Link.open (of: Link) of.transport:open () end
+
+-- A client this endpoint may now send to, and the two lists its targeted blocks queue in.
+function Link.admit (of: Link, player: Player)
+    of.ready[player] = true
+    of.divergent[player] = buckets ()
+    of.divergentLossy[player] = {}
+end
+
+-- A client gone, and everything queued for them let go.
+function Link.drop (of: Link, player: Player)
+    of.ready[player] = nil
+
+    local held = of.divergent[player]
+    if held ~= nil then
+        for _, one in held do
+            Blocks.drain (one)
+        end
+        of.divergent[player] = nil
+    end
+
+    local lossy = of.divergentLossy[player]
+    if lossy == nil then return end
+
+    Blocks.drain (lossy)
+    of.divergentLossy[player] = nil
+end
+
+-- The next block's place in its bucket, which is the half of a merge key a class does not decide.
+function Link.next (of: Link): number
+    local at = of.seq
+    of.seq = at + 1
+    return at
+end
+
+-- The sequence back to nothing, which a flush does once every bucket it filled has drained.
+function Link.rewind (of: Link) of.seq = 0 end
+
+-- An endpoint let go: nothing queued, nobody ready, and the remotes heard no longer.
+function Link.close (of: Link)
+    of.sending = false
+
+    for _, one in of.shared do
+        Blocks.drain (one)
+    end
+    Blocks.drain (of.sharedLossy)
+
+    --[[
+        Over the readiness set, because a client is admitted and given its buckets in one call, so
+        that set is the list of everyone holding any. Clearing a key mid-walk is what `next` allows.
+    ]]
+    for player in of.ready do
+        Link.drop (of, player)
+    end
+
+    table.clear (of.audience)
+    of.transport:close ()
+end
+
+return table.freeze (Link)

package/channel/Outbox.luau

@@ -0,0 +1,261 @@
+--!strict
+--!optimize 2
+-- Everything queued, as the frames it becomes: one lane merged and ordered, one split and lost.
+
+local Blocks = require (script.Parent.Blocks)
+local Link = require (script.Parent.Link)
+local Log = require (script.Parent.Parent.kernel.Log)
+local Protocol = require (script.Parent.Parent.wire.Protocol)
+local Tally = require (script.Parent.Parent.kernel.Tally)
+local Transport = require (script.Parent.Transport)
+
+local Outbox = {}
+
+-- Constants -----------------------------------------------------------
+
+-- The one lane a class ever reaches, since the other never defers and so never needs ordering.
+const SURE: Transport.Channel = "reliable"
+
+-- The lane whose frames may vanish, and what one fire of it carries.
+const LOSSY: Transport.Channel = "unreliable"
+const CAP = Protocol.UNRELIABLE_CAP
+
+--[[
+    The hard ceiling on one fire, which is a tripwire and not a budget.
+
+    A frame this wide is a place with a loop that forgot to flush, and the throw names the size so
+    whoever wrote the loop reads the number rather than an engine's refusal to send.
+]]
+const CEILING = Protocol.MAX_FIRE
+
+-- What a client with nothing of their own is merged against.
+const NONE = table.freeze ({} :: { Blocks.Block })
+
+-- Types ---------------------------------------------------------------
+
+-- One client's own buckets, or nothing where the frame being assembled is everybody's.
+type Mine = { { Blocks.Block } }?
+
+-- Private -------------------------------------------------------------
+
+-- What a frame comes to, and whether anything in it carries an instance.
+local function summed (of: Link.Link, mine: Mine): (number, boolean)
+    local bytes = 0
+    local carried = false
+
+    for class = 1, Blocks.CLASSES do
+        for _, block in of.shared[class] do
+            bytes += block.len
+            if block.refs ~= nil then carried = true end
+        end
+
+        if mine == nil then continue end
+        for _, block in mine[class] do
+            bytes += block.len
+            if block.refs ~= nil then carried = true end
+        end
+    end
+
+    return bytes, carried
+end
+
+-- One frame, in the order the classes put its blocks in.
+local function assembled (
+    of: Link.Link,
+    mine: Mine,
+    bytes: number,
+    carried: boolean
+): (buffer, Transport.Sidecar?)
+    local frame = buffer.create (bytes)
+    local side: Transport.Sidecar? = if carried then {} else nil
+    local at = 0
+
+    for class = 1, Blocks.CLASSES do
+        local ours = of.shared[class]
+        local theirs = if mine == nil then NONE else mine[class]
+        local reach, alsoReach = #ours, #theirs
+        local one, also = 1, 1
+
+        while one <= reach or also <= alsoReach do
+            local block
+            if also > alsoReach or (one <= reach and ours[one].seq < theirs[also].seq) then
+                block = ours[one]
+                one += 1
+            else
+                block = theirs[also]
+                also += 1
+            end
+
+            buffer.copy (frame, at, block.buf, 0, block.len)
+            at += block.len
+
+            local refs = block.refs
+            if side ~= nil and refs ~= nil then table.insert (side, refs) end
+        end
+    end
+
+    return frame, side
+end
+
+-- Whether any client has anything of their own queued.
+local function diverges (of: Link.Link): boolean
+    for _, buckets in of.divergent do
+        for class = 1, Blocks.CLASSES do
+            if #buckets[class] > 0 then return true end
+        end
+    end
+    return false
+end
+
+-- One frame, assembled and gone.
+local function sent (of: Link.Link, mine: Mine, to: Player?)
+    local bytes, carried = summed (of, mine)
+    if bytes == 0 then return end
+
+    if bytes > CEILING then
+        Log.error (
+            `{of.name} assembled a frame of {bytes} bytes, past the {CEILING} one fire takes`,
+            { namespace = of.name }
+        )
+    end
+
+    local frame, side = assembled (of, mine, bytes, carried)
+    of.transport:fire (SURE, to, frame, side)
+    Tally.moved (of.tally, bytes)
+end
+
+-- The holds a block needs for an audience of that many, and whether there is anyone at all.
+local function reaches (block: Blocks.Block, count: number): boolean
+    if count == 0 then
+        Blocks.release (block)
+        return false
+    end
+
+    for _ = 2, count do
+        Blocks.retain (block)
+    end
+    return true
+end
+
+-- Everything queued on the reliable lane, out, and every bucket it drew from emptied.
+local function reliable (of: Link.Link)
+    if of.isServer and diverges (of) then
+        for player in of.ready do
+            sent (of, of.divergent[player], player)
+        end
+    else
+        sent (of, nil, nil)
+    end
+
+    for class = 1, Blocks.CLASSES do
+        Blocks.drain (of.shared[class])
+    end
+    for _, buckets in of.divergent do
+        for class = 1, Blocks.CLASSES do
+            Blocks.drain (buckets[class])
+        end
+    end
+end
+
+-- One lossy frame, from a run of blocks that fit inside the cap.
+local function posted (
+    of: Link.Link,
+    held: { Blocks.Block },
+    from: number,
+    upto: number,
+    bytes: number,
+    at: Player?
+)
+    if bytes == 0 then return end
+
+    local frame = buffer.create (bytes)
+    local side: Transport.Sidecar? = nil
+    local pos = 0
+
+    for index = from, upto do
+        local block = held[index]
+        buffer.copy (frame, pos, block.buf, 0, block.len)
+        pos += block.len
+
+        local refs = block.refs
+        if refs == nil then continue end
+
+        if side == nil then
+            side = { refs }
+            continue
+        end
+        table.insert (side, refs)
+    end
+
+    of.transport:fire (LOSSY, at, frame, side)
+    Tally.moved (of.tally, bytes)
+end
+
+-- One queue of lossy blocks, as the fires it splits into.
+local function looses (of: Link.Link, held: { Blocks.Block }, at: Player?)
+    local reach = #held
+    local from = 1
+    local bytes = 0
+
+    for index = 1, reach do
+        local len = held[index].len
+        if bytes + len > CAP then
+            posted (of, held, from, index - 1, bytes, at)
+            from = index
+            bytes = 0
+        end
+        bytes += len
+    end
+
+    posted (of, held, from, reach, bytes, at)
+end
+
+-- Everything queued on the lossy lane, out, and the queues left empty.
+local function lossy (of: Link.Link)
+    looses (of, of.sharedLossy, nil)
+    Blocks.drain (of.sharedLossy)
+
+    for player, held in of.divergentLossy do
+        looses (of, held, player)
+        Blocks.drain (held)
+    end
+end
+
+-- Public --------------------------------------------------------------
+
+-- A block everybody gets, in the bucket its class drains in.
+function Outbox.shared (of: Link.Link, block: Blocks.Block)
+    table.insert (of.shared[block.class], block)
+end
+
+-- A block some of them get, in each of their own buckets.
+function Outbox.targeted (of: Link.Link, to: { Player }, count: number, block: Blocks.Block)
+    if not reaches (block, count) then return end
+
+    for index = 1, count do
+        table.insert (of.divergent[to[index] ][block.class], block)
+    end
+end
+
+-- A block everybody gets on the lane that may lose it, in the one list that lane keeps.
+function Outbox.loose (of: Link.Link, block: Blocks.Block) table.insert (of.sharedLossy, block) end
+
+-- A block some of them get on the lane that may lose it, in each of their own lists.
+function Outbox.looseTo (of: Link.Link, to: { Player }, count: number, block: Blocks.Block)
+    if not reaches (block, count) then return end
+
+    for index = 1, count do
+        table.insert (of.divergentLossy[to[index] ], block)
+    end
+end
+
+-- Both lanes out, and the flush over.
+function Outbox.fire (of: Link.Link)
+    if not of.sending then return end
+
+    reliable (of)
+    lossy (of)
+    Link.rewind (of)
+end
+
+return table.freeze (Outbox)

package/channel/Recipients.luau

@@ -0,0 +1,129 @@
+--!strict
+--!optimize 2
+-- The five ways to name an audience, and the one walk that turns any of them into players.
+
+local Group = require (script.Parent.Group)
+local Types = require (script.Parent.Parent.Types)
+
+local Recipients = {}
+
+-- Types ---------------------------------------------------------------
+
+--[[
+    The clients a namespace may send to, which is the ones that have been told they may receive. A
+    player who has joined and not finished the handshake discards a data frame on arrival, so naming
+    one costs the bytes and buys nothing, and a player who has left is not in here at all.
+]]
+export type Ready = { [Player]: boolean }
+
+-- Private -------------------------------------------------------------
+
+--[[
+    The members of one recipient, written from the front, and how many there are. The tail is left
+    for the caller above to cut, because a resolve that is one form deep and one that recursed have
+    different ideas about where the end is and only one of them is right.
+]]
+local function filled (into: { Player }, of: Types.Recipient, ready: Ready): number
+    if typeof (of) == "Instance" then
+        local player = of :: Player
+        if not ready[player] then return 0 end
+
+        into[1] = player
+        return 1
+    end
+
+    local tagged = of :: any
+    local count = 0
+
+    if tagged._all == true then
+        for player, allowed in ready do
+            if not allowed then continue end
+
+            count += 1
+            into[count] = player
+        end
+        return count
+    end
+
+    if tagged._except == true then
+        for player, allowed in ready do
+            if not allowed or Recipients.holds (tagged.from, player) then continue end
+
+            count += 1
+            into[count] = player
+        end
+        return count
+    end
+
+    if Group.is (of) then
+        for _, player in of :: Types.Group do
+            if not ready[player] then continue end
+
+            count += 1
+            into[count] = player
+        end
+        return count
+    end
+
+    --[[
+        A caller's own list, which is the one form that can name somebody twice. Two of a player is
+        two frames to them, so the ones already written are read back before each is taken. Nothing
+        else pays for that: the other four forms are sets already, and the scan here is over what a
+        caller wrote rather than over everybody connected.
+    ]]
+    for _, player in of :: { Player } do
+        if not ready[player] then continue end
+
+        -- Past the count is whatever the last resolve left, which is nobody this one named.
+        local seen = table.find (into, player)
+        if seen ~= nil and seen <= count then continue end
+
+        count += 1
+        into[count] = player
+    end
+    return count
+end
+
+-- Public --------------------------------------------------------------
+
+--[[
+    Tagged with the phantom field its type declares, because the router tells the five recipient
+    forms apart at run time and an untagged table would read as a list of players. Frozen, since one
+    value is shared by every caller of the surface.
+]]
+Recipients.ALL = table.freeze ({ _all = true }) :: Types.All
+
+--[[
+    Everyone but this one, whatever form it takes. What it excludes is held rather than resolved,
+    because a group's members and the connected set are both read when the flush goes out.
+]]
+function Recipients.except (from: Types.Recipient): Types.Except
+    return table.freeze ({ _except = true, from = from }) :: any
+end
+
+--[[
+    Whether a recipient names this player, which is the question an exclusion asks of everyone. A
+    test, so nothing has to be built to answer it: an exclusion is asked once per ready client, and
+    what it excludes is usually one player.
+]]
+function Recipients.holds (of: Types.Recipient, player: Player): boolean
+    if typeof (of) == "Instance" then return of == player end
+
+    local tagged = of :: any
+    if tagged._all == true then return true end
+    if tagged._except == true then return not Recipients.holds (tagged.from, player) end
+    if Group.is (of) then return (of :: Types.Group):has (player) end
+
+    return table.find (of :: { Player }, player) ~= nil
+end
+
+-- A recipient as the players it comes to, in an array the caller keeps and hands back next time.
+function Recipients.resolve (into: { Player }, of: Types.Recipient, ready: Ready)
+    local count = filled (into, of, ready)
+
+    for index = #into, count + 1, -1 do
+        into[index] = nil
+    end
+end
+
+return table.freeze (Recipients)

package/channel/Transport.luau

@@ -0,0 +1,138 @@
+--!strict
+--!optimize 2
+-- The three remote instances, and the only module that touches them.
+
+local Transport = {}
+Transport.__index = Transport
+
+-- Constants -----------------------------------------------------------
+
+const FOLDER = "Lync"
+const CHANNELS: { Channel } = { "handshake", "reliable", "unreliable" }
+const LOSSY: Channel = "unreliable"
+
+-- Types ---------------------------------------------------------------
+
+export type Channel = "handshake" | "reliable" | "unreliable"
+
+-- Which machine this is, taken rather than read, since one place reads the engine for both ends.
+export type Side = "server" | "client"
+
+export type Sidecar = { { Instance } }
+
+export type Received = (from: Player?, bytes: buffer, refs: Sidecar?) -> ()
+
+export type Transport = {
+    read open: (self: Transport) -> (),
+    read fire: (self: Transport, at: Channel, to: Player?, bytes: buffer, refs: Sidecar?) -> (),
+    read onReceive: (self: Transport, at: Channel, take: Received) -> (),
+    read close: (self: Transport) -> (),
+}
+
+--[[
+    The unreliable lane is an UnreliableRemoteEvent and is held as a RemoteEvent anyway. The two
+    classes declare the same three fire methods and the same two signals, so one table over both
+    keeps the lane out of every signature below, and a client casts all three regardless because
+    discovery answers an Instance.
+]]
+type Self = {
+    namespace: string,
+    isServer: boolean,
+    remotes: { [Channel]: RemoteEvent },
+    heard: { RBXScriptConnection },
+}
+
+-- Private -------------------------------------------------------------
+
+-- One folder for every namespace, so the first to open makes it and the rest find it.
+local function rooted (storage: Instance): Instance
+    local found = storage:FindFirstChild (FOLDER)
+    if found ~= nil then return found end
+
+    local made = Instance.new ("Folder")
+    made.Name = FOLDER
+    made.Parent = storage
+    return made
+end
+
+-- Public --------------------------------------------------------------
+
+function Transport.new (namespace: string, side: Side): Transport
+    local self: Self = {
+        namespace = namespace,
+        isServer = side == "server",
+        remotes = {},
+        heard = {},
+    }
+    return (setmetatable (self, Transport) :: any) :: Transport
+end
+
+--[[
+    A client waits without a deadline. The engine already warns and names the path it is waiting on,
+    and a namespace slow to replicate is a slow join, where a deadline would make it a failure with
+    nothing to recover to.
+]]
+function Transport.open (self: Self)
+    local storage = game:GetService ("ReplicatedStorage")
+
+    if not self.isServer then
+        local folder = storage:WaitForChild (FOLDER):WaitForChild (self.namespace)
+        for _, at in CHANNELS do
+            self.remotes[at] = folder:WaitForChild (at) :: RemoteEvent
+        end
+        return
+    end
+
+    local folder = Instance.new ("Folder")
+    folder.Name = self.namespace
+
+    for _, at in CHANNELS do
+        local remote: RemoteEvent = if at == LOSSY
+            then Instance.new ("UnreliableRemoteEvent") :: any
+            else Instance.new ("RemoteEvent")
+        remote.Name = at
+        remote.Parent = folder
+        self.remotes[at] = remote
+    end
+
+    folder.Parent = rooted (storage)
+end
+
+--[[
+    One frame handed to the engine, on the lane and to whoever the caller named. A client names
+    nobody and reaches the server, and a server naming nobody reaches everyone, which is the one
+    place the three engine calls a remote offers are told apart.
+]]
+function Transport.fire (self: Self, at: Channel, to: Player?, bytes: buffer, refs: Sidecar?)
+    local remote = self.remotes[at]
+    if not self.isServer then return remote:FireServer (bytes, refs) end
+    if to ~= nil then return remote:FireClient (to, bytes, refs) end
+    remote:FireAllClients (bytes, refs)
+end
+
+-- A server receiver is the engine's own, since the player it names is the authenticated sender.
+function Transport.onReceive (self: Self, at: Channel, take: Received)
+    local remote = self.remotes[at]
+
+    if self.isServer then
+        table.insert (self.heard, remote.OnServerEvent:Connect (take))
+        return
+    end
+
+    local function relay (bytes: buffer, refs: Sidecar?) take (nil, bytes, refs) end
+    table.insert (self.heard, remote.OnClientEvent:Connect (relay))
+end
+
+--[[
+    Released rather than destroyed. Destroying the remotes would take the namespace out from under a
+    counterparty still running on it, and an endpoint that hears nothing is what a caller who shut
+    one down asked for.
+]]
+function Transport.close (self: Self)
+    for _, made in self.heard do
+        made:Disconnect ()
+    end
+    table.clear (self.heard)
+end
+
+return table.freeze (Transport)