@fudanda/client 0.0.0-stage → 1.20261015.1-beta.1

package/src/event-stream.ts

@@ -0,0 +1,74 @@
+import type { AnyOperation } from '@fudanda/shared/core';
+import { fillPath } from '@fudanda/shared/core';
+import { ClientError } from './errors';
+import type { Client } from './client';
+import type { Subscription } from './subscriptions';
+
+export interface EventStreamOptions<T> {
+  params: Record<string,string|number>;
+  signal?: AbortSignal;
+  parse: (event:string, data:unknown)=>T;
+  onEvent: (event:T)=>void;
+  onConnection?: (state:'connecting'|'connected'|'reconnecting'|'closed')=>void;
+  onError?: (error:unknown)=>void;
+  onUnauthorized?: ()=>void;
+  reconnectDelay?: number;
+}
+/** An instance-local registered SSE operation. Reconnect begins with a server ready
+ * frame; the consumer must requery durable data instead of trusting token replay. */
+export function subscribeOperation<T>(client:Client, op:AnyOperation, options:EventStreamOptions<T>):Subscription {
+  if(op.kind!=='sse'||op.method!=='get')throw Error('Expected a GET SSE contract');
+  const path=client.resolveOperationPath(op);
+  if(!path)throw Error('SSE operation is not registered on this Client');
+  const url=fillPath(path,options.params);
+  const abort=new AbortController(); let reader:ReadableStreamDefaultReader<Uint8Array>|undefined;
+  const close=()=>{abort.abort();void reader?.cancel().catch(()=>{});};
+  options.signal?.addEventListener('abort',close,{once:true});if(options.signal?.aborted)close();
+  const done=(async()=>{
+    let failures=0;
+    while(!abort.signal.aborted){
+      options.onConnection?.(failures?'reconnecting':'connecting');
+      try{
+        const response=await client.fetchRaw(url,{signal:abort.signal,headers:{Accept:'text/event-stream'}});
+        if(response.status===401){options.onUnauthorized?.();return;}
+        if([403,404].includes(response.status))throw new ClientError(response.status,'stream_denied','无法订阅该运行');
+        if(!response.ok||!response.body||!response.headers.get('content-type')?.startsWith('text/event-stream'))throw Error('Invalid SSE response');
+        reader=response.body.getReader();options.onConnection?.('connected');
+        const decoder=new TextDecoder();let buffer='';
+        while(!abort.signal.aborted){
+          const part=await reader.read();if(part.done)break;
+          buffer+=decoder.decode(part.value,{stream:true});
+          // Normalize only complete frames: CRLF can be split across TCP chunks.
+          let match:RegExpExecArray|null;
+          while((match=/\r?\n\r?\n/.exec(buffer))){
+            const frame=buffer.slice(0,match.index).replaceAll('\r\n','\n');buffer=buffer.slice(match.index+match[0].length);
+            if(frame.length>512*1024)throw Error('SSE frame exceeds limit');
+            let event='message';const data:string[]=[];
+            for(const line of frame.split('\n')){if(line.startsWith('event:'))event=line.slice(6).trim();else if(line.startsWith('data:'))data.push(line.slice(5).replace(/^ /,''));}
+            if(event==='session-expired'){options.onUnauthorized?.();return;}
+            if(event==='denied')throw new ClientError(403,'stream_denied','订阅权限已失效');
+            if(event==='unavailable')throw Error('Stream unavailable');
+            if(!data.length)continue;
+            const value=options.parse(event,JSON.parse(data.join('\n')));
+            if(!abort.signal.aborted)options.onEvent(value);
+            failures=0;
+            if(event==='done')return;
+          }
+          if(buffer.length>512*1024)throw Error('SSE frame exceeds limit');
+        }
+      }catch(error){
+        if(abort.signal.aborted)return;
+        options.onError?.(error);
+        if(error instanceof ClientError&&[403,404].includes(error.status))return;
+      }finally{await reader?.cancel().catch(()=>{});reader?.releaseLock();reader=undefined;}
+      if(abort.signal.aborted)return;
+      failures++;options.onConnection?.('reconnecting');
+      await new Promise<void>(resolve=>{
+        const finish=()=>{clearTimeout(timer);abort.signal.removeEventListener('abort',finish);resolve();};
+        const timer=setTimeout(finish,Math.min(15000,Math.max(250,options.reconnectDelay??750)*2**Math.min(failures-1,4)));
+        abort.signal.addEventListener('abort',finish,{once:true});
+      });
+    }
+  })().finally(()=>{options.signal?.removeEventListener('abort',close);options.onConnection?.('closed');});
+  return {close,done};
+}

package/src/index.ts

