@flamework-experimental/networking 2.0.0-alpha.0 → 2.0.0-alpha.2

package/out/middleware/createGuards.luau

@@ -0,0 +1,32 @@
+-- Compiled with roblox-ts v3.0.0
+local TS = _G[script]
+local Players = TS.import(script, TS.getModule(script, "@rbxts", "services")).Players
+--[[
+	*
+	 * The generated argument checks of one event or function, for the receive pipeline, which runs them
+	 * ahead of all user middleware. A failure warns (with `warnOnInvalid`) and fires `onBadRequest`.
+	 
+]]
+local function createGuards(name, fixedParameters, restParameter, networkInfo, warnOnInvalid, signals)
+	return {
+		fixed = fixedParameters,
+		rest = restParameter,
+		reject = function(player, index, value)
+			if warnOnInvalid then
+				if player then
+					warn(`'{player}' sent invalid arguments for event '{name}' (arg #{index}):`, value)
+				else
+					warn(`Server sent invalid arguments for event '{name}' (arg #{index}):`, value)
+				end
+			end
+			signals:fire("onBadRequest", player or Players.LocalPlayer, {
+				networkInfo = networkInfo,
+				argIndex = index,
+				argValue = value,
+			})
+		end,
+	}
+end
+return {
+	createGuards = createGuards,
+}

package/out/middleware/processor.d.ts

@@ -0,0 +1,62 @@
+import { Serialization } from "@flamework-experimental/core";
+import { t } from "@rbxts/t";
+import { NetworkInfo } from "../types";
+import { MiddlewareFactory } from "./types";
+import { Signal } from "../util/signal";
+
+/** One step of the receive pipeline: `(player, ...args) -> result`. The player is `undefined` on a client. */
+export type Processor = (player: Player | undefined, ...args: unknown[]) => unknown;
+
+/** The generated argument checks, run ahead of all user middleware. */
+export interface Guards {
+	/** `fixed[i]` checks argument `i`. */
+	fixed: ReadonlyArray<t.check<unknown>>;
+
+	/** Checks every argument past the fixed ones, for a rest parameter. */
+	rest: t.check<unknown> | undefined;
+
+	/** Called with the first argument that failed, by its 0-based index. */
+	reject: (player: Player | undefined, index: number, value: unknown) => void;
+}
+
+/**
+ * Folds the guards and the middleware into one processor that runs them as plain calls in the
+ * calling thread and returns what the last link did, a Promise already followed (see `processor.luau`).
+ * @param rejected What the processor returns when a guard fails.
+ * @param cancelled What a Promise that was cancelled reads as.
+ */
+export function createProcessor(
+	middleware: ReadonlyArray<MiddlewareFactory<any, any>> | undefined,
+	networkInfo: NetworkInfo,
+	final: Processor,
+	guards: Guards | undefined,
+	rejected: unknown,
+	cancelled: unknown,
+): Processor;
+
+/**
+ * The handler for a remote's `OnServerEvent` (`withPlayer`) or `OnClientEvent`: decodes the payload
+ * when there is a decoder, reporting and dropping one it cannot read, and runs `process`.
+ */
+export function createReceiver(
+	decoder: Serialization.Decoder | undefined,
+	onMalformed: ((player: Player | undefined, message: string) => void) | undefined,
+	process: Processor,
+	withPlayer: boolean,
+): (...args: unknown[]) => void;
+
+/**
+ * Unpacks a serialized argument list, `(payload, blobs?)` as the remote carried it, under `pcall`:
+ * `true` and the list, or `false` and why it could not be read.
+ */
+export function decode(
+	decoder: Serialization.Decoder,
+	payload: unknown,
+	blobs: unknown,
+): LuaTuple<[ok: true, list: unknown[]] | [ok: false, message: string]>;
+
+/** The last step of an event's chain: fires `signal`, with the sender first when `withPlayer`. */
+export function deliverTo(signal: Signal, withPlayer: boolean): Processor;
+
+/** `callback` called without the player in front, which is how a client's callback is written. */
+export function withoutPlayer(callback: (...args: never[]) => unknown): Processor;

package/out/middleware/processor.luau

