@enkaku/client 0.14.3 → 0.14.4

package/lib/client.d.ts

@@ -4,6 +4,7 @@ import { type Tracer } from '@enkaku/otel';
 import type { AnyProcedureDefinition, AnyRequestProcedureDefinition, ChannelProcedureDefinition, ClientTransportOf, DataOf, EventProcedureDefinition, ProtocolDefinition, RequestProcedureDefinition, RequestType, ReturnOf, StreamProcedureDefinition } from '@enkaku/protocol';
 import { type Runtime } from '@enkaku/runtime';
 import { type Identity } from '@enkaku/token';
+import type { ClientEmitter } from './events.js';
 type FilterNever<T> = {
     [K in keyof T as T[K] extends never ? never : K]: T[K];
 };
@@ -80,6 +81,7 @@ export type ClientParams<Protocol extends ProtocolDefinition> = {
 export declare class Client<Protocol extends ProtocolDefinition, ClientDefinitions extends ClientDefinitionsType<Protocol> = ClientDefinitionsType<Protocol>> extends Disposer {
     #private;
     constructor(params: ClientParams<Protocol>);
+    get events(): ClientEmitter;
     sendEvent<Procedure extends keyof ClientDefinitions['Events'] & string, T extends ClientDefinitions['Events'][Procedure] = ClientDefinitions['Events'][Procedure]>(procedure: Procedure, ...args: T['Data'] extends never ? [config?: {
         data?: never;
         header?: AnyHeader;

package/lib/client.js

@@ -1,10 +1,12 @@
 import { Disposer, defer } from '@enkaku/async';
+import { EventEmitter } from '@enkaku/event';
 import { getEnkakuLogger } from '@enkaku/log';
 import { AttributeKeys, createTracer, injectTraceContext as otelInjectTraceContext, SpanNames, SpanStatusCode, setSpanOnContext, withActiveContext, withSpan } from '@enkaku/otel';
 import { createRuntime } from '@enkaku/runtime';
 import { createPipe, writeTo } from '@enkaku/stream';
 import { createUnsignedToken, isSigningIdentity } from '@enkaku/token';
 import { RequestError } from './error.js';
+import { safeWrite } from './safe-write.js';
 const defaultTracer = createTracer('client');
 function createController(params, onDone) {
     const deferred = defer();
@@ -73,11 +75,18 @@ export class Client extends Disposer {
     #logger;
     #tracer;
     #transport;
+    #events = new EventEmitter();
     constructor(params){
         super({
             dispose: async (reason)=>{
+                await this.#events.emit('disposing', {
+                    reason
+                });
                 this.#abortControllers(reason);
                 await this.#transport.dispose(reason);
+                await this.#events.emit('disposed', {
+                    reason
+                });
                 this.#logger.debug('disposed');
             }
         });
@@ -96,10 +105,11 @@ export class Client extends Disposer {
         this.#setupTransport();
     }
     #abortControllers(reason) {
-        if (!this.signal.aborted) {
-            for (const controller of Object.values(this.#controllers)){
-                controller.abort(reason);
-            }
+        // Runs during dispose (where this.signal is already aborted by the base
+        // Disposer) and on transport replacement. Clearing the map after the loop
+        // makes re-entry a no-op, so no guard is needed.
+        for (const controller of Object.values(this.#controllers)){
+            controller.abort(reason);
         }
         this.#controllers = {};
     }
@@ -118,18 +128,23 @@ export class Client extends Disposer {
                 // Abort running procedures and start using new transport
                 this.#abortControllers('TransportDisposed');
                 this.#transport = newTransport;
+                this.#events.emit('transportReplaced', {});
                 this.#setupTransport();
             }
         });
         this.#read();
     }
-    #endSpanOnResult(span, result, rid) {
+    #endSpanOnResult(span, result, meta) {
         result.then(()=>{
             span.setStatus({
                 code: SpanStatusCode.OK
             });
             span.end();
-            if (rid != null) delete this.#spans[rid];
+            this.#events.emit('requestEnd', {
+                ...meta,
+                status: 'ok'
+            });
+            delete this.#spans[meta.rid];
         }, (error)=>{
             if (error instanceof RequestError) {
                 span.setAttribute(AttributeKeys.ERROR_CODE, error.code);
@@ -141,7 +156,12 @@ export class Client extends Disposer {
             });
             span.recordException(error instanceof Error ? error : new Error(String(error)));
             span.end();
-            if (rid != null) delete this.#spans[rid];
+            const status = error === 'Close' || error?.name === 'AbortError' ? 'aborted' : 'error';
+            this.#events.emit('requestEnd', {
+                ...meta,
+                status
+            });
+            delete this.#spans[meta.rid];
         });
     }
     async #read() {
