feat(examples): discover relay endpoints

Author: rwl4

README.md

@@ -322,6 +322,16 @@ joining FETCH; degrades to a normal live join otherwise), `?log=info|debug`
 (player logs on the console), `?catalog=<base64 JSON>` (inject a catalog), and
 `?fetchCatalog=1` (FETCH the catalog instead of subscribing).
 
+`?url=` is the complete WebTransport endpoint, including its deployment-specific
+path. For example, use `?url=https%3A%2F%2Frelay.example.com%3A4433%2Fmoq-relay`
+when a relay is mounted at `/moq-relay`. When omitted, the browser examples
+discover the endpoint by probing `https://<page-host>:4433` at `/moq`,
+`/moq-relay`, then `/` and selecting the first successful path in that order.
+`/moq` and `/moq-relay` are deployment conventions, not
+MOQT-standard paths (a relay that accepts any path simply matches on `/moq`).
+Discovery is a convenience for these examples: a deployed application knows its
+relay endpoint and should configure the complete URL.
+
 ---
 
 ## Testing

conformance/media/runner/src/fuzz/catalog-fuzz.properties.test.ts

@@ -152,8 +152,8 @@ describe('Catalog crash fuzz — parseCatalogAuto', () => {
 
     const proj = catalogProjection(cat) as { tracks: Record<string, unknown>[] };
     const t = proj.tracks[0]!;
-    // The projected key set must be EXACTLY the CatalogTrack field set — no field
-    // silently dropped (finding 2), none accidentally added.
+    // The projected key set must exactly match the CatalogTrack field set, with
+    // no fields silently dropped or accidentally added.
     expect(Object.keys(t).sort()).toEqual(Object.keys(track).sort());
     // A spot-check of the string-rendered numerics and the array field.
     expect(t['displayWidth']).toBe('1920');

conformance/media/runner/src/validate.test.ts

@@ -63,7 +63,7 @@ describe('validateEntry — discriminating failures', () => {
   }
 });
 
-describe('validateEntry — strictness (the cases Codex exercised)', () => {
+describe('validateEntry — strictness', () => {
   const encEntry = (pm: unknown): CorpusEntry => ({
     ...validDecodeEntry(), id: 'properties/strict',
     input: { propertyMap: pm } as never,

conformance/media/schema/scenario.schema.json

@@ -2,7 +2,7 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://moq-playa/conformance/media/schema/scenario.schema.json",
   "title": "moq-media-scenario/1",
-  "description": "Deterministic, implementation-neutral media scenario. Finalized in Slice -1; its runner lands in Slice 1. Steps are an ordered list; advanceTimeUs is the ONLY way virtual time moves. Traces preserve actual emission order. Wide integers are decimal strings. Every nested structure is exact-keyed (additionalProperties:false).",
+  "description": "Deterministic, implementation-neutral media scenario. Steps are an ordered list; advanceTimeUs is the only way virtual time moves. Traces preserve actual emission order. Wide integers are decimal strings. Every nested structure is exact-keyed (additionalProperties:false).",
   "type": "object",
   "required": ["scenarioSchema", "id", "description", "expectationBasis", "provenance", "input", "steps", "expect"],
   "additionalProperties": false,

docs/catalog-testing.md

@@ -71,7 +71,11 @@ You can also prefill the harness with query parameters:
 Supported parameters:
 
 - `url`
-  - Full WebTransport relay URL
+  - Full WebTransport relay URL, including its endpoint path (for example,
+    `https://relay.example.com:4433/moq-relay` — the path is
+    deployment-specific; `/moq` and `/moq-relay` are conventions, not
+    MOQT-standard paths). When omitted, the form prefills from endpoint
+    discovery against the page host.
 - `ns`
   - Broadcast namespace
 - `v`

examples/broadcast/index.html

@@ -286,7 +286,7 @@ <h2>Share Viewer Link</h2>
   <div class="modal">
     <h2>Broadcast Settings</h2>
     <label for="s-url">Relay URL</label>
-    <input id="s-url" type="text" placeholder="https://localhost:4443">
+    <input id="s-url" type="text" placeholder="auto-discovered (/moq, /moq-relay, /)">
     <div class="hint">WebTransport relay endpoint</div>
 
     <label for="s-ns">Namespace</label>

examples/broadcast/main.ts

@@ -20,7 +20,8 @@ import type { BroadcastSessionConnection } from './broadcast-session.js';
 import { BroadcastAttempt } from './broadcast-attempt.js';
 import type { AttemptResources } from './broadcast-attempt.js';
 import { log } from '../shared/log.js';
-import { relayUrl, namespace, certHash, draftVersion } from '../shared/cert.js';
+import { namespace, certHash, draftVersion } from '../shared/cert.js';
+import { resolveRelayEndpoint, discoveredRelayUrl } from '../shared/relay-endpoint.js';
 import {
   WebCodecsVideoEncoder,
   WebCodecsAudioEncoder,
@@ -50,8 +51,26 @@ const keyframeInterval = parseInt(params.get('keyframe') ?? '60', 10);
   const applyBtn = document.getElementById('settings-apply')!;
   const cancelBtn = document.getElementById('settings-cancel')!;
 
+  // Modal-scoped lazy discovery: opening settings with no explicit ?url= and
+  // no cached result starts its own discovery consumer, aborted on
+  // close/Apply. Independent of the Go Live flow's consumer — neither can
+  // block the other (Stop never waits on this, and vice versa).
+  let modalDiscovery: AbortController | undefined;
+
+  function abortModalDiscovery() {
+    modalDiscovery?.abort(new Error('settings closed'));
+    modalDiscovery = undefined;
+  }
+
   function populateFields() {
-    sUrl.value = params.get('url') ?? 'https://localhost:4443';
+    sUrl.value = params.get('url') ?? discoveredRelayUrl() ?? '';
+    if (!sUrl.value && !modalDiscovery) {
+      modalDiscovery = new AbortController();
+      void resolveRelayEndpoint({ signal: modalDiscovery.signal }).then(
+        (url) => { if (!sUrl.value) sUrl.value = url; },
+        () => { /* aborted or failed — the field stays editable */ },
+      );
+    }
     sNs.value = params.get('ns') ?? 'live';
     sHash.value = params.get('hash') ?? '';
     sVersion.value = params.get('v') ?? '';
@@ -61,14 +80,17 @@ const keyframeInterval = parseInt(params.get('keyframe') ?? '60', 10);
   }
 
   settingsBtn.addEventListener('click', () => { populateFields(); backdrop.classList.add('visible'); });
-  cancelBtn.addEventListener('click', () => backdrop.classList.remove('visible'));
-  backdrop.addEventListener('click', (e) => { if (e.target === backdrop) backdrop.classList.remove('visible'); });
+  cancelBtn.addEventListener('click', () => { abortModalDiscovery(); backdrop.classList.remove('visible'); });
+  backdrop.addEventListener('click', (e) => {
+    if (e.target === backdrop) { abortModalDiscovery(); backdrop.classList.remove('visible'); }
+  });
 
   applyBtn.addEventListener('click', () => {
+    abortModalDiscovery();
     const np = new URLSearchParams();
     const url = sUrl.value.trim();
     const ns = sNs.value.trim();
-    if (url && url !== 'https://localhost:4443') np.set('url', url);
+    if (url) np.set('url', url);
     if (ns && ns !== 'live') np.set('ns', ns);
     if (sHash.value.trim()) np.set('hash', sHash.value.trim());
     if (sVersion.value) np.set('v', sVersion.value);
@@ -151,6 +173,7 @@ async function startBroadcast(source: 'camera' | 'screen'): Promise<void> {
   let videoEncoder: WebCodecsVideoEncoder | null = null;
   let audioEncoder: WebCodecsAudioEncoder | null = null;
   let connection: MoqtConnection | null = null;
+  let resolvedRelayUrl = '';   // set by openSession; feeds the viewer link
   let audio: { sampleRate: number; channels: number } | undefined;
   let width = 1280;
   let height = 720;
@@ -229,6 +252,17 @@ async function startBroadcast(source: 'camera' | 'screen'): Promise<void> {
     // behavior binds to the NEGOTIATED draft (connection.draftVersion after
     // connect), not the configured preference.
     openSession: async (ctx: AttemptResources) => {
+      // Resolve the relay endpoint (explicit ?url= as-is, discovery
+      // otherwise). The consumer aborts with the attempt: Stop during
+      // probing closes the connecting probe transport once no other
+      // consumer remains — it never hangs the cancellation.
+      const discoveryAbort = new AbortController();
+      ctx.onCancel(() => discoveryAbort.abort(new Error('broadcast stopped')));
+      log('Discovering relay endpoint...');
+      const relayUrl = await resolveRelayEndpoint({ signal: discoveryAbort.signal });
+      ctx.throwIfCancelled();
+      resolvedRelayUrl = relayUrl;
+
       log(`Connecting to ${relayUrl}...`);
       const transportFactory = createWebTransport({ ...(certHash ? { certHash } : {}), ...(draftVersion ? { draftVersion } : {}) });
       // Each resource is adopted the moment it exists — a cancellation or a
@@ -345,12 +379,14 @@ async function startBroadcast(source: 'camera' | 'screen'): Promise<void> {
         data.close();
       };
 
-      // Show viewer URL + resolution
+      // Carry the resolved endpoint and certificate hash into the viewer link.
       const viewerBase = window.location.origin + '/player/';
       const viewerParams = new URLSearchParams();
-      viewerParams.set('url', relayUrl);
+      viewerParams.set('url', resolvedRelayUrl);
       viewerParams.set('ns', namespace);
       if (draftVersion) viewerParams.set('v', String(draftVersion));
+      const hashParam = params.get('hash');
+      if (hashParam) viewerParams.set('hash', hashParam);
       currentViewerLink = `${viewerBase}?${viewerParams.toString()}`;
       viewerCard.style.display = 'block';
       statRes.textContent = `${width}x${height}`;

examples/catalog/index.html

@@ -171,7 +171,7 @@
   <form id="config" class="controls">
     <div class="field field-url">
       <label for="relay-url">Relay URL</label>
-      <input type="url" id="relay-url" placeholder="https://localhost:4433" spellcheck="false" />
+      <input type="url" id="relay-url" placeholder="https://localhost:4433/moq" spellcheck="false" />
     </div>
     <div class="field">
       <label for="namespace">Namespace</label>

examples/catalog/main.ts

@@ -15,6 +15,10 @@
 import { MoqtConnection } from '@moqt/webtransport';
 import { varint } from '@moqt/transport';
 import { createWebTransport } from '../shared/browser/index.js';
+import { resolveRelayEndpoint } from '../shared/relay-endpoint.js';
+import { parseCertHashHex, relayCandidates } from '../shared/relay-url.js';
+import { discoverEndpoint } from '../shared/discover-endpoint.js';
+import { probeTransport } from '../shared/probe-transport.js';
 import {
   CATALOG_TRACK_NAME,
   applyCatalogUpdate,
@@ -146,6 +150,17 @@ class CatalogAccumulator {
 
 let activeRun = 0;
 let activeConnection: InstanceType<typeof MoqtConnection> | null = null;
+// Keep at most one discovery flight active. A submission replaces the page
+// prefill or an earlier blank-URL discovery and closes its probes.
+let prefillAbort: AbortController | null = null;
+let manualDiscoveryAbort: AbortController | null = null;
+
+function abortDiscoveryFlights(reason: string): void {
+  prefillAbort?.abort(new Error(reason));
+  prefillAbort = null;
+  manualDiscoveryAbort?.abort(new Error(reason));
+  manualDiscoveryAbort = null;
+}
 
 form.addEventListener('submit', (e) => {
   e.preventDefault();
@@ -159,13 +174,54 @@ if (!('WebTransport' in window)) {
 
 async function run(): Promise<void> {
   const runId = ++activeRun;
-  const url = (document.getElementById('relay-url') as HTMLInputElement).value.trim();
+  // Every submission supersedes any in-flight discovery (prefill or a
+  // previous blank-URL run) — their probes are aborted and closed.
+  abortDiscoveryFlights('superseded by run');
+  const urlInput = document.getElementById('relay-url') as HTMLInputElement;
+  let url = urlInput.value.trim();
   const ns = (document.getElementById('namespace') as HTMLInputElement).value.trim();
   const vRaw = (document.getElementById('draft-version') as HTMLSelectElement).value;
   const hashHex = (document.getElementById('cert-hash') as HTMLInputElement).value.trim();
   const v: 14 | 16 | 18 | undefined = vRaw === '14' ? 14 : vRaw === '16' ? 16 : vRaw === '18' ? 18 : undefined;
 
-  if (!url || !ns) { setStatus('URL and namespace required.', 'error'); return; }
+  if (!ns) { setStatus('Namespace required.', 'error'); return; }
+  if (!url) {
+    // Use the current form values for a fresh discovery. This bypasses the
+    // page-query singleton so a newly entered hash or draft cannot share an
+    // incompatible probe.
+    if (!('WebTransport' in window)) {
+      setStatus('WebTransport not available. Use Chrome 97+.', 'error');
+      return;
+    }
+    setStatus('Discovering relay endpoint…');
+    const discoveryController = new AbortController();
+    manualDiscoveryAbort = discoveryController;
+    try {
+      const certHashBuf = hashHex ? parseCertHashHex(hashHex) : undefined;
+      url = await discoverEndpoint({
+        candidates: relayCandidates(window.location.hostname),
+        connect: (candidate, signal) => probeTransport(candidate, {
+          ...(certHashBuf ? { certHash: certHashBuf } : {}),
+          ...(v ? { draftVersion: v } : {}),
+          signal,
+        }),
+        signal: discoveryController.signal,
+        onAttempt: (candidate, outcome) => {
+          if (runId === activeRun) log(`probe ${candidate}: ${outcome}`);
+        },
+      });
+    } catch (err) {
+      if (runId === activeRun && !discoveryController.signal.aborted) {
+        setStatus((err as Error).message, 'error');
+      }
+      return;
+    } finally {
+      // Identity-safe: a superseding run owns the slot by now.
+      if (manualDiscoveryAbort === discoveryController) manualDiscoveryAbort = null;
+    }
+    if (runId !== activeRun) return;   // superseded while discovering
+    urlInput.value = url;
+  }
 
   const method = (document.getElementById('read-method') as HTMLSelectElement).value as 'subscribe' | 'fetch';
   const groupId = BigInt((document.getElementById('fetch-group') as HTMLInputElement).value || '0');
@@ -186,12 +242,7 @@ async function run(): Promise<void> {
 
   try {
     // WebTransport — use shared factory for protocol negotiation
-    const certHashBuf = hashHex ? (() => {
-      const clean = hashHex.replace(/[^0-9a-fA-F]/g, '');
-      const bytes = new Uint8Array(clean.length / 2);
-      for (let i = 0; i < bytes.length; i++) bytes[i] = parseInt(clean.slice(i * 2, i * 2 + 2), 16);
-      return bytes.buffer as ArrayBuffer;
-    })() : undefined;
+    const certHashBuf = hashHex ? parseCertHashHex(hashHex) : undefined;
     const transportFactory = createWebTransport({ ...(certHashBuf ? { certHash: certHashBuf } : {}), ...(v ? { draftVersion: v } : {}) });
     const transport = await transportFactory(url);
     log(`WebTransport connected${(transport as any).protocol ? ` (${(transport as any).protocol})` : ''}`);
@@ -449,8 +500,39 @@ function setStatus(msg: string, type: 'info' | 'error' | 'success' = 'info'): vo
 
 function seedForm(): void {
   const p = new URLSearchParams(window.location.search);
-  (document.getElementById('relay-url') as HTMLInputElement).value =
-    p.get('url') ?? `${window.location.origin.replace(/\/$/, '')}:4433`;
+  const urlInput = document.getElementById('relay-url') as HTMLInputElement;
+  const explicit = p.get('url');
+  if (explicit) {
+    urlInput.value = explicit;
+  } else if (!('WebTransport' in window)) {
+    // No discovery without the API — and never overwrite the capability
+    // diagnostic with a "no endpoint found" message.
+    urlInput.placeholder = 'https://relay.example.com:4433/moq';
+  } else {
+    // Prefill asynchronously from the shared discovery. The user can type
+    // while it runs — a typed value always wins over the discovered one —
+    // and a run started meanwhile owns the status bar AND aborts this
+    // flight (identity-safe controller; a late failure of a superseded
+    // prefill must not overwrite an active run's status).
+    const prefillRun = activeRun;
+    const controller = new AbortController();
+    prefillAbort = controller;
+    urlInput.placeholder = 'discovering…';
+    void resolveRelayEndpoint({ signal: controller.signal }).then(
+      (url) => {
+        if (prefillAbort === controller) prefillAbort = null;
+        if (!urlInput.value) urlInput.value = url;
+        urlInput.placeholder = 'https://relay.example.com:4433/moq';
+      },
+      (err: unknown) => {
+        if (prefillAbort === controller) prefillAbort = null;
+        urlInput.placeholder = 'https://relay.example.com:4433/moq';
+        if (activeRun === prefillRun && !controller.signal.aborted) {
+          setStatus((err as Error).message, 'error');
+        }
+      },
+    );
+  }
   (document.getElementById('namespace') as HTMLInputElement).value = p.get('ns') ?? 'live';
   (document.getElementById('draft-version') as HTMLSelectElement).value = p.get('v') ?? '';
   (document.getElementById('cert-hash') as HTMLInputElement).value = p.get('hash') ?? '';

examples/connect/main.ts

@@ -20,7 +20,9 @@ import { varint } from '@moqt/transport';
 import { parseCatalogAuto } from '@moqt/msf';
 import type { CatalogTrack } from '@moqt/msf';
 import { log } from '../shared/log.js';
-import { relayUrl, namespace, certHash, draftVersion } from '../shared/cert.js';
+import { namespace, certHash, draftVersion } from '../shared/cert.js';
+import { resolveRelayEndpoint, onDiscoveryAttempt } from '../shared/relay-endpoint.js';
+import { createWebTransport } from '../shared/browser/index.js';
 
 // ─── Capability check ────────────────────────────────────────────────
 
@@ -34,32 +36,27 @@ if (!('WebTransport' in window)) {
 const enc = new TextEncoder();
 
 async function main(): Promise<void> {
+  // Resolve the relay endpoint: explicit ?url= is used as-is; otherwise the
+  // shared discovery probes the page host's common endpoint paths.
+  log('Discovering relay endpoint...');
+  onDiscoveryAttempt((url, outcome) => log(`  probe ${url}: ${outcome}`));
+  const relayUrl = await resolveRelayEndpoint();
+
   log(`Relay: ${relayUrl}`);
   log(`Namespace: ${namespace}`);
   log(`Cert hash: ${certHash ? 'provided' : 'none (using system trust)'}`);
   log('');
 
-  // 1. Create WebTransport connection
-  //    serverCertificateHashes pins the relay's self-signed cert.
+  // 1. Create WebTransport connection via the shared factory (cert-hash
+  //    pinning + WT-Available-Protocols offer with strict-UA fallback).
+  //    Connect to the relay URL as-is: the namespace is communicated via
+  //    SUBSCRIBE, never appended to a deployment-specific endpoint path.
   //    @see draft-ietf-moq-transport-16 §3.1
   log('Creating WebTransport connection...');
-  const transportOptions: WebTransportOptions = {};
-  if (certHash) {
-    transportOptions.serverCertificateHashes = [{
-      algorithm: 'sha-256',
-      value: certHash,
-    }];
-  }
-  // §3.1: WT-Available-Protocols for MOQT version negotiation
-  if (draftVersion) {
-    (transportOptions as any).protocols = [`moqt-${draftVersion}`];
-  }
-  // Connect to relay URL as-is. Namespace is communicated via SUBSCRIBE,
-  // not the connection URL. Some relays (moquito) accept ?ns= but others
-  // (Red5) reject unrecognized URL paths.
-  const connectUrl = relayUrl;
-  const transport = new WebTransport(connectUrl, transportOptions);
-  await transport.ready;
+  const transport = await createWebTransport({
+    ...(certHash ? { certHash } : {}),
+    ...(draftVersion ? { draftVersion } : {}),
+  })(relayUrl);
   log('WebTransport connected.');
 
   // 2. Create MoqtConnection — internally creates Session(EndpointRole.CLIENT)