@wavehouse/sdk 0.0.0-dev.h70dbf5d8f5ed → 0.0.0-dev.h7362ab3863f6

package/README.md

@@ -1,6 +1,6 @@
 # @wavehouse/sdk
 
-Zero-dependency TypeScript client for [WaveHouse](https://github.com/Wave-RF/WaveHouse) — schema-aware real-time API gateway for ClickHouse.
+TypeScript client for [WaveHouse](https://github.com/Wave-RF/WaveHouse) — schema-aware real-time API gateway for ClickHouse. One runtime dependency (`eventsource-parser`, ~1.4 KB gzipped, itself dependency-free).
 
 ## Installation
 
@@ -8,7 +8,7 @@ Zero-dependency TypeScript client for [WaveHouse](https://github.com/Wave-RF/Wav
 npm install @wavehouse/sdk
 ```
 
-Requires Node 22 or newer — the only line this SDK is tested against; Node 18 and 20 are past upstream end-of-life. Browsers need no polyfill, and Node needs an `EventSource` polyfill only for streaming — see [Runtime support](https://wavehouse.dev/sdk/#runtime-support).
+Requires Node 22 or newer — the only line this SDK is tested against; Node 18 and 20 are past upstream end-of-life. Neither browsers nor Node need a polyfill: streaming runs on `fetch`, like the rest of the SDK — see [Runtime support](https://wavehouse.dev/sdk/#runtime-support).
 
 This works in any framework that uses a bundler — React, Vue, Svelte, Angular, Astro, SolidJS, or plain Vite — with `import { createClient } from '@wavehouse/sdk'`.
 
@@ -44,7 +44,7 @@ Pin a version for production (`https://esm.sh/@wavehouse/sdk@0.1.0`). jsDelivr (
 
 **Versioning.** A bare CDN URL serves the latest published **release**; pin for production (`@wavehouse/sdk@0.1.0`) or float on a range (`@0` for the newest 0.x, `@0.1` for 0.1.x). Builds from `main` are published under the `dev` tag — `@wavehouse/sdk@dev` — for trying unreleased changes.
 
-Streaming (`.stream()`) uses the browser's native `EventSource`, so it works in both forms with no polyfill.
+Streaming (`.stream()`) runs on `fetch`, so it works in both forms with no polyfill.
 
 ## Quick Start
 
@@ -57,7 +57,7 @@ const wh = createClient({
 });
 ```
 
-`baseURL` may include a path prefix (`https://app.example.com/api/warehouse`) when WaveHouse is served under one — see [Serving under a path prefix](https://wavehouse.dev/sdk#serving-under-a-path-prefix).
+`baseURL` may include a path prefix (`https://app.example.com/api/wavehouse`) when WaveHouse is served under one — see [Serving under a path prefix](https://wavehouse.dev/sdk#serving-under-a-path-prefix).
 
 ### Query Data
 
@@ -131,7 +131,7 @@ const { data } = await wh.from('clicks').select('page').limit(10);
 
 Async request methods return a `Result<T>` object — destructure it as `{ data, error }` — and never throw for anything the server returns. `.stream()` and `.liveQuery()` return controllers instead, reporting failures through the subscriber's `error` callback.
 
-The SDK does throw on caller and environment errors: a non-absolute `baseURL` (REST calls reject with a `TypeError`; streams report `SSE_CONNECT_ERROR`, and despite that error's `retryable: true` the SDK never re-dials the stream itself), `.stream()` / `.liveQuery()` in a runtime with no `EventSource`, and an `auth` callback that rejects — a token-refresh failure propagates out of the REST call.
+The SDK does throw on caller and environment errors: a non-absolute `baseURL` (REST calls reject with a `TypeError`; streams report a terminal `SSE_CONNECT_ERROR`), `.stream()` / `.liveQuery()` in a runtime with no global `fetch` and no `options.fetch`, and an `auth` callback that rejects — a token-refresh failure propagates out of the REST call, and on a stream is reported as a retryable `SSE_AUTH_ERROR`. A dropped stream *is* re-dialed by the SDK, on a jittered backoff; only non-retryable failures end it. One more exception can escape an SDK call, though it is yours rather than ours: a subscriber's `status` handler throwing on the first, synchronous `.subscribe()` / `.liveQuery()` call — see [Error Handling](https://wavehouse.dev/sdk/reference#error-handling).
 
 ```ts
 const { data, error } = await wh.from('clicks').fetch();

package/dist/index.cjs

@@ -103,6 +103,13 @@ function mergeHeaders(base, extra) {
   }
   return merged;
 }
+function abortedResult() {
+  return {
+    data: null,
+    error: { status: 0, code: "ABORTED", message: "Request aborted", retryable: false },
+    headers: new Headers()
+  };
+}
 async function request(ctx, opts) {
   const url = resolveURL(ctx.baseURL, opts.path, opts.params).toString();
   const headers = {
@@ -152,16 +159,19 @@ async function request(ctx, opts) {
       }
       return { data: null, error, headers: res.headers };
     } catch (e) {
-      if (e instanceof DOMException && e.name === "AbortError") {
-        return {
-          data: null,
-          error: { status: 0, code: "ABORTED", message: "Request aborted", retryable: false },
-          headers: new Headers()
-        };
+      if (opts.signal?.aborted) {
+        return abortedResult();
       }
       lastError = networkError(e);
       if (attempt < maxAttempts - 1) {
-        await sleep(backoff(attempt), opts.signal);
+        try {
+          await sleep(backoff(attempt), opts.signal);
+        } catch (abort) {
+          if (opts.signal?.aborted) {
+            return abortedResult();
+          }
+          throw abort;
+        }
       }
     }
   }
@@ -555,11 +565,50 @@ var StreamController = class {
 };
 
 // src/stream/sse.ts
+var import_eventsource_parser = require("eventsource-parser");
 var activeSSEConnections = 0;
 var SSE_WARN_THRESHOLD = 5;
+var MAX_BUFFER_CHARS = 16 * 1024 * 1024;
+var MAX_BACKOFF_MS = 3e4;
+var STABLE_CONNECTION_MS = 3e3;
+function backoff2(attempt, retryFloorMs) {
+  const nominal = Math.max(retryFloorMs, Math.min(1e3 * 2 ** attempt, MAX_BACKOFF_MS));
+  const low = Math.max(retryFloorMs, nominal / 2);
+  return low + Math.random() * (nominal - low);
+}
+function releaseBody(res) {
+  if (res.body && !res.body.locked) res.body.cancel().catch(() => {
+  });
+}
 var SSETransport = class {
   _opts;
-  _es = null;
+  _abort = null;
+  /**
+   * Set by `disconnect()` before it calls `abort()` — both synchronously — so
+   * a rejection caused by our own abort always observes this as `true`. That
+   * makes it a complete and precise test for "did we cause this?", which is
+   * why the catch blocks read it directly instead of matching on the error
+   * type: an `AbortError` we *didn't* raise (a custom `fetch` enforcing a
+   * per-attempt deadline, an `auth()` call cancelled by its own controller) is
+   * a transient failure to re-dial, exactly as on the REST path. Treating one
+   * as a teardown killed the stream permanently, and silently.
+   */
+  _closed = false;
+  _started = false;
+  _counted = false;
+  /**
+   * Most recent non-empty event id, replayed as `Last-Event-ID` on reconnect.
+   *
+   * Deliberately ignores empty ids. The server emits a blank `id:` line for
+   * passthrough payloads, and per the SSE spec an empty `id` field *clears* the
+   * last-event-id — so tracking it faithfully would silently discard the
+   * resumption point mid-stream and re-open from the beginning.
+   */
+  _lastEventId = null;
+  /** Reconnect floor most recently requested by the server via `retry:`. */
+  _retryFloorMs = 0;
+  /** Cuts a reconnect gap short when set — see `_sleep`. */
+  _wake = null;
   onEvent = null;
   onStatus = null;
   onError = null;
@@ -567,79 +616,332 @@ var SSETransport = class {
     this._opts = opts;
   }
   connect() {
-    if (typeof EventSource === "undefined") {
+    if (this._closed || this._started) return;
+    this._started = true;
+    if (!this._opts.fetch && typeof fetch === "undefined") {
       throw new Error(
-        "[wavehouse] EventSource is not available in this environment. Please provide a global polyfill (e.g., `globalThis.EventSource = require('eventsource')`)."
+        "[wavehouse] global fetch is not available in this environment. Upgrade to Node 22+ or supply one via `options.fetch`."
       );
     }
-    this._doConnect().catch((err2) => {
-      this.onError?.({
+    activeSSEConnections++;
+    this._counted = true;
+    if (activeSSEConnections > SSE_WARN_THRESHOLD) {
+      console.warn(
+        `[wavehouse] ${activeSSEConnections} SSE connections open. Browsers limit HTTP/1.1 to 6 connections per domain.`
+      );
+    }
+    this._run().catch((err2) => {
+      this._emitError({
         status: 0,
         code: "SSE_CONNECT_ERROR",
         message: err2 instanceof Error ? err2.message : String(err2),
-        retryable: true
+        retryable: false
       });
+      this.disconnect();
     });
   }
   disconnect() {
-    if (this._es) {
-      this._es.close();
-      this._es = null;
-      activeSSEConnections = Math.max(0, activeSSEConnections - 1);
+    if (!this._closed) {
+      this._closed = true;
+      this._abort?.abort();
+      this._abort = null;
+      this._wake?.();
+      if (this._counted) {
+        activeSSEConnections = Math.max(0, activeSSEConnections - 1);
+        this._counted = false;
+      }
+      try {
+        this.onStatus?.("closed");
+      } catch (e) {
+        console.error("[wavehouse] SSE status handler threw:", e);
+      }
+    }
+  }
+  /** Connect/read/reconnect until the stream is closed or hits a terminal error. */
+  async _run() {
+    await Promise.resolve();
+    let attempt = 0;
+    while (!this._closed) {
+      const { liveMs, terminal } = await this._attempt();
+      if (this._closed) return;
+      if (terminal) {
+        this.disconnect();
+        return;
+      }
+      if (liveMs >= STABLE_CONNECTION_MS) attempt = 0;
+      this._emitStatus("reconnecting");
+      await this._sleep(backoff2(attempt, this._retryFloorMs));
+      attempt++;
+    }
+  }
+  /** One connection attempt: request, validate, then pump frames until it ends. */
+  async _attempt() {
+    const ac = new AbortController();
+    this._abort = ac;
+    let target;
+    try {
+      target = this._url();
+    } catch (e) {
+      this._emitError({
+        status: 0,
+        code: "SSE_CONNECT_ERROR",
+        message: e instanceof Error ? e.message : String(e),
+        retryable: false
+      });
+      return { liveMs: 0, terminal: true };
+    }
+    let init;
+    try {
+      init = await this._init(ac.signal);
+    } catch (e) {
+      if (this._closed) return { liveMs: 0, terminal: true };
+      this._emitError({
+        status: 0,
+        code: "SSE_AUTH_ERROR",
+        message: e instanceof Error ? e.message : String(e),
+        retryable: true
+      });
+      return { liveMs: 0, terminal: false };
+    }
+    let res;
+    try {
+      const doFetch = this._opts.fetch;
+      res = doFetch ? await doFetch(target, init) : await fetch(target, init);
+    } catch (e) {
+      if (this._closed) return { liveMs: 0, terminal: true };
+      this._emitError({
+        status: 0,
+        code: "SSE_NETWORK_ERROR",
+        message: e instanceof Error ? e.message : String(e),
+        retryable: true
+      });
+      return { liveMs: 0, terminal: false };
+    }
+    if (res.type === "opaqueredirect" || res.status >= 300 && res.status < 400) {
+      this._emitError({
+        status: res.status,
+        code: "SSE_REDIRECT",
+        message: "The stream endpoint redirected and the SDK did not follow it. Redirects are refused when the request carries a credential \u2014 an `auth` token or configured `headers` \u2014 because a cross-origin hop strips the Authorization header, and this endpoint answers an unauthenticated caller with a reduced view instead of an error, while forwarding any configured headers to wherever the redirect points. If this request carries neither, `fetch` was left to follow the redirect itself, so arriving here means a response it will not follow (a 304, or a 3xx with no Location header) or an `options.fetch` that returned the redirect verbatim. Either way, set `baseURL` to the final URL; most often this is an http\u2192https upgrade or a canonical-host redirect at a proxy. To follow a credentialed redirect anyway, supply an `options.fetch` that overrides `redirect`.",
+        retryable: false
+      });
+      releaseBody(res);
+      return { liveMs: 0, terminal: true };
+    }
+    if (!res.ok) {
+      const error = await parseErrorResponse(res);
+      this._emitError(error);
+      return { liveMs: 0, terminal: !error.retryable };
+    }
+    const contentType = res.headers.get("content-type") ?? "";
+    if (!contentType.toLowerCase().split(";")[0].trim().startsWith("text/event-stream")) {
+      this._emitError({
+        status: res.status,
+        code: "SSE_BAD_CONTENT_TYPE",
+        message: `Expected \`text/event-stream\`, got \`${contentType || "(none)"}\`. Something between the client and WaveHouse answered this request \u2014 an auth gateway's login page is the usual cause.`,
+        retryable: false
+      });
+      releaseBody(res);
+      return { liveMs: 0, terminal: true };
+    }
+    const body = res.body;
+    if (!body || typeof body.getReader !== "function" || body.locked || res.bodyUsed) {
+      this._emitError({
+        status: res.status,
+        code: "SSE_NO_STREAM_BODY",
+        message: "Streaming requires a response with a readable body. The configured `options.fetch` returned one whose body is absent or already read \u2014 an implementation that buffers or consumes the response cannot be used for `.stream()` or `.liveQuery()`.",
+        retryable: false
+      });
+      releaseBody(res);
+      return { liveMs: 0, terminal: true };
     }
-    this.onStatus?.("closed");
+    this._emitStatus("live");
+    const openedAt = Date.now();
+    await this._pump(body);
+    return { liveMs: Date.now() - openedAt, terminal: false };
   }
-  async _doConnect() {
+  /** Resolve the stream URL. Throws on a `baseURL` that isn't a usable http(s) origin. */
+  _url() {
     const url = resolveURL(this._opts.baseURL, "/v1/stream");
+    if (url.protocol !== "http:" && url.protocol !== "https:") {
+      throw new Error(
+        `baseURL must use http or https, got "${url.protocol}". Streaming is plain HTTP \u2014 there is no WebSocket endpoint.`
+      );
+    }
     url.searchParams.set("table", this._opts.table);
     if (this._opts.since) {
       url.searchParams.set("since", this._opts.since);
     }
+    return url.toString();
+  }
+  /** Build the request init, minting a token for this attempt. */
+  async _init(signal) {
+    const base = { Accept: "text/event-stream" };
     if (this._opts.auth) {
       const token = await this._opts.auth();
       if (token) {
-        url.searchParams.set("token", token);
+        base.Authorization = `Bearer ${token}`;
       }
     }
-    activeSSEConnections++;
-    if (activeSSEConnections > SSE_WARN_THRESHOLD) {
-      console.warn(
-        `[wavehouse] ${activeSSEConnections} SSE connections open. Browsers limit HTTP/1.1 to 6 connections per domain.`
-      );
+    if (this._lastEventId) {
+      base["Last-Event-ID"] = this._lastEventId;
     }
-    this._es = new EventSource(url.toString());
-    this._es.onopen = () => {
-      this.onStatus?.("live");
-    };
-    this._es.onmessage = (e) => {
-      try {
-        const msg = JSON.parse(e.data);
-        const event = {
-          table: msg.table_name,
-          timestamp: msg.received_timestamp,
-          data: msg.data
-        };
-        this.onEvent?.(event);
-      } catch {
-        console.warn("[wavehouse] SSE received malformed message:", e.data);
-      }
+    const credentialed = base.Authorization !== void 0 || Object.keys(this._opts.headers ?? {}).length > 0;
+    const init = {
+      ...this._opts.fetchOptions,
+      method: "GET",
+      headers: mergeHeaders(base, this._opts.headers),
+      signal,
+      // Owned by the SDK rather than left to `fetchOptions`, unlike the REST
+      // path, because on a stream these are correctness rather than preference:
+      //
+      //   cache    — as an init field, not a `Cache-Control` header. The header
+      //              form is not in the server's Access-Control-Allow-Headers,
+      //              so it would fail every cross-origin preflight.
+      //   redirect — followed only when this request carries no credential.
+      //              Platforms strip `Authorization` on a cross-origin redirect
+      //              (whatwg/fetch#1544) and forward other headers intact, so a
+      //              credentialed hop either silently downgrades the stream to
+      //              the default role — this endpoint answers an unauthenticated
+      //              caller rather than rejecting them — or delivers a configured
+      //              secret to whatever the redirect names. Neither is worth a
+      //              convenience. Without either, redirects are followed, so CDN
+      //              canonicalization, geo/LB indirection, and an http→https
+      //              upgrade all just work. The test is deliberately that
+      //              concrete pair and not "is this authenticated": cookies do
+      //              not appear in it. A cookie is re-derived per
+      //              destination rather than carried, so under the default
+      //              same-origin credentials mode it survives a redirect only
+      //              while the hop stays inside both the request's origin and
+      //              the cookie's Path; outside either the stream is
+      //              silently unauthed. See #478 and the SDK guide under
+      //              "Supplying your own fetch".
+      //              `manual` over `error` for the credentialed case so the
+      //              outcome stays inspectable: `error` rejects with a bare
+      //              TypeError indistinguishable from a connection failure, which
+      //              the loop above would retry forever against a redirect that
+      //              is never going to stop happening.
+      cache: "no-store",
+      redirect: credentialed ? "manual" : "follow",
+      // Neutralized like the REST path does, and for a sharper reason here: a
+      // body on a GET makes `fetch` throw, which reads as a network failure and
+      // would be retried forever against a request that can never be built.
+      body: void 0
     };
-    this._es.onerror = () => {
-      if (this._es?.readyState === EventSource.CONNECTING) {
-        this.onStatus?.("reconnecting");
-      } else if (this._es?.readyState === EventSource.CLOSED) {
-        this.onStatus?.("closed");
-      } else if (this._es?.readyState === EventSource.OPEN) {
-        this.onStatus?.("live");
-      } else {
-        this.onError?.({
+    if (!("window" in globalThis)) {
+      delete init.credentials;
+    }
+    return init;
+  }
+  /** Decode and parse frames until the stream ends, aborts, or errors. */
+  async _pump(body) {
+    let overflowed = false;
+    const parser = (0, import_eventsource_parser.createParser)({
+      onEvent: (msg) => {
+        if (msg.id) this._lastEventId = msg.id;
+        if (!msg.data) return;
+        this._dispatch(msg.data);
+      },
+      onRetry: (ms) => {
+        this._retryFloorMs = Math.min(Math.max(ms, 0), MAX_BACKOFF_MS);
+      },
+      onError: (err2) => {
+        if (err2.type === "max-buffer-size-exceeded") overflowed = true;
+        this._emitError({
           status: 0,
-          code: "SSE_ERROR",
-          message: "SSE connection error",
+          code: "SSE_PARSE_ERROR",
+          message: err2.message,
           retryable: true
         });
+      },
+      maxBufferSize: MAX_BUFFER_CHARS
+    });
+    const reader = body.getReader();
+    const decoder = new TextDecoder();
+    try {
+      for (; ; ) {
+        const { done, value } = await reader.read();
+        if (done) return;
+        parser.feed(decoder.decode(value, { stream: true }));
+        if (overflowed) return;
       }
-    };
+    } catch (e) {
+      if (this._closed) return;
+      this._emitError({
+        status: 0,
+        code: "SSE_READ_ERROR",
+        message: e instanceof Error ? e.message : String(e),
+        retryable: true
+      });
+    } finally {
+      reader.cancel().catch(() => {
+      });
+    }
+  }
+  /**
+   * Turn one frame's `data` into a StreamEvent.
+   *
+   * Guarded like `_emitError` and `_emitStatus`: `parser.feed()` dispatches
+   * every complete frame in a chunk synchronously, so a subscriber that closes
+   * from inside its own `next` — "read until I see my event, then stop" —
+   * would otherwise keep receiving the rest of that chunk. `EventSource` ended
+   * delivery on `close()`, and gap-fill replay routinely lands many frames in
+   * one chunk.
+   */
+  _dispatch(data) {
+    if (this._closed) return;
+    let event;
+    try {
+      const msg = JSON.parse(data);
+      event = { table: msg.table_name, timestamp: msg.received_timestamp, data: msg.data };
+    } catch {
+      console.warn("[wavehouse] SSE received malformed message:", data);
+      return;
+    }
+    try {
+      this.onEvent?.(event);
+    } catch (e) {
+      console.error("[wavehouse] SSE event handler threw:", e);
+    }
+  }
+  /** Suppress callbacks that race a `disconnect()`. */
+  _emitError(error) {
+    if (this._closed) return;
+    try {
+      this.onError?.(error);
+    } catch (e) {
+      console.error("[wavehouse] SSE error handler threw:", e);
+    }
+  }
+  /**
+   * Same guard for status. Aborting does not retract an already-resolved
+   * `Response`, so a `disconnect()` landing between the fetch settling and the
+   * "live" below would otherwise flip a closed controller back to live — and it
+   * stays there, since the loop then exits without emitting anything further.
+   * `disconnect()` calls `onStatus` directly; that terminal "closed" is the one
+   * status that must always get through.
+   */
+  _emitStatus(status) {
+    if (this._closed) return;
+    try {
+      this.onStatus?.(status);
+    } catch (e) {
+      console.error("[wavehouse] SSE status handler threw:", e);
+    }
+  }
+  /** Wait out a reconnect gap, cut short by `disconnect()`. */
+  _sleep(ms) {
+    if (this._closed) return Promise.resolve();
+    return new Promise((resolve) => {
+      const timer = setTimeout(() => {
+        this._wake = null;
+        resolve();
+      }, ms);
+      this._wake = () => {
+        clearTimeout(timer);
+        this._wake = null;
+        resolve();
+      };
+    });
   }
 };
 
@@ -1177,16 +1479,14 @@ var WaveHouseClient = class {
   }
   /** @internal Create a stream for the given table. */
   _createStream(table, opts) {
-    if (typeof EventSource === "undefined") {
-      throw new Error(
-        "[WaveHouse SDK] Native EventSource is not available in this environment. Please provide a global polyfill (e.g., `globalThis.EventSource = require('eventsource')`)."
-      );
-    }
     const transport = new SSETransport({
       baseURL: this._ctx.baseURL,
       table,
       since: opts?.since,
-      auth: this._ctx.auth
+      auth: this._ctx.auth,
+      fetch: this._ctx.options.fetch,
+      headers: this._ctx.options.headers,
+      fetchOptions: this._ctx.options.fetchOptions
     });
     const controller = new StreamController(transport);
     if (opts?.signal) controller.attachSignal(opts.signal);