@hashtree/worker 0.1.26 → 0.2.1

package/src/capabilities/rootResolver.ts

@@ -0,0 +1,497 @@
+import type { CID, HashTree } from '@hashtree/core';
+import { parseHashtreeRootEvent, type NostrEvent } from '@hashtree/nostr';
+import { nip19 } from 'nostr-tools';
+
+export const DEFAULT_ROOT_RESOLVE_TIMEOUT_MS = 15_000;
+export const DEFAULT_ROOT_RESOLVE_SETTLE_MS = 500;
+
+const MAX_TREE_ROOT_EVENTS = 8;
+const DEFAULT_ROOT_RESOLVE_RELAYS = [
+  'wss://relay.damus.io',
+  'wss://relay.primal.net',
+  'wss://relay.nostr.band',
+  'wss://relay.snort.social',
+];
+
+function withUniqueRelays(relays?: string[]): string[] {
+  const seen = new Set<string>();
+  const result: string[] = [];
+
+  for (const relay of [...(relays ?? []), ...DEFAULT_ROOT_RESOLVE_RELAYS]) {
+    const normalized = relay.trim();
+    if (!normalized || seen.has(normalized)) continue;
+    seen.add(normalized);
+    result.push(normalized);
+  }
+
+  return result;
+}
+
+function safeDecodePathSegment(segment: string): string {
+  try {
+    return decodeURIComponent(segment);
+  } catch {
+    return segment;
+  }
+}
+
+function splitPathSegments(path?: string): string[] {
+  return path
+    ?.split('/')
+    .filter(Boolean)
+    .map(safeDecodePathSegment) ?? [];
+}
+
+function compareReplaceableEvents(left: NostrEvent, right: NostrEvent): number {
+  const createdAtDiff = (right.created_at ?? 0) - (left.created_at ?? 0);
+  if (createdAtDiff !== 0) {
+    return createdAtDiff;
+  }
+
+  const leftId = left.id ?? '';
+  const rightId = right.id ?? '';
+  return rightId.localeCompare(leftId);
+}
+
+type ParsedRootPath = {
+  exactTreeName: string;
+  treeName: string;
+  subPath: string[];
+  watchTreeNames: string[];
+};
+
+type RootRecord = {
+  event: NostrEvent;
+  cid: CID;
+};
+
+export interface RootWatchHandle {
+  initialCid: CID | null;
+  close(): Promise<void>;
+}
+
+function decodeNpub(npub: string): string | null {
+  try {
+    const decoded = nip19.decode(npub);
+    if (decoded.type !== 'npub' || typeof decoded.data !== 'string') {
+      return null;
+    }
+    return decoded.data;
+  } catch {
+    return null;
+  }
+}
+
+function parseRootLookupPath(path?: string): ParsedRootPath {
+  const pathSegments = splitPathSegments(path);
+  const exactTreeName = pathSegments.join('/') || 'public';
+  const treeName = pathSegments[0] || 'public';
+  const subPath = pathSegments.slice(1);
+  const watchTreeNames = Array.from(new Set([exactTreeName, treeName]));
+
+  return {
+    exactTreeName,
+    treeName,
+    subPath,
+    watchTreeNames,
+  };
+}
+
+function cidKey(cid: CID | null): string {
+  if (!cid) return '';
+  const keyHex = cid.key ? Array.from(cid.key).map((byte) => byte.toString(16).padStart(2, '0')).join('') : '';
+  const hashHex = Array.from(cid.hash).map((byte) => byte.toString(16).padStart(2, '0')).join('');
+  return keyHex ? `${hashHex}:${keyHex}` : hashHex;
+}
+
+function updateLatestRecord(current: RootRecord | null, event: NostrEvent, cid: CID): RootRecord | null {
+  if (current && compareReplaceableEvents(event, current.event) >= 0) {
+    return null;
+  }
+
+  return { event, cid };
+}
+
+function createSubscriptionId(): string {
+  if (typeof crypto !== 'undefined' && typeof crypto.randomUUID === 'function') {
+    return crypto.randomUUID();
+  }
+  return `htree-root-${Math.random().toString(16).slice(2)}`;
+}
+
+function parseRelayMessage(data: unknown): unknown[] | null {
+  if (typeof data !== 'string') {
+    return null;
+  }
+
+  try {
+    const parsed = JSON.parse(data);
+    return Array.isArray(parsed) ? parsed : null;
+  } catch {
+    return null;
+  }
+}
+
+function openRelaySubscriptions(
+  relays: string[],
+  filter: Record<string, unknown>,
+  handlers: {
+    onEvent?: (event: NostrEvent, relay: string) => void;
+    onEose?: (relay: string) => void;
+    onError?: (relay: string) => void;
+  },
+): { close(): Promise<void> } {
+  const subId = createSubscriptionId();
+  const sockets: WebSocket[] = [];
+  let closed = false;
+
+  for (const relay of relays) {
+    let socket: WebSocket | null = null;
+    try {
+      socket = new WebSocket(relay);
+    } catch {
+      handlers.onError?.(relay);
+      continue;
+    }
+
+    sockets.push(socket);
+
+    socket.onopen = () => {
+      if (closed) {
+        try {
+          socket?.close();
+        } catch {
+          // Ignore close errors.
+        }
+        return;
+      }
+
+      try {
+        socket.send(JSON.stringify(['REQ', subId, filter]));
+      } catch {
+        handlers.onError?.(relay);
+      }
+    };
+
+    socket.onerror = () => {
+      handlers.onError?.(relay);
+    };
+
+    socket.onmessage = (event) => {
+      const message = parseRelayMessage(event.data);
+      if (!message || message[1] !== subId) {
+        return;
+      }
+
+      if (message[0] === 'EVENT' && message[2] && typeof message[2] === 'object') {
+        handlers.onEvent?.(message[2] as NostrEvent, relay);
+        return;
+      }
+
+      if (message[0] === 'EOSE' || message[0] === 'CLOSED') {
+        handlers.onEose?.(relay);
+      }
+    };
+  }
+
+  return {
+    async close() {
+      if (closed) {
+        return;
+      }
+      closed = true;
+
+      for (const socket of sockets) {
+        try {
+          socket.send(JSON.stringify(['CLOSE', subId]));
+        } catch {
+          // Ignore close frame errors.
+        }
+        try {
+          socket.close();
+        } catch {
+          // Ignore socket close errors.
+        }
+      }
+    },
+  };
+}
+
+async function resolvePreferredCid(
+  tree: Pick<HashTree, 'resolvePath'> | null,
+  exactRecord: RootRecord | null,
+  treeRecord: RootRecord | null,
+  subPath: string[],
+): Promise<CID | null> {
+  if (exactRecord) {
+    return exactRecord.cid;
+  }
+
+  if (!treeRecord) {
+    return null;
+  }
+
+  if (subPath.length === 0) {
+    return treeRecord.cid;
+  }
+
+  if (!tree) {
+    throw new Error('Tree not initialized');
+  }
+
+  return (await tree.resolvePath(treeRecord.cid, subPath))?.cid ?? null;
+}
+
+async function queryLatestTreeRoot(
+  relays: string[],
+  npub: string,
+  treeName: string,
+  timeoutMs: number,
+  settleMs: number,
+): Promise<RootRecord | null> {
+  const pubkey = decodeNpub(npub);
+  if (!pubkey) {
+    return null;
+  }
+
+  return await new Promise<RootRecord | null>((resolve) => {
+    let closed = false;
+    let latestRecord: RootRecord | null = null;
+    let settleTimer: ReturnType<typeof setTimeout> | null = null;
+    let timeoutId: ReturnType<typeof setTimeout> | null = null;
+
+    const subscription = openRelaySubscriptions(relays, {
+      kinds: [30078],
+      authors: [pubkey],
+      '#d': [treeName],
+      limit: MAX_TREE_ROOT_EVENTS,
+    }, {
+      onEvent(event) {
+        const parsed = parseHashtreeRootEvent(event as Parameters<typeof parseHashtreeRootEvent>[0]);
+        if (!parsed || parsed.treeName !== treeName) {
+          return;
+        }
+
+        const nextRecord = updateLatestRecord(latestRecord, event, parsed.rootCid);
+        if (!nextRecord) {
+          return;
+        }
+
+        latestRecord = nextRecord;
+        if (settleTimer) {
+          clearTimeout(settleTimer);
+        }
+        settleTimer = setTimeout(() => {
+          finish(latestRecord);
+        }, settleMs);
+      },
+      onError() {
+        // Ignore individual relay failures and let timeout decide.
+      },
+      onEose() {
+        // Slower relays may still provide a newer replaceable event.
+      },
+    });
+
+    const finish = (record: RootRecord | null): void => {
+      if (closed) {
+        return;
+      }
+      closed = true;
+      if (settleTimer) {
+        clearTimeout(settleTimer);
+      }
+      if (timeoutId) {
+        clearTimeout(timeoutId);
+      }
+      void subscription.close().finally(() => {
+        resolve(record);
+      });
+    };
+
+    timeoutId = setTimeout(() => {
+      finish(latestRecord);
+    }, timeoutMs);
+  });
+}
+
+export async function watchRootPathFromRelays(
+  tree: Pick<HashTree, 'resolvePath'> | null,
+  relays: string[] | undefined,
+  npub: string,
+  path: string | undefined,
+  onUpdate: (cid: CID | null) => void | Promise<void>,
+  timeoutMs: number = DEFAULT_ROOT_RESOLVE_TIMEOUT_MS,
+  settleMs: number = DEFAULT_ROOT_RESOLVE_SETTLE_MS,
+): Promise<RootWatchHandle> {
+  const relayList = withUniqueRelays(relays);
+  const pubkey = decodeNpub(npub);
+  if (!pubkey) {
+    return {
+      initialCid: null,
+      async close() {
+        // no-op
+      },
+    };
+  }
+
+  const { exactTreeName, treeName, subPath, watchTreeNames } = parseRootLookupPath(path);
+  let exactRecord: RootRecord | null = null;
+  let treeRecord: RootRecord | null = null;
+  let subscription: { close(): Promise<void> } | null = null;
+  let settleTimer: ReturnType<typeof setTimeout> | null = null;
+  let timeoutId: ReturnType<typeof setTimeout> | null = null;
+  let resolveTicket = 0;
+  let currentCidKey: string | null = null;
+  let initialResolved = false;
+  let closed = false;
+
+  const close = async (): Promise<void> => {
+    if (closed) {
+      return;
+    }
+    closed = true;
+
+    if (settleTimer) {
+      clearTimeout(settleTimer);
+    }
+    if (timeoutId) {
+      clearTimeout(timeoutId);
+    }
+
+    await Promise.resolve(subscription?.close()).catch(() => undefined);
+  };
+
+  const emitCurrent = async (mode: 'initial' | 'update'): Promise<CID | null> => {
+    const ticket = ++resolveTicket;
+    const cid = await resolvePreferredCid(tree, exactRecord, treeRecord, subPath);
+    if (closed || ticket !== resolveTicket) {
+      return cid;
+    }
+
+    const nextKey = cidKey(cid);
+    if (mode === 'initial') {
+      if (settleTimer) {
+        clearTimeout(settleTimer);
+        settleTimer = null;
+      }
+      if (timeoutId) {
+        clearTimeout(timeoutId);
+        timeoutId = null;
+      }
+      initialResolved = true;
+      currentCidKey = nextKey;
+      return cid;
+    }
+
+    if (currentCidKey === nextKey) {
+      return cid;
+    }
+
+    currentCidKey = nextKey;
+    await onUpdate(cid);
+    return cid;
+  };
+
+  const settleInitial = (): void => {
+    if (settleTimer) {
+      clearTimeout(settleTimer);
+    }
+    settleTimer = setTimeout(() => {
+      void emitCurrent('initial').then((cid) => {
+        if (!closed) {
+          void onUpdate(cid);
+        }
+      });
+    }, settleMs);
+  };
+
+  timeoutId = setTimeout(() => {
+    void emitCurrent('initial').then((cid) => {
+      if (!closed) {
+        void onUpdate(cid);
+      }
+    });
+  }, timeoutMs);
+
+  subscription = openRelaySubscriptions(relayList, {
+    kinds: [30078],
+    authors: [pubkey],
+    '#d': watchTreeNames,
+    limit: Math.max(MAX_TREE_ROOT_EVENTS, watchTreeNames.length * MAX_TREE_ROOT_EVENTS),
+  }, {
+    onEvent(event) {
+      const parsed = parseHashtreeRootEvent(event as Parameters<typeof parseHashtreeRootEvent>[0]);
+      if (!parsed) {
+        return;
+      }
+
+      let updated = false;
+      if (parsed.treeName === exactTreeName) {
+        const nextRecord = updateLatestRecord(exactRecord, event, parsed.rootCid);
+        if (nextRecord) {
+          exactRecord = nextRecord;
+          updated = true;
+        }
+      }
+
+      if (parsed.treeName === treeName) {
+        const nextRecord = updateLatestRecord(treeRecord, event, parsed.rootCid);
+        if (nextRecord) {
+          treeRecord = nextRecord;
+          updated = true;
+        }
+      }
+
+      if (!updated) {
+        return;
+      }
+
+      if (!initialResolved) {
+        settleInitial();
+        return;
+      }
+
+      void emitCurrent('update');
+    },
+    onEose() {
+      // Ignore faster relay EOSE notifications. The live watch keeps listening.
+    },
+    onError() {
+      // Ignore relay close notifications. Other relays may still be active.
+    },
+  });
+
+  return {
+    initialCid: null,
+    close,
+  };
+}
+
+export async function resolveRootPathFromRelays(
+  tree: Pick<HashTree, 'resolvePath'> | null,
+  relays: string[] | undefined,
+  npub: string,
+  path?: string,
+  timeoutMs: number = DEFAULT_ROOT_RESOLVE_TIMEOUT_MS,
+  settleMs: number = DEFAULT_ROOT_RESOLVE_SETTLE_MS,
+): Promise<CID | null> {
+  const relayList = withUniqueRelays(relays);
+  const { exactTreeName, treeName, subPath } = parseRootLookupPath(path);
+
+  const exactRoot = await queryLatestTreeRoot(relayList, npub, exactTreeName, timeoutMs, settleMs);
+  if (exactRoot) {
+    return exactRoot.cid;
+  }
+
+  if (subPath.length === 0) {
+    return null;
+  }
+
+  const root = await queryLatestTreeRoot(relayList, npub, treeName, timeoutMs, settleMs);
+  if (!root) {
+    return null;
+  }
+
+  return resolvePreferredCid(tree, null, root, subPath);
+}