@@ -0,0 +1,214 @@
+--[[
+	The receive pipeline: what runs between a remote delivering a message (or `predict` standing in
+	for one) and the handler that receives it.
+
+	Plain calls in the thread that received the message: the payload is decoded, the generated guards
+	check the arguments, each middleware calls the next through `processNext`, and the last step
+	delivers (an event's signal, a function's callback). Nothing here makes a Promise or a thread. A
+	middleware may still yield, which holds up only the message it is processing, and one that
+	returns a Promise is waited for in place.
+
+	Plain Luau rather than TypeScript so that an argument list keeps its count: roblox-ts builds a
+	table from every `...args` and spreads it with `unpack`, which stops at `#list` and may lose the
+	values after a nil (see `util/trimArguments.ts`). Here the list travels as varargs, and is only cut
+	after its last value where it enters and where a middleware hands on a list of its own.
+]]
+
+local TS = _G[script]
+
+--- Stands in for a missing blob list when decoding: a sender whose type has blob slots always sends one.
+local NO_BLOBS = {}
+
+--[[
+	`callback(player, ...)`, with the argument list cut after its last value.
+
+	A list that ends in nil would reach a TypeScript `(...args)` as a table whose `#` can stop at any
+	earlier gap: `{1, nil, 3, nil}` may read as one value. One that ends in a value spreads whole. A
+	middleware that names its parameters, `(player, id, name) => processNext(player, id, name)`,
+	passes on a list ending in nil when `name` was not sent, which is why every link cuts it again.
+	Nothing is lost: an argument that was not passed reads as nil too.
+]]
+local function callTrimmed(callback: (...any) -> ...any, player: any, ...: any): any
+	local count = select("#", ...)
+	if count == 0 or select(count, ...) ~= nil then
+		return callback(player, ...)
+	end
+
+	repeat
+		count -= 1
+	until count == 0 or select(count, ...) ~= nil
+
+	return callback(player, table.unpack({ ... }, 1, count))
+end
+
+--[[
+	A link's result, with a Promise it returned followed in this thread: its value once resolved,
+	`cancelled` if it was cancelled, and its rejection raised.
+]]
+local function follow(value: any, cancelled: any): any
+	if type(value) ~= "table" then
+		return value
+	end
+
+	local Promise = TS.Promise
+	if not Promise.is(value) then
+		return value
+	end
+
+	local status, result = value:awaitStatus()
+	if status == Promise.Status.Resolved then
+		return result
+	elseif status == Promise.Status.Cancelled then
+		return cancelled
+	end
+
+	error(result, 0)
+end
+
+--[[
+	Folds the guards and the middleware into one function, `(player, ...args) -> result`, that runs
+	them in order in the calling thread and returns what the last one did.
+
+	`middleware` is a list of factories, the first the outermost; each is handed `processNext`, which
+	calls the next link and returns its result (a Promise the link returned already followed). A link
+	that does not call it drops the message there. `final` ends the chain.
+
+	`guards`, when given, check the arguments before any middleware runs: `fixed[i]` checks argument
+	`i`, `rest` every one past them. The first one that fails is reported through `reject` with its
+	0-based index, and the processor returns `rejected` without calling anything else.
+
+	`cancelled` is what a Promise that was cancelled reads as (`Networking.Skip` for a function).
+]]
+local function createProcessor(
+	middleware: { (processNext: any, networkInfo: any) -> any }?,
+	networkInfo: any,
+	final: (...any) -> ...any,
+	guards: any,
+	rejected: any,
+	cancelled: any
+)
+	local head = final
+	if middleware ~= nil then
+		for index = #middleware, 1, -1 do
+			local after = head
+			head = middleware[index](function(player, ...)
+				return follow(callTrimmed(after, player, ...), cancelled)
+			end, networkInfo)
+		end
+	end
+
+	if guards == nil then
+		return function(player, ...)
+			return follow(callTrimmed(head, player, ...), cancelled)
+		end
+	end
+
+	local fixed = guards.fixed
+	local rest = guards.rest
+	local reject = guards.reject
+	local fixedCount = #fixed
+
+	return function(player, ...)
+		-- Checked up to the last value: a trailing nil is an argument that was not passed.
+		local count = select("#", ...)
+		while count > 0 and select(count, ...) == nil do
+			count -= 1
+		end
+
+		for index = 1, math.max(fixedCount, count) do
+			local guard = fixed[index] or rest
+			if guard ~= nil then
+				local value = select(index, ...)
+				if not guard(value) then
+					reject(player, index - 1, value)
+					return rejected
+				end
+			end
+		end
+
+		return follow(callTrimmed(head, player, ...), cancelled)
+	end
+end
+
+--[[
+	Unpacks a serialized argument list, `(payload, blobs?)` as the remote carried it. Returns `true`
+	and the list, or `false` and why it could not be read. The decoder runs under `pcall`: a hostile
+	buffer raises instead of yielding garbage.
+]]
+local function decode(decoder: (buffer, { any }) -> { any }, payload: any, blobs: any): (boolean, any)
+	if type(payload) ~= "buffer" or (blobs ~= nil and type(blobs) ~= "table") then
+		return false, "payload is not a buffer with an optional blob list"
+	end
+
+	local ok, result = pcall(decoder, payload, blobs or NO_BLOBS)
+	if not ok then
+		return false, tostring(result)
+	end
+
+	return true, result
+end
+
+--[[
+	The handler to connect to a remote's `OnServerEvent` (`withPlayer`) or `OnClientEvent`: decodes
+	the payload when there is a `decoder`, reporting one it cannot read through `onMalformed` and
+	dropping it, and hands the arguments to `process`, in the thread the engine runs the handler on.
+]]
+local function createReceiver(
+	decoder: ((buffer, { any }) -> { any })?,
+	onMalformed: ((player: any, message: string) -> ())?,
+	process: (...any) -> ...any,
+	withPlayer: boolean
+)
+	local receive = process
+	if decoder ~= nil then
+		receive = function(player, payload, blobs)
+			local ok, result = decode(decoder, payload, blobs)
+			if not ok then
+				if onMalformed ~= nil then
+					onMalformed(player, result)
+				end
+				return
+			end
+
+			-- A decoded list has a slot per declared parameter, so an absent trailing optional leaves
+			-- it ending in nil: unpacked up to its last value.
+			return process(player, table.unpack(result, 1, table.maxn(result)))
+		end
+	end
+
+	if withPlayer then
+		return receive
+	end
+
+	return function(...)
+		return receive(nil, ...)
+	end
+end
+
+--- The last step of an event's chain: fires `signal`, with the sender first on the server.
+local function deliverTo(signal: any, withPlayer: boolean)
+	if withPlayer then
+		return function(player, ...)
+			signal:Fire(player, ...)
+		end
+	end
+
+	return function(_player, ...)
+		signal:Fire(...)
+	end
+end
+
+--- `callback` called without the player in front, which is how a client's callback is written.
+local function withoutPlayer(callback: (...any) -> ...any)
+	return function(_player, ...)
+		return callback(...)
+	end
+end
+
+return {
+	createProcessor = createProcessor,
+	createReceiver = createReceiver,
+	decode = decode,
+	deliverTo = deliverTo,
+	withoutPlayer = withoutPlayer,
+}

