@mostra/protocol 0.0.0-stage → 0.1.0

package/src/rpc/error.ts

@@ -0,0 +1,107 @@
+/**
+ * Errors on a JSON-RPC connection. Every error carries a diagnostic (INTERFACES §1, §6): the
+ * JSON-RPC `error.code` says which kind of failure it is, and `error.data` is the diagnostic.
+ */
+import { type HostDiagnosticCode, hostDiagnostics } from "../diagnostics/codes/host.ts";
+import { Diagnostic } from "../diagnostics/diagnostic.ts";
+import { buildDiagnostic, type DiagnosticDetails } from "../diagnostics/spec.ts";
+import type { JsonRpcErrorObject } from "./messages.ts";
+
+/** The JSON-RPC 2.0 error codes Mostra uses (INTERFACES §6). */
+export const JSON_RPC_ERROR_CODES: {
+  /** The line wasn't valid JSON. */
+  readonly parseError: -32700;
+  /** The message wasn't a valid request, or was a batch. */
+  readonly invalidRequest: -32600;
+  /** The method doesn't exist on this side. */
+  readonly methodNotFound: -32601;
+  /** The params failed the method's schema. */
+  readonly invalidParams: -32602;
+  /** An unexpected failure. */
+  readonly internalError: -32603;
+  /** Every other diagnostic. */
+  readonly diagnostic: -32000;
+} = {
+  parseError: -32700,
+  invalidRequest: -32600,
+  methodNotFound: -32601,
+  invalidParams: -32602,
+  internalError: -32603,
+  diagnostic: -32000,
+};
+
+function codeFor(diagnostic: Diagnostic): number {
+  switch (diagnostic.code) {
+    case "MOSTRA_HOST_MALFORMED":
+      return JSON_RPC_ERROR_CODES.invalidRequest;
+    case "MOSTRA_HOST_METHOD_UNKNOWN":
+      return JSON_RPC_ERROR_CODES.methodNotFound;
+    case "MOSTRA_HOST_INVALID_PARAMS":
+      return JSON_RPC_ERROR_CODES.invalidParams;
+    case "MOSTRA_HOST_INTERNAL_ERROR":
+      return JSON_RPC_ERROR_CODES.internalError;
+    default:
+      return JSON_RPC_ERROR_CODES.diagnostic;
+  }
+}
+
+/**
+ * An error that crosses a connection as a JSON-RPC error. Throw it from a request handler to
+ * answer with this diagnostic; a request's promise rejects with it when the other side answers
+ * with an error, the connection closes or the request times out.
+ *
+ * ```ts
+ * throw new RpcError(
+ *   createDiagnostic("MOSTRA_HOME_MISMATCH", { message: "This instance serves /a, not /b." }),
+ * );
+ * ```
+ */
+export class RpcError extends Error {
+  /** The JSON-RPC error code. */
+  readonly code: number;
+  /** The diagnostic: what happened and what to do. */
+  readonly diagnostic: Diagnostic;
+
+  constructor(diagnostic: Diagnostic, code: number = codeFor(diagnostic)) {
+    super(diagnostic.message);
+    this.name = "RpcError";
+    this.code = code;
+    this.diagnostic = diagnostic;
+  }
+
+  /** The JSON-RPC error object for a response. */
+  toErrorObject(): JsonRpcErrorObject {
+    return { code: this.code, message: this.diagnostic.message, data: this.diagnostic };
+  }
+
+  /**
+   * Reads a received error object. When its `data` isn't a diagnostic (a peer that isn't Mostra),
+   * the result is a `MOSTRA_HOST_MALFORMED` diagnostic that keeps the peer's message.
+   */
+  static fromErrorObject(error: JsonRpcErrorObject, docsBase?: string): RpcError {
+    const parsed = Diagnostic.safeParse(error.data);
+    if (parsed.success) return new RpcError(parsed.data, error.code);
+    return new RpcError(
+      hostDiagnostic(
+        "MOSTRA_HOST_MALFORMED",
+        {
+          message: `The other side answered with error ${error.code} without a diagnostic: ${error.message.slice(0, 200)}`,
+        },
+        docsBase,
+      ),
+      error.code,
+    );
+  }
+}
+
+/**
+ * Builds a HOST-area diagnostic from that area's catalog alone, so the JSON-RPC core doesn't pull
+ * every area's text into browser bundles (D83).
+ */
+export function hostDiagnostic(
+  code: HostDiagnosticCode,
+  details: DiagnosticDetails,
+  docsBase?: string,
+): Diagnostic {
+  return buildDiagnostic(code, hostDiagnostics[code], details, docsBase);
+}

