@rbxts/tether 1.1.6 → 1.2.0

package/README.md

@@ -1,5 +1,5 @@
 # Tether
-A message-based networking solution for Roblox with automatic binary serialization.
+A message-based networking solution for Roblox with automatic binary serialization and type validation.
 
 > [!CAUTION]
 > Depends on `rbxts-transformer-flamework`!
@@ -14,7 +14,8 @@ import { MessageEmitter } from "@rbxts/tether";
 export const messaging = MessageEmitter.create<MessageData>();
 
 export const enum Message {
-  Test
+  Test,
+  Packed
 }
 
 export interface MessageData {
@@ -22,6 +23,16 @@ export interface MessageData {
     readonly foo: string;
     readonly n: DataType.u8;
   };
+  [Message.Packed]: DataType.Packed<{
+    boolean1: boolean;
+    boolean2: boolean;
+    boolean3: boolean;
+    boolean4: boolean;
+    boolean5: boolean;
+    boolean6: boolean;
+    boolean7: boolean;
+    boolean8: boolean;
+  }>;
 }
 ```
 
@@ -32,7 +43,7 @@ export interface MessageData {
 ```ts
 import { Message, messaging } from "shared/messaging";
 
-messaging.onServerMessage(Message.Test, (player, data) => {
+messaging.server.on(Message.Test, (player, data) => {
   print(player, "sent data:", data);
 });
 ```
@@ -41,12 +52,59 @@ messaging.onServerMessage(Message.Test, (player, data) => {
 ```ts
 import { Message, messaging } from "shared/messaging";
 
-messaging.emitServer(Message.Test, {
+messaging.server.emit(Message.Test, {
   foo: "bar",
   n: 69
 });
 ```
 
+## Simulated Remote Functions
+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.
+
+For each function you will need two messages. One to invoke the function, and one to send the return value back (which is done automatically).
+
+### In `shared/messaging.ts`
+```ts
+import type { DataType } from "@rbxts/flamework-binary-serializer";
+import { MessageEmitter } from "@rbxts/tether";
+
+export const messaging = MessageEmitter.create<MessageData>();
+
+export const enum Message {
+  Increment,
+  IncrementReturn
+}
+
+export interface MessageData {
+  [Message.Increment]: DataType.u8;
+  [Message.IncrementReturn]: DataType.u8;
+}
+```
+
+### Server
+```ts
+import { Message, messaging } from "shared/messaging";
+
+messaging.server.setCallback(Message.Increment, Message.IncrementReturn, (_, n) => n + 1);
+```
+
+### Client
+```ts
+import { Message, messaging } from "shared/messaging";
+
+messaging.server
+  .invoke(Message.Increment, Message.IncrementReturn, 69)
+  .then(print); // 70 - incremented by the server
+
+// or use await style
+async function main(): Promise<void> {
+  const value = await messaging.server.invoke(Message.Increment, Message.IncrementReturn, 69);
+  print(value) // 70
+}
+
+main();
+```
+
 ## Middleware
 Drop, delay, or modify requests
 
@@ -107,19 +165,18 @@ export const messaging = MessageEmitter.create<MessageData>();
 messaging.middleware
   // only allows requests to the server every 5 seconds,
   // drops any requests that occur within 5 seconds of each other
-  .useServer(Message.Test, [BuiltinMiddlewares.rateLimit(5)]) 
-  // automatically validates that the data sent through the remote matches
-  // the data associated with the message at runtime using type guards
-  .useServer(Message.Test, [BuiltinMiddlewares.validate()])
+  .useServer(Message.Test, BuiltinMiddlewares.rateLimit(5)) 
+  .useShared(Message.Packed, () => (_, __, getRawData) => print("Packed object size:", buffer.len(getRawData()))); // will be just one byte!
   // logs every message fired
-  .useServerGlobal([logServer()])
-  .useClientGlobal([logClient()])
-  .useSharedGlobal([BuiltinMiddlewares.debug()]); // verbosely logs every packet sent
-  .useServer(Message.Test, [incrementNumberData()]) // error! - data for Message.Test is not a number 
-  .useServerGlobal([incrementNumberData()]); // error! - global data type is always 'unknown', we cannot guarantee a number
+  .useServerGlobal(logServer())
+  .useClientGlobal(logClient())
+  .useSharedGlobal(BuiltinMiddlewares.debug()); // verbosely logs every packet sent
+  .useServer(Message.Test, incrementNumberData()) // error! - data for Message.Test is not a number 
+  .useServerGlobal(incrementNumberData()); // error! - global data type is always 'unknown', we cannot guarantee a number
 
 export const enum Message {
-  Test
+  Test,
+  Packed
 }
 
 export interface MessageData {
@@ -127,5 +184,15 @@ export interface MessageData {
     readonly foo: string;
     readonly n: DataType.u8;
   };
+  [Message.Packed]: DataType.Packed<{
+    boolean1: boolean;
+    boolean2: boolean;
+    boolean3: boolean;
+    boolean4: boolean;
+    boolean5: boolean;
+    boolean6: boolean;
+    boolean7: boolean;
+    boolean8: boolean;
+  }>;
 }
 ```

package/out/builtin-middlewares.d.ts

@@ -1,7 +1,16 @@
 import { Modding } from "@flamework/core";
+import type { SerializerMetadata } from "@rbxts/flamework-binary-serializer";
 import { type SharedMiddleware } from "./middleware";
-type Guard<T> = (value: unknown) => value is T;
+import type { TetherPacket } from "./structs";
+import { Any } from "ts-toolbelt";
 export declare namespace BuiltinMiddlewares {
+    /**
+     * Creates a shared middleware that will simulate a ping of the given amount when a message is sent
+     *
+     * @param pingInMs The amount of time in milliseconds that the middleware should wait
+     * @returns A shared middleware that will simulate a ping
+     */
+    function simulatePing(pingInMs: number): SharedMiddleware;
     /**
      * Creates a shared middleware that will drop any message that occurs within the given interval of the previous message
      *
@@ -10,15 +19,17 @@ export declare namespace BuiltinMiddlewares {
      */
     function rateLimit(interval: number): SharedMiddleware;
     /**
-     * Creates a shared middleware that validates the data with the given guard (or a generated guard if none was provided)
-     *
-     * If the guard fails, the middleware will drop the message
+     * Creates a shared middleware that will log a message whenever a message is sent, containing the following information:
+     * - The message kind
+     * - The data associated with the message
+     * - The raw data (buffer and blobs) associated with the message
+     * - The size of the packet (in bytes)
+     * - The size of the buffer (in bytes)
+     * - The size of the blobs (in bytes)
+     * - The schema string associated with the message (if it can be deduced)
      *
-     * @param guard The guard to use to validate the data.
-     * @returns A shared middleware that validates the data with the given guard.
+     * @returns A shared middleware that will log a message whenever a message is sent.
      * @metadata macro
      */
-    function validate<T>(guard?: Guard<T> | Modding.Generic<T, "guard">): SharedMiddleware;
-    function debug(): SharedMiddleware;
+    function debug<T>(schema?: Modding.Many<Any.Equals<T, unknown> extends 1 ? undefined : SerializerMetadata<TetherPacket<T>>>): SharedMiddleware<T>;
 }
-export {};

package/out/builtin-middlewares.luau

@@ -1,20 +1,29 @@
 -- Compiled with roblox-ts v3.0.0
 local TS = _G[script]
-local DropRequest = TS.import(script, script.Parent, "middleware").DropRequest
 local RunService = TS.import(script, TS.getModule(script, "@rbxts", "services")).RunService
-local noOp = function()
-	return function() end
-end
-local validationGuardGenerationFailed = function()
-	return `[@rbxts/tether]: Failed to generate guard for validate<T>() builtin middleware - skipping validation`
-end
-local guardFailed = function(message)
-	return `[@rbxts/tether]: Type validation guard failed for message '{tostring(message)}' - check your sent data`
-end
+local repr = TS.import(script, TS.getModule(script, "@rbxts", "repr").out)
+local DropRequest = TS.import(script, script.Parent, "middleware").DropRequest
 local BLOB_SIZE = 5
 local BuiltinMiddlewares = {}
 do
 	local _container = BuiltinMiddlewares
+	--[[
+		*
+		     * Creates a shared middleware that will simulate a ping of the given amount when a message is sent
+		     *
+		     * @param pingInMs The amount of time in milliseconds that the middleware should wait
+		     * @returns A shared middleware that will simulate a ping
+		     
+	]]
+	local function simulatePing(pingInMs)
+		return function()
+			return function()
+				task.wait(pingInMs / 1000)
+				return nil
+			end
+		end
+	end
+	_container.simulatePing = simulatePing
 	--[[
 		*
 		     * Creates a shared middleware that will drop any message that occurs within the given interval of the previous message
@@ -35,34 +44,7 @@ do
 		end
 	end
 	_container.rateLimit = rateLimit
-	--[[
-		*
-		     * Creates a shared middleware that validates the data with the given guard (or a generated guard if none was provided)
-		     *
-		     * If the guard fails, the middleware will drop the message
-		     *
-		     * @param guard The guard to use to validate the data.
-		     * @returns A shared middleware that validates the data with the given guard.
-		     * @metadata macro
-		     
-	]]
-	local function validate(guard)
-		if guard == nil then
-			warn(validationGuardGenerationFailed())
-			return noOp
-		end
-		return function(message)
-			return function(data)
-				if guard(data) then
-					return nil
-				end
-				warn(guardFailed(message))
-				return DropRequest
-			end
-		end
-	end
-	_container.validate = validate
-	local function toStringBuffer(buf)
+	local function bufferToString(buf)
 		local s = { "{ " }
 		do
 			local i = 0
@@ -87,24 +69,42 @@ do
 		table.insert(s, " }")
 		return table.concat(s, "")
 	end
-	local line = "------------------------------------"
-	local function debug()
+	local horizontalLine = "------------------------------------"
+	--[[
+		*
+		     * Creates a shared middleware that will log a message whenever a message is sent, containing the following information:
+		     * - The message kind
+		     * - The data associated with the message
+		     * - The raw data (buffer and blobs) associated with the message
+		     * - The size of the packet (in bytes)
+		     * - The size of the buffer (in bytes)
+		     * - The size of the blobs (in bytes)
+		     * - The schema string associated with the message (if it can be deduced)
+		     *
+		     * @returns A shared middleware that will log a message whenever a message is sent.
+		     * @metadata macro
+		     
+	]]
+	local function debug(schema)
 		return function(message)
 			return function(data, _, getRawData)
 				local rawData = getRawData()
 				local bufferSize = buffer.len(rawData.buffer)
 				local blobsSize = #rawData.blobs * BLOB_SIZE
-				print(line)
-				print("Packet sent to", (if RunService:IsServer() then "client" else "server") .. "!")
-				print(" - Message:", message)
-				print(" - Data:", data)
-				print(" - Raw data:")
-				print("   - Buffer:", toStringBuffer(rawData.buffer))
-				print("   - Blobs:", rawData.blobs)
-				print(" - Packet size:", bufferSize + blobsSize, "bytes")
-				print("   - Buffer:", bufferSize, "bytes")
-				print("   - Blobs:", blobsSize, "bytes")
-				print(line)
+				local schemaString = if schema ~= nil then " " .. table.concat(string.split(repr(schema[2], {
+					pretty = true,
+				}), "\n"), "\n ") else "unknown"
+				local text = { "\n", horizontalLine, "\n", "Packet sent to ", (if RunService:IsServer() then "client" else "server"), "!\n", " - Message: ", message, "\n", " - Data: ", if data == nil then "undefined" else data, "\n", " - Raw data:\n", "   - Buffer: ", bufferToString(rawData.buffer), "\n", "   - Blobs: ", repr(rawData.blobs, {
+					pretty = false,
+					robloxClassName = true,
+				}), "\n", " - Packet size: ", bufferSize + blobsSize, " bytes\n", "   - Buffer: ", bufferSize, " bytes\n", "   - Blobs: ", blobsSize, " bytes\n", " - Schema: ", schemaString, "\n", horizontalLine, "\n" }
+				-- ▼ ReadonlyArray.join ▼
+				local _result = table.create(#text)
+				for _k, _v in text do
+					_result[_k] = tostring(_v)
+				end
+				-- ▲ ReadonlyArray.join ▲
+				print(table.concat(_result, ""))
 			end
 		end
 	end

package/out/message-emitter.d.ts

@@ -1,54 +1,103 @@
 import { Modding } from "@flamework/core";
-import { type SerializerMetadata } from "@rbxts/flamework-binary-serializer";
 import Destroyable from "@rbxts/destroyable";
 import { MiddlewareProvider } from "./middleware";
-import type { TetherPacket, ClientMessageCallback, ServerMessageCallback, BaseMessage } from "./structs";
+import type { ClientMessageCallback, ServerMessageCallback, BaseMessage, MessageEmitterMetadata, ClientMessageFunctionCallback, ServerMessageFunctionCallback } from "./structs";
 export declare class MessageEmitter<MessageData> extends Destroyable {
     readonly middleware: MiddlewareProvider<MessageData>;
     private readonly clientCallbacks;
+    private readonly clientFunctions;
     private readonly serverCallbacks;
+    private readonly serverFunctions;
+    private readonly guards;
     private serializers;
     private serverEvents;
     private clientEvents;
     /** @metadata macro */
-    static create<MessageData>(metaForEachMessage?: Modding.Many<{
-        [Kind in keyof MessageData]: MessageData[Kind] extends undefined ? undefined : Modding.Many<SerializerMetadata<TetherPacket<MessageData[Kind]>>>;
-    }>): MessageEmitter<MessageData>;
+    static create<MessageData>(meta?: Modding.Many<MessageEmitterMetadata<MessageData>>): MessageEmitter<MessageData>;
     private constructor();
-    /**.
-     * @returns A destructor function that disconnects the callback from the message
-     */
-    onServerMessage<Kind extends keyof MessageData>(message: Kind & BaseMessage, callback: ServerMessageCallback<MessageData[Kind]>): () => void;
-    /**.
-     * @returns A destructor function that disconnects the callback from the message
-     */
-    onClientMessage<Kind extends keyof MessageData>(message: Kind & BaseMessage, callback: ClientMessageCallback<MessageData[Kind]>): () => 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
-     */
-    emitServer<Kind extends keyof MessageData>(message: Kind & BaseMessage, data?: MessageData[Kind], unreliable?: boolean): void;
-    /**
-     * Emits a message to a specific client
-     *
-     * @param player The player 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
-     */
-    emitClient<Kind extends keyof MessageData>(player: Player | Player[], message: Kind & BaseMessage, data?: MessageData[Kind], 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
-     */
-    emitAllClients<Kind extends keyof MessageData>(message: Kind & BaseMessage, data?: MessageData[Kind], unreliable?: boolean): void;
+    readonly server: {
+        /**
+         * @returns A destructor function that disconnects the callback from the message
+         */
+        on: <Kind extends keyof MessageData>(message: Kind & BaseMessage, callback: ServerMessageCallback<MessageData[Kind]>) => () => void;
+        /**
+         * 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: <Kind extends keyof MessageData>(message: Kind & BaseMessage, callback: ServerMessageCallback<MessageData[Kind]>) => () => 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: <Kind extends keyof MessageData>(message: Kind & BaseMessage, data?: MessageData[Kind], unreliable?: boolean) => void;
+        /**
+         * Simulates a remote function invocation.
+         *
+         * @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
+         */
+        invoke: <Kind extends keyof MessageData, ReturnKind extends keyof MessageData>(message: Kind & BaseMessage, returnMessage: ReturnKind & BaseMessage, data?: MessageData[Kind], unreliable?: boolean) => Promise<MessageData[ReturnKind]>;
+        /**
+         * Sets a callback for a simulated remote function
+         *
+         * @returns A destructor function that disconnects the callback from the message
+         */
+        setCallback: <Kind extends keyof MessageData, ReturnKind extends keyof MessageData>(message: Kind & BaseMessage, returnMessage: ReturnKind & BaseMessage, callback: ServerMessageFunctionCallback<MessageData[Kind], MessageData[ReturnKind]>) => () => void;
+    };
+    readonly client: {
+        /**
+         * @returns A destructor function that disconnects the callback from the message
+         */
+        on: <Kind extends keyof MessageData>(message: Kind & BaseMessage, callback: ClientMessageCallback<MessageData[Kind]>) => () => void;
+        /**
+         * 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: <Kind extends keyof MessageData>(message: Kind & BaseMessage, callback: ClientMessageCallback<MessageData[Kind]>) => () => void;
+        /**
+         * Emits a message to a specific client
+         *
+         * @param player The player 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: <Kind extends keyof MessageData>(player: Player | Player[], message: Kind & BaseMessage, data?: MessageData[Kind], 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: <Kind extends keyof MessageData>(message: Kind & BaseMessage, data?: MessageData[Kind], unreliable?: boolean) => void;
+        /**
+         * Simulates a remote function invocation.
+         *
+         * @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
+         */
+        invoke: <Kind extends keyof MessageData, ReturnKind extends keyof MessageData>(message: Kind & BaseMessage, returnMessage: ReturnKind & BaseMessage, player: Player, data?: MessageData[Kind], unreliable?: boolean) => Promise<MessageData[ReturnKind]>;
+        /**
+         * Sets a callback for a simulated remote function
+         *
+         * @returns A destructor function that disconnects the callback from the message
+         */
+        setCallback: <Kind extends keyof MessageData, ReturnKind extends keyof MessageData>(message: Kind & BaseMessage, returnMessage: ReturnKind & BaseMessage, callback: ClientMessageFunctionCallback<MessageData[Kind], MessageData[ReturnKind]>) => () => void;
+    };
+    private validateData;
     private initialize;
+    private readMessageFromPacket;
+    private executeFunctions;
+    private executeEventCallbacks;
+    private once;
     private on;
     private getPacket;
     /** @metadata macro */

package/out/message-emitter.luau

@@ -10,7 +10,12 @@ local Destroyable = TS.import(script, TS.getModule(script, "@rbxts", "destroyabl
 local _middleware = TS.import(script, script.Parent, "middleware")
 local DropRequest = _middleware.DropRequest
 local MiddlewareProvider = _middleware.MiddlewareProvider
-local GlobalEvents = Networking.createEvent("@rbxts/tether:message-emitter@GlobalEvents")
+-- TODO: error when trying to do something like server.emit() from the server
+local remotes = Networking.createEvent("@rbxts/tether:message-emitter@remotes")
+local metaGenerationFailed = "[@rbxts/tether]: Failed to generate message metadata - make sure you are using Flamework macro-friendly types in your schemas"
+local guardFailed = function(message)
+	return `[@rbxts/tether]: Type validation guard failed for message '{message}' - check your sent data`
+end
 local MessageEmitter
 do
 	local super = Destroyable
@@ -29,8 +34,213 @@ do
 		super.constructor(self)
 		self.middleware = MiddlewareProvider.new()
 		self.clientCallbacks = {}
+		self.clientFunctions = {}
 		self.serverCallbacks = {}
+		self.serverFunctions = {}
+		self.guards = {}
 		self.serializers = {}
+		self.server = {
+			on = function(message, callback)
+				return self:on(message, callback, self.serverCallbacks)
+			end,
+			once = function(message, callback)
+				return self:once(message, callback, self.serverCallbacks)
+			end,
+			emit = function(message, data, unreliable)
+				if unreliable == nil then
+					unreliable = false
+				end
+				local updateData = function(newData)
+					data = newData
+					return nil
+				end
+				local getPacket = function()
+					return self:getPacket(message, data)
+				end
+				if not self:validateData(message, data) then
+					return nil
+				end
+				task.spawn(function()
+					for _, globalMiddleware in self.middleware:getServerGlobal() do
+						if not self:validateData(message, data) then
+							return nil
+						end
+						local result = globalMiddleware(message)(data, updateData, getPacket)
+						if result == DropRequest then
+							return nil
+						end
+					end
+					for _, middleware in self.middleware:getServer(message) do
+						if not self:validateData(message, data) then
+							return nil
+						end
+						local result = middleware(message)(data, updateData, getPacket)
+						if result == DropRequest then
+							return nil
+						end
+					end
+					if not self:validateData(message, data) then
+						return nil
+					end
+					local send = if unreliable then self.clientEvents.sendUnreliableServerMessage else self.clientEvents.sendServerMessage
+					send(getPacket())
+				end)
+			end,
+			invoke = TS.async(function(message, returnMessage, data, unreliable)
+				if unreliable == nil then
+					unreliable = false
+				end
+				local _clientFunctions = self.clientFunctions
+				local _returnMessage = returnMessage
+				if not (_clientFunctions[_returnMessage] ~= nil) then
+					local _clientFunctions_1 = self.clientFunctions
+					local _returnMessage_1 = returnMessage
+					_clientFunctions_1[_returnMessage_1] = {}
+				end
+				local _clientFunctions_1 = self.clientFunctions
+				local _returnMessage_1 = returnMessage
+				local functions = _clientFunctions_1[_returnMessage_1]
+				local returnValue
+				functions[function(data)
+					returnValue = data
+					return returnValue
+				end] = true
+				self.server.emit(message, data, unreliable)
+				while returnValue == nil do
+					RunService.Heartbeat:Wait()
+				end
+				return returnValue
+			end),
+			setCallback = function(message, returnMessage, callback)
+				return self.server.on(message, function(player, data)
+					local returnValue = callback(player, data)
+					self.client.emit(player, returnMessage, returnValue)
+				end)
+			end,
+		}
+		self.client = {
+			on = function(message, callback)
+				return self:on(message, callback, self.clientCallbacks)
+			end,
+			once = function(message, callback)
+				return self:once(message, callback, self.clientCallbacks)
+			end,
+			emit = function(player, message, data, unreliable)
+				if unreliable == nil then
+					unreliable = false
+				end
+				local updateData = function(newData)
+					data = newData
+					return nil
+				end
+				local getPacket = function()
+					return self:getPacket(message, data)
+				end
+				if not self:validateData(message, data) then
+					return nil
+				end
+				task.spawn(function()
+					for _, globalMiddleware in self.middleware:getClientGlobal() do
+						if not self:validateData(message, data) then
+							return nil
+						end
+						local result = globalMiddleware(message)(player, data, updateData, getPacket)
+						if result == DropRequest then
+							return nil
+						end
+					end
+					for _, middleware in self.middleware:getClient(message) do
+						if not self:validateData(message, data) then
+							return nil
+						end
+						local result = middleware(message)(player, data, updateData, getPacket)
+						if result == DropRequest then
+							return nil
+						end
+					end
+					if not self:validateData(message, data) then
+						return nil
+					end
+					local send = if unreliable then self.serverEvents.sendUnreliableClientMessage else self.serverEvents.sendClientMessage
+					send(player, getPacket())
+				end)
+			end,
+			emitAll = function(message, data, unreliable)
+				if unreliable == nil then
+					unreliable = false
+				end
+				local updateData = function(newData)
+					data = newData
+					return nil
+				end
+				local getPacket = function()
+					return self:getPacket(message, data)
+				end
+				if not self:validateData(message, data) then
+					return nil
+				end
+				task.spawn(function()
+					for _, globalMiddleware in self.middleware:getClientGlobal() do
+						for _1, player in Players:GetPlayers() do
+							if not self:validateData(message, data) then
+								return nil
+							end
+							local result = globalMiddleware(message)(player, data, updateData, getPacket)
+							if result == DropRequest then
+								return nil
+							end
+						end
+					end
+					for _, middleware in self.middleware:getClient(message) do
+						for _1, player in Players:GetPlayers() do
+							if not self:validateData(message, data) then
+								return nil
+							end
+							local result = middleware(message)(player, data, updateData, getPacket)
+							if result == DropRequest then
+								return nil
+							end
+						end
+					end
+					if not self:validateData(message, data) then
+						return nil
+					end
+					local send = if unreliable then self.serverEvents.sendUnreliableClientMessage else self.serverEvents.sendClientMessage
+					send:broadcast(getPacket())
+				end)
+			end,
+			invoke = TS.async(function(message, returnMessage, player, data, unreliable)
+				if unreliable == nil then
+					unreliable = false
+				end
+				local _serverFunctions = self.serverFunctions
+				local _returnMessage = returnMessage
+				if not (_serverFunctions[_returnMessage] ~= nil) then
+					local _serverFunctions_1 = self.serverFunctions
+					local _returnMessage_1 = returnMessage
+					_serverFunctions_1[_returnMessage_1] = {}
+				end
+				local _serverFunctions_1 = self.serverFunctions
+				local _returnMessage_1 = returnMessage
+				local functions = _serverFunctions_1[_returnMessage_1]
+				local returnValue
+				functions[function(data)
+					returnValue = data
+					return returnValue
+				end] = true
+				self.client.emit(player, message, data, unreliable)
+				while returnValue == nil do
+					RunService.Heartbeat:Wait()
+				end
+				return returnValue
+			end),
+			setCallback = function(message, returnMessage, callback)
+				return self.client.on(message, function(data)
+					local returnValue = callback(data)
+					self.server.emit(returnMessage, returnValue)
+				end)
+			end,
+		}
 		self.janitor:Add(function()
 			table.clear(self.clientCallbacks)
 			table.clear(self.serverCallbacks)
@@ -39,7 +249,7 @@ do
 			self.clientEvents = nil
 		end)
 		if RunService:IsServer() then
-			self.serverEvents = GlobalEvents:createServer({}, {
+			self.serverEvents = remotes:createServer({}, {
 				incomingIds = { "sendServerMessage", "sendUnreliableServerMessage" },
 				incoming = {
 					sendServerMessage = { { t.interface({
@@ -62,7 +272,7 @@ do
 				namespaces = {},
 			})
 		else
-			self.clientEvents = GlobalEvents:createClient({}, {
+			self.clientEvents = remotes:createClient({}, {
 				incomingIds = { "sendClientMessage", "sendUnreliableClientMessage" },
 				incoming = {
 					sendClientMessage = { { t.interface({
@@ -86,180 +296,130 @@ do
 			})
 		end
 	end
-	function MessageEmitter:create(metaForEachMessage)
+	function MessageEmitter:create(meta)
 		local emitter = MessageEmitter.new()
-		if metaForEachMessage == nil then
-			warn("[@rbxts/tether]: Failed to generate serializer metadata for MessageEmitter")
+		if meta == nil then
+			warn(metaGenerationFailed)
 			return emitter:initialize()
 		end
-		for kind, meta in pairs(metaForEachMessage) do
-			if meta == nil then
+		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:addSerializer(tonumber(kind), meta)
+			emitter:addSerializer(numberKind, serializerMetadata)
 		end
 		return emitter:initialize()
 	end
-	function MessageEmitter:onServerMessage(message, callback)
-		return self:on(message, callback)
-	end
-	function MessageEmitter:onClientMessage(message, callback)
-		return self:on(message, callback)
-	end
-	function MessageEmitter:emitServer(message, data, unreliable)
-		if unreliable == nil then
-			unreliable = false
-		end
-		local updateData = function(newData)
-			data = newData
-			return nil
-		end
-		local getPacket = function()
-			return self:getPacket(message, data)
-		end
-		for _, globalMiddleware in self.middleware:getServerGlobal() do
-			local result = globalMiddleware(message)(data, updateData, getPacket)
-			if result == DropRequest then
-				return nil
-			end
-		end
-		for _, middleware in self.middleware:getServer(message) do
-			local result = middleware(message)(data, updateData, getPacket)
-			if result == DropRequest then
-				return nil
-			end
+	function MessageEmitter:validateData(message, data)
+		local _guards = self.guards
+		local _message = message
+		local guard = _guards[_message]
+		local guardPassed = guard(data)
+		if not guardPassed then
+			warn(guardFailed(message))
 		end
-		local send = if unreliable then self.clientEvents.sendUnreliableServerMessage else self.clientEvents.sendServerMessage
-		send(getPacket())
+		return guardPassed
 	end
-	function MessageEmitter:emitClient(player, message, data, unreliable)
-		if unreliable == nil then
-			unreliable = false
+	function MessageEmitter:initialize()
+		if RunService:IsClient() then
+			self.janitor:Add(self.clientEvents.sendClientMessage:connect(function(serializedPacket)
+				local sentMessage = self:readMessageFromPacket(serializedPacket)
+				self:executeEventCallbacks(sentMessage, serializedPacket)
+				self:executeFunctions(sentMessage, serializedPacket)
+			end))
+		else
+			self.janitor:Add(self.serverEvents.sendServerMessage:connect(function(player, serializedPacket)
+				local sentMessage = self:readMessageFromPacket(serializedPacket)
+				self:executeEventCallbacks(sentMessage, serializedPacket, player)
+				self:executeFunctions(sentMessage, serializedPacket)
+			end))
 		end
-		local updateData = function(newData)
-			data = newData
+		return self
+	end
+	function MessageEmitter:readMessageFromPacket(serializedPacket)
+		return buffer.readu8(serializedPacket.buffer, 0)
+	end
+	function MessageEmitter:executeFunctions(message, serializedPacket)
+		local isServer = RunService:IsServer()
+		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 getPacket = function()
-			return self:getPacket(message, data)
-		end
-		for _, globalMiddleware in self.middleware:getClientGlobal() do
-			local result = globalMiddleware(message)(player, data, updateData, getPacket)
-			if result == DropRequest then
-				return nil
-			end
+		local serializer = self:getSerializer(message)
+		local _packet = serializer
+		if _packet ~= nil then
+			_packet = _packet.deserialize(serializedPacket.buffer, serializedPacket.blobs)
 		end
-		for _, middleware in self.middleware:getClient(message) do
-			local result = middleware(message)(player, data, updateData, getPacket)
-			if result == DropRequest then
-				return nil
+		local packet = _packet
+		for callback in functions do
+			local _result = packet
+			if _result ~= nil then
+				_result = _result.data
 			end
+			callback(_result)
 		end
-		local send = if unreliable then self.serverEvents.sendUnreliableClientMessage else self.serverEvents.sendClientMessage
-		send(player, getPacket())
 	end
-	function MessageEmitter:emitAllClients(message, data, unreliable)
-		if unreliable == nil then
-			unreliable = false
-		end
-		local updateData = function(newData)
-			data = newData
+	function MessageEmitter:executeEventCallbacks(message, serializedPacket, player)
+		local isServer = RunService:IsServer()
+		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 getPacket = function()
-			return self:getPacket(message, data)
+		local serializer = self:getSerializer(message)
+		local _packet = serializer
+		if _packet ~= nil then
+			_packet = _packet.deserialize(serializedPacket.buffer, serializedPacket.blobs)
 		end
-		for _, globalMiddleware in self.middleware:getClientGlobal() do
-			for _1, player in Players:GetPlayers() do
-				local result = globalMiddleware(message)(player, data, updateData, getPacket)
-				if result == DropRequest then
-					return nil
+		local packet = _packet
+		for callback in callbacks do
+			if isServer then
+				local _exp = player
+				local _result = packet
+				if _result ~= nil then
+					_result = _result.data
 				end
-			end
-		end
-		for _, middleware in self.middleware:getClient(message) do
-			for _1, player in Players:GetPlayers() do
-				local result = middleware(message)(player, data, updateData, getPacket)
-				if result == DropRequest then
-					return nil
+				callback(_exp, _result)
+			else
+				local _result = packet
+				if _result ~= nil then
+					_result = _result.data
 				end
+				callback(_result)
 			end
 		end
-		local send = if unreliable then self.serverEvents.sendUnreliableClientMessage else self.serverEvents.sendClientMessage
-		send:broadcast(self:getPacket(message, data))
 	end
-	function MessageEmitter:initialize()
-		if RunService:IsClient() then
-			self.janitor:Add(self.clientEvents.sendClientMessage:connect(function(serializedPacket)
-				local sentMessage = buffer.readu8(serializedPacket.buffer, 0)
-				local messageCallbacks = self.clientCallbacks[sentMessage] or {}
-				-- ▼ ReadonlySet.size ▼
-				local _size = 0
-				for _ in messageCallbacks do
-					_size += 1
-				end
-				-- ▲ ReadonlySet.size ▲
-				if _size == 0 then
-					return nil
-				end
-				local serializer = self:getSerializer(sentMessage)
-				local _packet = serializer
-				if _packet ~= nil then
-					_packet = _packet.deserialize(serializedPacket.buffer, serializedPacket.blobs)
-				end
-				local packet = _packet
-				for callback in messageCallbacks do
-					local _result = packet
-					if _result ~= nil then
-						_result = _result.data
-					end
-					callback(_result)
-				end
-			end))
-		else
-			self.janitor:Add(self.serverEvents.sendServerMessage:connect(function(player, serializedPacket)
-				local sentMessage = buffer.readu8(serializedPacket.buffer, 0)
-				local messageCallbacks = self.serverCallbacks[sentMessage] or {}
-				-- ▼ ReadonlySet.size ▼
-				local _size = 0
-				for _ in messageCallbacks do
-					_size += 1
-				end
-				-- ▲ ReadonlySet.size ▲
-				if _size == 0 then
-					return nil
-				end
-				local serializer = self:getSerializer(sentMessage)
-				local _packet = serializer
-				if _packet ~= nil then
-					_packet = _packet.deserialize(serializedPacket.buffer, serializedPacket.blobs)
-				end
-				local packet = _packet
-				for callback in messageCallbacks do
-					local _exp = player
-					local _result = packet
-					if _result ~= nil then
-						_result = _result.data
-					end
-					callback(_exp, _result)
-				end
-			end))
-		end
-		return self
+	function MessageEmitter:once(message, callback, callbacksMap)
+		local destructor
+		destructor = self:on(message, function(player, data)
+			destructor()
+			callback(player, data)
+		end, callbacksMap)
+		return destructor
 	end
-	function MessageEmitter:on(message, callback)
-		local callbacksMap = if RunService:IsServer() then self.serverCallbacks else self.clientCallbacks
+	function MessageEmitter:on(message, callback, callbacksMap)
+		local _callbacksMap = callbacksMap
 		local _message = message
-		if not (callbacksMap[_message] ~= nil) then
+		if not (_callbacksMap[_message] ~= nil) then
+			local _callbacksMap_1 = callbacksMap
 			local _message_1 = message
-			callbacksMap[_message_1] = {}
+			_callbacksMap_1[_message_1] = {}
 		end
+		local _callbacksMap_1 = callbacksMap
 		local _message_1 = message
-		local callbacks = callbacksMap[_message_1]
+		local callbacks = _callbacksMap_1[_message_1]
 		local _callback = callback
 		callbacks[_callback] = true
+		local _callbacksMap_2 = callbacksMap
 		local _message_2 = message
-		callbacksMap[_message_2] = callbacks
+		_callbacksMap_2[_message_2] = callbacks
 		return function()
 			local _callback_1 = callback
 			-- ▼ Set.delete ▼

package/out/middleware.d.ts

@@ -4,10 +4,15 @@ type DropRequestSymbol = symbol & {
 };
 export declare const DropRequest: DropRequestSymbol;
 type UpdateDataFn<T> = (newData: T) => void;
-export type ClientMiddleware<Data = unknown> = (message: BaseMessage) => (player: Player | Player[], data: Readonly<Data>, updateData: UpdateDataFn<Data>, getRawData: () => SerializedPacket) => DropRequestSymbol | void;
-export type ServerMiddleware<Data = unknown> = (message: BaseMessage) => (data: Readonly<Data>, updateData: UpdateDataFn<Data>, getRawData: () => SerializedPacket) => DropRequestSymbol | void;
-export type SharedMiddleware = (message: BaseMessage) => (data: unknown, updateData: UpdateDataFn<unknown>, getRawData: () => SerializedPacket) => DropRequestSymbol | void;
-export type Middleware<Data = unknown> = ServerMiddleware<Data> & ClientMiddleware<Data>;
+type GetRawDataFn = () => SerializedPacket;
+export type ClientMiddleware<Data = unknown> = {
+    _client?: void;
+} & ((message: BaseMessage) => (player: Player | Player[], data: Readonly<Data>, updateData: UpdateDataFn<Data>, getRawData: GetRawDataFn) => DropRequestSymbol | void);
+export type ServerMiddleware<Data = unknown> = SharedMiddleware<Data> & {
+    _server?: void;
+};
+export type SharedMiddleware<Data = unknown> = (message: BaseMessage) => (data: Readonly<Data>, updateData: UpdateDataFn<Data>, getRawData: GetRawDataFn) => DropRequestSymbol | void;
+export type Middleware<Data = unknown> = ServerMiddleware<Data> & ClientMiddleware<Data> & SharedMiddleware<Data>;
 export declare class MiddlewareProvider<MessageData> {
     private readonly clientGlobalMiddlewares;
     private readonly serverGlobalMiddlewares;
@@ -21,9 +26,9 @@ export declare class MiddlewareProvider<MessageData> {
     getClientGlobal<Data>(): ClientMiddleware<Data>[];
     /** @hidden */
     getServerGlobal<Data>(): ServerMiddleware<Data>[];
-    useClient<Kind extends keyof MessageData>(message: Kind & BaseMessage, middlewares: ClientMiddleware<MessageData[Kind]> | readonly ClientMiddleware<MessageData[Kind]>[], order?: number): this;
-    useServer<Kind extends keyof MessageData>(message: Kind & BaseMessage, middlewares: ServerMiddleware<MessageData[Kind]> | readonly ServerMiddleware<MessageData[Kind]>[], order?: number): this;
-    useShared<Kind extends keyof MessageData>(message: Kind & BaseMessage, middlewares: SharedMiddleware | readonly SharedMiddleware[], order?: number): this;
+    useClient<Kind extends keyof MessageData>(message: Kind & BaseMessage, middlewares: ClientMiddleware<MessageData[Kind]> | readonly ClientMiddleware<MessageData[Kind]>[] | ClientMiddleware | readonly ClientMiddleware[], order?: number): this;
+    useServer<Kind extends keyof MessageData>(message: Kind & BaseMessage, middlewares: ServerMiddleware<MessageData[Kind]> | readonly ServerMiddleware<MessageData[Kind]>[] | ServerMiddleware | readonly ServerMiddleware[], order?: number): this;
+    useShared<Kind extends keyof MessageData>(message: Kind & BaseMessage, middlewares: SharedMiddleware<MessageData[Kind]> | readonly SharedMiddleware<MessageData[Kind]>[] | SharedMiddleware | readonly SharedMiddleware[], order?: number): this;
     useClientGlobal(middlewares: ClientMiddleware | readonly ClientMiddleware[], order?: number): this;
     useServerGlobal(middlewares: ServerMiddleware | readonly ServerMiddleware[], order?: number): this;
     useSharedGlobal(middlewares: SharedMiddleware | readonly SharedMiddleware[], order?: number): this;

package/out/structs.d.ts

@@ -1,8 +1,11 @@
+import { Modding } from "@flamework/core";
 import type { Networking } from "@flamework/networking";
-import type { DataType } from "@rbxts/flamework-binary-serializer";
+import type { DataType, SerializerMetadata } from "@rbxts/flamework-binary-serializer";
 export type MessageCallback<T = unknown> = ServerMessageCallback<T> | ClientMessageCallback<T>;
 export type ClientMessageCallback<T = unknown> = (data: T) => void;
+export type ClientMessageFunctionCallback<T = unknown, R = unknown> = (data: T) => R;
 export type ServerMessageCallback<T = unknown> = (player: Player, data: T) => void;
+export type ServerMessageFunctionCallback<T = unknown, R = unknown> = (player: Player, data: T) => R;
 export type BaseMessage = number;
 export interface SerializedPacket {
     readonly buffer: buffer;
@@ -22,3 +25,11 @@ export interface ClientEvents {
     sendClientMessage: MessageEvent;
     sendUnreliableClientMessage: UnreliableMessageEvent;
 }
+export interface MessageMetadata<MessageData, Kind extends keyof MessageData> {
+    readonly guard: Modding.Generic<MessageData[Kind], "guard">;
+    readonly serializerMetadata: MessageData[Kind] extends undefined ? undefined : Modding.Many<SerializerMetadata<TetherPacket<MessageData[Kind]>>>;
+}
+export type Guard<T = unknown> = (value: unknown) => value is T;
+export type MessageEmitterMetadata<MessageData> = {
+    [Kind in keyof MessageData]: MessageMetadata<MessageData, Kind>;
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rbxts/tether",
-  "version": "1.1.6",
+  "version": "1.2.0",
   "main": "out/init.lua",
   "scripts": {
     "build": "rbxtsc",
@@ -20,7 +20,7 @@
   },
   "author": "runicly",
   "license": "ISC",
-  "description": "A message-based networking solution for Roblox with automatic binary serialization",
+  "description": "A message-based networking solution for Roblox with automatic binary serialization and type validation",
   "types": "out/index.d.ts",
   "files": [
     "out",
@@ -43,6 +43,7 @@
     "@rbxts/destroyable": "^1.0.1",
     "@rbxts/flamework-binary-serializer": "^0.6.0",
     "@rbxts/flamework-meta-utils": "^1.0.4",
+    "@rbxts/repr": "^1.0.1",
     "@rbxts/services": "^1.5.5"
   }
 }