JSON-RPC error infrastructure for fuz_app routes.
Provides error types, named constructors, and HTTP status mapping
for the throw/catch error pattern used by apply_route_specs.
Core error codes (5 standard + 10 general application). Domain-specific
codes stay in consumers — add by casting as JsonrpcErrorCode.
JsonrpcErrorCode and JsonrpcErrorObject types are Zod-inferred from http/jsonrpc.ts — this module re-uses those as the single source of truth.
Complementary to http/error_schemas.ts: that module is declarative (Zod schemas for surface introspection), this one is runtime (throw + catch + map).
12 declarations
http/jsonrpc_errors.ts view source
(status: number): -32700 | -32600 | -32601 | -32602 | -32603 | (number & $brand<"JsonrpcServerErrorCode">) import {http_status_to_jsonrpc_error_code} from '@fuzdev/fuz_app/http/jsonrpc_errors.js'; Map an HTTP status code to a JSON-RPC error code.
Returns internal_error (-32603) for unrecognized status codes.
statusnumberhttp/jsonrpc_errors.ts view source
Record<number, -32700 | -32600 | -32601 | -32602 | -32603 | (number & $brand<"JsonrpcServerErrorCode">)> type Record<number, JsonrpcErrorCode>
import {HTTP_STATUS_TO_JSONRPC_ERROR_CODE} from '@fuzdev/fuz_app/http/jsonrpc_errors.js'; Maps HTTP status codes to JSON-RPC error codes (reverse mapping).
When multiple error codes map to the same HTTP status (e.g. parse_error and invalid_request both map to 400), the last one wins. Use for best-effort HTTP → JSON-RPC translation.
http/jsonrpc_errors.ts view source
(code: -32700 | -32600 | -32601 | -32602 | -32603 | (number & $brand<"JsonrpcServerErrorCode">)): ContentfulStatusCode import {jsonrpc_error_code_to_http_status} from '@fuzdev/fuz_app/http/jsonrpc_errors.js'; Map a JSON-RPC error code to an HTTP status code.
Returns 500 for unrecognized codes (consumer-defined codes
without a mapping default to internal server error). The return
is narrowed to Hono's ContentfulStatusCode so call sites can
pass the result to c.json(body, status) without as any —
499 (nginx "client closed request") is non-standard and gets
absorbed by the cast here rather than at every dispatcher branch.
codeContentfulStatusCode
http/jsonrpc_errors.ts view source
Record<number, number> type Record<number, number>
import {JSONRPC_ERROR_CODE_TO_HTTP_STATUS} from '@fuzdev/fuz_app/http/jsonrpc_errors.js'; Maps JSON-RPC error codes to HTTP status codes.
Extensible — consumers with domain-specific error codes assign directly
(JSONRPC_ERROR_CODE_TO_HTTP_STATUS[-32020] = 502) at module load. The
lookup function reads at call time, so mutation is the supported
extension mechanism.
http/jsonrpc_errors.ts view source
(code: -32700 | -32600 | -32601 | -32602 | -32603 | (number & $brand<"JsonrpcServerErrorCode">)): JsonrpcErrorName import {jsonrpc_error_code_to_name} from '@fuzdev/fuz_app/http/jsonrpc_errors.js'; Map a JSON-RPC error code to its canonical name ('not_found',
'forbidden', etc.). Falls back to 'internal_error' for codes
outside the standard taxonomy so REST emitters that read this for
their error field always have a stable string to emit.
codehttp/jsonrpc_errors.ts view source
Readonly<Record<number, JsonrpcErrorName>> type Readonly<Record<number, JsonrpcErrorName>>
import {JSONRPC_ERROR_CODE_TO_NAME} from '@fuzdev/fuz_app/http/jsonrpc_errors.js'; Reverse map of JSONRPC_ERROR_CODES — JSON-RPC error code → name.
Used by REST emitters that need a stable string identifier for the
code in their flat-shape error body ({error: '<name>', ...})
without inventing a separate vocabulary. Built once at module load
from the canonical JSONRPC_ERROR_CODES map so the two cannot drift.
Consumer-defined codes outside the standard taxonomy are not present;
jsonrpc_error_code_to_name falls back to 'internal_error' so the
REST shape always carries some reason rather than undefined.
http/jsonrpc_errors.ts view source
Readonly<Record<JsonrpcErrorName, -32700 | -32600 | -32601 | -32602 | -32603 | (number & $brand<"JsonrpcServerErrorCode">)>> type Readonly<Record<JsonrpcErrorName, -32700 | -32600 | -32601 | -32602 | -32603 | (number & $brand<"JsonrpcServerErrorCode">)>>
import {JSONRPC_ERROR_CODES} from '@fuzdev/fuz_app/http/jsonrpc_errors.js'; Standard JSON-RPC error codes (5) plus general application codes (10).
Extensible — consumers add domain-specific codes to their own objects
by casting as JsonrpcErrorCode. Application codes use the -32000 to
-32099 range reserved by the JSON-RPC spec.
Frozen with Object.freeze to convert accidental mutation (test
cross-contamination, cast escapes) into loud TypeErrors. Spread into
a fresh object to extend.
http/jsonrpc_errors.ts view source
Readonly<Record<JsonrpcErrorName, (...args: any[]) => { [x: string]: unknown; code: -32700 | -32600 | -32601 | -32602 | -32603 | (number & $brand<"JsonrpcServerErrorCode">); message: string; data?: unknown; }>> type Readonly<Record<JsonrpcErrorName, (...args: any[]) => { [x: string]: unknown; code: -32700 | -32600 | -32601 | -32602 | -32603 | (number & $brand<"JsonrpcServerErrorCode">); message: string; data?: unknown; }>>
import {jsonrpc_error_messages} from '@fuzdev/fuz_app/http/jsonrpc_errors.js'; Named constructors for JsonrpcErrorObject values.
Each function creates a JSON-RPC error object with the correct code and a sensible default message. Used by the catch layer in apply_route_specs to build response bodies.
Frozen so tests must compose new objects rather than monkey-patch.
http/jsonrpc_errors.ts view source
{ readonly parse_error: (...args: any[]) => ThrownJsonrpcError; readonly invalid_request: (...args: any[]) => ThrownJsonrpcError; readonly method_not_found: (...args: any[]) => ThrownJsonrpcError; ... 11 more ...; readonly request_cancelled: (...args: any[]) => ThrownJsonrpcError; } import {jsonrpc_errors} from '@fuzdev/fuz_app/http/jsonrpc_errors.js'; Named constructors for ThrownJsonrpcError.
Usage: throw jsonrpc_errors.not_found('user') or throw jsonrpc_errors.forbidden().
http/jsonrpc_errors.ts view source
JsonrpcErrorName type "parse_error" | "invalid_request" | "method_not_found" | "invalid_params" | "internal_error" | "unauthenticated" | "forbidden" | "not_found" | "conflict" | "validation_error" | "rate_limited" | "service_unavailable" | "timeout" | "queue_overflow" | "request_cancelled"
import type {JsonrpcErrorName} from '@fuzdev/fuz_app/http/jsonrpc_errors.js'; Names of standard and general application JSON-RPC error codes.
http/jsonrpc_errors.ts view source
import {ThrownJsonrpcError} from '@fuzdev/fuz_app/http/jsonrpc_errors.js'; Error class carrying a JSON-RPC error code — thrown by handlers, caught by apply_route_specs and mapped to HTTP status + JSON-RPC error response.
Named for what it is: an error with a JSON-RPC error code that gets thrown.
Errorcodetype JsonrpcErrorCode
data?type unknown
constructortype new (code: -32700 | -32600 | -32601 | -32602 | -32603 | (number & $brand<"JsonrpcServerErrorCode">), message: string, data?: unknown, options?: ErrorOptions | undefined): ThrownJsonrpcError
codemessagestringdata?unknownoptions?ErrorOptionshttp/jsonrpc_errors.ts view source
"unknown error" import {UNKNOWN_ERROR_MESSAGE} from '@fuzdev/fuz_app/http/jsonrpc_errors.js'; Default message for unknown errors.