@hashtree/worker 0.2.0 → 0.2.1

package/src/index.ts

@@ -0,0 +1,76 @@
+export { HashtreeWorkerClient } from './client.js';
+export type { WorkerFactory, P2PFetchHandler } from './client.js';
+export { RelayWorkerClient } from './relay-client.js';
+export type {
+  TreeRootInfo as RelayTreeRootInfo,
+  TreeRootUpdate as RelayTreeRootUpdate,
+  RelayWorkerConfig,
+  RelayWorkerRequest,
+  RelayWorkerResponse,
+} from './relay-client.js';
+export {
+  canUseInjectedHtreeServerUrl,
+  canUseSameOriginHtreeProtocolStreaming,
+  getInjectedHtreeServerUrl,
+  resolveRuntimeHtreeBaseUrl,
+  shouldEagerLoadMediaInNativeChildRuntime,
+  shouldPreferSameOriginHtreeRoutes,
+} from './runtime.js';
+export type {
+  HtreeRuntimeLocationLike,
+  HtreeRuntimeWindowLike,
+  ResolveRuntimeHtreeBaseUrlOptions,
+} from './runtime.js';
+export {
+  resolveRuntimeEndpoints,
+} from './runtime-network.js';
+export type {
+  ResolveRuntimeEndpointsOptions,
+  RuntimeEndpoints,
+} from './runtime-network.js';
+export { createHtreeRuntime } from './app-runtime.js';
+export type {
+  HtreeRuntime,
+  HtreeRuntimeEndpointOverrides,
+  HtreeRuntimeMediaPortOptions,
+  HtreeRuntimeMediaUrlOptions,
+  HtreeRuntimeOptions,
+  HtreeRuntimeRequestUrlOptions,
+  HtreeRuntimeWorkerConfigOptions,
+  RuntimeValueSource,
+} from './app-runtime.js';
+export {
+  buildHtreeRequestPath,
+  parseHtreeUrl,
+  resolveHtreeRequestUrl,
+} from './htree-url.js';
+export type {
+  MutableHtreeRequestStyle,
+  ParsedHtreeUrl,
+  ResolveHtreeRequestUrlOptions,
+} from './htree-url.js';
+export type { HtreeClientIdStorageLike } from './client-id.js';
+export type {
+  BlossomServerConfig,
+  WorkerConfig,
+  WorkerRequest,
+  WorkerResponse,
+  RootResolveOptions,
+  ConnectivityState,
+  UploadProgressState,
+  WorkerDiagnosticEvent,
+  WorkerDiagnosticLevel,
+  BlossomBandwidthState,
+  BlossomBandwidthServerStats,
+  BlobSource,
+} from './protocol.js';
+
+export {
+  WebRTCController,
+  WebRTCProxy,
+  initWebRTCProxy,
+  getWebRTCProxy,
+  closeWebRTCProxy,
+} from './p2p/index.js';
+
+export type { WebRTCControllerConfig } from './p2p/index.js';

package/src/mediaStreaming.ts

@@ -0,0 +1,64 @@
+import type { CID, HashTree } from '@hashtree/core';
+
+const DEFAULT_PREFETCH = 2;
+
+/**
+ * Stream a bounded byte range from a CID without materializing the whole range in memory.
+ * Output chunks are capped at `chunkSize` bytes.
+ */
+export async function* streamFileRangeChunks(
+  tree: Pick<HashTree, 'readFileStream'>,
+  cid: CID,
+  start: number,
+  endInclusive: number,
+  chunkSize: number,
+  prefetch: number = DEFAULT_PREFETCH
+): AsyncGenerator<Uint8Array> {
+  if (chunkSize <= 0) {
+    throw new Error('chunkSize must be > 0');
+  }
+  if (endInclusive < start) {
+    return;
+  }
+
+  let remaining = endInclusive - start + 1;
+  let pending = new Uint8Array(chunkSize);
+  let pendingLength = 0;
+
+  for await (const sourceChunk of tree.readFileStream(cid, { offset: start, prefetch })) {
+    if (remaining <= 0) break;
+    if (sourceChunk.byteLength === 0) continue;
+
+    const consumed = Math.min(sourceChunk.byteLength, remaining);
+    const source = consumed === sourceChunk.byteLength ? sourceChunk : sourceChunk.subarray(0, consumed);
+    remaining -= consumed;
+
+    let cursor = 0;
+    while (cursor < source.byteLength) {
+      const available = source.byteLength - cursor;
+
+      if (pendingLength === 0 && available >= chunkSize) {
+        // Emit direct full-size chunks with independent buffers for transfer.
+        yield source.slice(cursor, cursor + chunkSize);
+        cursor += chunkSize;
+        continue;
+      }
+
+      const toCopy = Math.min(chunkSize - pendingLength, available);
+      pending.set(source.subarray(cursor, cursor + toCopy), pendingLength);
+      pendingLength += toCopy;
+      cursor += toCopy;
+
+      if (pendingLength === chunkSize) {
+        yield pending;
+        pending = new Uint8Array(chunkSize);
+        pendingLength = 0;
+      }
+    }
+  }
+
+  if (pendingLength > 0) {
+    yield pending.slice(0, pendingLength);
+  }
+}
+

