@rbxts/tether 1.0.5 → 1.0.7

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,50 @@ 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
+  // 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 data sent through the remote
+  // matches the data associated with the message at runtime
+  .useShared(Message.Test, [BuiltinMiddlewares.validateClient()])
+  // rate limit every server remote (global)
+  .useServerGlobal([BuiltinMiddlewares.rateLimit(1)]);
+
+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 SharedMiddleware, 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): SharedMiddleware;
+    /**
+     * 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 `[@rbxts/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,10 +86,10 @@ 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")
+			warn("[@rbxts/tether]: Failed to generate serializer metadata for MessageEmitter")
 			return emitter:initialize()
 		end
 		for kind, meta in pairs(metaForEachMessage) do

package/out/middleware.d.ts

@@ -2,17 +2,28 @@ 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 SharedMiddleware = () => DropRequestSymbol | void;
 export type Middleware<Data = unknown> = ServerMiddleware<Data> & ClientMiddleware<Data>;
 export declare class MiddlewareProvider<MessageData> {
+    private readonly clientGlobalMiddlewares;
+    private readonly serverGlobalMiddlewares;
     private readonly clientMiddlewares;
     private readonly serverMiddlewares;
     /** @hidden */
     getClient<Kind extends keyof MessageData>(message: Kind): ClientMiddleware<MessageData[Kind]>[];
     /** @hidden */
     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;
+    /** @hidden */
+    getClientGlobal<Data>(): ClientMiddleware<Data>[];
+    /** @hidden */
+    getServerGlobal<Data>(): ServerMiddleware<Data>[];
+    useClient<Kind extends keyof MessageData>(message: Kind, middlewares: ClientMiddleware<MessageData[Kind]> | readonly ClientMiddleware<MessageData[Kind]>[], order?: number): this;
+    useServer<Kind extends keyof MessageData>(message: Kind, middlewares: ServerMiddleware<MessageData[Kind]> | readonly ServerMiddleware<MessageData[Kind]>[], order?: number): this;
+    useShared<Kind extends keyof MessageData>(message: Kind, middlewares: SharedMiddleware | readonly SharedMiddleware[], order?: number): this;
+    useClientGlobal<Data>(middlewares: ClientMiddleware<Data> | readonly ClientMiddleware<Data>[], order?: number): this;
+    useServerGlobal<Data>(middlewares: ServerMiddleware<Data> | readonly ServerMiddleware<Data>[], order?: number): this;
+    useSharedGlobal(middlewares: SharedMiddleware | readonly SharedMiddleware[], 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({}, {
@@ -21,6 +13,8 @@ do
 		return self:constructor(...) or self
 	end
 	function MiddlewareProvider:constructor()
+		self.clientGlobalMiddlewares = {}
+		self.serverGlobalMiddlewares = {}
 		self.clientMiddlewares = {}
 		self.serverMiddlewares = {}
 	end
@@ -36,6 +30,12 @@ do
 		end
 		return self.serverMiddlewares[message]
 	end
+	function MiddlewareProvider:getClientGlobal()
+		return self.clientGlobalMiddlewares
+	end
+	function MiddlewareProvider:getServerGlobal()
+		return self.serverGlobalMiddlewares
+	end
 	function MiddlewareProvider:useClient(message, middlewares, order)
 		local messageMiddleware = self:getClient(message)
 		local _middlewares = middlewares
@@ -48,7 +48,7 @@ do
 			table.insert(messageMiddleware, _condition + 1, _middlewares_1)
 		else
 			for _, middleware in middlewares do
-				self:useClient(message, middleware)
+				self:useClient(message, middleware, order)
 			end
 		end
 		return self
@@ -65,11 +65,55 @@ do
 			table.insert(messageMiddleware, _condition + 1, _middlewares_1)
 		else
 			for _, middleware in middlewares do
-				self:useServer(message, middleware)
+				self:useServer(message, middleware, order)
+			end
+		end
+		return self
+	end
+	function MiddlewareProvider:useShared(message, middlewares, order)
+		self:useClient(message, middlewares, order)
+		self:useServer(message, middlewares, order)
+		return self
+	end
+	function MiddlewareProvider:useClientGlobal(middlewares, order)
+		local globalMiddleware = self:getClientGlobal()
+		local _middlewares = middlewares
+		if typeof(_middlewares) == "function" then
+			local _condition = order
+			if _condition == nil then
+				_condition = #globalMiddleware - 1
+			end
+			local _middlewares_1 = middlewares
+			table.insert(globalMiddleware, _condition + 1, _middlewares_1)
+		else
+			for _, middleware in middlewares do
+				self:useClientGlobal(middleware, order)
+			end
+		end
+		return self
+	end
+	function MiddlewareProvider:useServerGlobal(middlewares, order)
+		local globalMiddleware = self:getServerGlobal()
+		local _middlewares = middlewares
+		if typeof(_middlewares) == "function" then
+			local _condition = order
+			if _condition == nil then
+				_condition = #globalMiddleware - 1
+			end
+			local _middlewares_1 = middlewares
+			table.insert(globalMiddleware, _condition + 1, _middlewares_1)
+		else
+			for _, middleware in middlewares do
+				self:useServerGlobal(middleware, order)
 			end
 		end
 		return self
 	end
+	function MiddlewareProvider:useSharedGlobal(middlewares, order)
+		self:useClientGlobal(middlewares, order)
+		self:useServerGlobal(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.7",
   "main": "out/init.lua",
   "scripts": {
     "build": "rbxtsc",