@trioforge/crucible 0.1.0 → 0.3.0

package/out/internal/network/claims.d.ts

@@ -0,0 +1 @@
+export {};

package/out/internal/network/claims.luau

@@ -0,0 +1,146 @@
+-- Compiled with roblox-ts v3.0.0
+local TS = _G[script]
+local ClientReady = TS.import(script, script.Parent.Parent.Parent, "network").ClientReady
+local readClaim = TS.import(script, script.Parent.Parent, "construction-claim").readClaim
+local definitionOf = TS.import(script, script.Parent, "catalog").definitionOf
+--* @internal 
+--* @internal 
+local session
+local frozen = false
+local receivers = {}
+local ready = {}
+local live = {}
+local function retire(claim)
+	local _claim = claim
+	-- ▼ Set.delete ▼
+	local _valueExisted = live[_claim] ~= nil
+	live[_claim] = nil
+	-- ▲ Set.delete ▲
+	if not _valueExisted then
+		return nil
+	end
+	if claim.target == ClientReady then
+		local _claim_1 = claim
+		local _arg0 = (table.find(ready, _claim_1) or 0) - 1
+		table.remove(ready, _arg0 + 1)
+	else
+		local _target = claim.target
+		receivers[_target] = nil
+	end
+	local _result = session
+	if _result ~= nil then
+		_result.retired(claim)
+	end
+end
+--[[
+	*
+	 * @internal
+	 * Re-checks what the transformer checked, because untransformed or cast code skips it. A violation throws from the
+	 * constructor and fails boot.
+	 
+]]
+local function claim(owner, field, target, callback)
+	local state = readClaim()
+	if state == nil or state.object ~= owner then
+		error("receive() must initialize a readonly field of the Subsystem being constructed")
+	end
+	local record = state.record
+	local label = `{record.id}.{field}`
+	if record.kind ~= 0 then
+		error(`{label}: receive() must initialize a readonly field of a Subsystem; behaviours do not receive`)
+	end
+	if frozen then
+		error(`{label}: receive() after the network commit`)
+	end
+	local side = (session or error(`{label}: receive() before the network session opened`)).side()
+	local _callback = callback
+	if not (type(_callback) == "function") then
+		error(`{label}: receive() needs a callback`)
+	end
+	if target == ClientReady then
+		if side ~= "server" then
+			error(`{label}: ClientReady is received in a server Subsystem.`)
+		end
+		for _, other in ready do
+			if other.owner == state then
+				error(`{label}: {other.label} already receives ClientReady; a Subsystem holds one`)
+			end
+		end
+	else
+		local definition = definitionOf(target) or error(`{label}: receive() needs a message declared with toServer, toClient or askServer`)
+		local serverSide = definition.kind ~= "to-client"
+		if serverSide ~= (side == "server") then
+			error(if serverSide then `{label}: {definition.name} is client-to-server; receive it in a server Subsystem.` else `{label}: {definition.name} is server-to-client; receive it in a client Subsystem.`)
+		end
+		local other = receivers[definition]
+		if other ~= nil then
+			error(`{definition.name} has two receivers: {other.label} and {label}`)
+		end
+	end
+	local entry = {
+		owner = state,
+		label = label,
+		target = target,
+		callback = callback,
+	}
+	if target == ClientReady then
+		table.insert(ready, entry)
+	else
+		local _target = target
+		receivers[_target] = entry
+	end
+	live[entry] = true
+	if state.subscriptions == nil then
+		state.subscriptions = {}
+	end
+	local _exp = state.subscriptions
+	table.insert(_exp, function()
+		return retire(entry)
+	end)
+	return table.freeze({})
+end
+--* @internal 
+local function isLive(claim)
+	local _claim = claim
+	return live[_claim] ~= nil
+end
+--* @internal 
+local function receiverOf(definition)
+	local _definition = definition
+	return receivers[_definition]
+end
+--* @internal 
+local function readyClaims()
+	local _array = {}
+	local _length = #_array
+	table.move(ready, 1, #ready, _length + 1, _array)
+	return _array
+end
+--* @internal 
+local function openClaims(value)
+	session = value
+end
+--* @internal 
+local function freezeClaims()
+	frozen = true
+end
+--* @internal 
+local function closeClaims(discard)
+	session = nil
+	if not discard then
+		return nil
+	end
+	frozen = false
+	table.clear(receivers)
+	table.clear(ready)
+	table.clear(live)
+end
+return {
+	claim = claim,
+	isLive = isLive,
+	receiverOf = receiverOf,
+	readyClaims = readyClaims,
+	openClaims = openClaims,
+	freezeClaims = freezeClaims,
+	closeClaims = closeClaims,
+}

package/out/internal/network/client-session.d.ts

@@ -0,0 +1 @@
+export {};

package/out/internal/network/client-session.luau

@@ -0,0 +1,405 @@
+-- Compiled with roblox-ts v3.0.0
+local TS = _G[script]
+local runtimeDiagnostic = TS.import(script, script.Parent.Parent, "diagnostics").runtimeDiagnostic
+local _catalog = TS.import(script, script.Parent, "catalog")
+local adopt = _catalog.adopt
+local catalogSize = _catalog.catalogSize
+local definitionAt = _catalog.definitionAt
+local definitionOf = _catalog.definitionOf
+local discardIndices = _catalog.discardIndices
+local unpublished = _catalog.unpublished
+local _claims = TS.import(script, script.Parent, "claims")
+local closeClaims = _claims.closeClaims
+local freezeClaims = _claims.freezeClaims
+local openClaims = _claims.openClaims
+local receiverOf = _claims.receiverOf
+local _envelope = TS.import(script, script.Parent, "envelope")
+local argumentCount = _envelope.argumentCount
+local controlPacket = _envelope.controlPacket
+local decodeBody = _envelope.decodeBody
+local encodeBody = _envelope.encodeBody
+local failureReason = _envelope.failureReason
+local frame = _envelope.frame
+local missingInstance = _envelope.missingInstance
+local openBody = _envelope.openBody
+local readHeader = _envelope.readHeader
+local L = TS.import(script, script.Parent, "limits")
+local _session = TS.import(script, script.Parent, "session")
+local newPeer = _session.newPeer
+local Session = _session.Session
+local FAIL_NAMES = { "overflow", "overloaded", "closing", "malformed" }
+local ERROR_REASONS = { "unavailable", "handler-error", "overloaded", "invalid" }
+local function failed(reason)
+	return table.freeze({
+		ok = false,
+		reason = reason,
+	})
+end
+--* @internal 
+local toServer
+local ClientSession
+do
+	local super = Session
+	ClientSession = setmetatable({}, {
+		__tostring = function()
+			return "ClientSession"
+		end,
+		__index = super,
+	})
+	ClientSession.__index = ClientSession
+	function ClientSession.new(...)
+		local self = setmetatable({}, ClientSession)
+		return self:constructor(...) or self
+	end
+	function ClientSession:constructor(...)
+		super.constructor(self, ...)
+		self.peer = newPeer()
+		self.nextNonce = 1
+		self.pending = {}
+		self.fired = false
+		self.unpublishedReported = {}
+		self.undeclared = {}
+		self.unmatched = {}
+		self.undecoded = {}
+		self.missingPlayer = {}
+	end
+	function ClientSession:open()
+		self.stage = 1
+		openClaims({
+			side = function()
+				return "client"
+			end,
+			retired = function() end,
+		})
+		local where = `ReplicatedStorage.{L.REMOTE_NAME}`
+		local found = self.port.discover(L.CLIENT_DISCOVERY_TIMEOUT_SECONDS, function(...)
+			local args = { ... }
+			return self:receive(argumentCount(args), args[1], args[2])
+		end)
+		if found == nil then
+			error(`Crucible found no {where} within {L.CLIENT_DISCOVERY_TIMEOUT_SECONDS} seconds`, 0)
+		end
+		if found.className ~= "RemoteEvent" then
+			error(`Crucible found {where} as a {found.className}`, 0)
+		end
+		if found.protocol ~= L.PROTOCOL_VERSION then
+			error(`Crucible {where} has Protocol {tostring(found.protocol)}; this client needs {L.PROTOCOL_VERSION}`, 0)
+		end
+		local adopted, err = pcall(adopt, found.catalog)
+		if not adopted then
+			error(`Crucible {where} has an invalid Catalog: {tostring(err)}`, 0)
+		end
+	end
+	function ClientSession:loaded()
+		self.stage = 2
+	end
+	function ClientSession:commit()
+		freezeClaims()
+		for _, definition in unpublished() do
+			if receiverOf(definition) ~= nil then
+				self:unpublished(definition)
+			end
+		end
+		if self.peer.state == 0 then
+			self:fire(self.peer, controlPacket(4, {}))
+			self.fired = true
+			self.peer.state = 1
+			self:flush(self.peer)
+		end
+		self.stage = 3
+	end
+	function ClientSession:close()
+		if self.stage == 4 then
+			return nil
+		end
+		local committed = self.stage == 3
+		self.stage = 4
+		if self.fired and self.peer.state ~= 2 then
+			pcall(function()
+				return self:fire(self.peer, controlPacket(5, {}, 2))
+			end)
+		end
+		pcall(function()
+			return self["end"](self, self.peer)
+		end)
+		pcall(function()
+			return self.port.disconnect()
+		end)
+		closeClaims(not committed)
+		if not committed then
+			discardIndices()
+		end
+	end
+	function ClientSession:send(token, value)
+		local sendable = self:sendable()
+		local definition = toServer(token, "to-server", "Network.send needs a message declared with toServer")
+		local body = encodeBody(definition.name, definition.input, "payload", value)
+		if not sendable or self.peer.state == 2 then
+			return false
+		end
+		local index = definition.index
+		if index == nil then
+			self:unpublished(definition)
+			return false
+		end
+		return self:deliver(self.peer, frame(body, 0, { index }))
+	end
+	function ClientSession:ask(token, value)
+		local sendable = self:sendable()
+		local definition = toServer(token, "ask-server", "Network.ask needs a message declared with askServer")
+		local body = encodeBody(definition.name, definition.input, "request", value)
+		if not sendable or self.peer.state == 2 then
+			return failed("disconnected")
+		end
+		local index = definition.index
+		if index == nil then
+			self:unpublished(definition)
+			return failed("unavailable")
+		end
+		-- ▼ ReadonlyMap.size ▼
+		local _size = 0
+		for _ in self.pending do
+			_size += 1
+		end
+		-- ▲ ReadonlyMap.size ▲
+		if _size >= L.MAX_PENDING_ASKS then
+			return failed("overloaded")
+		end
+		local nonce = self.nextNonce
+		local packet = frame(body, 1, { index, nonce })
+		self.nextNonce = nonce + 1
+		local entry = {
+			definition = definition,
+			thread = coroutine.running(),
+			packet = packet,
+		}
+		self.pending[nonce] = entry
+		entry.deadline = self.port.delay(definition.timeout, function()
+			return self:expire(nonce)
+		end)
+		self:deliver(self.peer, packet)
+		if entry.result ~= nil then
+			return entry.result
+		end
+		return (coroutine.yield())
+	end
+	function ClientSession:fire(_peer, packet)
+		self.port.fireServer(packet.bytes, packet.sidecar)
+	end
+	ClientSession["end"] = function(self, peer)
+		if not super["end"](self, peer) then
+			return false
+		end
+		local nonces = {}
+		for nonce in self.pending do
+			table.insert(nonces, nonce)
+		end
+		table.sort(nonces)
+		for _, nonce in nonces do
+			self:settle(nonce, failed("disconnected"))
+		end
+		return true
+	end
+	function ClientSession:fail(peer, reason, detail)
+		if peer.state == 2 then
+			return nil
+		end
+		runtimeDiagnostic("error", `Crucible network session failed ({FAIL_NAMES[reason + 1]}){if detail == nil then "" else `: {detail}`}`)
+		pcall(function()
+			return self:fire(peer, controlPacket(5, {}, reason))
+		end)
+		self["end"](self, peer)
+	end
+	function ClientSession:unpublished(definition)
+		local _unpublishedReported = self.unpublishedReported
+		local _definition = definition
+		if _unpublishedReported[_definition] ~= nil then
+			return nil
+		end
+		local _unpublishedReported_1 = self.unpublishedReported
+		local _definition_1 = definition
+		_unpublishedReported_1[_definition_1] = true
+		runtimeDiagnostic("warning", `Crucible {definition.name} is not in the server's network catalog`)
+	end
+	function ClientSession:once(seen, definition, message)
+		local _seen = seen
+		local _definition = definition
+		if _seen[_definition] ~= nil then
+			return nil
+		end
+		local _seen_1 = seen
+		local _definition_1 = definition
+		_seen_1[_definition_1] = true
+		runtimeDiagnostic("warning", message)
+	end
+	function ClientSession:expire(nonce)
+		local _pending = self.pending
+		local _nonce = nonce
+		local entry = _pending[_nonce]
+		if entry == nil then
+			return nil
+		end
+		local _queue = self.peer.queue
+		local _packet = entry.packet
+		local index = (table.find(_queue, _packet) or 0) - 1
+		if index ~= -1 then
+			table.remove(self.peer.queue, index + 1)
+			self.peer.queuedBytes -= entry.packet.charge
+		end
+		self:settle(nonce, failed("timeout"))
+	end
+	function ClientSession:settle(nonce, result)
+		local _pending = self.pending
+		local _nonce = nonce
+		local entry = _pending[_nonce]
+		if entry == nil then
+			return nil
+		end
+		local _pending_1 = self.pending
+		local _nonce_1 = nonce
+		_pending_1[_nonce_1] = nil
+		local _result = entry.deadline
+		if _result ~= nil then
+			_result()
+		end
+		entry.result = result
+		if self.later ~= nil then
+			local _exp = self.later
+			table.insert(_exp, entry)
+		else
+			self:resume(entry)
+		end
+	end
+	function ClientSession:resume(entry)
+		if coroutine.status(entry.thread) == "suspended" then
+			self.port.resume(entry.thread, entry.result)
+		end
+	end
+	function ClientSession:receive(count, packet, sidecar)
+		local later = {}
+		self.later = later
+		local ok, err = pcall(function()
+			return self:dispatch(count, packet, sidecar)
+		end)
+		self.later = nil
+		if not ok then
+			self:fail(self.peer, 3, `receive failed: {tostring(err)}`)
+		end
+		for _, entry in later do
+			self:resume(entry)
+		end
+	end
+	function ClientSession:violation(detail)
+		self:fail(self.peer, 3, detail)
+	end
+	function ClientSession:dispatch(count, packet, sidecar)
+		if self.peer.state == 2 then
+			return nil
+		end
+		local header = readHeader(count, packet, sidecar)
+		if header == nil then
+			return self:violation("a malformed packet")
+		end
+		if header.opcode == 5 then
+			local _condition = FAIL_NAMES[header.reason + 1]
+			if _condition == nil then
+				_condition = `unknown reason {header.reason}`
+			end
+			local reason = _condition
+			runtimeDiagnostic("error", `Crucible network session ended: the server sent FAIL ({reason})`)
+			self["end"](self, self.peer)
+			return nil
+		end
+		if not self.fired then
+			return self:violation("a game packet before READY")
+		end
+		if header.opcode == 0 then
+			return self:event(header, packet, sidecar)
+		end
+		if header.opcode == 2 or header.opcode == 3 then
+			return self:answer(header, packet, sidecar)
+		end
+		self:violation("a client-to-server packet")
+	end
+	function ClientSession:event(header, packet, sidecar)
+		if header.index >= catalogSize() then
+			return self:violation("an unknown message index")
+		end
+		local definition = definitionAt(header.index)
+		if definition == nil then
+			local _undeclared = self.undeclared
+			local _index = header.index
+			if _undeclared[_index] ~= nil then
+				return nil
+			end
+			local _undeclared_1 = self.undeclared
+			local _index_1 = header.index
+			_undeclared_1[_index_1] = true
+			runtimeDiagnostic("warning", `Crucible dropped catalog message {header.index}: this client never declared it`)
+			return nil
+		end
+		if definition.kind ~= "to-client" then
+			return self:violation(`{definition.name} sent as an event`)
+		end
+		local decoded, value = pcall(function()
+			return decodeBody(definition.input, "payload", openBody(packet, sidecar, header))
+		end)
+		if not decoded then
+			if missingInstance(value) then
+				return self:once(self.missingPlayer, definition, `Crucible dropped {definition.name}: a Player left`)
+			end
+			return self:violation(`{definition.name} {failureReason(value)}`)
+		end
+		local receiver = receiverOf(definition)
+		if receiver == nil then
+			return self:unreceived(definition)
+		end
+		if self.peer.counted >= L.MAX_ACTIVE_HANDLERS then
+			return self:fail(self.peer, 1)
+		end
+		self:start(self.peer, receiver, { value })
+	end
+	function ClientSession:answer(header, packet, sidecar)
+		local definition = definitionAt(header.index)
+		if definition == nil or definition.kind ~= "ask-server" then
+			return self:violation("a reply naming a message that is not an ask")
+		end
+		local _pending = self.pending
+		local _nonce = header.nonce
+		local entry = _pending[_nonce]
+		if entry == nil then
+			return self:once(self.unmatched, definition, `Crucible ignored a late or unknown reply to {definition.name}`)
+		end
+		if entry.definition ~= definition then
+			return self:violation(`a reply to {entry.definition.name} naming {definition.name}`)
+		end
+		if header.opcode == 3 then
+			local reason = ERROR_REASONS[header.reason + 1]
+			if reason == nil then
+				return self:violation(`an unknown ERROR reason {header.reason}`)
+			end
+			return self:settle(header.nonce, failed(reason))
+		end
+		local decoded, value = pcall(function()
+			return decodeBody(definition.output, "response", openBody(packet, sidecar, header))
+		end)
+		if not decoded then
+			self:once(self.undecoded, definition, `Crucible could not decode a reply to {definition.name}: {failureReason(value)}`)
+			return self:settle(header.nonce, failed("invalid"))
+		end
+		self:settle(header.nonce, table.freeze({
+			ok = true,
+			value = value,
+		}))
+	end
+end
+function toServer(token, kind, message)
+	local definition = definitionOf(token)
+	if definition == nil or definition.kind ~= kind then
+		error(message, 0)
+	end
+	return definition
+end
+return {
+	ClientSession = ClientSession,
+}

package/out/internal/network/codec.d.ts

@@ -0,0 +1,63 @@
+import { type Branch, type Node } from "./schema";
+export interface CodecFailure {
+    readonly codecFailure: true;
+    readonly path: string;
+    readonly reason: string;
+    readonly missing?: true;
+}
+export declare class Budget {
+    visits: number;
+    entries: number;
+    depth: number;
+    chargeEntries(count: number, path: string): void;
+    visit(path: string): void;
+    enter(path: string): void;
+    leave(): void;
+}
+export declare class Writer {
+    readonly budget: Budget;
+    readonly slots: Instance[];
+    private data;
+    private cursor;
+    private reserve;
+    u8(value: number): void;
+    u16(value: number): void;
+    u32(value: number): void;
+    varuint(value: number): void;
+    f32(value: number): void;
+    f64(value: number): void;
+    bytes(text: string): void;
+    slot(instance: Instance): void;
+    finish(header: buffer): LuaTuple<[buffer, Readonly<Record<string, Instance>>, number]>;
+}
+export declare class Reader {
+    private readonly packet;
+    private cursor;
+    private readonly sidecar;
+    private readonly slotCount;
+    readonly budget: Budget;
+    private nextSlot;
+    constructor(packet: buffer, cursor: number, sidecar: Readonly<Record<string, Instance>>, slotCount: number);
+    private take;
+    u8(): number;
+    u16(): number;
+    u32(): number;
+    varuint(): number;
+    f32(): number;
+    f64(): number;
+    string(): string;
+    count(minElementBytes: number, path: string): number;
+    slot(path: string): Instance | undefined;
+    finished(): boolean;
+}
+export interface Codec {
+    readonly node: Branch;
+    readonly minBytes: number;
+    readonly encode: (writer: Writer, value: unknown, path: string) => void;
+    readonly decode: (reader: Reader, path: string) => unknown;
+}
+export declare function compile(node: Node, tally?: {
+    nodes: number;
+}): Codec;
+export declare function encodeDynamic(w: Writer, value: unknown, path: string, active: Set<object>, topLevel?: boolean, arrayElement?: boolean): void;
+export declare function decodeDynamic(r: Reader, path: string, topLevel: boolean, arrayElement?: boolean): unknown;