@rbxts/tether 1.4.0 → 1.4.2

package/README.md

@@ -64,7 +64,7 @@ messaging.server.emit(Message.Test, {
 });
 ```
 
-## Simulated Remote Functions
+## Function Messages
 
 Tether does not directly use RemoteFunctions since it's based on the MessageEmitter structure. However I have created a small framework to simulate remote functions, as shown below.
 

package/out/emitters/client-emitter.d.ts

@@ -0,0 +1,49 @@
+import { ContextualEmitter } from "./contextual-emitter";
+import type { BaseMessage, ClientMessageCallback, ClientFunctionMessageCallback } from "../structs";
+export declare class ClientEmitter<MessageData> extends ContextualEmitter<MessageData> {
+    readonly context = "client";
+    readonly on: <K extends keyof MessageData>(this: ClientEmitter<MessageData>, message: K & BaseMessage, callback: ClientMessageCallback<MessageData[K]>) => () => void;
+    readonly once: <K extends keyof MessageData>(this: ClientEmitter<MessageData>, message: K & BaseMessage, callback: ClientMessageCallback<MessageData[K]>) => () => void;
+    /**
+     * Emits a message to a specific client or multiple clients
+     *
+     * @param player The player(s) to whom the message is sent
+     * @param message The message kind to be sent
+     * @param data The data associated with the message
+     * @param unreliable Whether the message should be sent unreliably
+     */
+    emit<K extends keyof MessageData>(player: Player | Player[], message: K & BaseMessage, data?: MessageData[K], unreliable?: boolean): void;
+    /**
+     * Emits a message to all clients except the specified client(s)
+     *
+     * @param player The player(s) to whom the message is not sent
+     * @param message The message kind to be sent
+     * @param data The data associated with the message
+     * @param unreliable Whether the message should be sent unreliably
+     */
+    emitExcept<K extends keyof MessageData>(player: Player | Player[], message: K & BaseMessage, data?: MessageData[K], unreliable?: boolean): void;
+    /**
+   * Emits a message to all connected clients
+   *
+   * @param message The message kind to be sent
+   * @param data The data associated with the message
+   * @param unreliable Whether the message should be sent unreliably
+   */
+    emitAll<K extends keyof MessageData>(message: K & BaseMessage, data?: MessageData[K], unreliable?: boolean): void;
+    /**
+     * Sets a callback for a simulated remote function
+     *
+     * @returns A destructor function that disconnects the callback from the message
+     */
+    setCallback<K extends keyof MessageData, R extends keyof MessageData>(message: K & BaseMessage, returnMessage: R & BaseMessage, callback: ClientFunctionMessageCallback<MessageData[K], MessageData[R]>): () => void;
+    /**
+     * Simulates a remote function invocation
+     *
+     * @param message The message kind to be sent
+     * @param returnMessage The message kind to be returned
+     * @param player The player to whom the function is sent
+     * @param data The data associated with the message
+     * @param unreliable Whether the message should be sent unreliably
+     */
+    invoke<K extends keyof MessageData, R extends keyof MessageData>(message: K & BaseMessage, returnMessage: R & BaseMessage, player: Player, data?: MessageData[K], unreliable?: boolean): Promise<MessageData[R]>;
+}

package/out/emitters/client-emitter.luau

@@ -0,0 +1,156 @@
+-- Compiled with roblox-ts v3.0.0
+local TS = _G[script]
+local _services = TS.import(script, TS.getModule(script, "@rbxts", "services"))
+local Players = _services.Players
+local RunService = _services.RunService
+local ContextualEmitter = TS.import(script, script.Parent, "contextual-emitter").ContextualEmitter
+if setLuneContext == nil then
+	setLuneContext = function() end
+end
+local ClientEmitter
+do
+	local super = ContextualEmitter
+	ClientEmitter = setmetatable({}, {
+		__tostring = function()
+			return "ClientEmitter"
+		end,
+		__index = super,
+	})
+	ClientEmitter.__index = ClientEmitter
+	function ClientEmitter.new(...)
+		local self = setmetatable({}, ClientEmitter)
+		return self:constructor(...) or self
+	end
+	function ClientEmitter:constructor(...)
+		super.constructor(self, ...)
+		self.context = "client"
+	end
+	function ClientEmitter:emit(player, message, data, unreliable)
+		if unreliable == nil then
+			unreliable = false
+		end
+		if RunService:IsClient() then
+			error("[tether::error] Cannot emit message from client to client")
+		end
+		task.spawn(function()
+			local _binding = self.master:runClientMiddlewares(message, data, player)
+			local dropRequest = _binding[1]
+			local newData = _binding[2]
+			if dropRequest then
+				return nil
+			end
+			self.master.relayer:queueMessage(self.context, message, { player, message, newData, unreliable })
+		end)
+	end
+	function ClientEmitter:emitExcept(player, message, data, unreliable)
+		if unreliable == nil then
+			unreliable = false
+		end
+		local shouldSendTo = function(p)
+			local _player = player
+			local _result
+			if typeof(_player) == "Instance" then
+				_result = p ~= player
+			else
+				local _player_1 = player
+				local _p = p
+				_result = not (table.find(_player_1, _p) ~= nil)
+			end
+			return _result
+		end
+		local _self = self
+		local _exp = Players:GetPlayers()
+		-- ▼ ReadonlyArray.filter ▼
+		local _newValue = {}
+		local _length = 0
+		for _k, _v in _exp do
+			if shouldSendTo(_v, _k - 1, _exp) == true then
+				_length += 1
+				_newValue[_length] = _v
+			end
+		end
+		-- ▲ ReadonlyArray.filter ▲
+		_self:emit(_newValue, message, data, unreliable)
+	end
+	function ClientEmitter:emitAll(message, data, unreliable)
+		if unreliable == nil then
+			unreliable = false
+		end
+		if RunService:IsClient() then
+			error("[tether::error] Cannot emit message from client to all clients")
+		end
+		task.spawn(function()
+			local _binding = self.master:runClientMiddlewares(message, data)
+			local dropRequest = _binding[1]
+			local newData = _binding[2]
+			if dropRequest then
+				return nil
+			end
+			self.master.relayer:queueMessage(true, message, { message, newData, unreliable })
+		end)
+	end
+	function ClientEmitter:setCallback(message, returnMessage, callback)
+		if RunService:IsServer() then
+			error("[tether::error] Cannot listen to server message from client")
+		end
+		return self:on(message, function(data)
+			local returnValue = callback(data)
+			-- Defer the response emission to end of frame and swap context to avoid context check issues
+			-- task.defer guarantees response is sent by end of current frame, ensuring predictable timing in production
+			task.defer(function()
+				setLuneContext("client")
+				self.master.server:emit(returnMessage, returnValue)
+				setLuneContext("both")
+			end)
+		end)
+	end
+	function ClientEmitter:invoke(message, returnMessage, player, data, unreliable)
+		if unreliable == nil then
+			unreliable = false
+		end
+		if RunService:IsClient() then
+			error("[tether::error] Cannot invoke function from client to client")
+		end
+		local _binding = self.master
+		local serverFunctions = _binding.serverFunctions
+		local _returnMessage = returnMessage
+		if not (serverFunctions[_returnMessage] ~= nil) then
+			local _returnMessage_1 = returnMessage
+			serverFunctions[_returnMessage_1] = {}
+		end
+		local _returnMessage_1 = returnMessage
+		local functions = serverFunctions[_returnMessage_1]
+		local returnValue
+		local responseCallback = function(data)
+			returnValue = data
+			return returnValue
+		end
+		functions[responseCallback] = true
+		self:emit(player, message, data, unreliable)
+		return TS.Promise.new(function(resolve, reject)
+			-- awful
+			local frames = 0
+			while true do
+				local _condition = returnValue == nil
+				if _condition then
+					local _original = frames
+					frames += 1
+					_condition = _original < 400
+				end
+				if not _condition then
+					break
+				end
+				RunService.Heartbeat:Wait()
+			end
+			if frames == 400 then
+				return reject("[tether::error] Client function timed out (no response)")
+			end
+			-- clean up the callback after receiving the response
+			functions[responseCallback] = nil
+			resolve(returnValue)
+		end)
+	end
+end
+return {
+	ClientEmitter = ClientEmitter,
+}

package/out/emitters/contextual-emitter.d.ts

@@ -0,0 +1,26 @@
+import type { MessageEmitter } from "./message-emitter";
+import type { BaseMessage, MessageCallback, FunctionMessageCallback } from "../structs";
+type Cleanup = () => void;
+export declare abstract class ContextualEmitter<MessageData> {
+    protected readonly master: MessageEmitter<MessageData>;
+    abstract readonly context: "client" | "server";
+    /**
+     * Constructs a new ContextualEmitter.
+     * @param master The master emitter to which messages are delegated.
+     */
+    constructor(master: MessageEmitter<MessageData>);
+    abstract emit<K extends keyof MessageData>(player: (K & BaseMessage) | (Player | Player[]), message?: MessageData[K] | (K & BaseMessage), data?: MessageData[K] | boolean, unreliable?: boolean): void;
+    abstract setCallback<K extends keyof MessageData, R extends keyof MessageData>(message: K & BaseMessage, returnMessage: R & BaseMessage, callback: FunctionMessageCallback<MessageData[K], MessageData[R]>): Cleanup;
+    abstract invoke<K extends keyof MessageData, R extends keyof MessageData>(message: K & BaseMessage, returnMessage: R & BaseMessage, player?: Player | MessageData[K], data?: MessageData[K] | boolean, unreliable?: boolean): Promise<MessageData[R]>;
+    /**
+     * @returns A destructor function that disconnects the callback from the message
+     */
+    on<K extends keyof MessageData>(message: K & BaseMessage, callback: MessageCallback<MessageData[K]>): Cleanup;
+    /**
+     * Disconnects the callback as soon as it is called for the first time
+     *
+     * @returns A destructor function that disconnects the callback from the message
+     */
+    once<K extends keyof MessageData>(message: K & BaseMessage, callback: MessageCallback<MessageData[K]>): Cleanup;
+}
+export {};

package/out/emitters/contextual-emitter.luau

@@ -0,0 +1,49 @@
+-- Compiled with roblox-ts v3.0.0
+local TS = _G[script]
+local RunService = TS.import(script, TS.getModule(script, "@rbxts", "services")).RunService
+local ContextualEmitter
+do
+	ContextualEmitter = {}
+	function ContextualEmitter:constructor(master)
+		self.master = master
+	end
+	function ContextualEmitter:on(message, callback)
+		local isClient = self.context == "client"
+		if RunService:IsClient() and not isClient then
+			return error("[tether::error] Cannot listen to server message from client")
+		elseif RunService:IsServer() and isClient then
+			return error("[tether::error] Cannot listen to client message from server")
+		end
+		local callbacksMap = if isClient then self.master.clientCallbacks else self.master.serverCallbacks
+		local _message = message
+		if not (callbacksMap[_message] ~= nil) then
+			local _message_1 = message
+			callbacksMap[_message_1] = {}
+		end
+		local _message_1 = message
+		local callbacks = callbacksMap[_message_1]
+		local _callback = callback
+		callbacks[_callback] = true
+		local _message_2 = message
+		callbacksMap[_message_2] = callbacks
+		return function()
+			local _callback_1 = callback
+			-- ▼ Set.delete ▼
+			local _valueExisted = callbacks[_callback_1] ~= nil
+			callbacks[_callback_1] = nil
+			-- ▲ Set.delete ▲
+			return _valueExisted
+		end
+	end
+	function ContextualEmitter:once(message, callback)
+		local destructor
+		destructor = self:on(message, function(player, data)
+			destructor()
+			callback(player, data)
+		end)
+		return destructor
+	end
+end
+return {
+	ContextualEmitter = ContextualEmitter,
+}

package/out/emitters/message-emitter.d.ts

@@ -0,0 +1,41 @@
+import { Modding } from "@flamework/core";
+import { Trash } from "@rbxts/trash";
+import Destroyable from "@rbxts/destroyable";
+import { MiddlewareProvider } from "../middleware";
+import type { SerializedPacket, ClientMessageCallback, ServerMessageCallback, BaseMessage, MessageEmitterMetadata } from "../structs";
+import { ServerEmitter } from "./server-emitter";
+import { ClientEmitter } from "./client-emitter";
+import { Relayer } from "../relayer";
+import { Serdes } from "../serdes";
+export interface MessageEmitterOptions<MessageData> {
+    readonly batchRemotes: boolean;
+    readonly batchRate: number;
+    readonly doNotBatch: Set<keyof MessageData>;
+}
+export declare class MessageEmitter<MessageData> extends Destroyable {
+    readonly options: MessageEmitterOptions<MessageData>;
+    readonly server: ServerEmitter<MessageData>;
+    readonly client: ClientEmitter<MessageData>;
+    readonly middleware: MiddlewareProvider<MessageData>;
+    /** @hidden */ readonly trash: Trash;
+    /** @hidden */ readonly relayer: Relayer<MessageData>;
+    /** @hidden */ readonly serdes: Serdes<MessageData>;
+    /** @hidden */ clientCallbacks: Map<keyof MessageData, Set<ClientMessageCallback>>;
+    /** @hidden */ clientFunctions: Map<keyof MessageData, Set<(data: unknown) => void>>;
+    /** @hidden */ serverCallbacks: Map<keyof MessageData, Set<ServerMessageCallback>>;
+    /** @hidden */ serverFunctions: Map<keyof MessageData, Set<(data: unknown) => void>>;
+    private readonly guards;
+    /** @metadata macro */
+    static create<MessageData>(options?: Partial<MessageEmitterOptions<MessageData>>, meta?: Modding.Many<MessageEmitterMetadata<MessageData>>): MessageEmitter<MessageData>;
+    private constructor();
+    /** @hidden */
+    runClientMiddlewares<Kind extends keyof MessageData>(message: Kind & BaseMessage, data?: MessageData[Kind], player?: Player | Player[]): [boolean, MessageData[Kind]];
+    /** @hidden */
+    runServerMiddlewares<Kind extends keyof MessageData>(message: Kind & BaseMessage, data?: MessageData[Kind]): [boolean, MessageData[Kind]];
+    /** @hidden */
+    onRemoteFire(isServer: boolean, serializedPackets: SerializedPacket[], player?: Player): void;
+    private validateData;
+    private executeFunctions;
+    private executeEventCallbacks;
+    private deserializeAndValidate;
+}

package/out/emitters/message-emitter.luau

@@ -0,0 +1,222 @@
+-- Compiled with roblox-ts v3.0.0
+local TS = _G[script]
+local Players = TS.import(script, TS.getModule(script, "@rbxts", "services")).Players
+local Destroyable = TS.import(script, TS.getModule(script, "@rbxts", "destroyable").out).default
+local Object = TS.import(script, TS.getModule(script, "@rbxts", "object-utils"))
+local repr = TS.import(script, TS.getModule(script, "@rbxts", "repr").out)
+local _middleware = TS.import(script, script.Parent.Parent, "middleware")
+local DropRequest = _middleware.DropRequest
+local MiddlewareProvider = _middleware.MiddlewareProvider
+local ServerEmitter = TS.import(script, script.Parent, "server-emitter").ServerEmitter
+local ClientEmitter = TS.import(script, script.Parent, "client-emitter").ClientEmitter
+local Relayer = TS.import(script, script.Parent.Parent, "relayer").Relayer
+local Serdes = TS.import(script, script.Parent.Parent, "serdes").Serdes
+local readMessage = TS.import(script, script.Parent.Parent, "utility").readMessage
+if setLuneContext == nil then
+	setLuneContext = function() end
+end
+setLuneContext("both")
+local guardFailed = function(message, data)
+	return `[tether::warning]: Type validation guard failed for message '{message}' - check your sent data\nSent data: {repr(data)}`
+end
+local defaultMesssageEmitterOptions = {
+	batchRemotes = true,
+	batchRate = 1 / 24,
+	doNotBatch = {},
+}
+local MessageEmitter
+do
+	local super = Destroyable
+	MessageEmitter = setmetatable({}, {
+		__tostring = function()
+			return "MessageEmitter"
+		end,
+		__index = super,
+	})
+	MessageEmitter.__index = MessageEmitter
+	function MessageEmitter.new(...)
+		local self = setmetatable({}, MessageEmitter)
+		return self:constructor(...) or self
+	end
+	function MessageEmitter:constructor(options)
+		if options == nil then
+			options = defaultMesssageEmitterOptions
+		end
+		super.constructor(self)
+		self.options = options
+		self.server = ServerEmitter.new(self)
+		self.client = ClientEmitter.new(self)
+		self.middleware = MiddlewareProvider.new()
+		self.relayer = Relayer.new(self)
+		self.serdes = Serdes.new()
+		self.clientCallbacks = {}
+		self.clientFunctions = {}
+		self.serverCallbacks = {}
+		self.serverFunctions = {}
+		self.guards = {}
+		self.trash:add(function()
+			self.clientCallbacks = {}
+			self.serverCallbacks = {}
+			self.clientFunctions = {}
+			self.clientCallbacks = {}
+			self.serdes.serializers = {}
+			self.relayer:relayAll()
+			setmetatable(self, nil)
+		end)
+	end
+	function MessageEmitter:create(options, meta)
+		local emitter = MessageEmitter.new(Object.assign({}, defaultMesssageEmitterOptions, options))
+		if meta == nil then
+			warn("[tether::warning] Failed to generate message metadata - make sure you have the Flamework transformer and are using Flamework macro-friendly types in your schemas")
+			return emitter
+		end
+		-- lore
+		-- https://discord.com/channels/476080952636997633/506983834877689856/1363938149486821577
+		for kind, _binding in pairs(meta) do
+			local guard = _binding.guard
+			local serializerMetadata = _binding.serializerMetadata
+			local numberKind = tonumber(kind)
+			emitter.guards[numberKind] = guard
+			if serializerMetadata == nil then
+				continue
+			end
+			emitter.serdes:addSerializer(numberKind, serializerMetadata)
+		end
+		return emitter
+	end
+	function MessageEmitter:runClientMiddlewares(message, data, player)
+		if not self:validateData(message, data) then
+			return { true, data }
+		end
+		local players = player or Players:GetPlayers()
+		local ctx = {
+			message = message,
+			data = data,
+			getRawData = function()
+				return self.serdes:serializePacket(message, data)
+			end,
+		}
+		for _, globalMiddleware in self.middleware:getClientGlobal() do
+			local result = globalMiddleware(players, ctx)
+			if not self:validateData(message, ctx.data, "Invalid data after global client middleware") then
+				return { false, ctx.data }
+			end
+			if result == DropRequest then
+				self.middleware:notifyRequestDropped(message, "Global client middleware")
+				return { true, ctx.data }
+			end
+		end
+		for _, middleware in self.middleware:getClient(message) do
+			local result = middleware(players, ctx)
+			if not self:validateData(message, ctx.data, "Invalid data after client middleware") then
+				return { false, ctx.data }
+			end
+			if result == DropRequest then
+				self.middleware:notifyRequestDropped(message, "Client middleware")
+				return { true, ctx.data }
+			end
+		end
+		if not self:validateData(message, ctx.data) then
+			return { true, ctx.data }
+		end
+		return { false, ctx.data }
+	end
+	function MessageEmitter:runServerMiddlewares(message, data)
+		if not self:validateData(message, data) then
+			return { true, data }
+		end
+		local ctx = {
+			message = message,
+			data = data,
+			getRawData = function()
+				return self.serdes:serializePacket(message, data)
+			end,
+		}
+		for _, globalMiddleware in self.middleware:getServerGlobal() do
+			if not self:validateData(message, ctx.data, "Invalid data after global server middleware") then
+				return { false, ctx.data }
+			end
+			local result = globalMiddleware(ctx)
+			if result == DropRequest then
+				self.middleware:notifyRequestDropped(message, "Global server middleware")
+				return { true, ctx.data }
+			end
+		end
+		for _, middleware in self.middleware:getServer(message) do
+			if not self:validateData(message, ctx.data, "Invalid data after server middleware") then
+				return { false, ctx.data }
+			end
+			local result = middleware(ctx)
+			if result == DropRequest then
+				self.middleware:notifyRequestDropped(message, "Server middleware")
+				return { true, ctx.data }
+			end
+		end
+		if not self:validateData(message, ctx.data) then
+			return { true, ctx.data }
+		end
+		return { false, ctx.data }
+	end
+	function MessageEmitter:onRemoteFire(isServer, serializedPackets, player)
+		for _, packet in serializedPackets do
+			if buffer.len(packet.messageBuf) > 1 then
+				return warn("[tether::warning] Rejected packet because message buffer was larger than one byte")
+			end
+			local message = readMessage(packet)
+			self:executeEventCallbacks(isServer, message, packet, player)
+			self:executeFunctions(isServer, message, packet)
+		end
+	end
+	function MessageEmitter:validateData(message, data, requestDropReason)
+		if requestDropReason == nil then
+			requestDropReason = "Invalid data"
+		end
+		local _guards = self.guards
+		local _message = message
+		local guard = _guards[_message]
+		local guardPassed = guard(data)
+		if not guardPassed then
+			warn(guardFailed(message, data))
+			self.middleware:notifyRequestDropped(message, requestDropReason)
+		end
+		return guardPassed
+	end
+	function MessageEmitter:executeFunctions(isServer, message, serializedPacket)
+		local functionsMap = if isServer then self.serverFunctions else self.clientFunctions
+		local _message = message
+		local functions = functionsMap[_message]
+		if functions == nil then
+			return nil
+		end
+		local packet = self:deserializeAndValidate(message, serializedPacket)
+		for callback in functions do
+			callback(packet)
+		end
+	end
+	function MessageEmitter:executeEventCallbacks(isServer, message, serializedPacket, player)
+		local callbacksMap = if isServer then self.serverCallbacks else self.clientCallbacks
+		local _message = message
+		local callbacks = callbacksMap[_message]
+		if callbacks == nil then
+			return nil
+		end
+		local packet = self:deserializeAndValidate(message, serializedPacket)
+		for callback in callbacks do
+			if isServer then
+				local _arg0 = player ~= nil
+				assert(_arg0)
+				callback(player, packet)
+			else
+				callback(packet)
+			end
+		end
+	end
+	function MessageEmitter:deserializeAndValidate(message, serializedPacket)
+		local packet = self.serdes:deserializePacket(message, serializedPacket)
+		self:validateData(message, packet)
+		return packet
+	end
+end
+return {
+	MessageEmitter = MessageEmitter,
+}

package/out/emitters/server-emitter.d.ts

@@ -0,0 +1,30 @@
+import { ContextualEmitter } from "./contextual-emitter";
+import type { BaseMessage, ServerMessageCallback, ServerFunctionMessageCallback } from "../structs";
+export declare class ServerEmitter<MessageData> extends ContextualEmitter<MessageData> {
+    readonly context = "server";
+    readonly on: <K extends keyof MessageData>(this: ServerEmitter<MessageData>, message: K & BaseMessage, callback: ServerMessageCallback<MessageData[K]>) => () => void;
+    readonly once: <K extends keyof MessageData>(this: ServerEmitter<MessageData>, message: K & BaseMessage, callback: ServerMessageCallback<MessageData[K]>) => () => void;
+    /**
+     * Emits a message to the server
+     *
+     * @param message The message kind to be sent
+     * @param data The data associated with the message
+     * @param unreliable Whether the message should be sent unreliably
+     */
+    emit<K extends keyof MessageData>(message: K & BaseMessage, data?: MessageData[K], unreliable?: boolean): void;
+    /**
+     * Sets a callback for a simulated remote function
+     *
+     * @returns A destructor function that disconnects the callback from the message
+     */
+    setCallback<K extends keyof MessageData, R extends keyof MessageData>(message: K & BaseMessage, returnMessage: R & BaseMessage, callback: ServerFunctionMessageCallback<MessageData[K], MessageData[R]>): () => void;
+    /**
+     * Simulates a remote function invocation
+     *
+     * @param message The message kind to be sent
+     * @param returnMessage The message kind to be returned
+     * @param data The data associated with the message
+     * @param unreliable Whether the message should be sent unreliably
+     */
+    invoke<K extends keyof MessageData, R extends keyof MessageData>(message: K & BaseMessage, returnMessage: R & BaseMessage, data?: MessageData[K], unreliable?: boolean): Promise<MessageData[R]>;
+}