@rbxts/tether 1.2.0 → 1.2.2

package/README.md

@@ -1,198 +1,197 @@
-# Tether
-A message-based networking solution for Roblox with automatic binary serialization and type validation.
-
-> [!CAUTION]
-> Depends on `rbxts-transformer-flamework`!
-
-## Usage
-
-### 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 {
-  Test,
-  Packed
-}
-
-export interface MessageData {
-  [Message.Test]: {
-    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;
-  }>;
-}
-```
-
-> [!CAUTION]
-> Every single message kind must implement an interface for it's data (in the example that would be the object with the `foo` and `bar` fields). Message serialization (as well as your message itself) will not work if you don't do this.
-
-### Server
-```ts
-import { Message, messaging } from "shared/messaging";
-
-messaging.server.on(Message.Test, (player, data) => {
-  print(player, "sent data:", data);
-});
-```
-
-### Client
-```ts
-import { Message, messaging } from "shared/messaging";
-
-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
-
-### Creating middleware
-
-**Note:** These client/server middlewares can be implemented as shared middlewares. This is strictly an example.
-#### Client
-```ts
-import type { ClientMiddleware } from "@rbxts/tether";
-
-export function logClient(): ClientMiddleware {
-  return message => (player, data) => print(`[LOG]: Sent message '${message}' to player ${player} with data:`, data);
-}
-```
-
-#### Server
-```ts
-import type { ServerMiddleware } from "@rbxts/tether";
-
-export function logServer(): ServerMiddleware {
-  return message => data => print(`[LOG]: Sent message '${message}' to server with data:`, data);
-}
-```
-
-#### Shared
-```ts
-import { type SharedMiddleware, DropRequest } from "@rbxts/tether";
-
-export function rateLimit(interval: number): SharedMiddleware {
-  let lastRequest = 0;
-
-  return message => // message attempting to be sent
-    () => { // no data/player - it's a shared middleware
-      if (os.clock() - lastRequest < interval)
-        return DropRequest;
-
-      lastRequest = os.clock();
-    };
-}
-```
-
-#### Transforming data
-```ts
-import type { ServerMiddleware } from "@rbxts/tether";
-
-export function incrementNumberData(): ServerMiddleware<number> {
-  // sets the data to be used by the any subsequent middlewares as well as sent through the remote
-  return () => (data, updateData) => updateData(data + 1);
-}
-```
-
-### Using middleware
-```ts
-import type { DataType } from "@rbxts/flamework-binary-serializer";
-import { MessageEmitter, BuiltinMiddlewares } from "@rbxts/tether";
-
-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)) 
-  .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
-
-export const enum Message {
-  Test,
-  Packed
-}
-
-export interface MessageData {
-  [Message.Test]: {
-    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;
-  }>;
-}
+# Tether
+A message-based networking solution for Roblox with automatic binary serialization and type validation.
+
+> [!CAUTION]
+> Depends on `rbxts-transformer-flamework`!
+
+## Usage
+
+### 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 {
+  Test,
+  Packed
+}
+
+export interface MessageData {
+  [Message.Test]: {
+    readonly foo: string;
+    readonly n: DataType.u8;
+  };
+  [Message.Packed]: DataType.Packed<{
+    readonly boolean1: boolean;
+    readonly boolean2: boolean;
+    readonly boolean3: boolean;
+    readonly boolean4: boolean;
+    readonly boolean5: boolean;
+    readonly boolean6: boolean;
+    readonly boolean7: boolean;
+    readonly boolean8: boolean;
+  }>;
+}
+```
+
+> [!CAUTION]
+> Every single message kind must implement an interface for it's data (in the example that would be the object types in `MessageData`). Message serialization (as well as your message itself) will not work if you don't do this.
+
+### Server
+```ts
+import { Message, messaging } from "shared/messaging";
+
+messaging.server.on(Message.Test, (player, data) => print(player, "sent data:", data));
+```
+
+### Client
+```ts
+import { Message, messaging } from "shared/messaging";
+
+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
+
+### Creating middleware
+
+**Note:** These client/server middlewares can be implemented as shared middlewares. This is strictly an example.
+#### Client
+```ts
+import type { ClientMiddleware } from "@rbxts/tether";
+
+export function logClient(): ClientMiddleware {
+  return message => (player, ctx) => print(`[LOG]: Sent message '${message}' to player ${player} with data:`, ctx.data);
+}
+```
+
+#### Server
+```ts
+import type { ServerMiddleware } from "@rbxts/tether";
+
+export function logServer(): ServerMiddleware {
+  return message => ctx => print(`[LOG]: Sent message '${message}' to server with data:`, ctx.data);
+}
+```
+
+#### Shared
+```ts
+import { type SharedMiddleware, DropRequest } from "@rbxts/tether";
+
+export function rateLimit(interval: number): SharedMiddleware {
+  let lastRequest = 0;
+
+  return message => // message attempting to be sent
+    () => { // no data/player - it's a shared middleware
+      if (os.clock() - lastRequest < interval)
+        return DropRequest;
+
+      lastRequest = os.clock();
+    };
+}
+```
+
+#### Transforming data
+```ts
+import type { ServerMiddleware } from "@rbxts/tether";
+
+export function incrementNumberData(): ServerMiddleware<number> {
+  // sets the data to be used by the any subsequent middlewares as well as sent through the remote
+  return () => ({ data, updateData }) => updateData(data + 1);
+}
+```
+
+### Using middleware
+```ts
+import type { DataType } from "@rbxts/flamework-binary-serializer";
+import { MessageEmitter, BuiltinMiddlewares } from "@rbxts/tether";
+
+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)) 
+  // will be just one byte!
+  .useShared(Message.Packed, () => ctx => print("Packed object size:", buffer.len(ctx.getRawData().buffer)));
+  // 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
+
+export const enum Message {
+  Test,
+  Packed
+}
+
+export interface MessageData {
+  [Message.Test]: {
+    readonly foo: string;
+    readonly n: DataType.u8;
+  };
+  [Message.Packed]: DataType.Packed<{
+    readonly boolean1: boolean;
+    readonly boolean2: boolean;
+    readonly boolean3: boolean;
+    readonly boolean4: boolean;
+    readonly boolean5: boolean;
+    readonly boolean6: boolean;
+    readonly boolean7: boolean;
+    readonly boolean8: boolean;
+  }>;
+}
 ```

package/out/builtin-middlewares.d.ts

@@ -1,8 +1,8 @@
 import { Modding } from "@flamework/core";
 import type { SerializerMetadata } from "@rbxts/flamework-binary-serializer";
+import type { Any } from "ts-toolbelt";
 import { type SharedMiddleware } from "./middleware";
 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
@@ -11,6 +11,14 @@ export declare namespace BuiltinMiddlewares {
      * @returns A shared middleware that will simulate a ping
      */
     function simulatePing(pingInMs: number): SharedMiddleware;
+    /**
+     * Creates a shared middleware that will check if a message packet exceeds the given maximum size in bytes
+     *
+     * @param maxBytes The maximum size of the packet in bytes
+     * @param throwError Whether the middleware should throw an error if the packet exceeds the maximum size, or simply drop the request
+     * @returns A shared middleware that will check if a message packet exceeds the given maximum size
+     */
+    function maxPacketSize(maxBytes: number, throwError?: boolean): SharedMiddleware;
     /**
      * Creates a shared middleware that will drop any message that occurs within the given interval of the previous message
      *

package/out/builtin-middlewares.luau

@@ -24,6 +24,30 @@ do
 		end
 	end
 	_container.simulatePing = simulatePing
+	--[[
+		*
+		     * Creates a shared middleware that will check if a message packet exceeds the given maximum size in bytes
+		     *
+		     * @param maxBytes The maximum size of the packet in bytes
+		     * @param throwError Whether the middleware should throw an error if the packet exceeds the maximum size, or simply drop the request
+		     * @returns A shared middleware that will check if a message packet exceeds the given maximum size
+		     
+	]]
+	local function maxPacketSize(maxBytes, throwError)
+		if throwError == nil then
+			throwError = true
+		end
+		return function(message)
+			return function(ctx)
+				local rawData = ctx.getRawData()
+				local totalSize = buffer.len(rawData.buffer) + #rawData.blobs * BLOB_SIZE
+				if totalSize > maxBytes then
+					return if throwError then error(`[@rbxts/tether]: Message '{message}' exceeded maximum packet size of {maxBytes} bytes`) else DropRequest
+				end
+			end
+		end
+	end
+	_container.maxPacketSize = maxPacketSize
 	--[[
 		*
 		     * Creates a shared middleware that will drop any message that occurs within the given interval of the previous message
@@ -87,7 +111,9 @@ do
 	]]
 	local function debug(schema)
 		return function(message)
-			return function(data, _, getRawData)
+			return function(_param)
+				local data = _param.data
+				local getRawData = _param.getRawData
 				local rawData = getRawData()
 				local bufferSize = buffer.len(rawData.buffer)
 				local blobsSize = #rawData.blobs * BLOB_SIZE

package/out/message-emitter.d.ts

@@ -9,7 +9,7 @@ export declare class MessageEmitter<MessageData> extends Destroyable {
     private readonly serverCallbacks;
     private readonly serverFunctions;
     private readonly guards;
-    private serializers;
+    private readonly serializers;
     private serverEvents;
     private clientEvents;
     /** @metadata macro */

package/out/message-emitter.luau

@@ -61,11 +61,16 @@ do
 					return nil
 				end
 				task.spawn(function()
+					local ctx = {
+						data = data,
+						updateData = updateData,
+						getRawData = getPacket,
+					}
 					for _, globalMiddleware in self.middleware:getServerGlobal() do
 						if not self:validateData(message, data) then
 							return nil
 						end
-						local result = globalMiddleware(message)(data, updateData, getPacket)
+						local result = globalMiddleware(message)(ctx)
 						if result == DropRequest then
 							return nil
 						end
@@ -74,7 +79,7 @@ do
 						if not self:validateData(message, data) then
 							return nil
 						end
-						local result = middleware(message)(data, updateData, getPacket)
+						local result = middleware(message)(ctx)
 						if result == DropRequest then
 							return nil
 						end
@@ -140,11 +145,16 @@ do
 					return nil
 				end
 				task.spawn(function()
+					local ctx = {
+						data = data,
+						updateData = updateData,
+						getRawData = getPacket,
+					}
 					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)
+						local result = globalMiddleware(message)(player, ctx)
 						if result == DropRequest then
 							return nil
 						end
@@ -153,7 +163,7 @@ do
 						if not self:validateData(message, data) then
 							return nil
 						end
-						local result = middleware(message)(player, data, updateData, getPacket)
+						local result = middleware(message)(player, ctx)
 						if result == DropRequest then
 							return nil
 						end
@@ -180,12 +190,17 @@ do
 					return nil
 				end
 				task.spawn(function()
+					local ctx = {
+						data = data,
+						updateData = updateData,
+						getRawData = getPacket,
+					}
 					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)
+							local result = globalMiddleware(message)(player, ctx)
 							if result == DropRequest then
 								return nil
 							end
@@ -196,7 +211,7 @@ do
 							if not self:validateData(message, data) then
 								return nil
 							end
-							local result = middleware(message)(player, data, updateData, getPacket)
+							local result = middleware(message)(player, ctx)
 							if result == DropRequest then
 								return nil
 							end
@@ -244,7 +259,7 @@ do
 		self.janitor:Add(function()
 			table.clear(self.clientCallbacks)
 			table.clear(self.serverCallbacks)
-			self.serializers = nil
+			table.clear(self.serializers)
 			self.serverEvents = nil
 			self.clientEvents = nil
 		end)

package/out/middleware.d.ts

@@ -3,16 +3,19 @@ type DropRequestSymbol = symbol & {
     _drop_req?: undefined;
 };
 export declare const DropRequest: DropRequestSymbol;
-type UpdateDataFn<T> = (newData: T) => void;
-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> & {
+} & ((message: BaseMessage) => (player: Player | Player[], ctx: MiddlewareContext<Data>) => DropRequestSymbol | void);
+export type ServerMiddleware<Data = unknown> = {
     _server?: void;
-};
-export type SharedMiddleware<Data = unknown> = (message: BaseMessage) => (data: Readonly<Data>, updateData: UpdateDataFn<Data>, getRawData: GetRawDataFn) => DropRequestSymbol | void;
+} & SharedMiddleware<Data>;
+export type SharedMiddleware<Data = unknown> = (message: BaseMessage) => (ctx: MiddlewareContext<Data>) => DropRequestSymbol | void;
 export type Middleware<Data = unknown> = ServerMiddleware<Data> & ClientMiddleware<Data> & SharedMiddleware<Data>;
+export interface MiddlewareContext<Data = unknown> {
+    readonly data: Readonly<Data>;
+    updateData: (newData: Data) => void;
+    getRawData: () => SerializedPacket;
+}
 export declare class MiddlewareProvider<MessageData> {
     private readonly clientGlobalMiddlewares;
     private readonly serverGlobalMiddlewares;

package/out/middleware.luau

@@ -78,8 +78,8 @@ do
 		local _newValue = table.create(#_exp)
 		local _callback = function(middleware)
 			return function(message)
-				return function(_, data, updateData, getRawData)
-					return middleware(message)(data, updateData, getRawData)
+				return function(_, ctx)
+					return middleware(message)(ctx)
 				end
 			end
 		end
@@ -133,8 +133,8 @@ do
 		local _newValue = table.create(#_exp)
 		local _callback = function(middleware)
 			return function(message)
-				return function(_, data, updateData, getRawData)
-					return middleware(message)(data, updateData, getRawData)
+				return function(_, ctx)
+					return middleware(message)(ctx)
 				end
 			end
 		end

package/package.json

@@ -1,49 +1,49 @@
-{
-  "name": "@rbxts/tether",
-  "version": "1.2.0",
-  "main": "out/init.lua",
-  "scripts": {
-    "build": "rbxtsc",
-    "watch": "rbxtsc -w",
-    "prepublishOnly": "npm run build"
-  },
-  "keywords": [
-    "roblox",
-    "tether",
-    "networking",
-    "message",
-    "serialization",
-    "middleware"
-  ],
-  "repository": {
-    "url": "git+https://github.com/R-unic/tether.git"
-  },
-  "author": "runicly",
-  "license": "ISC",
-  "description": "A message-based networking solution for Roblox with automatic binary serialization and type validation",
-  "types": "out/index.d.ts",
-  "files": [
-    "out",
-    "!**/*.tsbuildinfo"
-  ],
-  "publishConfig": {
-    "access": "public"
-  },
-  "devDependencies": {
-    "@rbxts/compiler-types": "^3.0.0-types.0",
-    "@rbxts/types": "^1.0.835",
-    "rbxts-transformer-flamework": "^1.2.4",
-    "roblox-ts": "^3.0.0",
-    "ts-toolbelt": "^9.6.0",
-    "typescript": "^5.5.3"
-  },
-  "dependencies": {
-    "@flamework/core": "^1.2.4",
-    "@flamework/networking": "^1.2.4",
-    "@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"
-  }
-}
+{
+  "name": "@rbxts/tether",
+  "version": "1.2.2",
+  "main": "out/init.lua",
+  "scripts": {
+    "build": "rbxtsc",
+    "watch": "rbxtsc -w",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "roblox",
+    "tether",
+    "networking",
+    "message",
+    "serialization",
+    "middleware"
+  ],
+  "repository": {
+    "url": "git+https://github.com/R-unic/tether.git"
+  },
+  "author": "runicly",
+  "license": "ISC",
+  "description": "A message-based networking solution for Roblox with automatic binary serialization and type validation",
+  "types": "out/index.d.ts",
+  "files": [
+    "out",
+    "!**/*.tsbuildinfo"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "@rbxts/compiler-types": "^3.0.0-types.0",
+    "@rbxts/types": "^1.0.835",
+    "rbxts-transformer-flamework": "^1.2.4",
+    "roblox-ts": "^3.0.0",
+    "typescript": "^5.5.3"
+  },
+  "dependencies": {
+    "@flamework/core": "^1.2.4",
+    "@flamework/networking": "^1.2.4",
+    "@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",
+    "ts-toolbelt": "^9.6.0"
+  }
+}