@rbxts/tether 1.1.4 → 1.1.6

package/README.md

@@ -52,6 +52,7 @@ 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";
@@ -109,10 +110,11 @@ messaging.middleware
   .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.validateServer()])
+  .useServer(Message.Test, [BuiltinMiddlewares.validate()])
   // 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
 

package/out/builtin-middlewares.d.ts

@@ -1,33 +1,24 @@
 import { Modding } from "@flamework/core";
-import { type SharedMiddleware, type ServerMiddleware, type ClientMiddleware } from "./middleware";
+import { type SharedMiddleware } from "./middleware";
 type Guard<T> = (value: unknown) => value is T;
 export declare namespace BuiltinMiddlewares {
     /**
-     * Creates a shared per-message middleware that will drop any message that occurs within the given interval of the previous message
+     * Creates a shared 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
-     * @metadata macro
-     */
-    function validateServer<T>(guard?: Guard<T> | Modding.Generic<T, "guard">): ServerMiddleware<T>;
-    /**
-     * Creates a client middleware that validates the data with the given guard (or a generated guard if none was provided)
+     * 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 client middleware that validates the data with the given guard.
+     * @returns A shared middleware that validates the data with the given guard.
      * @metadata macro
      */
-    function validateClient<T>(guard?: Guard<T> | Modding.Generic<T, "guard">): ClientMiddleware<T>;
+    function validate<T>(guard?: Guard<T> | Modding.Generic<T, "guard">): SharedMiddleware;
+    function debug(): SharedMiddleware;
 }
 export {};

package/out/builtin-middlewares.luau

@@ -1,21 +1,23 @@
 -- 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(context)
