@kizunajs/fetch 2.0.0-beta.20 → 2.0.0-beta.21

package/dist/index.cjs

@@ -58,6 +58,7 @@ export interface ClientConfig {
     fetch?: typeof fetch;
     onRequest?: (request: OutgoingRequest) => void | Promise<void>;
     retry?: RetryOptions;
+    reconnect?: ReconnectOptions;
 }
 
 /**
@@ -79,6 +80,25 @@ export interface RetryOptions {
     maximumDelay?: number;
 }
 
+/**
+ * Reconnects an event stream on a GET, HEAD, OPTIONS, PUT or DELETE when its
+ * connection drops, sending the id of the last event as Last-Event-ID.
+ */
+export interface ReconnectOptions {
+    /**
+     * Reconnections in a row before the stream fails. An event received resets the count.
+     */
+    maximumAttempts?: number;
+    /**
+     * Milliseconds to wait before reconnecting, until the server sends a retry field.
+     */
+    reconnectionTime?: number;
+    /**
+     * Milliseconds the wait may grow to after reconnections in a row that fail.
+     */
+    maximumDelay?: number;
+}
+
 /**
  * One method on the client. Its '~route' names the method it sends and
  * whether its response streams, so a wrapper like @kizunajs/tanstack-query
@@ -187,17 +207,29 @@ const findLineEnd = (buffer: string, final: boolean): { index: number; length: n
 /**
  * Reads text/event-stream as the WHATWG HTML specification parses it.
  */
