@flamework-experimental/networking 2.0.0-alpha.0

package/README.md

@@ -0,0 +1,66 @@
+# Flamework
+
+Flamework is an extensible framework for roblox-ts designed around portable, isolated and testable modules.
+
+## Documentation
+
+**[docs/](docs/README.md)** -- start there. A ten-part guide that builds up from a working entry
+point to plugins and project layout, plus reference material:
+
+| | |
+|---|---|
+| [Guide](docs/README.md#guide) | Getting started, modules, providers, lifecycle events, components, networking, macros, plugins, project structure, migrating from v1. |
+| [Internals](docs/reference/internals.md) | What the transformer does to your code and what the runtime does with the result. |
+| [Transformer plugins](docs/reference/transformer-plugins.md) | Adding macro types of your own. |
+
+The Flamework website documents v1, most of which no longer applies:
+
+https://flamework.fireboltofdeath.dev/docs/introduction
+
+## Development
+
+This repository is a [Bun](https://bun.sh) workspace. It also needs
+[Lune](https://lune-org.github.io/docs) on `PATH` to run the runtime specs.
+
+```sh
+bun install
+bun run build          # builds every package in dependency order
+bun run test           # build + transformer tests + runtime specs
+bun run lint
+```
+
+### Packages
+
+| Package | Description |
+|---|---|
+| `packages/core` | Modules, dependency injection, plugins and lifecycle events |
+| `packages/components` | CollectionService components, built on the core plugin system |
+| `packages/networking` | Remote events and functions |
+| `packages/testing` | In-place tests: sections, cleanup, a bindable and a remote to run them, a cloud entry; and `flamework-test`, the CLI that runs them in Roblox Studio on this machine or through Open Cloud (`cli/`) |
+| `packages/transformer` | The roblox-ts transformer |
+| `packages/transformer-plugin` | Public API for writing transformer plugins |
+| `packages/specs` | Runtime specs, compiled by `rbxtsc` and executed under Lune |
+
+### Tests
+
+Two suites, both run by `bun run test`:
+
+- **Transformer tests** (`bun run test:unit`) compile a fixture project with the real `rbxtsc` and
+  assert on the emitted Luau — guard generation, identifiers, nested macros and the plugin system.
+- **Runtime specs** (`bun run test:runtime`) execute compiled `@flamework-experimental/core`, `components` and
+  `networking` under Lune using the harness in [`tests/runtime`](tests/runtime), which models
+  roblox-ts's `TS.import` tree over the filesystem and stubs the Roblox API surface Flamework
+  touches (Instances, attributes, CollectionService, RemoteEvents, Players, signals, `task`,
+  `Enum`, and a `Heartbeat` pump so `Promise.delay` -- and therefore request timeouts -- runs).
+  They cover dependency injection, modules, hooks and the per-frame lifecycle events, component
+  construction, dependencies and streaming, and both halves of networking: events, functions,
+  middleware and the generated guards.
+
+  They run twice, once as `Server` and once as `Client`, because realm-dependent code paths --
+  `@Provider`'s metadata, component streaming, and the client/server halves of networking -- differ
+  between them. Where a spec asserts something realm-specific, running it from both sides is what
+  proves the two agree: a function receives on `$name` and sends on `@name` from the server and the
+  mirror image from the client, so the pair of runs pins the wire format down from both ends.
+
+Specs live in [`packages/specs`](packages/specs) and are compiled by `rbxtsc` like any other
+Flamework consumer, so they exercise the transformer and the runtime together.

package/flamework.build

@@ -0,0 +1,7 @@
+{
+	"version": 1,
+	"flameworkVersion": "2.0.0-alpha.0",
+	"identifiers": {},
+	"idGenerationMode": "full",
+	"identifierPrefix": "$n"
+}

package/out/event/createEvent.d.ts

@@ -0,0 +1,59 @@
+import { Serialization } from "@flamework-experimental/core";
+import { MiddlewareFactory, MiddlewareProcessor } from "../middleware/types";
+import { NetworkInfo } from "../types";
+export interface CreateEventOptions {
+    /**
+     * The namespace this event should be created in.
+     */
+    namespace: string;
+    /**
+     * The name of the remote instance, not necessarily unique and used for debugging purposes.
+     */
+    debugName: string;
+    /**
+     * The remote's ID which must be unique.
+     */
+    id: string;
+    /**
+     * Information about the network, which includes some of the above.
+     *
+     * Passed to the middleware.
+     */
+    networkInfo: NetworkInfo;
+    /**
+     * The reliability of this remote.
+     *
+     * Defaults to reliable.
+     */
+    reliability?: "reliable" | "unreliable";
+    /**
+     * A list of middleware that this event uses when it receives an event.
+     */
+    incomingMiddleware?: MiddlewareFactory<any[], void>[];
+    /**
+     * Unpacks the argument list of incoming events. Absent when the project does not enable
+     * serialization. Outgoing lists reach `fire*` already packed: the transformer generates the
+     * encoding inline at each call site.
+     */
+    incomingDecoder?: Serialization.Decoder;
+    /**
+     * Called when an incoming payload cannot be decoded; the event is dropped.
+     */
+    onMalformed?: (player: Player | undefined, message: string) => void;
+}
+export interface EventInterface {
+    fireEither(player: Player | undefined, ...args: unknown[]): void;
+    fireServer(...args: unknown[]): void;
+    fireClient(player: Player, ...args: unknown[]): void;
+    fireAllClients(...args: unknown[]): void;
+    connectServer(callback: (player: Player, ...args: unknown[]) => void): RBXScriptConnection;
+    connectClient(callback: (...args: unknown[]) => void): RBXScriptConnection;
+    invoke: MiddlewareProcessor<any[], void>;
+}
+/**
+ * The argument list a remote delivered: `args` as they are without a decoder, otherwise the buffer
+ * and blob list unpacked. `undefined` when the payload was malformed, after reporting it through
+ * `onMalformed`. Decoding runs under `pcall`: a hostile buffer raises instead of yielding garbage.
+ */
+export declare function decodeArguments(decoder: Serialization.Decoder | undefined, player: Player | undefined, args: unknown[], onMalformed?: (player: Player | undefined, message: string) => void): unknown[] | undefined;
+export declare function createEvent(options: CreateEventOptions): EventInterface;

package/out/event/createEvent.luau

@@ -0,0 +1,114 @@
+-- Compiled with roblox-ts v3.0.0
+local TS = _G[script]
+local RunService = TS.import(script, TS.getModule(script, "@rbxts", "services")).RunService
+local createRemoteInstance = TS.import(script, script.Parent, "createRemoteInstance").createRemoteInstance
+local createMiddlewareProcessor = TS.import(script, script.Parent.Parent, "middleware", "createMiddlewareProcessor").createMiddlewareProcessor
+--* A sender whose type has blob slots always sends a table; one without never does. 
+local NO_BLOBS = {}
+--[[
+	*
+	 * The argument list a remote delivered: `args` as they are without a decoder, otherwise the buffer
+	 * and blob list unpacked. `undefined` when the payload was malformed, after reporting it through
+	 * `onMalformed`. Decoding runs under `pcall`: a hostile buffer raises instead of yielding garbage.
+	 
+]]
+local function decodeArguments(decoder, player, args, onMalformed)
+	if not decoder then
+		return args
+	end
+	local _binding = args
+	local payload = _binding[1]
+	local blobs = _binding[2]
+	if not (type(payload) == "buffer") or (blobs ~= nil and not (type(blobs) == "table")) then
+		local _result = onMalformed
+		if _result ~= nil then
+			_result(player, "payload is not a buffer with an optional blob list")
+		end
+		return nil
+	end
+	local ok, result = pcall(decoder, payload, (blobs or NO_BLOBS))
+	if not ok then
+		local _result = onMalformed
+		if _result ~= nil then
+			_result(player, tostring(result))
+		end
+		return nil
+	end
+	return result
+end
+local function createEvent(options)
+	local remote = createRemoteInstance(if options.reliability == "unreliable" then "UnreliableRemoteEvent" else "RemoteEvent", options.namespace, options.debugName, options.id)
+	local bindable
+	local invoke = createMiddlewareProcessor(options.incomingMiddleware, options.networkInfo, function(player, ...)
+		local args = { ... }
+		if RunService:IsServer() then
+			bindable:Fire(player, unpack(args))
+		else
+			bindable:Fire(unpack(args))
+		end
+	end)
+	local receive = function(player, args)
+		local decoded = decodeArguments(options.incomingDecoder, player, args, options.onMalformed)
+		if decoded then
+			invoke(player, unpack(decoded))
+		end
+	end
+	local createConnection = function(callback)
+		if bindable then
+			return bindable.Event:Connect(callback)
+		end
+		bindable = Instance.new("BindableEvent")
+		-- We defer to allow any other immediate connections to take place before unloading Roblox's queue.
+		task.defer(function()
+			if RunService:IsServer() then
+				remote.OnServerEvent:Connect(function(player, ...)
+					local args = { ... }
+					return receive(player, args)
+				end)
+			else
+				remote.OnClientEvent:Connect(function(...)
+					local args = { ... }
+					return receive(nil, args)
+				end)
+			end
+		end)
+		return bindable.Event:Connect(callback)
+	end
+	return {
+		fireEither = function(self, player, ...)
+			local args = { ... }
+			if player then
+				self:fireClient(player, unpack(args))
+			else
+				self:fireServer(unpack(args))
+			end
+		end,
+		fireServer = function(self, ...)
+			local args = { ... }
+			remote:FireServer(unpack(args))
+		end,
+		fireClient = function(self, player, ...)
+			local args = { ... }
+			remote:FireClient(player, unpack(args))
+		end,
+		fireAllClients = function(self, ...)
+			local args = { ... }
+			remote:FireAllClients(unpack(args))
+		end,
+		connectServer = function(self, callback)
+			local _arg0 = RunService:IsServer()
+			assert(_arg0)
+			return createConnection(callback)
+		end,
+		connectClient = function(self, callback)
+			local _arg0 = RunService:IsClient()
+			assert(_arg0)
+			return createConnection(callback)
+		end,
+		invoke = invoke,
+	}
+end
+return {
+	decodeArguments = decodeArguments,
+	createEvent = createEvent,
+}

package/out/event/createRemoteInstance.d.ts

@@ -0,0 +1 @@
+export declare function createRemoteInstance<T extends "RemoteEvent" | "UnreliableRemoteEvent">(remoteType: T, namespace: string, debugName: string, id: string): CreatableInstances[T];

package/out/event/createRemoteInstance.luau

@@ -0,0 +1,58 @@
+-- Compiled with roblox-ts v3.0.0
+local TS = _G[script]
+local _services = TS.import(script, TS.getModule(script, "@rbxts", "services"))
+local ReplicatedStorage = _services.ReplicatedStorage
+local RunService = _services.RunService
+local function findByAttribute(parent, id)
+	for _, child in parent:GetChildren() do
+		if child:GetAttribute("id") == id then
+			return child
+		end
+	end
+end
+local function waitByAttribute(parent, id)
+	local instance = findByAttribute(parent, id)
+	local watcherThread = task.delay(5, function()
+		warn(`Flamework is waiting on '{id}' for`, parent)
+	end)
+	if not instance then
+		-- A connection rather than `ChildAdded.Wait()` in a loop: with deferred signals, children
+		-- added while the loop is between waits are never seen, so the wait never ends.
+		local thread = coroutine.running()
+		local connection
+		connection = parent.ChildAdded:Connect(function(child)
+			if child:GetAttribute("id") == id then
+				connection:Disconnect()
+				task.spawn(thread, child)
+			end
+		end)
+		instance = (coroutine.yield())
+	end
+	task.cancel(watcherThread)
+	return instance
+end
+local function createRemoteInstance(remoteType, namespace, debugName, id)
+	if not RunService:IsRunning() then
+		return Instance.new(remoteType)
+	end
+	local namespaceFolder = if RunService:IsServer() then findByAttribute(ReplicatedStorage, namespace) else waitByAttribute(ReplicatedStorage, namespace)
+	if not namespaceFolder then
+		namespaceFolder = Instance.new("Folder")
+		namespaceFolder.Name = namespace
+		namespaceFolder:SetAttribute("id", namespace)
+		namespaceFolder.Parent = ReplicatedStorage
+	end
+	local existingInstance = if RunService:IsServer() then findByAttribute(namespaceFolder, id) else waitByAttribute(namespaceFolder, id)
+	if not existingInstance then
+		existingInstance = Instance.new(remoteType)
+		existingInstance.Name = debugName
+		existingInstance:SetAttribute("id", id)
+		existingInstance.Parent = namespaceFolder
+	end
+	local _arg0 = existingInstance:IsA(remoteType)
+	assert(_arg0)
+	return existingInstance
+end
+return {
+	createRemoteInstance = createRemoteInstance,
+}

package/out/events/createClientMethod.d.ts

@@ -0,0 +1,5 @@
+import { ClientReceiver, ClientSender } from "./types";
+import { EventInterface } from "../event/createEvent";
+type ClientMethod = ClientSender<never[]> & ClientReceiver<never[]>;
+export declare function createClientMethod(receiver: EventInterface, sender: EventInterface): ClientMethod;
+export {};

package/out/events/createClientMethod.luau

@@ -0,0 +1,30 @@
+-- Compiled with roblox-ts v3.0.0
+local function createClientMethod(receiver, sender)
+	local method = {
+		fire = function(self, ...)
+			local args = { ... }
+			sender:fireServer(unpack(args))
+		end,
+		_fire = function(self, ...)
+			local packed = { ... }
+			sender:fireServer(unpack(packed))
+		end,
+		connect = function(self, callback)
+			return receiver:connectClient(callback)
+		end,
+		predict = function(self, ...)
+			local args = { ... }
+			return receiver.invoke(nil, unpack(args))
+		end,
+	}
+	setmetatable(method, {
+		__call = function(method, ...)
+			local args = { ... }
+			method:fire(unpack(args))
+		end,
+	})
+	return method
+end
+return {
+	createClientMethod = createClientMethod,
+}

package/out/events/createGenericHandler.d.ts

@@ -0,0 +1,5 @@
+import { EventNetworkingEvents } from "../handlers";
+import { ClientHandler, EventCreateConfiguration, NamespaceMetadata, ServerHandler } from "./types";
+import { SignalContainer } from "../util/createSignalContainer";
+import { EventInterface } from "../event/createEvent";
+export declare function createGenericHandler<T extends ClientHandler<S, R> | ServerHandler<S, R>, S, R>(globalName: string, namespaceName: string | undefined, metadata: NamespaceMetadata<R, S>, config: EventCreateConfiguration<R>, signals: SignalContainer<EventNetworkingEvents>, method: (receiver: EventInterface, sender: EventInterface) => unknown): T;

package/out/events/createGenericHandler.luau

@@ -0,0 +1,102 @@
+-- Compiled with roblox-ts v3.0.0
+local TS = _G[script]
+local createGuardMiddleware = TS.import(script, script.Parent.Parent, "middleware", "createGuardMiddleware").createGuardMiddleware
+local createEvent = TS.import(script, script.Parent.Parent, "event", "createEvent").createEvent
+local getNamespaceConfig = TS.import(script, script.Parent.Parent, "util", "getNamespaceConfig").getNamespaceConfig
+local Players = TS.import(script, TS.getModule(script, "@rbxts", "services")).Players
+local function createGenericHandler(globalName, namespaceName, metadata, config, signals, method)
+	local handler = {}
+	local _set = {}
+	for _, _v in metadata.incomingIds do
+		_set[_v] = true
+	end
+	local receiverNameSet = _set
+	local _set_1 = {}
+	for _, _v in metadata.outgoingIds do
+		_set_1[_v] = true
+	end
+	local senderNameSet = _set_1
+	local _set_2 = {}
+	local _array = {}
+	local _length = #_array
+	local _array_1 = metadata.incomingIds
+	local _Length = #_array_1
+	table.move(_array_1, 1, _Length, _length + 1, _array)
+	_length += _Length
+	local _array_2 = metadata.outgoingIds
+	table.move(_array_2, 1, #_array_2, _length + 1, _array)
+	for _, _v in _array do
+		_set_2[_v] = true
+	end
+	for name in _set_2 do
+		local isIncoming = receiverNameSet[name] ~= nil
+		local isOutgoing = senderNameSet[name] ~= nil
+		-- If there is no incoming/outgoing event, use the same reliability as the other.
+		local incomingChannel = if isIncoming then metadata.incomingUnreliable else metadata.outgoingUnreliable
+		local outgoingChannel = if isOutgoing then metadata.outgoingUnreliable else metadata.incomingUnreliable
+		local isIncomingUnreliable = incomingChannel[name] == true
+		local isOutgoingUnreliable = outgoingChannel[name] == true
+		local configMiddleware = config.middleware[name]
+		local incomingMiddleware = if configMiddleware ~= nil then table.clone(configMiddleware) else {}
+		local effectiveName = if namespaceName ~= nil then `{namespaceName}/{name}` else name
+		local networkInfo = {
+			eventType = "Event",
+			name = effectiveName,
+			globalName = globalName,
+		}
+		if not config.disableIncomingGuards and isIncoming then
+			local guards = metadata.incoming[name]
+			assert(guards)
+			local _arg0 = createGuardMiddleware(name, guards[1], guards[2], networkInfo, config.warnOnInvalidGuards, signals)
+			table.insert(incomingMiddleware, 1, _arg0)
+		end
+		-- A malformed serialized payload is reported like a failed guard, with no argument index.
+		local onMalformed = function(player, message)
+			if config.warnOnInvalidGuards then
+				local sender = if player ~= nil then `'{player}'` else "Server"
+				warn(`{sender} sent a malformed payload for event '{name}': {message}`)
+			end
+			signals:fire("onBadRequest", player or Players.LocalPlayer, {
+				networkInfo = networkInfo,
+				argIndex = -1,
+				argValue = message,
+			})
+		end
+		local create = function(unreliable, receives)
+			local _object = {
+				reliability = if unreliable then "unreliable" else "reliable",
+				namespace = globalName,
+				id = if unreliable then `unreliable:{effectiveName}` else effectiveName,
+				debugName = name,
+				networkInfo = networkInfo,
+				incomingMiddleware = incomingMiddleware,
+			}
+			local _left = "incomingDecoder"
+			local _result
+			if receives then
+				local _result_1 = metadata.incomingSerializers
+				if _result_1 ~= nil then
+					_result_1 = _result_1[name]
+				end
+				_result = _result_1
+			else
+				_result = nil
+			end
+			_object[_left] = _result
+			_object.onMalformed = onMalformed
+			return createEvent(_object)
+		end
+		local shared = isOutgoingUnreliable == isIncomingUnreliable
+		local receiver = create(isIncomingUnreliable, true)
+		local sender = if shared then receiver else create(isOutgoingUnreliable, false)
+		handler[name] = method(receiver, sender)
+	end
+	for _, namespaceId in metadata.namespaceIds do
+		local namespace = metadata.namespaces[namespaceId]
+		handler[namespaceId] = createGenericHandler(globalName, if namespaceName ~= nil then `{namespaceName}/{namespaceId}` else namespaceId, namespace, getNamespaceConfig(config, namespaceId), signals, method)
+	end
+	return handler
+end
+return {
+	createGenericHandler = createGenericHandler,
+}

package/out/events/createNetworkingEvent.d.ts

@@ -0,0 +1,2 @@
+import { GlobalEvent } from "./types";
+export declare function createNetworkingEvent<S, C>(globalName: string): GlobalEvent<S, C>;

package/out/events/createNetworkingEvent.luau

@@ -0,0 +1,60 @@
+-- Compiled with roblox-ts v3.0.0
+local TS = _G[script]
+local RunService = TS.import(script, TS.getModule(script, "@rbxts", "services")).RunService
+local createClientMethod = TS.import(script, script.Parent, "createClientMethod").createClientMethod
+local createServerMethod = TS.import(script, script.Parent, "createServerMethod").createServerMethod
+local createSignalContainer = TS.import(script, script.Parent.Parent, "util", "createSignalContainer").createSignalContainer
+local createGenericHandler = TS.import(script, script.Parent, "createGenericHandler").createGenericHandler
+local function getDefaultConfiguration(config)
+	local _object = {}
+	local _left = "middleware"
+	local _condition = config.middleware
+	if _condition == nil then
+		_condition = {}
+	end
+	_object[_left] = _condition
+	local _left_1 = "warnOnInvalidGuards"
+	local _condition_1 = config.warnOnInvalidGuards
+	if _condition_1 == nil then
+		_condition_1 = RunService:IsStudio()
+	end
+	_object[_left_1] = _condition_1
+	local _left_2 = "disableIncomingGuards"
+	local _condition_2 = config.disableIncomingGuards
+	if _condition_2 == nil then
+		_condition_2 = false
+	end
+	_object[_left_2] = _condition_2
+	return _object
+end
+local function createNetworkingEvent(globalName)
+	local signals = createSignalContainer()
+	local server
+	local client
+	return {
+		createServer = function(self, config, meta)
+			if RunService:IsRunning() and not RunService:IsServer() then
+				return nil
+			end
+			if server == nil then
+				server = createGenericHandler(globalName, nil, meta, getDefaultConfiguration(config), signals, createServerMethod)
+			end
+			return server
+		end,
+		createClient = function(self, config, meta)
+			if RunService:IsRunning() and not RunService:IsClient() then
+				return nil
+			end
+			if client == nil then
+				client = createGenericHandler(globalName, nil, meta, getDefaultConfiguration(config), signals, createClientMethod)
+			end
+			return client
+		end,
+		registerHandler = function(self, key, callback)
+			return signals:connect(key, callback)
+		end,
+	}
+end
+return {
+	createNetworkingEvent = createNetworkingEvent,
+}

package/out/events/createServerMethod.d.ts

@@ -0,0 +1,13 @@
+import { EventInterface } from "../event/createEvent";
+export declare function createServerMethod(receiver: EventInterface, sender: EventInterface): {
+    readonly _flamework_send?: unknown[] | undefined;
+    _fire: (players: Player | Player[], payload?: buffer, blobs?: Array<defined>) => void;
+    _except: (players: Player | Player[], payload?: buffer, blobs?: Array<defined>) => void;
+    _broadcast: (payload?: buffer, blobs?: Array<defined>) => void;
+    fire: (players: Player | Player[], ...args: unknown[]) => void;
+    except: (players: Player | Player[], ...args: unknown[]) => void;
+    broadcast: (...args: unknown[]) => void;
+    readonly _flamework_receive?: unknown[] | undefined;
+    connect: (cb: (player: Player, ...args: unknown[]) => void) => RBXScriptConnection;
+    predict: (player: Player, ...args: unknown[]) => void;
+};

package/out/events/createServerMethod.luau

@@ -0,0 +1,63 @@
+-- Compiled with roblox-ts v3.0.0
+local TS = _G[script]
+local Players = TS.import(script, TS.getModule(script, "@rbxts", "services")).Players
+local function createServerMethod(receiver, sender)
+	local method = {
+		fire = function(self, players, ...)
+			local args = { ... }
+			local _players = players
+			if typeof(_players) == "Instance" then
+				sender:fireClient(players, unpack(args))
+			else
+				for _, player in players do
+					sender:fireClient(player, unpack(args))
+				end
+			end
+		end,
+		broadcast = function(self, ...)
+			local args = { ... }
+			sender:fireAllClients(unpack(args))
+		end,
+		except = function(self, players, ...)
+			local args = { ... }
+			local _players = players
+			if typeof(_players) == "Instance" then
+				players = { players }
+			end
+			for _, player in Players:GetPlayers() do
+				if not (table.find(players, player) ~= nil) then
+					self:fire(player, unpack(args))
+				end
+			end
+		end,
+		_fire = function(self, players, ...)
+			local packed = { ... }
+			self:fire(players, unpack(packed))
+		end,
+		_broadcast = function(self, ...)
+			local packed = { ... }
+			self:broadcast(unpack(packed))
+		end,
+		_except = function(self, players, ...)
+			local packed = { ... }
+			self:except(players, unpack(packed))
+		end,
+		connect = function(self, callback)
+			return receiver:connectServer(callback)
+		end,
+		predict = function(self, player, ...)
+			local args = { ... }
+			receiver.invoke(player, unpack(args))
+		end,
+	}
+	setmetatable(method, {
+		__call = function(method, player, ...)
+			local args = { ... }
+			method:fire(player, unpack(args))
+		end,
+	})
+	return method
+end
+return {
+	createServerMethod = createServerMethod,
+}