@@ -163,6 +183,9 @@ export class Client extends Disposer {
                 const error = new Error('Transport read failed', {
                     cause
                 });
+                this.#events.emit('transportError', {
+                    error
+                });
                 const newTransport = this.#handleTransportError?.(error);
                 if (newTransport == null) {
                     this.#logger.warn('aborting following unhanded transport error');
@@ -173,6 +196,7 @@ export class Client extends Disposer {
                     // Abort running procedures and start using new transport
                     this.#abortControllers(error);
                     this.#transport = newTransport;
+                    this.#events.emit('transportReplaced', {});
                     this.#setupTransport();
                 }
                 return;
@@ -228,7 +252,7 @@ export class Client extends Disposer {
             }
         }
     }
-    async #write(payload, header) {
+    async #write(payload, header, rid) {
         if (this.signal.aborted) {
             throw new Error('Client aborted', {
                 cause: this.signal.reason
@@ -238,7 +262,46 @@ export class Client extends Disposer {
         const enrichedHeader = otelInjectTraceContext(baseHeader);
         const finalHeader = Object.keys(enrichedHeader).length > 0 ? enrichedHeader : undefined;
         const message = await this.#createMessage(payload, finalHeader);
-        await this.#transport.write(message);
+        await safeWrite({
+            transport: this.#transport,
+            message,
+            rid,
+            events: this.#events,
+            signal: this.signal,
+            onFailure: (error)=>{
+                if (rid != null) {
+                    // Surface the write failure on the per-rid controller so the
+                    // awaited request/stream/channel promise rejects, instead of
+                    // hanging on a server reply that will never arrive.
+                    this.#controllers[rid]?.abort(error);
+                }
+            }
+        });
+    }
+    // Fire-and-forget abort notification for `#handleSignal`. Never rejects:
+    // `safeWrite` already absorbs benign teardown errors and routes non-benign
+    // ones through `writeFailed` + the per-rid controller. The try/catch here
+    // only covers `#write`'s synchronous preflight (`this.signal.aborted` ->
+    // throw) and signing errors from `#createMessage`, which are the only paths
+    // that still reject. `requestError` surfaces those so callers can observe
+    // mid-abort failures without each abort site needing its own `.catch`.
+    #notifyAbort(rid, reason, header) {
+        void (async ()=>{
+            try {
+                await this.#write({
+                    typ: 'abort',
+                    rid,
+                    rsn: reason
+                }, header, rid);
+            } catch (error) {
+                if (!this.signal.aborted) {
+                    await this.#events.emit('requestError', {
+                        rid,
+                        error: error
+                    });
+                }
+            }
+        })();
     }
     #handleSignal(rid, controller, providedSignal) {
         const signal = providedSignal ? AbortSignal.any([
@@ -246,27 +309,24 @@ export class Client extends Disposer {
             providedSignal
         ]) : controller.signal;
         signal.addEventListener('abort', ()=>{
-            const reason = signal.reason.name ?? signal.reason;
+            const reason = signal.reason?.name ?? signal.reason;
             this.#logger.trace('abort {type} {procedure} with ID {rid} and reason: {reason}', {
                 type: controller.type,
                 procedure: controller.procedure,
                 rid,
                 reason
             });
-            void this.#write({
-                typ: 'abort',
-                rid,
-                rsn: reason
-            }, controller.header);
-            if (signal.reason !== 'Close') {
-                controller.aborted(signal);
-                delete this.#controllers[rid];
-            }
+            this.#notifyAbort(rid, reason, controller.header);
+            controller.aborted(signal);
+            delete this.#controllers[rid];
         }, {
             once: true
         });
         return signal;
     }
