@limrun/api 0.48.4 → 0.49.0

package/src/internal/destination-tunnel-url.ts

@@ -1,9 +1,14 @@
 function deriveDestinationTunnelEndpointURL(apiUrl: string, suffix?: string): URL {
   const url = new URL(apiUrl);
-  if (url.protocol !== 'https:' && url.protocol !== 'http:') {
+  if (
+    url.protocol !== 'https:' &&
+    url.protocol !== 'http:' &&
+    url.protocol !== 'wss:' &&
+    url.protocol !== 'ws:'
+  ) {
     throw new Error(`Unsupported apiUrl protocol for tunnel: ${url.protocol}`);
   }
-  const tunnelPath = `${url.pathname.replace(/\/+$/, '')}/tunnel`;
+  const tunnelPath = `${withoutTrailingSlashes(url.pathname)}/tunnel`;
   url.pathname = suffix === undefined ? tunnelPath : `${tunnelPath}/${suffix}`;
   url.search = '';
   url.hash = '';
@@ -12,14 +17,65 @@ function deriveDestinationTunnelEndpointURL(apiUrl: string, suffix?: string): UR
 
 export function deriveDestinationTunnelURL(apiUrl: string): string {
   const url = deriveDestinationTunnelEndpointURL(apiUrl);
-  url.protocol = url.protocol === 'https:' ? 'wss:' : 'ws:';
+  url.protocol = url.protocol === 'https:' || url.protocol === 'wss:' ? 'wss:' : 'ws:';
   return url.toString();
 }
 
 export function deriveDestinationTunnelStatusURL(apiUrl: string): URL {
-  return deriveDestinationTunnelEndpointURL(apiUrl, 'status');
+  const url = deriveDestinationTunnelEndpointURL(apiUrl, 'status');
+  url.protocol =
+    url.protocol === 'wss:' ? 'https:'
+    : url.protocol === 'ws:' ? 'http:'
+    : url.protocol;
+  return url;
 }
 
 export function deriveDestinationTunnelStopURL(apiUrl: string, tunnelId: string): URL {
-  return deriveDestinationTunnelEndpointURL(apiUrl, encodeURIComponent(tunnelId));
+  const url = deriveDestinationTunnelEndpointURL(apiUrl, encodeURIComponent(tunnelId));
+  url.protocol =
+    url.protocol === 'wss:' ? 'https:'
+    : url.protocol === 'ws:' ? 'http:'
+    : url.protocol;
+  return url;
+}
+
+export function deriveDestinationTunnelInspectionURL(
+  tunnelUrl: string,
+  tunnelId: string,
+  token: string,
+): string;
+export function deriveDestinationTunnelInspectionURL(
+  tunnelUrl: string,
+  tunnelId: string,
+  afterSequence?: number,
+  token?: string,
+): string;
+export function deriveDestinationTunnelInspectionURL(
+  tunnelUrl: string,
+  tunnelId: string,
+  afterSequenceOrToken: number | string = 0,
+  explicitToken?: string,
+): string {
+  const afterSequence = typeof afterSequenceOrToken === 'number' ? afterSequenceOrToken : 0;
+  const token = typeof afterSequenceOrToken === 'string' ? afterSequenceOrToken : explicitToken;
+  if (!Number.isSafeInteger(afterSequence) || afterSequence < 0) {
+    throw new Error('afterSequence must be a safe non-negative integer');
+  }
+  const url = new URL(tunnelUrl);
+  url.protocol =
+    url.protocol === 'wss:' ? 'https:'
+    : url.protocol === 'ws:' ? 'http:'
+    : url.protocol;
+  url.pathname = `${withoutTrailingSlashes(url.pathname)}/${encodeURIComponent(tunnelId)}/inspection/events`;
+  url.search = '';
+  if (afterSequence > 0) url.searchParams.set('after-sequence', String(afterSequence));
+  if (token !== undefined) url.searchParams.set('token', token);
+  url.hash = '';
+  return url.toString();
+}
+
+function withoutTrailingSlashes(path: string): string {
+  let end = path.length;
+  while (end > 0 && path.charCodeAt(end - 1) === 47) end--;
+  return path.slice(0, end);
 }

package/src/internal/destination-tunnel-wire-reader.ts

@@ -0,0 +1,109 @@
+export class DestinationTunnelProtocolError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = 'DestinationTunnelProtocolError';
+  }
+}
+
+export function readRecord(value: unknown, name: string): Record<string, unknown> {
+  if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+    throw new DestinationTunnelProtocolError(`${name} must be an object`);
+  }
+  return value as Record<string, unknown>;
+}
+
+export function readArray(record: Record<string, unknown>, key: string): unknown[] {
+  const value = record[key];
+  if (!Array.isArray(value)) {
+    throw new DestinationTunnelProtocolError(`${key} must be an array`);
+  }
+  return value;
+}
+
+export function readString(record: Record<string, unknown>, key: string): string {
+  const value = record[key];
+  if (typeof value !== 'string') {
+    throw new DestinationTunnelProtocolError(`${key} must be a string`);
+  }
+  return value;
+}
+
+export function readNonEmptyString(record: Record<string, unknown>, key: string): string {
+  const value = readString(record, key);
+  if (value.length === 0) {
+    throw new DestinationTunnelProtocolError(`${key} must not be empty`);
+  }
+  return value;
+}
+
+export function readBoolean(record: Record<string, unknown>, key: string): boolean {
+  const value = record[key];
+  if (typeof value !== 'boolean') {
+    throw new DestinationTunnelProtocolError(`${key} must be a boolean`);
+  }
+  return value;
+}
+
+export function readInteger(record: Record<string, unknown>, key: string): number {
+  const value = record[key];
+  if (!Number.isInteger(value)) {
+    throw new DestinationTunnelProtocolError(`${key} must be an integer`);
+  }
+  return value as number;
+}
+
+export function readFiniteNumber(record: Record<string, unknown>, key: string): number {
+  const value = record[key];
+  if (typeof value !== 'number' || !Number.isFinite(value)) {
+    throw new DestinationTunnelProtocolError(`${key} must be a finite number`);
+  }
+  return value;
+}
+
+export function readSafeNonNegativeInteger(value: unknown, name: string): number {
+  if (!Number.isSafeInteger(value) || (value as number) < 0) {
+    throw new DestinationTunnelProtocolError(`${name} must be a safe non-negative integer`);
+  }
+  return value as number;
+}
+
+export function readOptionalString(
+  record: Record<string, unknown>,
+  key: string,
+): { [K in typeof key]?: string } {
+  return record[key] === undefined ? {} : { [key]: readString(record, key) };
+}
+
+export function readOptionalBoolean(
+  record: Record<string, unknown>,
+  key: string,
+): { [K in typeof key]?: boolean } {
+  return record[key] === undefined ? {} : { [key]: readBoolean(record, key) };
+}
+
+export function readOptionalNonNegativeInteger(
+  record: Record<string, unknown>,
+  key: string,
+): { [K in typeof key]?: number } {
+  const value = record[key];
+  if (value === undefined) return {};
+  if (!Number.isInteger(value) || (value as number) < 0) {
+    throw new DestinationTunnelProtocolError(`${key} must be a non-negative integer`);
+  }
+  return { [key]: value as number };
+}
+
+export function decodeUtf8(value: Buffer, name: string): string {
+  try {
+    return new TextDecoder('utf-8', { fatal: true }).decode(value);
+  } catch {
+    throw new DestinationTunnelProtocolError(`${name} must be valid UTF-8`);
+  }
+}
+
+export function toBuffer(data: Buffer | ArrayBuffer | Buffer[]): Buffer {
+  if (Buffer.isBuffer(data)) return data;
+  if (Array.isArray(data)) return Buffer.concat(data);
+  if (data instanceof ArrayBuffer) return Buffer.from(data);
+  throw new DestinationTunnelProtocolError('unsupported WebSocket payload type');
+}