package/out/middleware/types.d.ts

@@ -1,15 +1,26 @@
-import { NetworkInfo } from "../types";
-import { Skip } from "./skip";
-
-export type MiddlewareProcessor<I extends readonly unknown[], O> = (player?: Player, ...args: I) => Promise<O>;
-export type Middleware<I extends readonly unknown[] = unknown[], O = void> = (
-	player?: Player,
-	...args: I
-) => O | Promise<O>;
-export type MiddlewareFactory<I extends readonly unknown[] = [], O = void> = (
-	processNext: MiddlewareProcessor<I, O>,
-	event: NetworkInfo,
-) => Middleware<I, O>;
-
-export type EventMiddleware<I extends readonly unknown[] = unknown[]> = MiddlewareFactory<I, void>;
-export type FunctionMiddleware<I extends readonly unknown[] = unknown[], O = void> = MiddlewareFactory<I, O | Skip>;
+import { NetworkInfo } from "../types";
+import { Skip } from "./skip";
+
+/**
+ * Calls the next link of the chain and returns its result: nothing for an event, the value (or
+ * `Networking.Skip`) for a function. A Promise the next link returned has already been waited for,
+ * in this thread.
+ */
+export type MiddlewareProcessor<I extends readonly unknown[], O> = (player?: Player, ...args: I) => O;
+
+/**
+ * One link of the chain. It may yield, which holds up only the message it is processing, and it may
+ * return a Promise, which is waited for before the link ahead of it continues.
+ */
+export type Middleware<I extends readonly unknown[] = unknown[], O = void> = (
+	player?: Player,
+	...args: I
+) => O | Promise<O>;
+
+export type MiddlewareFactory<I extends readonly unknown[] = [], O = void> = (
+	processNext: MiddlewareProcessor<I, O>,
+	event: NetworkInfo,
+) => Middleware<I, O>;
+
+export type EventMiddleware<I extends readonly unknown[] = unknown[]> = MiddlewareFactory<I, void>;
+export type FunctionMiddleware<I extends readonly unknown[] = unknown[], O = void> = MiddlewareFactory<I, O | Skip>;

