@hashtree/worker 0.1.26 → 0.2.1

package/src/relay-client.ts

@@ -0,0 +1,265 @@
+import type { WorkerFactory } from './client.js';
+import type {
+  TreeRootInfo,
+  WorkerConfig as RelayWorkerConfig,
+  WorkerRequest as RelayWorkerRequest,
+  WorkerResponse as RelayWorkerResponse,
+} from './relay/protocol.js';
+
+const REQUEST_TIMEOUT_MS = 30_000;
+
+type PendingRequest = {
+  resolve: (message: RelayWorkerResponse) => void;
+  reject: (error: Error) => void;
+  timeoutId: ReturnType<typeof setTimeout>;
+};
+
+type RelayWorkerRequestPayload = RelayWorkerRequest extends infer T
+  ? T extends { id: string }
+    ? Omit<T, 'id'>
+    : never
+  : never;
+
+export interface TreeRootUpdate extends TreeRootInfo {
+  npub: string;
+  treeName: string;
+}
+
+export type {
+  TreeRootInfo,
+  RelayWorkerConfig,
+  RelayWorkerRequest,
+  RelayWorkerResponse,
+};
+
+export class RelayWorkerClient {
+  private readonly workerFactory: WorkerFactory;
+  private readonly config: RelayWorkerConfig;
+  private worker: Worker | null = null;
+  private initPromise: Promise<void> | null = null;
+  private initPending:
+    | {
+        resolve: () => void;
+        reject: (error: Error) => void;
+        timeoutId: ReturnType<typeof setTimeout>;
+      }
+    | null = null;
+  private pendingRequests = new Map<string, PendingRequest>();
+  private treeRootListeners = new Set<(update: TreeRootUpdate) => void>();
+
+  constructor(workerFactory: WorkerFactory, config: RelayWorkerConfig) {
+    this.workerFactory = workerFactory;
+    this.config = config;
+  }
+
+  async init(): Promise<void> {
+    if (this.initPromise) return this.initPromise;
+
+    try {
+      this.spawnWorker();
+    } catch (err) {
+      throw err instanceof Error ? err : new Error(String(err));
+    }
+
+    this.initPromise = new Promise<void>((resolve, reject) => {
+      if (!this.worker) {
+        reject(new Error('Failed to create worker'));
+        return;
+      }
+
+      const timeoutId = setTimeout(() => {
+        this.initPending = null;
+        this.initPromise = null;
+        reject(new Error('Worker init timed out'));
+      }, REQUEST_TIMEOUT_MS);
+
+      this.initPending = {
+        resolve,
+        reject,
+        timeoutId,
+      };
+
+      this.worker.postMessage({
+        type: 'init',
+        id: this.nextRequestId('worker_init'),
+        config: this.config,
+      } as RelayWorkerRequest);
+    });
+
+    return this.initPromise;
+  }
+
+  private spawnWorker(): void {
+    if (this.workerFactory instanceof URL) {
+      this.worker = new Worker(this.workerFactory, { type: 'module' });
+    } else if (typeof this.workerFactory === 'string') {
+      this.worker = new Worker(this.workerFactory, { type: 'module' });
+    } else {
+      this.worker = new this.workerFactory();
+    }
+
+    this.worker.onmessage = (event: MessageEvent<RelayWorkerResponse>) => {
+      const message = event.data;
+
+      if (message.type === 'ready') {
+        if (this.initPending) {
+          clearTimeout(this.initPending.timeoutId);
+          this.initPending.resolve();
+          this.initPending = null;
+        }
+        return;
+      }
+
+      if (message.type === 'treeRootUpdate') {
+        for (const listener of this.treeRootListeners) {
+          const { type: _type, ...update } = message;
+          listener(update);
+        }
+        return;
+      }
+
+      if (message.type === 'error' && message.id) {
+        const errorMessage = typeof message.error === 'string' ? message.error : 'Worker error';
+        this.rejectPending(message.id, new Error(errorMessage));
+        return;
+      }
+
+      if ('id' in message && typeof message.id === 'string') {
+        this.resolvePending(message.id, message);
+      }
+    };
+
+    this.worker.onerror = (event) => {
+      const errorMessage = event instanceof ErrorEvent ? event.message : 'Worker error';
+      this.rejectAllPending(new Error(errorMessage));
+    };
+  }
+
+  private nextRequestId(prefix: string): string {
+    if (typeof crypto !== 'undefined' && 'randomUUID' in crypto) {
+      return `${prefix}_${crypto.randomUUID()}`;
+    }
+    return `${prefix}_${Date.now().toString(36)}_${Math.random().toString(36).slice(2)}`;
+  }
+
+  private resolvePending(id: string, message: RelayWorkerResponse): void {
+    const pending = this.pendingRequests.get(id);
+    if (!pending) return;
+    clearTimeout(pending.timeoutId);
+    pending.resolve(message);
+    this.pendingRequests.delete(id);
+  }
+
+  private rejectPending(id: string, error: Error): void {
+    const pending = this.pendingRequests.get(id);
+    if (!pending) return;
+    clearTimeout(pending.timeoutId);
+    pending.reject(error);
+    this.pendingRequests.delete(id);
+  }
+
+  private rejectAllPending(error: Error): void {
+    for (const [id, pending] of this.pendingRequests.entries()) {
+      clearTimeout(pending.timeoutId);
+      pending.reject(error);
+      this.pendingRequests.delete(id);
+    }
+
+    if (this.initPending) {
+      clearTimeout(this.initPending.timeoutId);
+      this.initPending.reject(error);
+      this.initPending = null;
+    }
+
+    this.initPromise = null;
+  }
+
+  private async request(
+    payload: RelayWorkerRequestPayload,
+    timeoutMs = REQUEST_TIMEOUT_MS,
+    transfer: Transferable[] = [],
+  ): Promise<RelayWorkerResponse> {
+    await this.init();
+    if (!this.worker) {
+      throw new Error('Worker not initialized');
+    }
+
+    const id = this.nextRequestId(payload.type);
+    const message = { ...payload, id } as RelayWorkerRequest;
+
+    return new Promise<RelayWorkerResponse>((resolve, reject) => {
+      const timeoutId = setTimeout(() => {
+        this.pendingRequests.delete(id);
+        reject(new Error(`Worker request timed out: ${payload.type}`));
+      }, timeoutMs);
+
+      this.pendingRequests.set(id, { resolve, reject, timeoutId });
+      this.worker?.postMessage(message, transfer);
+    });
+  }
+
+  async registerMediaPort(port: MessagePort, debug?: boolean): Promise<void> {
+    await this.init();
+    if (!this.worker) {
+      throw new Error('Worker not initialized');
+    }
+
+    this.worker.postMessage({ type: 'registerMediaPort', port, debug } as RelayWorkerRequest, [port]);
+  }
+
+  async getTreeRootInfo(npub: string, treeName: string): Promise<TreeRootInfo | null> {
+    const res = await this.request({ type: 'getTreeRootInfo', npub, treeName });
+    if (res.type !== 'treeRootInfo') {
+      throw new Error('Unexpected tree root response');
+    }
+    if (res.error) {
+      throw new Error(res.error);
+    }
+    return res.record ?? null;
+  }
+
+  async subscribeTreeRoots(pubkey: string): Promise<void> {
+    const res = await this.request({ type: 'subscribeTreeRoots', pubkey });
+    if (res.type !== 'void') {
+      throw new Error('Unexpected tree root subscribe response');
+    }
+    if (res.error) {
+      throw new Error(res.error);
+    }
+  }
+
+  async unsubscribeTreeRoots(pubkey: string): Promise<void> {
+    const res = await this.request({ type: 'unsubscribeTreeRoots', pubkey });
+    if (res.type !== 'void') {
+      throw new Error('Unexpected tree root unsubscribe response');
+    }
+    if (res.error) {
+      throw new Error(res.error);
+    }
+  }
+
+  onTreeRootUpdate(listener: (update: TreeRootUpdate) => void): () => void {
+    this.treeRootListeners.add(listener);
+    return () => {
+      this.treeRootListeners.delete(listener);
+    };
+  }
+
+  async close(): Promise<void> {
+    try {
+      const res = await this.request({ type: 'close' });
+      if (res.type !== 'void' && res.type !== 'error') {
+        throw new Error('Unexpected response for close');
+      }
+    } catch {
+      // Ignore close errors and always terminate locally.
+    }
+
+    this.treeRootListeners.clear();
+    this.worker?.terminate();
+    this.worker = null;
+    this.initPromise = null;
+    this.initPending = null;
+    this.rejectAllPending(new Error('Worker closed'));
+  }
+}