-	return `[@rbxts/tether]: Failed to generate guard for validate{context}<T> builtin middleware - skipping validation`
+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 failed for message '{tostring(message)}' - check your sent data`
+	return `[@rbxts/tether]: Type validation guard failed for message '{tostring(message)}' - check your sent data`
 end
+local BLOB_SIZE = 5
 local BuiltinMiddlewares = {}
 do
 	local _container = BuiltinMiddlewares
 	--[[
 		*
-		     * Creates a shared per-message middleware that will drop any message that occurs within the given interval of the previous message
+		     * Creates a shared 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
@@ -35,18 +37,18 @@ do
 	_container.rateLimit = rateLimit
 	--[[
 		*
-		     * Creates a server middleware that validates the data with the given guard (or a generated guard if none was provided)
+		     * 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 server middleware that validates the data with the given guard
+		     * @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 validateServer(guard)
+	local function validate(guard)
 		if guard == nil then
-			warn(validationGuardGenerationFailed("Server"))
+			warn(validationGuardGenerationFailed())
 			return noOp
 		end
 		return function(message)
@@ -59,34 +61,54 @@ do
 			end
 		end
 	end
-	_container.validateServer = validateServer
-	--[[
-		*
-		     * Creates a client 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 client middleware that validates the data with the given guard.
-		     * @metadata macro
-		     
-	]]
-	local function validateClient(guard)
-		if guard == nil then
-			warn(validationGuardGenerationFailed("Client"))
-			return noOp
+	_container.validate = validate
+	local function toStringBuffer(buf)
+		local s = { "{ " }
+		do
+			local i = 0
+			local _shouldIncrement = false
+			while true do
+				if _shouldIncrement then
+					i += 1
+				else
+					_shouldIncrement = true
+				end
+				if not (i < buffer.len(buf)) then
+					break
+				end
+				local byte = buffer.readu8(buf, i)
+				local _arg0 = tostring(byte)
+				table.insert(s, _arg0)
+				if i < buffer.len(buf) - 1 then
+					table.insert(s, ", ")
+				end
+			end
 		end
+		table.insert(s, " }")
+		return table.concat(s, "")
+	end
+	local line = "------------------------------------"
+	local function debug()
 		return function(message)
-			return function(player, data)
-				if guard(data) then
-					return nil
-				end
-				warn(guardFailed(message))
-				return DropRequest
+			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)
 			end
 		end
 	end
-	_container.validateClient = validateClient
+	_container.debug = debug
 end
 return {
 	BuiltinMiddlewares = BuiltinMiddlewares,

package/out/message-emitter.d.ts

@@ -23,7 +23,6 @@ export declare class MessageEmitter<MessageData> extends Destroyable {
      * @returns A destructor function that disconnects the callback from the message
      */
     onClientMessage<Kind extends keyof MessageData>(message: Kind & BaseMessage, callback: ClientMessageCallback<MessageData[Kind]>): () => void;
-    private on;
     /**
      * Emits a message to all connected clients
      *
@@ -50,6 +49,7 @@ export declare class MessageEmitter<MessageData> extends Destroyable {
      */
     emitAllClients<Kind extends keyof MessageData>(message: Kind & BaseMessage, data?: MessageData[Kind], unreliable?: boolean): void;
     private initialize;
+    private on;
     private getPacket;
     /** @metadata macro */
     private addSerializer;

package/out/message-emitter.luau

@@ -106,28 +106,6 @@ do
 	function MessageEmitter:onClientMessage(message, callback)
 		return self:on(message, callback)
 	end
-	function MessageEmitter:on(message, callback)
-		local callbacksMap = if RunService:IsServer() then self.serverCallbacks else self.clientCallbacks
-		local _message = message
-		if not (callbacksMap[_message] ~= nil) then
-			local _message_1 = message
-			callbacksMap[_message_1] = {}
-		end
-		local _message_1 = message
-		local callbacks = callbacksMap[_message_1]
-		local _callback = callback
-		callbacks[_callback] = true
-		local _message_2 = message
-		callbacksMap[_message_2] = callbacks
-		return function()
-			local _callback_1 = callback
-			-- ▼ Set.delete ▼
-			local _valueExisted = callbacks[_callback_1] ~= nil
-			callbacks[_callback_1] = nil
-			-- ▲ Set.delete ▲
-			return _valueExisted
-		end
-	end
 	function MessageEmitter:emitServer(message, data, unreliable)
 		if unreliable == nil then
 			unreliable = false
@@ -136,20 +114,23 @@ do
 			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)
+			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)
+			local result = middleware(message)(data, updateData, getPacket)
 			if result == DropRequest then
 				return nil
 			end
 		end
 		local send = if unreliable then self.clientEvents.sendUnreliableServerMessage else self.clientEvents.sendServerMessage
-		send(self:getPacket(message, data))
+		send(getPacket())
 	end
 	function MessageEmitter:emitClient(player, message, data, unreliable)
 		if unreliable == nil then
@@ -159,20 +140,23 @@ do
 			data = newData
 			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)
+			local result = globalMiddleware(message)(player, data, updateData, getPacket)
 			if result == DropRequest then
 				return nil
 			end
 		end
 		for _, middleware in self.middleware:getClient(message) do
-			local result = middleware(message)(player, data, updateData)
+			local result = middleware(message)(player, data, updateData, getPacket)
 			if result == DropRequest then
 				return nil
 			end
 		end
 		local send = if unreliable then self.serverEvents.sendUnreliableClientMessage else self.serverEvents.sendClientMessage
-		send(player, self:getPacket(message, data))
+		send(player, getPacket())
 	end
 	function MessageEmitter:emitAllClients(message, data, unreliable)
 		if unreliable == nil then
@@ -182,9 +166,12 @@ do
 			data = newData
 			return nil
 		end
+		local getPacket = function()
+			return self:getPacket(message, data)
+		end
 		for _, globalMiddleware in self.middleware:getClientGlobal() do
 			for _1, player in Players:GetPlayers() do
-				local result = globalMiddleware(message)(player, data, updateData)
+				local result = globalMiddleware(message)(player, data, updateData, getPacket)
 				if result == DropRequest then
 					return nil
 				end
@@ -192,7 +179,7 @@ do
 		end
 		for _, middleware in self.middleware:getClient(message) do
 			for _1, player in Players:GetPlayers() do
-				local result = middleware(message)(player, data, updateData)
+				local result = middleware(message)(player, data, updateData, getPacket)
 				if result == DropRequest then
 					return nil
 				end
@@ -216,9 +203,17 @@ do
 					return nil
 				end
 				local serializer = self:getSerializer(sentMessage)
-				local packet = serializer.deserialize(serializedPacket.buffer, serializedPacket.blobs)
+				local _packet = serializer
+				if _packet ~= nil then
+					_packet = _packet.deserialize(serializedPacket.buffer, serializedPacket.blobs)
+				end
+				local packet = _packet
 				for callback in messageCallbacks do
-					callback(packet.data)
+					local _result = packet
+					if _result ~= nil then
+						_result = _result.data
+					end
+					callback(_result)
 				end
 			end))
 		else
@@ -235,20 +230,59 @@ do
 					return nil
 				end
 				local serializer = self:getSerializer(sentMessage)
-				local packet = serializer.deserialize(serializedPacket.buffer, serializedPacket.blobs)
+				local _packet = serializer
+				if _packet ~= nil then
+					_packet = _packet.deserialize(serializedPacket.buffer, serializedPacket.blobs)
+				end
+				local packet = _packet
 				for callback in messageCallbacks do
-					callback(player, packet.data)
+					local _exp = player
+					local _result = packet
+					if _result ~= nil then
+						_result = _result.data
+					end
+					callback(_exp, _result)
 				end
 			end))
 		end
 		return self
 	end
+	function MessageEmitter:on(message, callback)
+		local callbacksMap = if RunService:IsServer() then self.serverCallbacks else self.clientCallbacks
+		local _message = message
+		if not (callbacksMap[_message] ~= nil) then
+			local _message_1 = message
+			callbacksMap[_message_1] = {}
+		end
+		local _message_1 = message
+		local callbacks = callbacksMap[_message_1]
+		local _callback = callback
+		callbacks[_callback] = true
+		local _message_2 = message
+		callbacksMap[_message_2] = callbacks
+		return function()
+			local _callback_1 = callback
+			-- ▼ Set.delete ▼
+			local _valueExisted = callbacks[_callback_1] ~= nil
+			callbacks[_callback_1] = nil
+			-- ▲ Set.delete ▲
+			return _valueExisted
+		end
+	end
 	function MessageEmitter:getPacket(message, data)
 		local serializer = self:getSerializer(message)
-		return serializer.serialize({
-			message = message,
-			data = data,
-		})
+		if serializer ~= nil and data ~= nil then
+			return serializer.serialize({
+				message = message,
+				data = data,
+			})
+		end
+		local buf = buffer.create(1)
+		buffer.writeu8(buf, 0, message)
+		return {
+			buffer = buf,
+			blobs = {},
+		}
 	end
 	function MessageEmitter:addSerializer(message, meta)
 		self.serializers[message] = self:createMessageSerializer(meta)

package/out/middleware.d.ts

@@ -1,12 +1,12 @@
-import type { BaseMessage } from "./structs";
+import type { BaseMessage, SerializedPacket } from "./structs";
 type DropRequestSymbol = symbol & {
     _drop_req?: undefined;
 };
 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>) => DropRequestSymbol | void;
-export type ServerMiddleware<Data = unknown> = (message: BaseMessage) => (data: Readonly<Data>, updateData: UpdateDataFn<Data>) => DropRequestSymbol | void;
-export type SharedMiddleware = (message: BaseMessage) => () => DropRequestSymbol | 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>;
 export declare class MiddlewareProvider<MessageData> {
     private readonly clientGlobalMiddlewares;

package/out/middleware.luau

@@ -71,8 +71,25 @@ do
 		return self
 	end
 	function MiddlewareProvider:useShared(message, middlewares, order)
-		self:useClient(message, middlewares, order)
-		self:useServer(message, middlewares, order)
+		local server = middlewares
+		local _middlewares = middlewares
+		local _exp = (if type(_middlewares) == "function" then { middlewares } else middlewares)
+		-- ▼ ReadonlyArray.map ▼
+		local _newValue = table.create(#_exp)
+		local _callback = function(middleware)
+			return function(message)
+				return function(_, data, updateData, getRawData)
+					return middleware(message)(data, updateData, getRawData)
+				end
+			end
+		end
+		for _k, _v in _exp do
+			_newValue[_k] = _callback(_v, _k - 1, _exp)
+		end
+		-- ▲ ReadonlyArray.map ▲
+		local client = _newValue
+		self:useServer(message, server, order)
+		self:useClient(message, client, order)
 		return self
 	end
 	function MiddlewareProvider:useClientGlobal(middlewares, order)
@@ -110,7 +127,23 @@ do
 		return self
 	end
 	function MiddlewareProvider:useSharedGlobal(middlewares, order)
-		self:useClientGlobal(middlewares, order)
+		local _middlewares = middlewares
+		local _exp = (if type(_middlewares) == "function" then { middlewares } else middlewares)
+		-- ▼ ReadonlyArray.map ▼
+		local _newValue = table.create(#_exp)
+		local _callback = function(middleware)
+			return function(message)
+				return function(_, data, updateData, getRawData)
+					return middleware(message)(data, updateData, getRawData)
+				end
+			end
+		end
+		for _k, _v in _exp do
+			_newValue[_k] = _callback(_v, _k - 1, _exp)
+		end
+		-- ▲ ReadonlyArray.map ▲
+		local client = _newValue
+		self:useClientGlobal(client, order)
 		self:useServerGlobal(middlewares, order)
 		return self
 	end

package/out/structs.d.ts

@@ -10,7 +10,7 @@ export interface SerializedPacket {
 }
 export interface TetherPacket<Data> {
     readonly message: DataType.u8;
-    readonly data?: Data;
+    readonly data: Data;
 }
 export type MessageEvent = (packet: SerializedPacket) => void;
 export type UnreliableMessageEvent = Networking.Unreliable<MessageEvent>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rbxts/tether",
-  "version": "1.1.4",
+  "version": "1.1.6",
   "main": "out/init.lua",
   "scripts": {
     "build": "rbxtsc",
@@ -34,6 +34,7 @@
     "@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": {
@@ -41,6 +42,7 @@
     "@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/services": "^1.5.5"
   }
 }