@zudojs/rpc 0.1.0 → 1.1.0

package/dist/rpc/validation/rpcValidation.core.d.ts

@@ -0,0 +1,86 @@
+/**
+ * @zudojs/rpc/validation
+ *
+ * Request-level checks applied before a payload reaches a handler.
+ *
+ * Requests arrive from an untrusted peer over a transport, so these are
+ * the first checks the server runs, not the last.
+ */
+import type { Schema, SchemaIssue } from "@zudojs/schema";
+import type { RPCRequest } from "../types/rpcRequest.type.js";
+/**
+ * Limits applied to an incoming request.
+ */
+export interface RPCRequestLimits {
+    /**
+     * Maximum encoded payload size in bytes. Defaults to
+     * {@link MAX_RPC_PAYLOAD_SIZE}. Set to `0` to skip the check when the
+     * transport already enforces a frame limit.
+     */
+    readonly maxPayloadBytes?: number;
+    /**
+     * Whether procedure names must match {@link PROCEDURE_NAME_PATTERN}.
+     * Defaults to `true`.
+     */
+    readonly enforceProcedureNamePattern?: boolean;
+}
+/**
+ * Validates a procedure name.
+ *
+ * Length is checked before the pattern so a pathological name cannot
+ * drive regex backtracking.
+ */
+export declare function assertValidProcedureName(name: unknown): asserts name is string;
+/**
+ * Measures the encoded size of a payload in bytes.
+ *
+ * Returns `undefined` for a payload that cannot be encoded, which the
+ * caller reports as an invalid request rather than passing on.
+ */
+export declare function measurePayloadBytes(payload: unknown): number | undefined;
+/**
+ * Validates the shape and size of an incoming request.
+ *
+ * @throws {RPCInvalidRequestError} when the frame is malformed or the
+ * payload exceeds the configured limit.
+ */
+export declare function assertValidRequest(request: unknown, limits?: RPCRequestLimits): asserts request is RPCRequest;
+/**
+ * Converts schema issues into metadata safe to return to a caller.
+ *
+ * Only the path, code and message travel; the received input is dropped
+ * so a validation response cannot echo back data the caller sent.
+ */
+export declare function toValidationIssues(issues: readonly SchemaIssue[]): readonly {
+    path: string;
+    code: string;
+    message: string;
+}[];
+/**
+ * The part of a `@zudojs/schema` Schema this package depends on.
+ *
+ * Structural so any schema-like validator can be supplied, and so the
+ * dependency stays to the parse contract rather than the class.
+ */
+export type RPCSchema<TOutput = unknown> = Pick<Schema<TOutput, never>, "safeParse">;
+/**
+ * Parses caller input against a schema.
+ *
+ * @throws {RPCValidationError} carrying the issues, which are safe to
+ * return: they describe the caller's own input.
+ */
+export declare function parseInput<T>(schema: RPCSchema<T>, value: unknown, procedureName: string): T;
+/**
+ * Parses a handler's result against its output schema.
+ *
+ * An invalid output is a server defect rather than a caller mistake, so
+ * it is thrown as an `RPCInternalError` (`expose: false`): the server
+ * answers with the generic internal error and hands the detail — the
+ * failing paths and codes — to `onInternalError`. Throwing a validation
+ * error here told the caller *its* request was invalid, with an empty
+ * issue list, for a fault that is entirely the handler's.
+ *
+ * @throws {RPCInternalError}
+ */
+export declare function parseOutput<T>(schema: RPCSchema<T>, value: unknown, procedureName: string): T;
+//# sourceMappingURL=rpcValidation.core.d.ts.map

package/dist/rpc/validation/rpcValidation.core.js