package/out/util/createOnce.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Returns a function that builds a value on its first call and returns that value from then on.
+ *
+ * `build` may yield: a client handler waits for the server's remotes to replicate. A thread that
+ * calls while a build is under way waits for it rather than starting a second one, which would wire
+ * a second handler to the same remotes. If the build throws, the thread that started it gets the
+ * error and the next waiting thread builds again.
+ *
+ * The build runs on a thread of its own, and the thread that started it waits like the others. A
+ * caller can be killed while it waits (`task.cancel`, a cancelled Promise, a test's timeout), and a
+ * killed thread never reaches a `finally`: a build killed with its caller would leave every thread
+ * queued behind it, and every later caller, waiting for good.
+ */
+export declare function createOnce<T extends defined>(): (build: () => T) => T;

package/out/util/createOnce.luau

@@ -0,0 +1,66 @@
+-- Compiled with roblox-ts v3.0.0
+--[[
+	*
+	 * Returns a function that builds a value on its first call and returns that value from then on.
+	 *
+	 * `build` may yield: a client handler waits for the server's remotes to replicate. A thread that
+	 * calls while a build is under way waits for it rather than starting a second one, which would wire
+	 * a second handler to the same remotes. If the build throws, the thread that started it gets the
+	 * error and the next waiting thread builds again.
+	 *
+	 * The build runs on a thread of its own, and the thread that started it waits like the others. A
+	 * caller can be killed while it waits (`task.cancel`, a cancelled Promise, a test's timeout), and a
+	 * killed thread never reaches a `finally`: a build killed with its caller would leave every thread
+	 * queued behind it, and every later caller, waiting for good.
+	 
+]]
+local function createOnce()
+	local value
+	local waiting
+	return function(build)
+		while value == nil do
+			if waiting ~= nil then
+				local _waiting = waiting
+				local _arg0 = coroutine.running()
+				table.insert(_waiting, _arg0)
+				coroutine.yield()
+				continue
+			end
+			local threads = {}
+			waiting = threads
+			-- Set by the build's thread, so widened: the checks below must not narrow them to their start.
+			local finished = false
+			local failure = nil
+			task.spawn(function()
+				local ok, result = pcall(build)
+				if ok then
+					value = result
+				else
+					failure = {
+						reason = result,
+					}
+				end
+				finished = true
+				waiting = nil
+				for _, thread in threads do
+					-- A waiter killed meanwhile, the starter included, is not resumed.
+					if coroutine.status(thread) == "suspended" then
+						task.spawn(thread)
+					end
+				end
+			end)
+			if not finished then
+				local _arg0 = coroutine.running()
+				table.insert(threads, _arg0)
+				coroutine.yield()
+			end
+			if failure then
+				error(failure.reason, 0)
+			end
+		end
+		return value
+	end
+end
+return {
+	createOnce = createOnce,
+}

package/out/util/createSignalContainer.d.ts

@@ -1,5 +1,6 @@
+import { SignalConnection } from "./signal";
 export interface SignalContainer<T> {
     fire<K extends keyof T>(name: K, ...args: Parameters<T[K]>): void;
-    connect<K extends keyof T>(name: K, callback: T[K]): RBXScriptConnection;
+    connect<K extends keyof T>(name: K, callback: T[K]): SignalConnection;
 }
 export declare function createSignalContainer<T>(): SignalContainer<T>;

package/out/util/createSignalContainer.luau

@@ -1,6 +1,6 @@
 -- Compiled with roblox-ts v3.0.0
 local TS = _G[script]
-local Signal = TS.import(script, TS.getModule(script, "@rbxts", "signal"))
+local createSignal = TS.import(script, script.Parent, "signal").createSignal
 local function createSignalContainer()
 	local signals = {}
 	return {
@@ -17,7 +17,7 @@ local function createSignalContainer()
 			local signal = signals[_name]
 			if not signal then
 				local _exp = name
-				signal = Signal.new()
+				signal = createSignal()
 				local _signal = signal
 				signals[_exp] = _signal
 			end

package/out/util/signal.d.ts

@@ -0,0 +1,27 @@
+/**
+ * A handler's connection, public as `Networking.Connection`. Shaped like an `RBXScriptConnection`
+ * (`Connected`, `Disconnect`), plus `Destroy` for maids and janitors; it is a table, not an engine
+ * connection.
+ */
+export interface SignalConnection {
+	readonly Connected: boolean;
+	Disconnect(): void;
+	Destroy(): void;
+}
+
+/**
+ * Networking's own signal (see `signal.luau`): arguments are passed by reference, each handler runs
+ * on a recycled thread of its own, newest connection first.
+ */
+export interface Signal<T extends Callback = Callback> {
+	Connect(callback: T): SignalConnection;
+	Fire(...args: Parameters<T>): void;
+}
+
+export function createSignal<T extends Callback = Callback>(): Signal<T>;
+
+/**
+ * Runs `callback(...args)` at once on a recycled thread: a yield inside it does not hold up the
+ * caller, and an error is printed rather than raised to it.
+ */
+export function spawn<A extends unknown[]>(callback: (...args: A) => unknown, ...args: A): void;

package/out/util/signal.luau

@@ -0,0 +1,135 @@
+--[[
+	A signal of networking's own, and the recycled threads it and the receive pipeline run on.
+
+	Plain Luau rather than TypeScript: roblox-ts turns every `...args` into a table and spreads it with
+	`unpack`, which stops at the first nil it happens to land on. Here a vararg list keeps its count
+	from the remote to the handler, and nothing is allocated on the way.
+
+	Arguments are handed over by reference. A BindableEvent would copy them, turning a decoded
+	`Map<Instance, ...>` into one keyed by strings and raising on a `Set<boolean>`.
+
+	Like an engine signal, each handler runs on a thread of its own: one that yields does not hold up
+	the others, and one that raises has its error printed while the others still run. The newest
+	connection runs first, which is the order the engine runs a BindableEvent's handlers in; one made
+	during a fire does not receive it, and one disconnected before its turn is skipped.
+]]
+
+--- Threads that finished their last job, waiting in `coroutine.yield()` for the next.
+local idle: { thread } = {}
+
+--- How many finished threads are kept. More than a few are only ever needed while handlers yield;
+--- past this, a thread that finishes simply ends.
+local MAX_IDLE = 16
+
+local function call(callback: (...any) -> ...any, ...: any)
+	callback(...)
+end
+
+--[[
+	The body of a recycled thread: waits for a job, runs it, parks itself, and runs whatever it is
+	resumed with next. A job that raises ends the thread, and the error is printed by the scheduler
+	that resumed it; a job that yields keeps the thread until it returns, so it is only ever parked
+	when idle.
+
+	It takes no arguments, and every job arrives through `coroutine.yield()`: a job passed as the
+	thread's own arguments would stay in this frame's varargs for as long as the thread lives,
+	keeping its handler, sender and arguments reachable long after it returned.
+]]
+local function runner()
+	local thread = coroutine.running()
+
+	while true do
+		call(coroutine.yield())
+
+		if #idle >= MAX_IDLE then
+			return
+		end
+		table.insert(idle, thread)
+	end
+end
+
+--[[
+	Runs `callback(...)` at once on a thread of its own, recycling one that finished its last job. An
+	idle thread that was killed meanwhile (`task.cancel`) is dropped rather than resumed.
+]]
+local function spawn(callback: (...any) -> ...any, ...: any)
+	local count = #idle
+	while count > 0 do
+		local thread = idle[count]
+		idle[count] = nil
+		count -= 1
+
+		if coroutine.status(thread) == "suspended" then
+			task.spawn(thread, callback, ...)
+			return
+		end
+	end
+
+	-- A new thread, started up to its first `coroutine.yield()`, gets its first job the same way.
+	local thread = coroutine.create(runner)
+	coroutine.resume(thread)
+	task.spawn(thread, callback, ...)
+end
+
+local Connection = {}
+Connection.__index = Connection
+
+--- Disconnects the handler. Takes effect at once, even for a fire under way.
+function Connection:Disconnect()
+	if not self.Connected then
+		return
+	end
+
+	self.Connected = false
+	self._callback = nil
+
+	-- Copied rather than edited in place: a fire under way keeps walking the list it started with.
+	local signal = self._signal
+	local connections = signal._connections
+	local index = table.find(connections, self)
+	if index ~= nil then
+		local remaining = table.clone(connections)
+		table.remove(remaining, index)
+		signal._connections = remaining
+	end
+end
+
+--- The name maids and janitors call.
+Connection.Destroy = Connection.Disconnect
+
+local Signal = {}
+Signal.__index = Signal
+
+function Signal:Connect(callback: (...any) -> ...any)
+	local connection = setmetatable({
+		Connected = true,
+		_callback = callback,
+		_signal = self,
+	}, Connection)
+
+	-- Newest first, copied so that a fire under way does not reach it.
+	local connections = self._connections
+	local updated = table.create(#connections + 1)
+	updated[1] = connection
+	table.move(connections, 1, #connections, 2, updated)
+	self._connections = updated
+
+	return connection
+end
+
+function Signal:Fire(...: any)
+	for _, connection in self._connections do
+		if connection.Connected then
+			spawn(connection._callback, ...)
+		end
+	end
+end
+
+local function createSignal()
+	return setmetatable({ _connections = {} }, Signal)
+end
+
+return {
+	createSignal = createSignal,
+	spawn = spawn,
+}

package/out/util/trimArguments.d.ts

@@ -0,0 +1,12 @@
+/**
+ * `args` cut after its last value, so that spreading it passes every argument.
+ *
+ * roblox-ts spreads a list as `unpack(list)`, which stops at `#list`. When the last slot is nil, `#`
+ * may stop at any earlier gap: `#{1, nil, nil, 4, nil}` can be 1, which drops the 4. A list that ends
+ * in a value always spreads whole. The `{ ... }` that roblox-ts rebuilds from that spread at the next
+ * hop also ends in a value, and so does every hop after it that passes the list on. So a list is
+ * trimmed where it enters, and again wherever code may build its own: a middleware that names its
+ * parameters passes on a list that can end in nil. Nothing is lost by trimming: an argument that was
+ * not passed reads as nil too.
+ */
+export declare function trimArguments<T extends unknown[]>(args: T): T;

package/out/util/trimArguments.luau

@@ -0,0 +1,48 @@
+-- Compiled with roblox-ts v3.0.0
+--[[
+	*
+	 * `args` cut after its last value, so that spreading it passes every argument.
+	 *
+	 * roblox-ts spreads a list as `unpack(list)`, which stops at `#list`. When the last slot is nil, `#`
+	 * may stop at any earlier gap: `#{1, nil, nil, 4, nil}` can be 1, which drops the 4. A list that ends
+	 * in a value always spreads whole. The `{ ... }` that roblox-ts rebuilds from that spread at the next
+	 * hop also ends in a value, and so does every hop after it that passes the list on. So a list is
+	 * trimmed where it enters, and again wherever code may build its own: a middleware that names its
+	 * parameters passes on a list that can end in nil. Nothing is lost by trimming: an argument that was
+	 * not passed reads as nil too.
+	 
+]]
+local function trimArguments(args)
+	-- `pairs` visits every value, holes or not. Read as a map, the list gives the raw Luau (1-based)
+	-- index, which is the length up to that value.
+	local length = 0
+	for index in pairs(args) do
+		if index > length then
+			length = index
+		end
+	end
+	if #args == length then
+		return args
+	end
+	-- Sized up front, so that the last slot is the last value and `#` is exact.
+	local trimmed = table.create(length)
+	do
+		local i = 0
+		local _shouldIncrement = false
+		while true do
+			if _shouldIncrement then
+				i += 1
+			else
+				_shouldIncrement = true
+			end
+			if not (i < length) then
+				break
+			end
+			trimmed[i + 1] = args[i + 1]
+		end
+	end
+	return trimmed
+end
+return {
+	trimArguments = trimArguments,
+}