package/src/relay-entry.ts

@@ -0,0 +1 @@
+import './relay/worker.js';

package/src/runtime-network.ts

@@ -0,0 +1,134 @@
+import type { BlossomServerConfig } from './protocol.js';
+import { getInjectedHtreeServerUrl, type HtreeRuntimeWindowLike } from './runtime.js';
+
+export interface RuntimeNetworkOptions {
+  windowLike?: HtreeRuntimeWindowLike;
+}
+
+export interface ResolveRuntimeEndpointsOptions extends RuntimeNetworkOptions {
+  relays?: readonly string[];
+  blossomServers?: readonly BlossomServerConfig[];
+}
+
+export interface RuntimeEndpoints {
+  htreeServerUrl: string | null;
+  nostrRelays: string[];
+  blossomServers: BlossomServerConfig[];
+}
+
+export function normalizeRuntimeServerUrl(url: string): string {
+  return url.trim().replace(/\/+$/, '');
+}
+
+export function normalizeRuntimeRelayUrl(url: string): string {
+  return url.trim().replace(/\/+$/, '');
+}
+
+function normalizeBlossomServer(server: BlossomServerConfig): BlossomServerConfig | null {
+  const url = normalizeRuntimeServerUrl(server.url);
+  if (!url) return null;
+  return {
+    url,
+    read: server.read ?? true,
+    write: server.write ?? false,
+  };
+}
+
+function uniqueRelayUrls(relays: readonly string[]): string[] {
+  const seen = new Set<string>();
+  const normalized: string[] = [];
+  for (const relay of relays) {
+    const url = normalizeRuntimeRelayUrl(relay);
+    if (!url || seen.has(url)) continue;
+    seen.add(url);
+    normalized.push(url);
+  }
+  return normalized;
+}
+
+export function getRuntimeHtreeServerUrl(windowLike?: HtreeRuntimeWindowLike): string | null {
+  const serverUrl = getInjectedHtreeServerUrl(windowLike);
+  if (!serverUrl) return null;
+  return normalizeRuntimeServerUrl(serverUrl);
+}
+
+export function getRuntimeNostrRelayUrl(windowLike?: HtreeRuntimeWindowLike): string | null {
+  const serverUrl = getRuntimeHtreeServerUrl(windowLike);
+  if (!serverUrl) return null;
+
+  try {
+    const url = new URL(serverUrl);
+    if (url.protocol === 'http:') {
+      url.protocol = 'ws:';
+    } else if (url.protocol === 'https:') {
+      url.protocol = 'wss:';
+    } else {
+      return null;
+    }
+    url.pathname = '/ws';
+    url.search = '';
+    url.hash = '';
+    return normalizeRuntimeRelayUrl(url.toString());
+  } catch {
+    return null;
+  }
+}
+
+export function getRuntimeBlossomServer(windowLike?: HtreeRuntimeWindowLike): BlossomServerConfig | null {
+  const serverUrl = getRuntimeHtreeServerUrl(windowLike);
+  if (!serverUrl) return null;
+  return {
+    url: serverUrl,
+    read: true,
+    write: true,
+  };
+}
+
+export function getRuntimeNostrRelays(
+  relays: readonly string[],
+  options: RuntimeNetworkOptions = {},
+): string[] {
+  const runtimeRelayUrl = getRuntimeNostrRelayUrl(options.windowLike);
+  if (runtimeRelayUrl) {
+    return [runtimeRelayUrl];
+  }
+  return uniqueRelayUrls(relays);
+}
+
+export function getRuntimeBlossomServers(
+  servers: readonly BlossomServerConfig[],
+  options: RuntimeNetworkOptions = {},
+): BlossomServerConfig[] {
+  const merged = new Map<string, BlossomServerConfig>();
+  const runtimeServer = getRuntimeBlossomServer(options.windowLike);
+  const candidates = runtimeServer ? [runtimeServer, ...servers] : [...servers];
+
+  for (const candidate of candidates) {
+    const normalized = normalizeBlossomServer(candidate);
+    if (!normalized) continue;
+
+    const existing = merged.get(normalized.url);
+    if (existing) {
+      merged.set(normalized.url, {
+        url: normalized.url,
+        read: existing.read || normalized.read,
+        write: existing.write || normalized.write,
+      });
+      continue;
+    }
+
+    merged.set(normalized.url, normalized);
+  }
+
+  return Array.from(merged.values());
+}
+
+export function resolveRuntimeEndpoints(
+  options: ResolveRuntimeEndpointsOptions = {},
+): RuntimeEndpoints {
+  return {
+    htreeServerUrl: getRuntimeHtreeServerUrl(options.windowLike),
+    nostrRelays: getRuntimeNostrRelays(options.relays ?? [], options),
+    blossomServers: getRuntimeBlossomServers(options.blossomServers ?? [], options),
+  };
+}