package/src/internal/persist-option.ts

@@ -0,0 +1,26 @@
+/**
+ * Whether a capture is persisted to Limrun's bucket after it stops.
+ * `true` persists with the server default TTL (72h); pass an object to set
+ * the TTL in seconds (capped server-side).
+ */
+export type PersistOption = boolean | { ttlSeconds?: number };
+
+/** Wire fields a persist option turns into on a start-capture message. */
+export function persistFields(persist: PersistOption | undefined): {
+  persist?: boolean;
+  ttlSeconds?: number;
+} {
+  if (!persist) {
+    return {};
+  }
+  if (persist === true) {
+    return { persist: true };
+  }
+  if (
+    persist.ttlSeconds !== undefined &&
+    (!Number.isInteger(persist.ttlSeconds) || persist.ttlSeconds <= 0)
+  ) {
+    throw new Error('ttlSeconds must be a positive integer');
+  }
+  return { persist: true, ...(persist.ttlSeconds !== undefined && { ttlSeconds: persist.ttlSeconds }) };
+}

package/src/internal/proxy-transport.ts

@@ -1,4 +1,6 @@
 import type { Agent as HttpAgent } from 'http';
+import net from 'net';
+import tls from 'tls';
 
 import { HttpsProxyAgent } from 'https-proxy-agent';
 import { getProxyForUrl } from 'proxy-from-env';