package/src/p2p/boundedQueue.ts

@@ -0,0 +1,168 @@
+/**
+ * BoundedQueue - Memory-safe queue with size limits
+ *
+ * Prevents memory blowup by enforcing both item count and byte limits.
+ * When limits are exceeded, oldest items are dropped (FIFO eviction).
+ *
+ * Use this instead of plain arrays for queues that could grow unbounded,
+ * especially for network buffers, send queues, and work queues.
+ */
+
+export interface BoundedQueueOptions<T> {
+  /** Maximum number of items in queue */
+  maxItems: number;
+  /** Maximum total bytes in queue */
+  maxBytes: number;
+  /** Function to get byte size of an item */
+  getBytes: (item: T) => number;
+  /** Optional callback when items are dropped due to overflow */
+  onDrop?: (item: T, reason: 'items' | 'bytes') => void;
+}
+
+export class BoundedQueue<T> {
+  private items: T[] = [];
+  private bytesUsed = 0;
+  private readonly maxItems: number;
+  private readonly maxBytes: number;
+  private readonly getBytes: (item: T) => number;
+  private readonly onDrop?: (item: T, reason: 'items' | 'bytes') => void;
+
+  constructor(options: BoundedQueueOptions<T>) {
+    this.maxItems = options.maxItems;
+    this.maxBytes = options.maxBytes;
+    this.getBytes = options.getBytes;
+    this.onDrop = options.onDrop;
+  }
+
+  /**
+   * Add item to queue, dropping oldest items if limits exceeded
+   * @returns Number of items dropped to make room
+   */
+  push(item: T): number {
+    const itemBytes = this.getBytes(item);
+    let dropped = 0;
+
+    // Drop oldest items until we have room
+    while (
+      this.items.length > 0 &&
+      (this.items.length >= this.maxItems || this.bytesUsed + itemBytes > this.maxBytes)
+    ) {
+      const droppedItem = this.items.shift()!;
+      const droppedBytes = this.getBytes(droppedItem);
+      this.bytesUsed -= droppedBytes;
+      dropped++;
+
+      if (this.onDrop) {
+        const reason = this.items.length >= this.maxItems ? 'items' : 'bytes';
+        this.onDrop(droppedItem, reason);
+      }
+    }
+
+    this.items.push(item);
+    this.bytesUsed += itemBytes;
+    return dropped;
+  }
+
+  /**
+   * Add item to the front of the queue, dropping items from the back if limits are exceeded.
+   * Useful for urgent control messages that should overtake bulk background traffic.
+   */
+  unshift(item: T): number {
+    const itemBytes = this.getBytes(item);
+    let dropped = 0;
+
+    while (
+      this.items.length > 0 &&
+      (this.items.length >= this.maxItems || this.bytesUsed + itemBytes > this.maxBytes)
+    ) {
+      const droppedItem = this.items.pop()!;
+      const droppedBytes = this.getBytes(droppedItem);
+      this.bytesUsed -= droppedBytes;
+      dropped++;
+
+      if (this.onDrop) {
+        const reason = this.items.length >= this.maxItems ? 'items' : 'bytes';
+        this.onDrop(droppedItem, reason);
+      }
+    }
+
+    this.items.unshift(item);
+    this.bytesUsed += itemBytes;
+    return dropped;
+  }
+
+  /**
+   * Remove and return oldest item, or undefined if empty
+   */
+  shift(): T | undefined {
+    const item = this.items.shift();
+    if (item !== undefined) {
+      this.bytesUsed -= this.getBytes(item);
+    }
+    return item;
+  }
+
+  /**
+   * Peek at oldest item without removing
+   */
+  peek(): T | undefined {
+    return this.items[0];
+  }
+
+  /**
+   * Clear all items
+   */
+  clear(): void {
+    this.items = [];
+    this.bytesUsed = 0;
+  }
+
+  /**
+   * Get current item count
+   */
+  get length(): number {
+    return this.items.length;
+  }
+
+  /**
+   * Get current byte usage
+   */
+  get bytes(): number {
+    return this.bytesUsed;
+  }
+
+  /**
+   * Check if queue is empty
+   */
+  get isEmpty(): boolean {
+    return this.items.length === 0;
+  }
+
+  /**
+   * Check if queue is at item capacity
+   */
+  get isFullItems(): boolean {
+    return this.items.length >= this.maxItems;
+  }
+
+  /**
+   * Check if queue is at byte capacity
+   */
+  get isFullBytes(): boolean {
+    return this.bytesUsed >= this.maxBytes;
+  }
+
+  /**
+   * Iterate over items (does not remove them)
+   */
+  *[Symbol.iterator](): Iterator<T> {
+    yield* this.items;
+  }
+
+  /**
+   * Get all items as array (for iteration/reduce operations)
+   */
+  toArray(): T[] {
+    return [...this.items];
+  }
+}