package/src/client-id.ts

@@ -0,0 +1,137 @@
+export interface HtreeClientIdStorageLike {
+  getItem(key: string): string | null;
+  setItem(key: string, value: string): void;
+}
+
+export interface ResolveHtreeClientIdOptions {
+  storageKey?: string;
+  prefix?: string;
+  storage?: HtreeClientIdStorageLike | null;
+  uuidFactory?: () => string;
+}
+
+export interface AppendHtreeQueryParamOptions {
+  baseOrigin?: string | null;
+}
+
+const DEFAULT_STORAGE_KEY = 'htree.mediaClientId';
+const DEFAULT_PREFIX = 'htc';
+const cachedClientIds = new Map<string, string>();
+
+function getDefaultStorage(): HtreeClientIdStorageLike | null {
+  try {
+    if (typeof sessionStorage !== 'undefined') {
+      return sessionStorage;
+    }
+  } catch {
+    return null;
+  }
+
+  try {
+    if (typeof window !== 'undefined' && window.sessionStorage) {
+      return window.sessionStorage;
+    }
+  } catch {
+    return null;
+  }
+
+  return null;
+}
+
+function hasClientRuntime(options: ResolveHtreeClientIdOptions): boolean {
+  return typeof window !== 'undefined'
+    || typeof options.storage !== 'undefined'
+    || typeof options.uuidFactory === 'function';
+}
+
+function getBaseOrigin(baseOrigin?: string | null): string {
+  if (typeof baseOrigin === 'string' && baseOrigin.trim()) {
+    return baseOrigin.trim().replace(/\/+$/, '');
+  }
+  if (typeof window !== 'undefined' && typeof window.location?.origin === 'string' && window.location.origin) {
+    return window.location.origin;
+  }
+  return 'https://example.invalid';
+}
+
+export function createHtreeClientId(
+  prefix = DEFAULT_PREFIX,
+  uuidFactory?: () => string,
+): string {
+  if (typeof uuidFactory === 'function') {
+    return uuidFactory();
+  }
+  if (typeof crypto !== 'undefined' && typeof crypto.randomUUID === 'function') {
+    return crypto.randomUUID();
+  }
+  return `${prefix}_${Date.now().toString(36)}_${Math.random().toString(36).slice(2, 10)}`;
+}
+
+export function getOrCreateHtreeClientId(
+  options: ResolveHtreeClientIdOptions = {},
+): string | null {
+  const storageKey = options.storageKey?.trim() || DEFAULT_STORAGE_KEY;
+  const cached = cachedClientIds.get(storageKey);
+  if (cached) {
+    return cached;
+  }
+
+  const storage = typeof options.storage === 'undefined' ? getDefaultStorage() : options.storage;
+  try {
+    const existing = storage?.getItem(storageKey);
+    if (existing) {
+      cachedClientIds.set(storageKey, existing);
+      return existing;
+    }
+  } catch {
+    // Ignore storage access failures and fall back to an in-memory id.
+  }
+
+  if (!hasClientRuntime(options)) {
+    return null;
+  }
+
+  const nextId = createHtreeClientId(options.prefix ?? DEFAULT_PREFIX, options.uuidFactory);
+  try {
+    storage?.setItem(storageKey, nextId);
+  } catch {
+    // Ignore storage write failures.
+  }
+  cachedClientIds.set(storageKey, nextId);
+  return nextId;
+}
+
+export function appendHtreeQueryParam(
+  url: string,
+  key: string,
+  value: string | null | undefined,
+  options: AppendHtreeQueryParamOptions = {},
+): string {
+  const trimmedValue = `${value ?? ''}`.trim();
+  if (!trimmedValue) {
+    return url;
+  }
+
+  try {
+    const baseOrigin = getBaseOrigin(options.baseOrigin);
+    const parsed = new URL(url, baseOrigin);
+    parsed.searchParams.set(key, trimmedValue);
+
+    if (!/^[a-z][a-z0-9+.-]*:\/\//i.test(url) && parsed.origin === baseOrigin) {
+      return `${parsed.pathname}${parsed.search}${parsed.hash}`;
+    }
+
+    return parsed.toString();
+  } catch {
+    const separator = url.includes('?') ? '&' : '?';
+    return `${url}${separator}${encodeURIComponent(key)}=${encodeURIComponent(trimmedValue)}`;
+  }
+}
+
+export function appendHtreeClientId(
+  url: string,
+  clientId: string | null | undefined,
+  options: AppendHtreeQueryParamOptions = {},
+): string {
+  return appendHtreeQueryParam(url, 'htree_c', clientId, options);
+}