@@ -11,6 +13,29 @@ import type { Fetch } from './builtin-types';
 // the first to give up. undici's defaults are 300s, which would abort e.g. an
 // instance-side artifact upload that takes longer.
 const longRequestTimeouts = { headersTimeout: 3_600_000, bodyTimeout: 3_600_000 };
+const maxConnectResponseHeaderBytes = 64 * 1024;
+
+export interface TcpConnectOptions {
+  /** Host actually sent to connect(2), or in the CONNECT authority. */
+  host: string;
+  port: number;
+  /**
+   * Original destination used only for HTTP_PROXY/HTTPS_PROXY/NO_PROXY
+   * selection. This may differ from host when the caller resolved a domain
+   * locally before dialing it.
+   */
+  proxyLookupHost?: string;
+  proxyLookupProtocol: 'http:' | 'https:';
+  timeoutMs: number;
+  signal?: AbortSignal;
+}
+
+export interface TcpConnectResult {
+  socket: net.Socket;
+  connectMs: number;
+  /** Address of the destination, never the address of an HTTP proxy. */
+  remoteAddress?: string;
+}
 
 class NodeProxyTransport {
   private envHttpProxyAgent: EnvHttpProxyAgent | undefined;
@@ -63,6 +88,21 @@ class NodeProxyTransport {
     return agent;
   }
 
+  /**
+   * Opens a paused TCP stream to a destination, tunneling through the proxy
+   * selected by proxy-from-env when applicable. The caller owns the returned
+   * socket and must resume it after installing data/end/error handlers.
+   */
+  connectTcp(options: TcpConnectOptions): Promise<TcpConnectResult> {
+    const lookupHost = options.proxyLookupHost ?? options.host;
+    const lookupUrl = `${options.proxyLookupProtocol}//${formatAuthority(lookupHost, options.port)}`;
+    const proxyUrl = getProxyForUrl(lookupUrl);
+    if (!proxyUrl) {
+      return connectDirect(options);
+    }
+    return connectThroughProxy(proxyUrl, options);
+  }
+
   private getEnvHttpProxyAgent(): EnvHttpProxyAgent {
     this.envHttpProxyAgent ??= new EnvHttpProxyAgent();
     return this.envHttpProxyAgent;
@@ -89,3 +129,211 @@ class NodeProxyTransport {
 }
 
 export const nodeProxyTransport = new NodeProxyTransport();
+
+function connectDirect(options: TcpConnectOptions): Promise<TcpConnectResult> {
+  const startedAt = Date.now();
+  return new Promise((resolve, reject) => {
+    let settled = false;
+    const socket = net.createConnection({
+      host: options.host,
+      port: options.port,
+      allowHalfOpen: true,
+    });
+    const timer = setTimeout(() => {
+      fail(codedError(`connection to ${formatAuthority(options.host, options.port)} timed out`, 'ETIMEDOUT'));
+    }, options.timeoutMs);
+    timer.unref();
+
+    const cleanup = (): void => {
+      clearTimeout(timer);
+      socket.removeListener('connect', onConnect);
+      socket.removeListener('error', fail);
+      options.signal?.removeEventListener('abort', onAbort);
+    };
+    const fail = (error: Error): void => {
+      if (settled) return;
+      settled = true;
+      cleanup();
+      socket.destroy();
+      reject(error);
+    };
+    const onAbort = (): void => fail(codedError('TCP connection cancelled', 'ECANCELED'));
+    const onConnect = (): void => {
+      if (settled) return;
+      settled = true;
+      socket.pause();
+      cleanup();
+      resolve({
+        socket,
+        connectMs: Date.now() - startedAt,
+        ...(socket.remoteAddress === undefined ? {} : { remoteAddress: socket.remoteAddress }),
+      });
+    };
+
+    socket.once('connect', onConnect);
+    socket.once('error', fail);
+    if (options.signal?.aborted) {
+      onAbort();
+    } else {
+      options.signal?.addEventListener('abort', onAbort, { once: true });
+    }
+  });
+}
+
+function connectThroughProxy(proxyUrlString: string, options: TcpConnectOptions): Promise<TcpConnectResult> {
+  const startedAt = Date.now();
+  return new Promise((resolve, reject) => {
+    let settled = false;
+    let response = Buffer.alloc(0);
+    let proxyUrl: URL;
+    try {
+      proxyUrl = new URL(proxyUrlString);
+    } catch {
+      reject(codedError(`invalid proxy URL: ${proxyUrlString}`, 'EPROXY'));
+      return;
+    }
+    if (proxyUrl.protocol !== 'http:' && proxyUrl.protocol !== 'https:') {
+      reject(codedError(`unsupported proxy protocol ${proxyUrl.protocol}`, 'EPROXY'));
+      return;
+    }
+
+    const proxyPort =
+      proxyUrl.port ? Number(proxyUrl.port)
+      : proxyUrl.protocol === 'https:' ? 443
+      : 80;
+    const proxyHost = unbracketHost(proxyUrl.hostname);
+    const socket =
+      proxyUrl.protocol === 'https:' ?
+        tls.connect({
+          host: proxyHost,
+          port: proxyPort,
+          rejectUnauthorized: true,
+          ...(net.isIP(proxyHost) ? {} : { servername: proxyHost }),
+          ALPNProtocols: ['http/1.1'],
+        })
+      : net.createConnection({
+          host: proxyHost,
+          port: proxyPort,
+          allowHalfOpen: true,
+        });
+    socket.allowHalfOpen = true;
+    const connectedEvent = proxyUrl.protocol === 'https:' ? 'secureConnect' : 'connect';
+    const timer = setTimeout(() => {
+      fail(
+        codedError(
+          `proxy connection to ${formatAuthority(options.host, options.port)} timed out`,
+          'ETIMEDOUT',
+        ),
+      );
+    }, options.timeoutMs);
+    timer.unref();
+
+    const cleanup = (): void => {
+      clearTimeout(timer);
+      socket.removeListener(connectedEvent, onProxyConnected);
+      socket.removeListener('data', onData);
+      socket.removeListener('end', onUnexpectedClose);
+      socket.removeListener('close', onUnexpectedClose);
+      socket.removeListener('error', fail);
+      options.signal?.removeEventListener('abort', onAbort);
+    };
+    const fail = (error: Error): void => {
+      if (settled) return;
+      settled = true;
+      cleanup();
+      socket.destroy();
+      reject(error);
+    };
+    const onAbort = (): void => fail(codedError('proxy connection cancelled', 'ECANCELED'));
+    const onUnexpectedClose = (): void =>
+      fail(codedError('proxy closed before completing CONNECT', 'ECONNRESET'));
+    const onProxyConnected = (): void => {
+      const authority = formatAuthority(options.host, options.port);
+      const headers = [`CONNECT ${authority} HTTP/1.1`, `Host: ${authority}`, 'Proxy-Connection: Keep-Alive'];
+      if (proxyUrl.username || proxyUrl.password) {
+        const username = decodeUrlCredential(proxyUrl.username);
+        const password = decodeUrlCredential(proxyUrl.password);
+        headers.push(
+          `Proxy-Authorization: Basic ${Buffer.from(`${username}:${password}`, 'utf8').toString('base64')}`,
+        );
+      }
+      socket.write(`${headers.join('\r\n')}\r\n\r\n`);
+    };
+    const onData = (chunk: Buffer): void => {
+      response = Buffer.concat([response, chunk]);
+      const headerEnd = response.indexOf('\r\n\r\n');
+      if (headerEnd < 0) {
+        if (response.length > maxConnectResponseHeaderBytes) {
+          fail(codedError('proxy CONNECT response headers exceeded 65536 bytes', 'EPROXY'));
+        }
+        return;
+      }
+      if (headerEnd + 4 > maxConnectResponseHeaderBytes) {
+        fail(codedError('proxy CONNECT response headers exceeded 65536 bytes', 'EPROXY'));
+        return;
+      }
+
+      const statusLineEnd = response.indexOf('\r\n');
+      const statusLine = response
+        .subarray(0, statusLineEnd < 0 ? headerEnd : statusLineEnd)
+        .toString('latin1');
+      const statusMatch = /^HTTP\/1\.[01] ([0-9]{3})(?: |$)/.exec(statusLine);
+      if (!statusMatch) {
+        fail(codedError(`invalid proxy CONNECT response: ${statusLine}`, 'EPROXY'));
+        return;
+      }
+      const statusCode = Number(statusMatch[1]);
+      if (statusCode < 200 || statusCode >= 300) {
+        fail(
+          codedError(
+            `proxy CONNECT failed with status ${statusCode}`,
+            statusCode === 407 ? 'EPROXYAUTH' : 'EPROXYCONNECT',
+          ),
+        );
+        return;
+      }
+
+      settled = true;
+      socket.pause();
+      cleanup();
+      const remainder = response.subarray(headerEnd + 4);
+      if (remainder.length > 0) socket.unshift(remainder);
+      resolve({
+        socket,
+        connectMs: Date.now() - startedAt,
+        remoteAddress: options.host,
+      });
+    };
+
+    socket.once(connectedEvent, onProxyConnected);
+    socket.on('data', onData);
+    socket.once('end', onUnexpectedClose);
+    socket.once('close', onUnexpectedClose);
+    socket.once('error', fail);
+    if (options.signal?.aborted) {
+      onAbort();
+    } else {
+      options.signal?.addEventListener('abort', onAbort, { once: true });
+    }
+  });
+}
+
+function formatAuthority(host: string, port: number): string {
+  return `${net.isIP(host) === 6 ? `[${host}]` : host}:${port}`;
+}
+
+function unbracketHost(host: string): string {
+  return host.startsWith('[') && host.endsWith(']') ? host.slice(1, -1) : host;
+}
+
+function decodeUrlCredential(value: string): string {
+  try {
+    return decodeURIComponent(value);
+  } catch {
+    return value;
+  }
+}
+
+function codedError(message: string, code: string): NodeJS.ErrnoException {
+  return Object.assign(new Error(message), { code });
+}

package/src/internal/session-stream.ts

@@ -0,0 +1,157 @@
+/**
+ * Long-lived tail of a runtime session SSE stream (live app logs or the
+ * coalesced event log). The runtime replays its buffer on first connect and
+ * tags every entry with a monotonic SSE id; eventsource-client sends
+ * Last-Event-ID on reconnect, so the runtime resumes exactly where the
+ * stream broke and each entry is delivered exactly once.
+ *
+ * Stream health follows the exec client's model (and reuses its policy): the
+ * EventSource reconnects forever on its own, so a dead stream (deleted
+ * instance) would otherwise retry silently for good. Proof of life — a
+ * delivered entry, a keepalive comment, or a clean connection that stays
+ * open healthyConnectionMs — resets the give-up clock; once the stream stays
+ * broken past giveUpAfterMs, onError fires once and the stream closes.
+ */
+
+import { createEventSource, type EventSourceMessage } from 'eventsource-client';
+import { sseStreamPolicy } from '../exec-client';
+import { nodeProxyTransport } from './proxy-transport';
+import { sseFetch } from './sse-fetch';
+import type { Fetch } from './builtin-types';
+
+/** The session stream kept failing past the give-up window; it has been closed. */
+export class SessionStreamLostError extends Error {}
+
+export interface SessionStreamOptions<T extends { ts: number }> {
+  /** Full URL of the runtime SSE endpoint, without credentials. */
+  url: string;
+  /** Instance token; sent as a bearer Authorization header. */
+  token: string;
+  /** Called once per delivered entry, in stream order. */
+  onEntry: (entry: T) => void;
+  /** Called at most once, when the stream is given up on and closed. */
+  onError?: ((error: Error) => void) | undefined;
+}
+
+/**
+ * Connects to a session SSE endpoint and delivers parsed entries until the
+ * returned function is called (or the stream is given up on). Entries are
+ * one JSON object per SSE data frame; frames that do not parse to an object
+ * with a numeric `ts` are skipped.
+ */
+export function streamSessionEntries<T extends { ts: number }>(options: SessionStreamOptions<T>): () => void {
+  let closed = false;
+  let connectedAt = 0;
+  let deadSince = 0;
+  let lastCycleAt = 0;
+  let lastCycleMono = 0;
+  let proofOfLifeThisCycle = false;
+  let cleanResponseThisCycle = false;
+  let lastStreamError: Error | undefined;
+
+  const fail = (error: Error) => {
+    if (closed) return;
+    closed = true;
+    eventSource.close();
+    options.onError?.(error);
+  };
+
+  // Stream health is judged at the fetch surface, where the response status
+  // is visible; the library fires onConnect for error responses too, so an
+  // error page held open must not read as a healthy connection. A rejected
+  // fetch never reaches onDisconnect (the hazard sseFetch exists for):
+  // capture it for the give-up message and let the clock decide, so one
+  // transient refusal does not kill a live stream.
+  const fetchWithStreamPolicy: Fetch = async (input, init) => {
+    const response = await nodeProxyTransport.fetch(input, init);
+    if (!response.ok) {
+      lastStreamError = new Error(`server answered HTTP ${response.status}`);
+    }
+    cleanResponseThisCycle = response.ok;
+    return response;
+  };
+
+  const eventSource = createEventSource({
+    url: options.url,
+    fetch: sseFetch(fetchWithStreamPolicy, (err) => {
+      lastStreamError = err instanceof Error ? err : new Error(String(err));
+    }),
+    headers: { Authorization: `Bearer ${options.token}` },
+    onConnect: () => {
+      connectedAt = Date.now();
+    },
+    // Keepalive comments count as proof of life (onMessage never sees them).
+    onComment: () => {
+      proofOfLifeThisCycle = true;
+    },
+    // Fires once per broken cycle, before the retry timer is armed, on both
+    // failure paths (request rejected, stream ended). This is where the
+    // give-up clock runs.
+    onScheduleReconnect: () => {
+      if (closed) return;
+      const now = Date.now();
+      const mono = performance.now();
+      const livedMs = connectedAt > 0 ? now - connectedAt : 0;
+      connectedAt = 0;
+      // Date.now() is wall clock: a laptop waking from sleep (or a clock
+      // step) would arrive with the whole window already "elapsed" and fail
+      // on its first attempt. Sleep is the wall clock advancing while the
+      // monotonic clock stands still; a large drift between the two restarts
+      // the streak.
+      if (deadSince > 0 && lastCycleAt > 0) {
+        const wallGapMs = now - lastCycleAt;
+        const monoGapMs = mono - lastCycleMono;
+        if (wallGapMs - monoGapMs > 30_000) {
+          deadSince = now;
+        }
+      }
+      lastCycleAt = now;
+      lastCycleMono = mono;
+      const healthy =
+        proofOfLifeThisCycle || (cleanResponseThisCycle && livedMs >= sseStreamPolicy.healthyConnectionMs);
+      proofOfLifeThisCycle = false;
+      cleanResponseThisCycle = false;
+      if (healthy) {
+        deadSince = 0;
+        lastStreamError = undefined;
+        return;
+      }
+      if (deadSince === 0) {
+        deadSince = now;
+        return;
+      }
+      if (now - deadSince >= sseStreamPolicy.giveUpAfterMs) {
+        const seconds = Math.round((now - deadSince) / 1000);
+        const cause = lastStreamError ? `; last error: ${lastStreamError.message}` : '';
+        fail(
+          new SessionStreamLostError(
+            `session stream to ${options.url} kept failing for ${seconds}s without delivering entries${cause}; ` +
+              'the instance may no longer exist',
+          ),
+        );
+      }
+    },
+    onMessage: (message: EventSourceMessage) => {
+      deadSince = 0;
+      proofOfLifeThisCycle = true;
+      lastStreamError = undefined;
+      const data = typeof message.data === 'string' ? message.data : String(message.data ?? '');
+      let parsed: unknown;
+      try {
+        parsed = JSON.parse(data);
+      } catch {
+        return;
+      }
+      if (typeof (parsed as { ts?: unknown })?.ts !== 'number') {
+        return;
+      }
+      options.onEntry(parsed as T);
+    },
+  });
+
+  return () => {
+    if (closed) return;
+    closed = true;
+    eventSource.close();
+  };
+}