package/src/p2p/errorMessage.ts

@@ -0,0 +1,6 @@
+/**
+ * Extract error message from unknown error type
+ */
+export function getErrorMessage(err: unknown): string {
+  return err instanceof Error ? err.message : String(err);
+}

package/src/p2p/index.ts

@@ -0,0 +1,48 @@
+export {
+  WebRTCController,
+  type WebRTCControllerConfig,
+} from './webrtcController.js';
+
+export {
+  MeshQueryRouter,
+  encodeForwardRequest,
+  type MeshQueryRouterConfig,
+  type MeshQueryRouterPeer,
+} from './meshQueryRouter.js';
+
+export {
+  QueryForwardingMachine,
+  type QueryForwardingMachineConfig,
+  type ForwardDecision,
+  type ForwardTimeoutEvent,
+} from './queryForwardingMachine.js';
+
+export {
+  WebRTCProxy,
+  initWebRTCProxy,
+  getWebRTCProxy,
+  closeWebRTCProxy,
+} from './webrtcProxy.js';
+
+export type {
+  WebRTCCommand,
+  WebRTCEvent,
+} from './protocol.js';
+
+export {
+  SIGNALING_KIND,
+  HELLO_TAG,
+  MAX_EVENT_AGE_SEC,
+  createSignalingFilters,
+  sendSignalingMessage,
+  decodeSignalingEvent,
+} from './signaling.js';
+
+export type {
+  SignalingEventLike,
+  GiftSeal,
+  SignalingTemplate,
+  SignalingInnerEvent,
+  SignalingFilters,
+  DecodedSignalingEvent,
+} from './signaling.js';

package/src/p2p/lruCache.ts

@@ -0,0 +1,78 @@
+/**
+ * Simple LRU Cache implementation
+ */
+export class LRUCache<K, V> {
+  private cache = new Map<K, V>();
+  private maxSize: number;
+
+  constructor(maxSize: number = 100) {
+    this.maxSize = maxSize;
+  }
+
+  get(key: K): V | undefined {
+    const value = this.cache.get(key);
+    if (value !== undefined) {
+      // Move to end (most recently used)
+      this.cache.delete(key);
+      this.cache.set(key, value);
+    }
+    return value;
+  }
+
+  set(key: K, value: V): void {
+    // Delete first to reset position if exists
+    this.cache.delete(key);
+
+    // Evict oldest if at capacity
+    if (this.cache.size >= this.maxSize) {
+      const oldest = this.cache.keys().next().value;
+      if (oldest !== undefined) {
+        this.cache.delete(oldest);
+      }
+    }
+
+    this.cache.set(key, value);
+  }
+
+  has(key: K): boolean {
+    return this.cache.has(key);
+  }
+
+  delete(key: K): boolean {
+    return this.cache.delete(key);
+  }
+
+  clear(): void {
+    this.cache.clear();
+  }
+
+  get size(): number {
+    return this.cache.size;
+  }
+
+  keys(): IterableIterator<K> {
+    return this.cache.keys();
+  }
+
+  values(): IterableIterator<V> {
+    return this.cache.values();
+  }
+
+  /**
+   * Iterate over all entries (note: does not update LRU order)
+   */
+  *entries(): IterableIterator<[K, V]> {
+    yield* this.cache.entries();
+  }
+
+  forEach(callback: (value: V, key: K) => void): void {
+    this.cache.forEach(callback);
+  }
+
+  /**
+   * Make the cache iterable
+   */
+  [Symbol.iterator](): IterableIterator<[K, V]> {
+    return this.entries();
+  }
+}