-async function* readEvents(body: ReadableStream<Uint8Array>): AsyncGenerator<ServerSentEvent> {
+interface EventStreamState {
+    lastEventId: string;
+    reconnectionTime: number;
+}
+
+async function* readEvents(
+    body: ReadableStream<Uint8Array>,
+    state: EventStreamState = {
+        lastEventId: '',
+        reconnectionTime: 3000,
+    }
+): AsyncGenerator<ServerSentEvent> {
     const reader = body.getReader();
     const decoder = new TextDecoder();
     let buffer = '';
     let first = true;
     let dataLines: string[] = [];
     let eventType = '';
-    let lastEventId = '';
+    let lastEventId = state.lastEventId;
     let retry: number | undefined;
 
     const dispatch = (): ServerSentEvent | undefined => {
+        state.lastEventId = lastEventId;
         if (dataLines.length === 0) {
             eventType = '';
             return undefined;
@@ -232,7 +264,10 @@ async function* readEvents(body: ReadableStream<Uint8Array>): AsyncGenerator<Ser
                 if (!value.includes('\0')) lastEventId = value;
                 break;
             case 'retry':
-                if (/^\d+$/.test(value)) retry = Number(value);
+                if (/^\d+$/.test(value)) {
+                    retry = Number(value);
+                    state.reconnectionTime = Math.min(retry, 3_600_000);
+                }
                 break;
         }
         return undefined;
@@ -262,6 +297,57 @@ async function* readEvents(body: ReadableStream<Uint8Array>): AsyncGenerator<Ser
     }
 }
 
+async function* reconnectingEvents(
+    first: Response,
+    reopen: (lastEventId: string) => Promise<Response>,
+    options: ReconnectOptions,
+    signal: AbortSignal | null | undefined
+): AsyncGenerator<ServerSentEvent> {
+    const maximumAttempts = options.maximumAttempts ?? 5;
+    const maximumDelay = options.maximumDelay ?? 30_000;
+    const state: EventStreamState = {
+        lastEventId: '',
+        reconnectionTime: options.reconnectionTime ?? 3000,
+    };
+    let response: Response | undefined = first;
+    let attempts = 0;
+    let failure: unknown;
+    for (;;) {
+        if (response?.body) {
+            try {
+                for await (const message of readEvents(response.body, state)) {
+                    attempts = 0;
+                    failure = undefined;
+                    yield message;
+                }
+            } catch (error) {
+                failure = error;
+            }
+        }
+        if (signal?.aborted) throw signal.reason;
+        if (attempts >= maximumAttempts) {
+            if (failure !== undefined) throw failure;
+            return;
+        }
+        attempts += 1;
+        const ceiling = Math.min(maximumDelay, state.reconnectionTime * 2 ** (attempts - 1));
+        await wait(state.reconnectionTime + Math.random() * Math.max(0, ceiling - state.reconnectionTime), signal);
+        try {
+            response = await reopen(state.lastEventId);
+        } catch (error) {
+            if (signal?.aborted) throw error;
+            failure = error;
+            response = undefined;
+            continue;
+        }
+        if (response.status === 204) return;
+        const contentType = response.headers.get('content-type') ?? '';
+        if (response.status !== first.status || !contentType.toLowerCase().startsWith('text/event-stream')) {
+            throw new Error('Reconnecting to the event stream failed with status ' + response.status);
+        }
+    }
+}
+
 async function* readText(body: ReadableStream<Uint8Array>): AsyncGenerator<string> {
     const reader = body.getReader();
     const decoder = new TextDecoder();
@@ -360,41 +446,45 @@ const buildMethod = (route: GeneratedRoute, config: ClientConfig) => {
     const call = async (args: CallArgs = {}) => {
         const query = args.query === undefined ? '' : buildSearchParams(args.query).toString();
         const url = config.baseUrl + buildPath(route.path, args.params) + (query.length > 0 ? '?' + query : '');
-        const headers = new Headers(config.baseHeaders);
-        for (const [name, value] of Object.entries(args.headers ?? {})) {
-            if (value !== undefined) headers.set(name, value);
-        }
-        const init: RequestInit = {
-            method: route.method,
-            headers,
-        };
-        if (args.body !== undefined) init.body = encodeBody(route, args.body, headers);
-        if (config.credentials !== undefined) init.credentials = config.credentials;
-        await config.onRequest?.({
-            url,
-            method: route.method,
-            headers,
-            route,
-        });
-
-        const response = await send(
-            url,
-            {
+        const prepare = async (lastEventId = ''): Promise<RequestInit> => {
+            const headers = new Headers(config.baseHeaders);
+            for (const [name, value] of Object.entries(args.headers ?? {})) {
+                if (value !== undefined) headers.set(name, value);
+            }
+            if (lastEventId !== '') headers.set('Last-Event-ID', lastEventId);
+            const init: RequestInit = {
+                method: route.method,
+                headers,
+            };
+            if (args.body !== undefined) init.body = encodeBody(route, args.body, headers);
+            if (config.credentials !== undefined) init.credentials = config.credentials;
+            await config.onRequest?.({
+                url,
+                method: route.method,
+                headers,
+                route,
+            });
+            return {
                 ...init,
                 ...args.fetchOptions,
-            },
-            route,
-            config
-        );
+            };
+        };
+
+        const response = await send(url, await prepare(), route, config);
         const responseHeaders: Record<string, string> = {};
         response.headers.forEach((value, name) => {
             responseHeaders[name] = value;
         });
         const declared = route.responses[response.status];
         if (declared !== undefined && 'stream' in declared && response.body !== null) {
+            const essence = (declared.contentType.split(';')[0] ?? '').trim().toLowerCase();
+            const reconnect = essence === 'text/event-stream' && IDEMPOTENT_METHODS.has(route.method) ? config.reconnect : undefined;
+            const reopen = async (lastEventId: string) => send(url, await prepare(lastEventId), route, config);
             return {
                 status: response.status,
-                body: readStream(response.body, declared.contentType),
+                body: reconnect
+                    ? reconnectingEvents(response, reopen, reconnect, args.fetchOptions?.signal)
+                    : readStream(response.body, declared.contentType),
                 headers: responseHeaders,
             };
         }

package/dist/index.mjs

@@ -57,6 +57,7 @@ export interface ClientConfig {
     fetch?: typeof fetch;
     onRequest?: (request: OutgoingRequest) => void | Promise<void>;
     retry?: RetryOptions;
+    reconnect?: ReconnectOptions;
 }
 
 /**
@@ -78,6 +79,25 @@ export interface RetryOptions {
     maximumDelay?: number;
 }
 
+/**
+ * Reconnects an event stream on a GET, HEAD, OPTIONS, PUT or DELETE when its
+ * connection drops, sending the id of the last event as Last-Event-ID.
+ */
+export interface ReconnectOptions {
+    /**
+     * Reconnections in a row before the stream fails. An event received resets the count.
+     */
+    maximumAttempts?: number;
+    /**
+     * Milliseconds to wait before reconnecting, until the server sends a retry field.
+     */
+    reconnectionTime?: number;
+    /**
+     * Milliseconds the wait may grow to after reconnections in a row that fail.
+     */
+    maximumDelay?: number;
+}
+
 /**
  * One method on the client. Its '~route' names the method it sends and
  * whether its response streams, so a wrapper like @kizunajs/tanstack-query
@@ -186,17 +206,29 @@ const findLineEnd = (buffer: string, final: boolean): { index: number; length: n
 /**
  * Reads text/event-stream as the WHATWG HTML specification parses it.
  */
-async function* readEvents(body: ReadableStream<Uint8Array>): AsyncGenerator<ServerSentEvent> {
+interface EventStreamState {
+    lastEventId: string;
+    reconnectionTime: number;
+}
+
+async function* readEvents(
+    body: ReadableStream<Uint8Array>,
+    state: EventStreamState = {
+        lastEventId: '',
+        reconnectionTime: 3000,
+    }
+): AsyncGenerator<ServerSentEvent> {
     const reader = body.getReader();
     const decoder = new TextDecoder();
     let buffer = '';
     let first = true;
     let dataLines: string[] = [];
     let eventType = '';
-    let lastEventId = '';
+    let lastEventId = state.lastEventId;
     let retry: number | undefined;
 
     const dispatch = (): ServerSentEvent | undefined => {
+        state.lastEventId = lastEventId;
         if (dataLines.length === 0) {
             eventType = '';
             return undefined;
@@ -231,7 +263,10 @@ async function* readEvents(body: ReadableStream<Uint8Array>): AsyncGenerator<Ser
                 if (!value.includes('\0')) lastEventId = value;
                 break;
             case 'retry':
-                if (/^\d+$/.test(value)) retry = Number(value);
+                if (/^\d+$/.test(value)) {
+                    retry = Number(value);
+                    state.reconnectionTime = Math.min(retry, 3_600_000);
+                }
                 break;
         }
         return undefined;
@@ -261,6 +296,57 @@ async function* readEvents(body: ReadableStream<Uint8Array>): AsyncGenerator<Ser
     }
 }
 
+async function* reconnectingEvents(
+    first: Response,
+    reopen: (lastEventId: string) => Promise<Response>,
+    options: ReconnectOptions,
+    signal: AbortSignal | null | undefined
+): AsyncGenerator<ServerSentEvent> {
+    const maximumAttempts = options.maximumAttempts ?? 5;
+    const maximumDelay = options.maximumDelay ?? 30_000;
+    const state: EventStreamState = {
+        lastEventId: '',
+        reconnectionTime: options.reconnectionTime ?? 3000,
+    };
+    let response: Response | undefined = first;
+    let attempts = 0;
+    let failure: unknown;
+    for (;;) {
+        if (response?.body) {
+            try {
+                for await (const message of readEvents(response.body, state)) {
+                    attempts = 0;
+                    failure = undefined;
+                    yield message;
+                }
+            } catch (error) {
+                failure = error;
+            }
+        }
+        if (signal?.aborted) throw signal.reason;
+        if (attempts >= maximumAttempts) {
+            if (failure !== undefined) throw failure;
+            return;
+        }
+        attempts += 1;
+        const ceiling = Math.min(maximumDelay, state.reconnectionTime * 2 ** (attempts - 1));
+        await wait(state.reconnectionTime + Math.random() * Math.max(0, ceiling - state.reconnectionTime), signal);
+        try {
+            response = await reopen(state.lastEventId);
+        } catch (error) {
+            if (signal?.aborted) throw error;
+            failure = error;
+            response = undefined;
+            continue;
+        }
+        if (response.status === 204) return;
+        const contentType = response.headers.get('content-type') ?? '';
+        if (response.status !== first.status || !contentType.toLowerCase().startsWith('text/event-stream')) {
+            throw new Error('Reconnecting to the event stream failed with status ' + response.status);
+        }
+    }
+}
+
 async function* readText(body: ReadableStream<Uint8Array>): AsyncGenerator<string> {
     const reader = body.getReader();
     const decoder = new TextDecoder();
@@ -359,41 +445,45 @@ const buildMethod = (route: GeneratedRoute, config: ClientConfig) => {
     const call = async (args: CallArgs = {}) => {
         const query = args.query === undefined ? '' : buildSearchParams(args.query).toString();
         const url = config.baseUrl + buildPath(route.path, args.params) + (query.length > 0 ? '?' + query : '');
-        const headers = new Headers(config.baseHeaders);
-        for (const [name, value] of Object.entries(args.headers ?? {})) {
-            if (value !== undefined) headers.set(name, value);
-        }
-        const init: RequestInit = {
-            method: route.method,
-            headers,
-        };
-        if (args.body !== undefined) init.body = encodeBody(route, args.body, headers);
-        if (config.credentials !== undefined) init.credentials = config.credentials;
-        await config.onRequest?.({
-            url,
-            method: route.method,
-            headers,
-            route,
-        });
-
-        const response = await send(
-            url,
-            {
+        const prepare = async (lastEventId = ''): Promise<RequestInit> => {
+            const headers = new Headers(config.baseHeaders);
+            for (const [name, value] of Object.entries(args.headers ?? {})) {
+                if (value !== undefined) headers.set(name, value);
+            }
+            if (lastEventId !== '') headers.set('Last-Event-ID', lastEventId);
+            const init: RequestInit = {
+                method: route.method,
+                headers,
+            };
+            if (args.body !== undefined) init.body = encodeBody(route, args.body, headers);
+            if (config.credentials !== undefined) init.credentials = config.credentials;
+            await config.onRequest?.({
+                url,
+                method: route.method,
+                headers,
+                route,
+            });
+            return {
                 ...init,
                 ...args.fetchOptions,
-            },
-            route,
-            config
-        );
+            };
+        };
+
+        const response = await send(url, await prepare(), route, config);
         const responseHeaders: Record<string, string> = {};
         response.headers.forEach((value, name) => {
             responseHeaders[name] = value;
         });
         const declared = route.responses[response.status];
         if (declared !== undefined && 'stream' in declared && response.body !== null) {
+            const essence = (declared.contentType.split(';')[0] ?? '').trim().toLowerCase();
+            const reconnect = essence === 'text/event-stream' && IDEMPOTENT_METHODS.has(route.method) ? config.reconnect : undefined;
+            const reopen = async (lastEventId: string) => send(url, await prepare(lastEventId), route, config);
             return {
                 status: response.status,
-                body: readStream(response.body, declared.contentType),
+                body: reconnect
+                    ? reconnectingEvents(response, reopen, reconnect, args.fetchOptions?.signal)
+                    : readStream(response.body, declared.contentType),
                 headers: responseHeaders,
             };
         }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kizunajs/fetch",
-  "version": "2.0.0-beta.20",
+  "version": "2.0.0-beta.21",
   "description": "Fetch client generation for Kizuna.js APIs",
   "keywords": [
     "kizunajs",
@@ -56,12 +56,12 @@
     "access": "public"
   },
   "peerDependencies": {
-    "kizunajs": "2.0.0-beta.20",
+    "kizunajs": "2.0.0-beta.21",
     "zod": "^4.0.0"
   },
   "devDependencies": {
-    "kizunajs": "2.0.0-beta.20",
-    "@kizunajs/express": "2.0.0-beta.20",
+    "kizunajs": "2.0.0-beta.21",
+    "@kizunajs/express": "2.0.0-beta.21",
     "@types/express": "^5.0.0",
     "express": "^5.0.0",
     "tsdown": "^0.21.0",