@@ -0,0 +1,9 @@
+export { Client, validateGoPath } from './client';
+export type { ClientOptions, RequestOptions, ApiEnvelope, Method } from './client';
+export { ClientError, ApiError } from './errors';
+export { subscribe } from './subscriptions';
+export {subscribeOperation} from './event-stream';
+export type {EventStreamOptions} from './event-stream';
+export type { ChangeEvent, SubscriptionOptions, Subscription } from './subscriptions';
+export { call, callRaw, operationURL, foundationPath, foundationRequestBody, isFoundationOperation, toQueryString, unwrap } from './contracts';
+export type { JsonClient, UrlInputOf } from './contracts';

package/src/subscriptions.ts

@@ -0,0 +1,74 @@
+import { integrationContract } from '@fudanda/shared/integrations';
+import { operationURL } from './contracts';
+import { ClientError } from './errors';
+import type { Client } from './client';
+
+export interface ChangeEvent { resources: string[]; cursor: string; requery: boolean }
+export interface SubscriptionOptions {
+  signal?: AbortSignal;
+  onChange: (event: ChangeEvent) => void;
+  onError?: (error: unknown) => void;
+  onUnauthorized?: () => void;
+  /** Bounded reconnect delay, in milliseconds. */
+  reconnectDelay?: number;
+}
+export interface Subscription { close(): void; done: Promise<void> }
+
+/** Fetch-based SSE works with both Cookie and restricted API Key clients.
+ * Cursor stays in memory; ready/reconnect always requests an authorized requery. */
+export function subscribe(client: Client, options: SubscriptionOptions): Subscription {
+  const controller = new AbortController();
+  let activeReader: ReadableStreamDefaultReader<Uint8Array> | undefined;
+  const close = () => { controller.abort(); void activeReader?.cancel().catch(() => {}); };
+  options.signal?.addEventListener('abort', close, { once: true });
+  if (options.signal?.aborted) close();
+  let cursor = '';
+  const done = (async () => {
+    while (!controller.signal.aborted) {
+      let reader: ReadableStreamDefaultReader<Uint8Array> | undefined;
+      try {
+        const response = await client.fetchRaw(operationURL(integrationContract.events), { signal: controller.signal, headers: { Accept: 'text/event-stream', ...(cursor ? { 'Last-Event-ID': cursor } : {}) } });
+        if (response.status === 401) { options.onUnauthorized?.(); return; }
+        if (response.status === 403) throw new ClientError(403, 'subscription_denied', '没有订阅权限');
+        if (!response.ok || !response.body || !response.headers.get('content-type')?.startsWith('text/event-stream')) throw new ClientError(response.status, 'subscription_unavailable', '订阅暂不可用');
+        reader = response.body.getReader();
+        activeReader = reader;
+        const decoder = new TextDecoder(); let buffer = '';
+        while (!controller.signal.aborted) {
+          const part = await reader.read(); if (part.done) break;
+          buffer = (buffer + decoder.decode(part.value, { stream: true })).replace(/\r\n/g, '\n');
+          if (buffer.length > 65536) throw new Error('SSE frame exceeds size limit');
+          let boundary: number;
+          while ((boundary = buffer.indexOf('\n\n')) >= 0) {
+            const frame = buffer.slice(0, boundary); buffer = buffer.slice(boundary + 2);
+            let event = ''; let id = ''; const data: string[] = [];
+            for (const line of frame.split('\n')) {
+              if (line.startsWith('event:')) event = line.slice(6).trim();
+              else if (line.startsWith('id:')) id = line.slice(3).trim();
+              else if (line.startsWith('data:')) data.push(line.slice(5).trimStart());
+            }
+            if (/^\d+$/.test(id)) cursor = id;
+            if (event === 'session-expired') { options.onUnauthorized?.(); return; }
+            if (event === 'unavailable') throw new Error('Subscription unavailable');
+            if (event === 'change' || event === 'ready') {
+              const parsed: unknown = JSON.parse(data.join('\n') || '{}');
+              const resources = parsed && typeof parsed === 'object' && 'resources' in parsed && Array.isArray(parsed.resources) && parsed.resources.every(value => typeof value === 'string') ? parsed.resources as string[] : [];
+              if (!controller.signal.aborted) options.onChange({ resources, cursor, requery: true });
+            }
+          }
+        }
+      } catch (error) {
+        if (controller.signal.aborted) return;
+        options.onError?.(error);
+        if (error instanceof ClientError && error.status === 403) return;
+      } finally { await reader?.cancel().catch(() => {}); reader?.releaseLock(); activeReader = undefined; }
+      if (controller.signal.aborted) return;
+      await new Promise<void>(resolve => {
+        const finished = () => { clearTimeout(timer); controller.signal.removeEventListener('abort', finished); resolve(); };
+        const timer = setTimeout(finished, Math.min(30000, Math.max(250, options.reconnectDelay ?? 1500)));
+        controller.signal.addEventListener('abort', finished, { once: true });
+      });
+    }
+  })().finally(() => { options.signal?.removeEventListener('abort', close); });
+  return { close, done };
+}