package/src/runtime.ts

@@ -0,0 +1,153 @@
+export interface HtreeRuntimeLocationLike {
+  protocol?: string;
+  hostname?: string;
+  search?: string;
+}
+
+export interface HtreeRuntimeWindowLike {
+  location?: HtreeRuntimeLocationLike;
+  __HTREE_SERVER_URL__?: string;
+  __HTREE_CANONICAL_URL__?: string | null;
+  htree?: {
+    htreeBaseUrl?: string;
+  };
+}
+
+export interface ResolveRuntimeHtreeBaseUrlOptions {
+  windowLike?: HtreeRuntimeWindowLike;
+  fallbackBaseUrl?: string | null;
+}
+
+function getWindowLike(windowLike?: HtreeRuntimeWindowLike): HtreeRuntimeWindowLike | null {
+  if (windowLike) return windowLike;
+  if (typeof window === 'undefined') return null;
+  return window as HtreeRuntimeWindowLike;
+}
+
+function normalizeBaseUrl(url: string | null | undefined): string {
+  return (url ?? '').trim().replace(/\/$/, '');
+}
+
+function getQueryParam(name: string, windowLike?: HtreeRuntimeWindowLike): string | null {
+  const runtimeWindow = getWindowLike(windowLike);
+  if (!runtimeWindow) return null;
+  try {
+    const value = new URLSearchParams(runtimeWindow.location?.search ?? '').get(name);
+    return typeof value === 'string' ? value.trim() || null : null;
+  } catch {
+    return null;
+  }
+}
+
+function getPageProtocol(windowLike?: HtreeRuntimeWindowLike): string | null {
+  const runtimeWindow = getWindowLike(windowLike);
+  const protocol = runtimeWindow?.location?.protocol;
+  return typeof protocol === 'string' ? protocol.toLowerCase() : null;
+}
+
+function getPageHostname(windowLike?: HtreeRuntimeWindowLike): string | null {
+  const runtimeWindow = getWindowLike(windowLike);
+  const hostname = runtimeWindow?.location?.hostname;
+  return typeof hostname === 'string' ? hostname.toLowerCase() : null;
+}
+
+function hasCanonicalHtreeIdentity(windowLike?: HtreeRuntimeWindowLike): boolean {
+  const runtimeWindow = getWindowLike(windowLike);
+  const injectedCanonical = runtimeWindow?.__HTREE_CANONICAL_URL__;
+  const canonical = typeof injectedCanonical === 'string' && injectedCanonical.trim()
+    ? injectedCanonical.trim()
+    : getQueryParam('htree_canonical', windowLike);
+  return typeof canonical === 'string' && canonical.toLowerCase().startsWith('htree://');
+}
+
+function isLoopbackChildRuntime(windowLike?: HtreeRuntimeWindowLike): boolean {
+  if (getPageProtocol(windowLike) !== 'http:') return false;
+  const hostname = getPageHostname(windowLike);
+  if (!hostname) return false;
+  return hostname === '127.0.0.1'
+    || hostname === 'localhost'
+    || hostname.endsWith('.htree.localhost');
+}
+
+function getServerProtocol(serverUrl: string): string | null {
+  try {
+    return new URL(serverUrl).protocol.toLowerCase();
+  } catch {
+    return null;
+  }
+}
+
+function isLocalHttpServerUrl(serverUrl: string): boolean {
+  try {
+    const parsed = new URL(serverUrl);
+    const hostname = parsed.hostname.toLowerCase();
+    return (parsed.protocol === 'http:' || parsed.protocol === 'https:')
+      && (hostname === '127.0.0.1' || hostname === 'localhost' || hostname.endsWith('.htree.localhost'));
+  } catch {
+    return false;
+  }
+}
+
+function getWindowHtreeBaseUrl(windowLike?: HtreeRuntimeWindowLike): string {
+  const runtimeWindow = getWindowLike(windowLike);
+  return normalizeBaseUrl(runtimeWindow?.htree?.htreeBaseUrl);
+}
+
+export function getInjectedHtreeServerUrl(windowLike?: HtreeRuntimeWindowLike): string | null {
+  const runtimeWindow = getWindowLike(windowLike);
+  if (!runtimeWindow) return null;
+  const override = runtimeWindow.__HTREE_SERVER_URL__;
+  const fallback = getQueryParam('htree_server', runtimeWindow);
+  const candidate = typeof override === 'string' && override.trim() ? override : fallback;
+  const normalized = normalizeBaseUrl(candidate);
+  return normalized || null;
+}
+
+export function shouldEagerLoadMediaInNativeChildRuntime(windowLike?: HtreeRuntimeWindowLike): boolean {
+  return isLoopbackChildRuntime(windowLike) && hasCanonicalHtreeIdentity(windowLike);
+}
+
+export function shouldPreferSameOriginHtreeRoutes(windowLike?: HtreeRuntimeWindowLike): boolean {
+  const serverUrl = getInjectedHtreeServerUrl(windowLike);
+  if (!serverUrl) return false;
+  const serverProtocol = getServerProtocol(serverUrl);
+  if (serverProtocol !== 'http:') return false;
+
+  const pageProtocol = getPageProtocol(windowLike);
+  if (pageProtocol === 'https:') return true;
+  if (pageProtocol === 'htree:') {
+    const hostname = getPageHostname(windowLike);
+    return hostname?.startsWith('npub1') === true || hostname === 'self';
+  }
+  if (hasCanonicalHtreeIdentity(windowLike) && !isLoopbackChildRuntime(windowLike)) return true;
+  return false;
+}
+
+export function canUseInjectedHtreeServerUrl(windowLike?: HtreeRuntimeWindowLike): boolean {
+  const serverUrl = getInjectedHtreeServerUrl(windowLike);
+  return !!serverUrl && !shouldPreferSameOriginHtreeRoutes(windowLike);
+}
+
+export function canUseSameOriginHtreeProtocolStreaming(windowLike?: HtreeRuntimeWindowLike): boolean {
+  return getPageProtocol(windowLike) === 'htree:';
+}
+
+export function resolveRuntimeHtreeBaseUrl(
+  options: ResolveRuntimeHtreeBaseUrlOptions = {},
+): string {
+  const { windowLike, fallbackBaseUrl } = options;
+  const injectedServerUrl = getInjectedHtreeServerUrl(windowLike);
+
+  if (injectedServerUrl && canUseInjectedHtreeServerUrl(windowLike)) {
+    return injectedServerUrl;
+  }
+
+  const windowBaseUrl = getWindowHtreeBaseUrl(windowLike);
+  if (windowBaseUrl) {
+    if (!isLocalHttpServerUrl(windowBaseUrl) || canUseInjectedHtreeServerUrl(windowLike)) {
+      return windowBaseUrl;
+    }
+  }
+
+  return normalizeBaseUrl(fallbackBaseUrl);
+}

package/src/transferableBytes.ts

@@ -0,0 +1,5 @@
+// Worker replies may reuse bytes from caches or stores. Copy them before
+// transfer so postMessage ownership changes do not detach the source buffer.
+export function cloneTransferableBytes(bytes: Uint8Array): Uint8Array {
+  return bytes.slice();
+}