+    get events() {
+        return this.#events;
+    }
     async sendEvent(procedure, ...args) {
         const config = args[0] ?? {};
         return withSpan(this.#tracer, SpanNames.CLIENT_CALL, {
@@ -357,8 +417,16 @@ export class Client extends Disposer {
                 param: prm
             });
         }
-        const sent = withActiveContext(spanCtx, ()=>this.#write(payload, config.header));
-        this.#endSpanOnResult(span, controller.result);
+        this.#events.emit('requestStart', {
+            rid,
+            procedure,
+            type: controller.type
+        });
+        const sent = withActiveContext(spanCtx, ()=>this.#write(payload, config.header, rid));
+        this.#endSpanOnResult(span, controller.result, {
+            rid,
+            procedure
+        });
         const signal = this.#handleSignal(rid, controller, providedSignal);
         return createRequest({
             id: rid,
@@ -432,8 +500,16 @@ export class Client extends Disposer {
                 param: prm
             });
         }
-        const sent = withActiveContext(spanCtx, ()=>this.#write(payload, config.header));
-        this.#endSpanOnResult(span, controller.result, rid);
+        this.#events.emit('requestStart', {
+            rid,
+            procedure,
+            type: controller.type
+        });
+        const sent = withActiveContext(spanCtx, ()=>this.#write(payload, config.header, rid));
+        this.#endSpanOnResult(span, controller.result, {
+            rid,
+            procedure
+        });
         const signal = this.#handleSignal(rid, controller, providedSignal);
         return createStream({
             id: rid,
@@ -513,8 +589,16 @@ export class Client extends Disposer {
                 param: prm
             });
         }