@@ -0,0 +1,133 @@
+/**
+ * @zudojs/rpc/validation
+ *
+ * Request-level checks applied before a payload reaches a handler.
+ *
+ * Requests arrive from an untrusted peer over a transport, so these are
+ * the first checks the server runs, not the last.
+ */
+import { RPCInternalError, RPCInvalidRequestError, RPCValidationError, } from "../errors/rpc.errors.js";
+import { MAX_PROCEDURE_NAME_LENGTH, MAX_RPC_PAYLOAD_SIZE, PROCEDURE_NAME_PATTERN, } from "../constants/rpcConstants.core.js";
+/**
+ * Validates a procedure name.
+ *
+ * Length is checked before the pattern so a pathological name cannot
+ * drive regex backtracking.
+ */
+export function assertValidProcedureName(name) {
+    if (typeof name !== "string" || name.length === 0) {
+        throw new RPCInvalidRequestError("Procedure name must be a non-empty string.");
+    }
+    if (name.length > MAX_PROCEDURE_NAME_LENGTH) {
+        throw new RPCInvalidRequestError(`Procedure name exceeds ${MAX_PROCEDURE_NAME_LENGTH} characters.`);
+    }
+    if (!PROCEDURE_NAME_PATTERN.test(name)) {
+        throw new RPCInvalidRequestError(`Procedure name "${name}" must be dot-separated identifiers, e.g. "users.getUser".`);
+    }
+}
+/**
+ * Measures the encoded size of a payload in bytes.
+ *
+ * Returns `undefined` for a payload that cannot be encoded, which the
+ * caller reports as an invalid request rather than passing on.
+ */
+export function measurePayloadBytes(payload) {
+    if (payload === undefined) {
+        return 0;
+    }
+    try {
+        const encoded = JSON.stringify(payload);
+        if (encoded === undefined) {
+            return undefined;
+        }
+        return Buffer.byteLength(encoded, "utf8");
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Validates the shape and size of an incoming request.
+ *
+ * @throws {RPCInvalidRequestError} when the frame is malformed or the
+ * payload exceeds the configured limit.
+ */
+export function assertValidRequest(request, limits = {}) {
+    if (typeof request !== "object" || request === null) {
+        throw new RPCInvalidRequestError("Request must be an object.");
+    }
+    const candidate = request;
+    if (typeof candidate.id !== "string" || candidate.id.length === 0) {
+        throw new RPCInvalidRequestError("Request id must be a non-empty string.");
+    }
+    if (limits.enforceProcedureNamePattern ?? true) {
+        assertValidProcedureName(candidate.procedure);
+    }
+    else if (typeof candidate.procedure !== "string" ||
+        candidate.procedure.length === 0) {
+        throw new RPCInvalidRequestError("Procedure name must be a non-empty string.", undefined);
+    }
+    if (candidate.metadata !== undefined &&
+        (typeof candidate.metadata !== "object" || candidate.metadata === null)) {
+        throw new RPCInvalidRequestError("Request metadata must be an object.", candidate.procedure);
+    }
+    const maxBytes = limits.maxPayloadBytes ?? MAX_RPC_PAYLOAD_SIZE;
+    if (maxBytes > 0) {
+        const size = measurePayloadBytes(candidate.payload);
+        if (size === undefined) {
+            throw new RPCInvalidRequestError("Request payload could not be encoded.", candidate.procedure);
+        }
+        if (size > maxBytes) {
+            throw new RPCInvalidRequestError(`Request payload of ${size} bytes exceeds the ${maxBytes} byte limit.`, candidate.procedure);
+        }
+    }
+}
+/**
+ * Converts schema issues into metadata safe to return to a caller.
+ *
+ * Only the path, code and message travel; the received input is dropped
+ * so a validation response cannot echo back data the caller sent.
+ */
+export function toValidationIssues(issues) {
+    return issues.map((issue) => ({
+        path: issue.path.map(String).join("."),
+        code: String(issue.code),
+        message: issue.message,
+    }));
+}
+/**
+ * Parses caller input against a schema.
+ *
+ * @throws {RPCValidationError} carrying the issues, which are safe to
+ * return: they describe the caller's own input.
+ */
+export function parseInput(schema, value, procedureName) {
+    const result = schema.safeParse(value);
+    if (result.success) {
+        return result.data;
+    }
+    throw new RPCValidationError(`Invalid input for procedure "${procedureName}".`, toValidationIssues(result.issues), procedureName);
+}
+/**
+ * Parses a handler's result against its output schema.
+ *
+ * An invalid output is a server defect rather than a caller mistake, so
+ * it is thrown as an `RPCInternalError` (`expose: false`): the server
+ * answers with the generic internal error and hands the detail — the
+ * failing paths and codes — to `onInternalError`. Throwing a validation
+ * error here told the caller *its* request was invalid, with an empty
+ * issue list, for a fault that is entirely the handler's.
+ *
+ * @throws {RPCInternalError}
+ */
+export function parseOutput(schema, value, procedureName) {
+    const result = schema.safeParse(value);
+    if (result.success) {
+        return result.data;
+    }
+    const where = toValidationIssues(result.issues)
+        .map((issue) => `${issue.path || "(root)"}: ${issue.code}`)
+        .join(", ");
+    throw new RPCInternalError(`Procedure "${procedureName}" produced a response that does not match its output schema at ${where}.`, procedureName);
+}
+//# sourceMappingURL=rpcValidation.core.js.map

package/package.json

@@ -1,8 +1,12 @@
 {
   "name": "@zudojs/rpc",
-  "version": "0.1.0",
+  "version": "1.1.0",
   "description": "Remote procedure call infrastructure for Zudojs applications.",
   "license": "MIT",
+  "author": {
+    "name": "Oluwayemi Oyinlola",
+    "url": "https://github.com/oyinlola-tech"
+  },
   "type": "module",
   "main": "./dist/index.js",
   "module": "./dist/index.js",
@@ -14,26 +18,22 @@
     }
   },
   "files": [
-    "dist"
+    "dist",
+    "!dist/**/*.map",
+    "!dist/**/*.tsbuildinfo",
+    "!dist/.tsbuildinfo"
   ],
-  "scripts": {
-    "build": "tsc -p tsconfig.json",
-    "typecheck": "tsc -p tsconfig.json --noEmit",
-    "clean": "rm -rf dist",
-    "test": "vitest run",
-    "test:watch": "vitest"
-  },
   "engines": {
     "node": ">=24.0.0"
   },
   "dependencies": {
-    "@zudojs/errors": "0.1.0",
-    "@zudojs/constants": "0.1.0",
-    "@zudojs/types": "0.1.0",
-    "@zudojs/schema": "0.1.0"
+    "@zudojs/errors": "1.0.1",
+    "@zudojs/constants": "1.0.1",
+    "@zudojs/types": "1.0.0",
+    "@zudojs/schema": "1.0.1"
   },
   "devDependencies": {
-    "typescript": "^7.0.2",
+    "typescript": "7.0.2",
     "vitest": "^4.1.11"
   },
   "publishConfig": {
@@ -46,8 +46,19 @@
     "procedure"
   ],
   "homepage": "https://github.com/oyinlola-tech/zudo#readme",
+  "bugs": {
+    "url": "https://github.com/oyinlola-tech/zudo/issues"
+  },
   "repository": {
     "type": "git",
-    "url": "https://github.com/oyinlola-tech/zudo"
+    "url": "https://github.com/oyinlola-tech/zudo",
+    "directory": "packages/rpc"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit && tsc -p tsconfig.test.json --noEmit",
+    "clean": "rm -rf dist",
+    "test": "vitest run",
+    "test:watch": "vitest"
   }
-}
+}