@swimmesberger/elarion-jsonrpc-client-generator 0.2.21 → 0.2.22-preview.191.1

package/README.md

@@ -87,7 +87,9 @@ When the schema carries an `events` block (the host registers Elarion client-eve
 additionally emits `events-client.ts`: `createElarionEvents(...)` multiplexes topic-typed subscriptions over one
 `EventSource`, validates incoming payloads with the generated Zod schemas (`rpcEventPayloadSchemas`), and exposes
 `$client.onConnected(...)` — fired on connect and every reconnect — as the "you may have missed events, re-query"
-signal. Event-free schemas produce byte-identical output with no events file.
+signal. The platform `EventSource` stops retrying when an answer is not a 200 event stream (a 401, a login page, a
+502 during a restart), so the client reopens such a connection itself, backing off from 1 s to 30 s
+(`reconnectDelay`). Event-free schemas produce byte-identical output with no events file.
 
 ```ts
 import { createElarionEvents } from './generated/events-client'

package/dist/events-client-source.js

@@ -23,6 +23,8 @@ export function generateEventsClientSource(options) {
         'export interface ElarionEventSourceLike {',
         '  addEventListener(type: string, listener: (event: { readonly data?: unknown }) => void): void',
         '  close(): void',
+        '  // 2 (CLOSED) once the source gave up for good; a source without it is never reconnected by the client.',
+        '  readonly readyState?: number',
         '}',
         '',
         'export type ElarionEventSourceFactory = (url: string) => ElarionEventSourceLike',
@@ -35,6 +37,9 @@ export function generateEventsClientSource(options) {
         '  readonly validateEvents?: boolean',
         '  // Called when an incoming event cannot be parsed or validated; the event is dropped either way.',
         '  readonly onEventError?: (topic: RpcEventTopic, error: unknown) => void',
+        '  // Milliseconds to wait before reopening a connection the platform EventSource gave up on, by attempt',
+        '  // (0-based, reset by every elarion.connected). Defaults to 1 s doubling up to 30 s.',
+        '  readonly reconnectDelay?: (attempt: number) => number',
         '}',
         '',
         'export interface ElarionEventSubscribeOptions {',
@@ -76,6 +81,8 @@ export function generateEventsClientSource(options) {
         '] as const satisfies readonly RpcEventTopic[]',
         '',
         "const CONNECTED_EVENT_TYPE = 'elarion.connected'",
+        '// EventSource.CLOSED — a literal, so the client needs no EventSource global to compare against.',
+        'const EVENT_SOURCE_CLOSED = 2',
         '',
         'interface EventSubscriptionEntry {',
         '  readonly topic: RpcEventTopic',
@@ -102,11 +109,14 @@ export function generateEventsClientSource(options) {
         'export function createElarionEventsClient(options: ElarionEventsOptions): ElarionEventsClient {',
         '  const createSource = options.eventSource ?? defaultEventSourceFactory',
         '  const validateEvents = options.validateEvents ?? true',
+        '  const reconnectDelay = options.reconnectDelay ?? defaultReconnectDelay',
         '',
         '  const subscriptions = new Map<string, EventSubscriptionEntry>()',
         '  const connectedHandlers = new Set<() => void>()',
         '  let source: ElarionEventSourceLike | undefined',
         '  let reconnectScheduled = false',
+        '  let retryTimer: ReturnType<typeof setTimeout> | undefined',
+        '  let failedAttempts = 0',
         '  let closed = false',
         '',
         '  // Subscription changes coalesce onto a microtask, so subscribing N topics during setup opens one',
@@ -120,7 +130,25 @@ export function generateEventsClientSource(options) {
         '    })',
         '  }',
         '',
+        '  // The platform EventSource retries a dropped connection by itself, but fails it for good (readyState',
+        '  // CLOSED, no further retries) when the answer is not a 200 event stream: an expired session\'s 401 or',
+        '  // login page, a 502 while the server restarts. Without a retry here the client would stay silent until',
+        '  // the page reloads.',
+        '  function scheduleRetry(): void {',
+        '    if (retryTimer !== undefined || closed) return',
+        '    const delay = reconnectDelay(failedAttempts)',
+        '    failedAttempts += 1',
+        '    retryTimer = setTimeout(() => {',
+        '      retryTimer = undefined',
+        '      if (!closed) connect()',
+        '    }, delay)',
+        '  }',
+        '',
         '  function connect(): void {',
+        '    if (retryTimer !== undefined) {',
+        '      clearTimeout(retryTimer)',
+        '      retryTimer = undefined',
+        '    }',
         '    source?.close()',
         '    source = undefined',
         '    if (subscriptions.size === 0) return',
@@ -134,8 +162,12 @@ export function generateEventsClientSource(options) {
         '      next.addEventListener(topic, (event) => dispatch(topic, event))',
         '    }',
         '    next.addEventListener(CONNECTED_EVENT_TYPE, () => {',
+        '      failedAttempts = 0',
         '      for (const handler of [...connectedHandlers]) handler()',
         '    })',
+        "    next.addEventListener('error', () => {",
+        '      if (source === next && next.readyState === EVENT_SOURCE_CLOSED) scheduleRetry()',
+        '    })',
         '    source = next',
         '  }',
         '',
@@ -208,6 +240,8 @@ export function generateEventsClientSource(options) {
         '    },',
         '    close(): void {',
         '      closed = true',
+        '      if (retryTimer !== undefined) clearTimeout(retryTimer)',
+        '      retryTimer = undefined',
         '      source?.close()',
         '      source = undefined',
         '      subscriptions.clear()',
@@ -216,6 +250,10 @@ export function generateEventsClientSource(options) {
         '  }',
         '}',
         '',
+        'function defaultReconnectDelay(attempt: number): number {',
+        '  return Math.min(30_000, 1_000 * 2 ** attempt)',
+        '}',
+        '',
         'function defaultEventSourceFactory(url: string): ElarionEventSourceLike {',
         '  const ctor = (globalThis as { EventSource?: new (url: string) => ElarionEventSourceLike }).EventSource',
         '  if (!ctor) {',

package/dist/generate.js

@@ -126,6 +126,24 @@ export function generateRpcClientFiles(schema, options = {}) {
         }
     }
     const idempotentMethods = methods.filter((method) => schema.methods[method].idempotent === true);
+    // Every method's client-visible facts, normalized so a consumer never has to tell "absent" from "false".
+    const methodInfo = {};
+    for (const method of methods) {
+        const definition = schema.methods[method];
+        const requires = definition.requires ?? {};
+        methodInfo[method] = {
+            readOnly: definition.readOnly === true,
+            idempotent: definition.idempotent === true,
+            requires: {
+                anonymous: requires.anonymous === true,
+                authenticated: requires.authenticated === true,
+                permissions: [...(requires.permissions ?? [])].sort(),
+                roles: [...(requires.roles ?? [])].sort(),
+                serverChecks: requires.serverChecks === true,
+            },
+            tags: Object.fromEntries(Object.entries(definition.tags ?? {}).sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))),
+        };
+    }
     // Where each method carries file payloads (x-elarion-file nodes), so the client can convert between
     // native File values and the base64 wire envelope. Methods without files are omitted entirely.
     const paramsFilePaths = {};
@@ -148,6 +166,7 @@ export function generateRpcClientFiles(schema, options = {}) {
         schemasFileName,
         methods,
         idempotentMethods,
+        methodInfo,
         errorCodesByMethod,
         paramsFilePaths,
         resultFilePaths,

package/dist/rpc-client-source.d.ts

@@ -1,3 +1,16 @@
+/** The normalized client-visible facts of one method, emitted verbatim into `rpcMethodInfo`. */
+export interface RpcMethodInfoLiteral {
+    readOnly: boolean;
+    idempotent: boolean;
+    requires: {
+        anonymous: boolean;
+        authenticated: boolean;
+        permissions: string[];
+        roles: string[];
+        serverChecks: boolean;
+    };
+    tags: Record<string, string>;
+}
 interface GenerateRpcClientSourceOptions {
     generatedBy: string;
     sourceLabel: string;
@@ -5,6 +18,8 @@ interface GenerateRpcClientSourceOptions {
     schemasFileName: string;
     methods: readonly string[];
     idempotentMethods: readonly string[];
+    /** Every method's normalized requirements, read-only flag and tags. */
+    methodInfo: Readonly<Record<string, RpcMethodInfoLiteral>>;
     /** The declared error codes per method (ADR-0080); methods without declared errors are omitted. */
     errorCodesByMethod: Readonly<Record<string, readonly string[]>>;
     /** Property paths of file payloads per method ('*' = array items, [] = the value itself); omitted methods carry none. */

package/dist/rpc-client-source.js

@@ -120,6 +120,39 @@ export function generateRpcClientSource(options) {
         ...generateMethodNameLines(options.methods),
         `const rpcIdempotentMethods: ReadonlySet<RpcMethod> = new Set(${JSON.stringify(options.idempotentMethods)})`,
         '',
+        '/**',
+        ' * What a caller needs, as far as a client can tell: `anonymous` (any caller), or `authenticated` with every',
+        ' * permission and role listed. `serverChecks` marks requirements only the server evaluates (a policy, claim or',
+        ' * resource check), so an allowed-looking call may still be refused.',
+        ' */',
+        'export interface RpcMethodRequirements {',
+        '  readonly anonymous: boolean',
+        '  readonly authenticated: boolean',
+        '  readonly permissions: readonly string[]',
+        '  readonly roles: readonly string[]',
+        '  readonly serverChecks: boolean',
+        '}',
+        '',
+        '/** What the schema says about a method before it is called. */',
+        'export interface RpcMethodInfo {',
+        '  /** The request is a query: the operation only reads. */',
+        '  readonly readOnly: boolean',
+        '  /** The operation is [Idempotent]: the client attaches an idempotency key by default. */',
+        '  readonly idempotent: boolean',
+        '  readonly requires: RpcMethodRequirements',
+        '  /** The handler\'s [ClientTag] hints (for example a timeout) by key. */',
+        '  readonly tags: Readonly<Record<string, string>>',
+        '}',
+        '',
+        '/**',
+        ' * Every method\'s requirements, read-only flag and tags, from the server\'s handler declarations — the input of',
+        ' * UI gating (for example canCall from @swimmesberger/elarion-contributions). A UX projection, never security:',
+        ' * the server authorizes every call.',
+        ' */',
+        'export const rpcMethodInfo: { readonly [M in RpcMethod]: RpcMethodInfo } = {',
+        ...options.methods.map((method) => `  ${JSON.stringify(method)}: ${JSON.stringify(options.methodInfo[method])},`),
+        '}',
+        '',
         `const rpcErrorCodes: Partial<Record<RpcMethod, readonly string[]>> = ${JSON.stringify(options.errorCodesByMethod)}`,
         '',
         '/** True when `error` is an RpcError carrying one of the error codes `method` declares. */',
@@ -180,6 +213,11 @@ export function generateRpcClientSource(options) {
         '  readonly data: TData',
         '  /** The numeric JSON-RPC error code (the coarse error kind, see ElarionErrorCodes). */',
         '  readonly rpcCode: number',
+        '  /**',
+        '   * The support reference of an unexpected server error (code "internal"): show it next to the message so a',
+        '   * user can quote it. Undefined for every other error.',
+        '   */',
+        '  readonly reference: string | undefined',
         '',
         '  constructor(rpcCode: number, message: string, wireData?: unknown) {',
         '    super(message)',
@@ -188,6 +226,7 @@ export function generateRpcClientSource(options) {
         '    const envelope = readErrorData(wireData)',
         '    this.code = (envelope?.code ?? defaultErrorCode(rpcCode)) as TCode',
         '    this.data = envelope?.data as TData',
+        '    this.reference = envelope?.reference',
         '  }',
         '',
         '  get isParseError() {',
@@ -677,10 +716,11 @@ export function generateRpcClientSource(options) {
         '  return rpcError',
         '}',
         '',
-        '// The wire shape of error.data is always { code, data? } (ADR-0080).',
-        'function readErrorData(value: unknown): { code: string; data?: unknown } | undefined {',
+        '// The wire shape of error.data is always { code, data?, reference? } (ADR-0080).',
+        'function readErrorData(value: unknown): { code: string; data?: unknown; reference?: string | undefined } | undefined {',
         '  if (!isRecord(value) || typeof value.code !== ' + "'string'" + ') return undefined',
-        '  return { code: value.code, data: value.data }',
+        "  const reference = typeof value.reference === 'string' ? value.reference : undefined",
+        '  return { code: value.code, data: value.data, reference }',
         '}',
         '',
         '// Fallback for a server that sends no error.data: the default code of the numeric kind.',

package/dist/schema.d.ts

@@ -47,6 +47,24 @@ export interface RpcMethodSchema {
     /** The declared error contract, keyed by stable error code; omitted when the method declares none. */
     errors?: Record<string, RpcErrorSchema>;
     idempotent?: boolean;
+    /** What a caller needs, as far as a client can tell; omitted when the handler declares nothing. */
+    requires?: RpcMethodRequirementsSchema;
+    /** Set when the request is an IQuery: the operation only reads. */
+    readOnly?: boolean;
+    /** The handler's [ClientTag] hints by key; omitted when it declares none. */
+    tags?: Record<string, string>;
+}
+/**
+ * The per-method `requires` block of the server exporter: `anonymous` alone, or the requirements a client can
+ * evaluate against its session (`authenticated`, `permissions`, `roles`, all of them) plus `serverChecks` for
+ * requirements only the server can evaluate (a policy, claim or resource check).
+ */
+export interface RpcMethodRequirementsSchema {
+    anonymous?: boolean;
+    authenticated?: boolean;
+    permissions?: string[];
+    roles?: string[];
+    serverChecks?: boolean;
 }
 /** One structured permission from the schema's capability vocabulary ({resource}.{verb} plus its parts). */
 export interface RpcCapabilityPermission {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@swimmesberger/elarion-jsonrpc-client-generator",
-  "version": "0.2.21",
+  "version": "0.2.22-preview.191.1",
   "description": "Generate TypeScript RPC contracts, Zod schemas, and a fetch client from Elarion JSON-RPC schema exports.",
   "license": "Apache-2.0",
   "type": "module",