package/src/rpc/lines.ts

@@ -0,0 +1,70 @@
+/**
+ * Newline-delimited JSON framing for byte streams (stdio, Unix sockets): one message per line.
+ * JSON text never contains a raw newline, so a newline always ends a message.
+ */
+import type { JsonRpcMessage } from "./messages.ts";
+
+/**
+ * The longest line, in UTF-16 code units, either side of a newline-delimited connection accepts:
+ * 64 Mi. Writers check it too, so a message that couldn't be read is never sent.
+ */
+export const MAX_LINE_LENGTH: number = 64 * 1024 * 1024;
+
+/** Serializes one message as a line, newline included. */
+export function encodeLine(message: JsonRpcMessage): string {
+  return `${JSON.stringify(message)}\n`;
+}
+
+/**
+ * Splits decoded text into lines. Feed it chunks as they arrive; it returns the complete lines
+ * and keeps the unfinished rest. A line longer than `maxLineLength` characters throws a
+ * `RangeError`, so a peer can't make the other side buffer without bound: the transport then
+ * answers with `MOSTRA_HOST_MALFORMED` and closes the connection.
+ */
+export class LineSplitter {
+  readonly #maxLineLength: number;
+  /** The unfinished line, in the pieces it arrived in: joined only once its newline comes. */
+  #pending: string[] = [];
+  #pendingLength = 0;
+
+  /** @param maxLineLength - The longest line accepted, in UTF-16 code units. Default 64 Mi. */
+  constructor(maxLineLength: number = MAX_LINE_LENGTH) {
+    this.#maxLineLength = maxLineLength;
+  }
+
+  /**
+   * Returns the lines completed by `chunk`, without their newlines (and without a trailing `\r`).
+   * Only `chunk` is searched for newlines, so a long line costs time in proportion to its length,
+   * however many chunks bring it.
+   */
+  push(chunk: string): string[] {
+    const lines: string[] = [];
+    let start = 0;
+    for (let index = chunk.indexOf("\n"); index >= 0; index = chunk.indexOf("\n", start)) {
+      if (this.#pendingLength + index - start > this.#maxLineLength) this.#overflow();
+      this.#pending.push(chunk.slice(start, index));
+      const line = this.#pending.join("");
+      this.#pending = [];
+      this.#pendingLength = 0;
+      lines.push(line.endsWith("\r") ? line.slice(0, -1) : line);
+      start = index + 1;
+    }
+    if (start < chunk.length) {
+      this.#pendingLength += chunk.length - start;
+      if (this.#pendingLength > this.#maxLineLength) this.#overflow();
+      this.#pending.push(chunk.slice(start));
+    }
+    return lines;
+  }
+
+  /** The unfinished text after the last newline. A stream that ends with it holds a cut-off message. */
+  get rest(): string {
+    return this.#pending.join("");
+  }
+
+  #overflow(): never {
+    this.#pending = [];
+    this.#pendingLength = 0;
+    throw new RangeError(`A message is longer than ${this.#maxLineLength} characters.`);
+  }
+}

package/src/rpc/messages.ts

@@ -0,0 +1,188 @@
+/**
+ * JSON-RPC 2.0 message shapes (D59, D83). Every Mostra connection carries these: the host protocol
+ * over stdio or the home socket, child-process messaging and the shell bridge. Revision
+ * `2026-10-10` has no batches.
+ */
+import * as z from "zod";
+import { wireRegistry } from "../wire-registry.ts";
+
+/** A request ID: a string or a number, chosen by the sender and echoed in the response. */
+export type JsonRpcId = string | number;
+
+/** Request params: a JSON object (Mostra always uses objects) or an array. */
+export type JsonRpcParams = Readonly<Record<string, unknown>> | readonly unknown[];
+
+/** A request: the receiver answers with a response carrying the same `id`. */
+export interface JsonRpcRequest {
+  /** Always `"2.0"`. */
+  readonly jsonrpc: "2.0";
+  /** Chosen by the sender; the response carries the same ID. */
+  readonly id: JsonRpcId;
+  /** The method name, `group/name` or a bare name. */
+  readonly method: string;
+  /** The method's params. */
+  readonly params?: JsonRpcParams;
+}
+
+/** A notification: a request without an `id`, which is never answered. */
+export interface JsonRpcNotification {
+  /** Always `"2.0"`. */
+  readonly jsonrpc: "2.0";
+  /** The notification's method name. */
+  readonly method: string;
+  /** The notification's params. */
+  readonly params?: JsonRpcParams;
+}
+
+/** The error member of a failed response. Mostra puts the diagnostic in `data`. */
+export interface JsonRpcErrorObject {
+  /** The JSON-RPC error code (INTERFACES §6). */
+  readonly code: number;
+  /** A short description; clients switch on `data.code`, never on this text. */
+  readonly message: string;
+  /** The diagnostic (INTERFACES §13). */
+  readonly data?: unknown;
+}
+
+/** A successful response. */
+export interface JsonRpcSuccess {
+  /** Always `"2.0"`. */
+  readonly jsonrpc: "2.0";
+  /** The ID of the request this answers. */
+  readonly id: JsonRpcId;
+  /** The method's result. */
+  readonly result: unknown;
+}
+
+/** A failed response. `id` is `null` when the request's ID couldn't be read. */
+export interface JsonRpcFailure {
+  /** Always `"2.0"`. */
+  readonly jsonrpc: "2.0";
+  /** The ID of the request this answers, or `null` when it couldn't be read. */
+  readonly id: JsonRpcId | null;
+  /** What went wrong. */
+  readonly error: JsonRpcErrorObject;
+}
+
+/** A response to a request. */
+export type JsonRpcResponse = JsonRpcSuccess | JsonRpcFailure;
+
+/** Any message on a Mostra connection. */
+export type JsonRpcMessage = JsonRpcRequest | JsonRpcNotification | JsonRpcResponse;
+
+const version = z.literal("2.0");
+const id: z.ZodType<JsonRpcId> = z.union([z.string(), z.number()]);
+const params: z.ZodType<JsonRpcParams> = z.union([
+  z.record(z.string(), z.unknown()),
+  z.array(z.unknown()).readonly(),
+]);
+
+/** The Zod schema of the `JsonRpcRequest` type. */
+export const JsonRpcRequest: z.ZodType<JsonRpcRequest> = z
+  .object({ jsonrpc: version, id, method: z.string(), params: params.exactOptional() })
+  .register(wireRegistry, {
+    id: "JsonRpcRequest",
+    description: "A JSON-RPC 2.0 request: answered by a response with the same id.",
+  });
+
+/** The Zod schema of the `JsonRpcNotification` type. */
+export const JsonRpcNotification: z.ZodType<JsonRpcNotification> = z
+  .object({ jsonrpc: version, method: z.string(), params: params.exactOptional() })
+  .register(wireRegistry, {
+    id: "JsonRpcNotification",
+    description: "A JSON-RPC 2.0 notification: a request without an id, never answered.",
+  });
+
+/** The Zod schema of the `JsonRpcErrorObject` type. */
+export const JsonRpcErrorObject: z.ZodType<JsonRpcErrorObject> = z
+  .object({ code: z.int(), message: z.string(), data: z.unknown().exactOptional() })
+  .register(wireRegistry, {
+    id: "JsonRpcErrorObject",
+    description: "The error of a failed JSON-RPC 2.0 response; Mostra puts the diagnostic in data.",
+  });
+
+/** The Zod schema of the `JsonRpcSuccess` type. */
+export const JsonRpcSuccess: z.ZodType<JsonRpcSuccess> = z
+  .object({ jsonrpc: version, id, result: z.unknown() })
+  .register(wireRegistry, {
+    id: "JsonRpcSuccess",
+    description: "A successful JSON-RPC 2.0 response.",
+  });
+
+/** The Zod schema of the `JsonRpcFailure` type. */
+export const JsonRpcFailure: z.ZodType<JsonRpcFailure> = z
+  .object({ jsonrpc: version, id: id.nullable(), error: JsonRpcErrorObject })
+  .register(wireRegistry, {
+    id: "JsonRpcFailure",
+    description: "A failed JSON-RPC 2.0 response; id is null when the request's id was unreadable.",
+  });
+
+/** A message sorted by kind, or the reason it isn't a valid message. */
+export type ClassifiedMessage =
+  | { readonly kind: "request"; readonly message: JsonRpcRequest }
+  | { readonly kind: "notification"; readonly message: JsonRpcNotification }
+  | { readonly kind: "success"; readonly message: JsonRpcSuccess }
+  | { readonly kind: "failure"; readonly message: JsonRpcFailure }
+  | { readonly kind: "invalid"; readonly reason: string; readonly id: JsonRpcId | null };
+
+const isObject = (value: unknown): value is Record<string, unknown> =>
+  typeof value === "object" && value !== null && !Array.isArray(value);
+
+/**
+ * Sorts a parsed JSON value into a request, notification, success or failure, or explains why it
+ * is none of them. A JSON array (a batch) is invalid in revision `2026-10-10` (D83).
+ */
+export function classifyMessage(value: unknown): ClassifiedMessage {
+  if (Array.isArray(value)) {
+    return {
+      kind: "invalid",
+      reason: "Batches (JSON arrays) aren't supported in host protocol revision 2026-10-10.",
+      id: null,
+    };
+  }
+  if (!isObject(value)) {
+    return { kind: "invalid", reason: "A message must be a JSON object.", id: null };
+  }
+  const rawId = value["id"];
+  const readableId = typeof rawId === "string" || typeof rawId === "number" ? rawId : null;
+  if (value["jsonrpc"] !== "2.0") {
+    return { kind: "invalid", reason: 'A message must have "jsonrpc": "2.0".', id: readableId };
+  }
+  if ("method" in value) {
+    if ("id" in value) {
+      const parsed = JsonRpcRequest.safeParse(value);
+      return parsed.success
+        ? { kind: "request", message: parsed.data }
+        : { kind: "invalid", reason: describeRequestProblem(value), id: readableId };
+    }
+    const parsed = JsonRpcNotification.safeParse(value);
+    return parsed.success
+      ? { kind: "notification", message: parsed.data }
+      : { kind: "invalid", reason: describeRequestProblem(value), id: null };
+  }
+  const hasResult = "result" in value;
+  const hasError = "error" in value;
+  if (hasResult !== hasError && "id" in value) {
+    if (hasResult) {
+      const parsed = JsonRpcSuccess.safeParse(value);
+      if (parsed.success) return { kind: "success", message: parsed.data };
+    } else {
+      const parsed = JsonRpcFailure.safeParse(value);
+      if (parsed.success) return { kind: "failure", message: parsed.data };
+    }
+  }
+  return {
+    kind: "invalid",
+    reason:
+      'A message must be a request (with "method") or a response (with "id" and exactly one of "result" and "error").',
+    id: readableId,
+  };
+}
+
+function describeRequestProblem(value: Record<string, unknown>): string {
+  if (typeof value["method"] !== "string") return 'A request\'s "method" must be a string.';
+  if ("id" in value && typeof value["id"] !== "string" && typeof value["id"] !== "number") {
+    return 'A request\'s "id" must be a string or a number.';
+  }
+  return 'A request\'s "params" must be an object or an array.';
+}