@rbxts/tether 1.0.5 → 1.0.6

package/README.md

@@ -1,5 +1,7 @@
 # Tether
-A message-based networking solution for Roblox with automatic binary serialization
+A message-based networking solution for Roblox with automatic binary serialization.
+
+## Usage
 
 ### In `shared/messaging.ts`
 ```ts
@@ -40,4 +42,46 @@ messaging.emitServer(Message.TEST, {
   foo: "bar",
   n: 69
 });
+```
+
+## Middleware
+
+### Creating middleware
+```ts
+import { type Middleware, DropRequest } from "@rbxts/tether";
+
+export function rateLimit(interval: number): Middleware {
+  let lastRequest = 0;
+
+  return () => {
+    if (os.clock() - lastRequest < interval)
+      return DropRequest;
+
+    lastRequest = os.clock();
+  };
+}
+```
+
+### 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
+  .useUniversal(Message.Test, [BuiltinMiddlewares.rateLimit(5)]) // only allows requests every 5 seconds, drops any
+                                                                 // requests that occur within 5 seconds of each other
+  .useClient(Message.Test, [BuiltinMiddlewares.validateClient()]); // automatically validates that data sent through the remote
+                                                                   // matches the data associated with the message at runtime
+
+export const enum Message {
+  Test
+}
+
+export interface MessageData {
+  [Message.Test]: {
+    readonly foo: string;
+    readonly n: DataType.u8;
+  };
+}
 ```

package/out/builtin-middlewares.d.ts

@@ -1,4 +1,30 @@
-import { Middleware } from "./middleware";
+import { Modding } from "@flamework/core";
+import { type UniversalMiddleware, type ServerMiddleware, type ClientMiddleware } from "./middleware";
+type Guard<T> = (value: unknown) => value is T;
 export declare namespace BuiltinMiddlewares {
-    function rateLimit<Data>(interval: number): Middleware<Data>;
+    /**
+     * Creates a universal middleware that will drop any message that occurs within the given interval of the previous message.
+     * @param interval The interval in seconds that the middleware should wait before allowing a new request.
+     * @returns A middleware that will drop any message that occurs within the given interval.
+     */
+    function rateLimit(interval: number): UniversalMiddleware;
+    /**
+     * Creates a server 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 server middleware that validates the data with the given guard.
+     * @macro
+     */
+    function validateServer<T>(guard?: Guard<T> | Modding.Generic<T, "guard">): ServerMiddleware<T>;
+    /**
+     * Creates a server 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 server middleware that validates the data with the given guard.
+     * @macro
+     */
+    function validateClient<T>(guard?: Guard<T> | Modding.Generic<T, "guard">): ClientMiddleware<T>;
 }
+export {};

package/out/builtin-middlewares.luau

@@ -1,9 +1,20 @@
 -- Compiled with roblox-ts v3.0.0
 local TS = _G[script]
 local DropRequest = TS.import(script, script.Parent, "middleware").DropRequest
+local noOp = function() end
+local validationGuardGenerationFailed = function(context)
+	return `[Tether]: Failed to generate guard for validate{context}<T> builtin middleware - skipping validation`
+end
 local BuiltinMiddlewares = {}
 do
 	local _container = BuiltinMiddlewares
+	--[[
+		*
+		     * Creates a universal middleware that will drop any message that occurs within the given interval of the previous message.
+		     * @param interval The interval in seconds that the middleware should wait before allowing a new request.
+		     * @returns A middleware that will drop any message that occurs within the given interval.
+		     
+	]]
 	local function rateLimit(interval)
 		local lastRequest = 0
 		return function()
@@ -14,6 +25,52 @@ do
 		end
 	end
 	_container.rateLimit = rateLimit
+	--[[
+		*
+		     * Creates a server 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 server middleware that validates the data with the given guard.
+		     * @macro
+		     
+	]]
+	local function validateServer(guard)
+		if guard == nil then
+			warn(validationGuardGenerationFailed("Server"))
+			return noOp
+		end
+		return function(data)
+			if guard(data) then
+				return nil
+			end
+			return DropRequest
+		end
+	end
+	_container.validateServer = validateServer
+	--[[
+		*
+		     * Creates a server 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 server middleware that validates the data with the given guard.
+		     * @macro
+		     
+	]]
+	local function validateClient(guard)
+		if guard == nil then
+			warn(validationGuardGenerationFailed("Client"))
+			return noOp
+		end
+		return function(data)
+			if guard(data) then
+				return nil
+			end
+			return DropRequest
+		end
+	end
+	_container.validateClient = validateClient
 end
 return {
 	BuiltinMiddlewares = BuiltinMiddlewares,

package/out/index.d.ts

@@ -1,3 +1,3 @@
 export { MessageEmitter } from "./message-emitter";
 export { BuiltinMiddlewares } from "./builtin-middlewares";
-export { MiddlewareProvider, DropRequest, type ClientMiddleware, type ServerMiddleware, type Middleware } from "./middleware";
+export { DropRequest, type ClientMiddleware, type ServerMiddleware, type Middleware } from "./middleware";

package/out/init.luau

@@ -3,7 +3,5 @@ local TS = _G[script]
 local exports = {}
 exports.MessageEmitter = TS.import(script, script, "message-emitter").MessageEmitter
 exports.BuiltinMiddlewares = TS.import(script, script, "builtin-middlewares").BuiltinMiddlewares
-local _middleware = TS.import(script, script, "middleware")
-exports.MiddlewareProvider = _middleware.MiddlewareProvider
-exports.DropRequest = _middleware.DropRequest
+exports.DropRequest = TS.import(script, script, "middleware").DropRequest
 return exports

package/out/message-emitter.d.ts

@@ -4,23 +4,23 @@ import Destroyable from "@rbxts/destroyable";
 import { MiddlewareProvider } from "./middleware";
 import type { ClientMessageCallback, ServerMessageCallback } from "./structs";
 export declare class MessageEmitter<MessageData> extends Destroyable {
-    private readonly middleware?;
+    readonly middleware: MiddlewareProvider<MessageData>;
     private readonly clientCallbacks;
     private readonly serverCallbacks;
     private serializers;
     private serverEvents;
     private clientEvents;
     /** @metadata macro */
-    static create<MessageData>(middleware?: MiddlewareProvider<MessageData>, metaForEachMessage?: Modding.Many<{
+    static create<MessageData>(metaForEachMessage?: Modding.Many<{
         [Kind in keyof MessageData]: MessageData[Kind] extends undefined ? undefined : Modding.Many<SerializerMetadata<MessageData[Kind]>>;
     }>): MessageEmitter<MessageData>;
     private constructor();
     /**.
-     * @returns A destructor function that disconnects the callback from the message
+     * @returns A destructor function that disconnects the callback from the message.
      */
     onServerMessage<Kind extends keyof MessageData>(message: Kind, callback: ServerMessageCallback<MessageData[Kind]>): () => void;
     /**.
-     * @returns A destructor function that disconnects the callback from the message
+     * @returns A destructor function that disconnects the callback from the message.
      */
     onClientMessage<Kind extends keyof MessageData>(message: Kind, callback: ClientMessageCallback<MessageData[Kind]>): () => void;
     private on;

package/out/message-emitter.luau

@@ -7,7 +7,9 @@ local _services = TS.import(script, TS.getModule(script, "@rbxts", "services"))
 local Players = _services.Players
 local RunService = _services.RunService
 local Destroyable = TS.import(script, TS.getModule(script, "@rbxts", "destroyable").out).default
-local DropRequest = TS.import(script, script.Parent, "middleware").DropRequest
+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")
 local MessageEmitter
 do
@@ -23,9 +25,9 @@ do
 		local self = setmetatable({}, MessageEmitter)
 		return self:constructor(...) or self
 	end
-	function MessageEmitter:constructor(middleware)
+	function MessageEmitter:constructor()
 		super.constructor(self)
-		self.middleware = middleware
+		self.middleware = MiddlewareProvider.new()
 		self.clientCallbacks = {}
 		self.serverCallbacks = {}
 		self.serializers = {}
@@ -84,8 +86,8 @@ do
 			})
 		end
 	end
-	function MessageEmitter:create(middleware, metaForEachMessage)
-		local emitter = MessageEmitter.new(middleware)
+	function MessageEmitter:create(metaForEachMessage)
+		local emitter = MessageEmitter.new()
 		if metaForEachMessage == nil then
 			warn("[Tether]: Failed to generate serializer metadata for MessageEmitter")
 			return emitter:initialize()

package/out/middleware.d.ts

@@ -2,8 +2,9 @@ type DropRequestSymbol = symbol & {
     _skip_middleware?: undefined;
 };
 export declare const DropRequest: DropRequestSymbol;
-export type ClientMiddleware<Data = unknown> = (player: Player, data: Data | undefined) => DropRequestSymbol | void;
-export type ServerMiddleware<Data = unknown> = (data: Data | undefined) => DropRequestSymbol | void;
+export type ClientMiddleware<Data = unknown> = (player: Player, data: Readonly<Data> | undefined) => DropRequestSymbol | void;
+export type ServerMiddleware<Data = unknown> = (data: Readonly<Data> | undefined) => DropRequestSymbol | void;
+export type UniversalMiddleware = () => DropRequestSymbol | void;
 export type Middleware<Data = unknown> = ServerMiddleware<Data> & ClientMiddleware<Data>;
 export declare class MiddlewareProvider<MessageData> {
     private readonly clientMiddlewares;
@@ -14,5 +15,6 @@ export declare class MiddlewareProvider<MessageData> {
     getServer<Kind extends keyof MessageData>(message: Kind): ServerMiddleware<MessageData[Kind]>[];
     useClient<Kind extends keyof MessageData>(message: Kind, middlewares: ClientMiddleware<MessageData[Kind]> | ClientMiddleware<MessageData[Kind]>[], order?: number): this;
     useServer<Kind extends keyof MessageData>(message: Kind, middlewares: ServerMiddleware<MessageData[Kind]> | ServerMiddleware<MessageData[Kind]>[], order?: number): this;
+    useUniversal<Kind extends keyof MessageData>(message: Kind, middlewares: UniversalMiddleware | UniversalMiddleware[], order?: number): this;
 }
 export {};

package/out/middleware.luau

@@ -1,13 +1,5 @@
 -- Compiled with roblox-ts v3.0.0
-local function createSymbol(name)
-	local symbol = newproxy(true)
-	local mt = getmetatable(symbol)
-	mt.__tostring = function()
-		return name
-	end
-	return symbol
-end
-local DropRequest = createSymbol("DropRequest")
+local DropRequest = newproxy()
 local MiddlewareProvider
 do
 	MiddlewareProvider = setmetatable({}, {
@@ -70,6 +62,11 @@ do
 		end
 		return self
 	end
+	function MiddlewareProvider:useUniversal(message, middlewares, order)
+		self:useClient(message, middlewares, order)
+		self:useServer(message, middlewares, order)
+		return self
+	end
 end
 return {
 	DropRequest = DropRequest,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rbxts/tether",
-  "version": "1.0.5",
+  "version": "1.0.6",
   "main": "out/init.lua",
   "scripts": {
     "build": "rbxtsc",