-        const sent = withActiveContext(spanCtx, ()=>this.#write(payload, config.header));
-        this.#endSpanOnResult(span, controller.result, rid);
+        this.#events.emit('requestStart', {
+            rid,
+            procedure,
+            type: controller.type
+        });
+        const sent = withActiveContext(spanCtx, ()=>this.#write(payload, config.header, rid));
+        this.#endSpanOnResult(span, controller.result, {
+            rid,
+            procedure
+        });
         const signal = this.#handleSignal(rid, controller, providedSignal);
         const send = async (val)=>{
             const channelSpan = this.#spans[rid];
@@ -532,7 +616,7 @@ export class Client extends Disposer {
                 typ: 'send',
                 rid,
                 val
-            }, config.header);
+            }, config.header, rid);
         };
         return Object.assign(createStream({
             id: rid,

package/lib/events.d.ts

@@ -0,0 +1,39 @@
+import type { EventEmitter } from '@enkaku/event';
+import type { RequestError } from './error.js';
+export type ClientRequestStatus = 'ok' | 'error' | 'aborted';
+export type ClientEvents = {
+    disposed: {
+        reason?: unknown;
+    };
+    disposing: {
+        reason?: unknown;
+    };
+    requestEnd: {
+        rid: string;
+        procedure: string;
+        status: ClientRequestStatus;
+    };
+    requestError: {
+        rid: string;
+        error: Error | RequestError;
+    };
+    requestStart: {
+        rid: string;
+        procedure: string;
+        type: string;
+    };
+    transportError: {
+        error: Error;
+    };
+    transportReplaced: Record<string, never>;
+    writeDropped: {
+        rid?: string;
+        reason: unknown;
+        error: Error;
+    };
+    writeFailed: {
+        error: Error;
+        rid?: string;
+    };
+};
+export type ClientEmitter = EventEmitter<ClientEvents>;

package/lib/events.js

@@ -0,0 +1 @@
+export { };

package/lib/index.d.ts

@@ -12,3 +12,4 @@
 export type { ChannelCall, ChannelDefinitionsType, ClientDefinitionsType, ClientParams, EventDefinitionsType, RequestCall, RequestDefinitionsType, StreamCall, StreamDefinitionsType, } from './client.js';
 export { Client } from './client.js';
 export { type ErrorObjectType, RequestError, type RequestErrorParams } from './error.js';
+export type { ClientEmitter, ClientEvents, ClientRequestStatus } from './events.js';

package/lib/safe-write.d.ts

@@ -0,0 +1,28 @@
+import type { ClientEmitter } from './events.js';
+export type WriteTarget = {
+    write: (message: unknown) => Promise<void>;
+};
+export type SafeWriteParams = {
+    transport: WriteTarget;
+    message: unknown;
+    rid?: string;
+    events: ClientEmitter;
+    signal: AbortSignal;
+    /**
+     * Called with the raw transport error when a write fails for a reason that
+     * is NOT a benign teardown. Benign teardown errors are absorbed as
+     * `writeDropped` events and do NOT invoke this callback. The callback is
+     * the client's hook to propagate the failure into the per-rid controller so
+     * the request/stream/channel promise rejects rather than hanging.
+     */
+    onFailure?: (error: Error) => void;
+};
+/**
+ * Send a client message through the transport. Classifies any failure as
+ * either a benign teardown (swallowed → `writeDropped` event) or a real
+ * transport failure (`writeFailed` event + `onFailure` hook for per-call
+ * surfacing). Never rejects, so fire-and-forget callers do not need a
+ * `.catch`; direct callers can still observe the failure by subscribing to
+ * the events emitter or by supplying `onFailure`.
+ */
+export declare function safeWrite(params: SafeWriteParams): Promise<void>;

package/lib/safe-write.js

@@ -0,0 +1,29 @@
+import { isBenignTeardownError } from '@enkaku/async';
+/**
+ * Send a client message through the transport. Classifies any failure as
+ * either a benign teardown (swallowed → `writeDropped` event) or a real
+ * transport failure (`writeFailed` event + `onFailure` hook for per-call
+ * surfacing). Never rejects, so fire-and-forget callers do not need a
+ * `.catch`; direct callers can still observe the failure by subscribing to
+ * the events emitter or by supplying `onFailure`.
+ */ export async function safeWrite(params) {
+    const { transport, message, rid, events, signal, onFailure } = params;
+    try {
+        await transport.write(message);
+        return;
+    } catch (error) {
+        if (isBenignTeardownError(error) && signal.aborted) {
+            await events.emit('writeDropped', {
+                rid,
+                reason: 'disposing',
+                error: error
+            });
+            return;
+        }
+        await events.emit('writeFailed', {
+            error: error,
+            rid
+        });
+        onFailure?.(error);
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@enkaku/client",
-  "version": "0.14.3",
+  "version": "0.14.4",
   "license": "MIT",
   "homepage": "https://enkaku.dev",
   "description": "Enkaku RPC client",
@@ -26,23 +26,23 @@
   ],
   "sideEffects": false,
   "dependencies": {
-    "@enkaku/async": "^0.14.0",
     "@enkaku/execution": "^0.14.0",
     "@enkaku/runtime": "^0.14.0",
     "@enkaku/log": "^0.14.0",
+    "@enkaku/event": "^0.14.1",
     "@enkaku/otel": "^0.14.0",
     "@enkaku/stream": "^0.14.1",
-    "@enkaku/token": "^0.14.1"
+    "@enkaku/token": "^0.14.1",
+    "@enkaku/async": "^0.14.1"
   },
   "devDependencies": {
     "@enkaku/protocol": "^0.14.0",
-    "@enkaku/transport": "^0.14.0"
+    "@enkaku/transport": "^0.14.1"
   },
   "scripts": {
     "build:clean": "del lib",
     "build:js": "swc src -d ./lib --config-file ../../swc.json --strip-leading-paths",
     "build:types": "tsc --emitDeclarationOnly --skipLibCheck",
-    "build:types:ci": "tsc --emitDeclarationOnly --skipLibCheck",
     "build": "pnpm run build:clean && pnpm run build:js && pnpm run build:types",
     "test:types": "tsc --noEmit --skipLibCheck -p tsconfig.test.json",
     "test:unit": "vitest run",