@displayxr/inline3d 1.47.5 → 1.48.0

package/signaling/room.mjs

@@ -0,0 +1,322 @@
+// signaling/room.mjs — the `dxr-signal/1` room logic, shared VERBATIM by the Cloudflare Worker's
+// Durable Object (worker.mjs) and the Node dev server (dev-server.mjs). Runtime-agnostic: no
+// sockets here, just "a connection said this; tell these connections that". The protocol is
+// documented in ./README.md.
+//
+// What this server knows: a room id, random per-join peer ids, and the SDP/ICE blobs it relays.
+// It never sees media (DTLS-SRTP is peer-to-peer) and holds nothing after the last peer leaves.
+
+import { CLOSE_CODES } from './limits.mjs';
+
+export const PROTOCOL = 'dxr-signal/1';
+export const ROOM_ID_RE = /^[A-Za-z0-9_-]{16,64}$/;
+export const PEER_ID_RE = /^[A-Za-z0-9_-]{8,32}$/;
+/** Default room size, and the largest a server will allow (full mesh stops scaling at 4). */
+export const DEFAULT_ROOM_CAP = 4;
+export const MAX_ROOM_CAP = 8;
+/** A single signalling message is a JSON SDP or candidate — 64 KiB is generous. */
+export const MAX_MESSAGE_BYTES = 64 * 1024;
+/** Per-connection flood guard: at most this many messages per window. */
+export const RATE_LIMIT = { messages: 300, windowMs: 10_000 };
+
+/** SHA-256 of the room id, hex — the only room-derived value that appears in a URL. */
+export async function roomKey(room) {
+  const bytes = new TextEncoder().encode(String(room));
+  const digest = await globalThis.crypto.subtle.digest('SHA-256', bytes);
+  return [...new Uint8Array(digest)].map((b) => b.toString(16).padStart(2, '0')).join('');
+}
+
+/**
+ * One room. `conn` is anything with `send(obj)` and `close(code, reason)`; the host runtime owns
+ * the socket and calls `onMessage(conn, text)` / `onClose(conn)`.
+ *
+ * @param {object} opts
+ * @param {string} opts.key  the roomKey this room was addressed by (join must match it)
+ * @param {number} [opts.cap]  server-side participant cap (clamped to MAX_ROOM_CAP)
+ * @param {(info: object|null) => Promise<object[]|null>} [opts.iceServers]  mints short-lived
+ *        TURN credentials per join (given the connection's admission session, see gate.mjs, whose
+ *        `turn.ttl` is the TTL to mint); null/absent = the client uses its own defaults (public STUN)
+ * @param {{ onFirst?: (info: object|null) => void, onEmpty?: () => void }} [opts.hooks]  the room
+ *        went 0→1 peers (start its lifetime clock) / 1→0 (stop it)
+ * @param {() => number} [opts.now]
+ */
+export class Room {
+  constructor({ key, cap = DEFAULT_ROOM_CAP, iceServers = null, hooks = {}, now = () => Date.now() } = {}) {
+    this.key = key || null;
+    this.cap = Math.max(2, Math.min(MAX_ROOM_CAP, cap | 0 || DEFAULT_ROOM_CAP));
+    this.max = null; // set by the first joiner (<= cap)
+    this.peers = new Map(); // id -> conn
+    this.meta = new WeakMap(); // conn -> { id, count, windowAt, session }
+    this.iceServers = iceServers;
+    this.hooks = hooks || {};
+    this.now = now;
+  }
+
+  get size() {
+    return this.peers.size;
+  }
+
+  _meta(conn) {
+    let m = this.meta.get(conn);
+    if (!m) {
+      m = { id: null, count: 0, windowAt: this.now(), session: null, pending: null };
+      this.meta.set(conn, m);
+    }
+    return m;
+  }
+
+  /**
+   * Record what a connection was admitted as (gate.mjs `Session`: tier, key id, TURN decision,
+   * room lifetime). Call before its first message; absent = anonymous, TURN per server config.
+   */
+  attach(conn, session) {
+    this._meta(conn).session = session || null;
+  }
+
+  /** Re-attach a connection that already joined (Durable Object wake from hibernation). */
+  restore(conn, id, session = null) {
+    if (!PEER_ID_RE.test(id)) return;
+    this.peers.set(id, conn);
+    this.meta.set(conn, { id, count: 0, windowAt: this.now(), session: session || null, pending: null });
+  }
+
+  /**
+   * Send to a peer, respecting the protocol's ordering rule: `welcome` is the FIRST message a
+   * joined peer receives. Between a peer's slot being reserved and its welcome going out there
+   * can be an await (the TURN mint is a network call), and in that window another peer's
+   * `peer-joined` / `signal` / `peer-left` may be addressed to it. Those are held here and
+   * flushed, in order, right behind the welcome.
+   */
+  _deliver(conn, obj) {
+    const m = conn && this.meta.get(conn);
+    if (m && m.pending) m.pending.push(obj);
+    else safeSend(conn, obj);
+  }
+
+  async onMessage(conn, text) {
+    if (typeof text !== 'string') text = String(text);
+    if (text.length > MAX_MESSAGE_BYTES) return this._fail(conn, 'too-big', 'message exceeds 64 KiB');
+    let msg;
+    try {
+      msg = JSON.parse(text);
+    } catch {
+      return this._fail(conn, 'bad-message', 'not JSON');
+    }
+    if (!msg || typeof msg !== 'object') return this._fail(conn, 'bad-message', 'not an object');
+    const m = this._meta(conn);
+    const t = this.now();
+    if (t - m.windowAt > RATE_LIMIT.windowMs) {
+      m.windowAt = t;
+      m.count = 0;
+    }
+    if (++m.count > RATE_LIMIT.messages) return this._fail(conn, 'rate-limited', 'slow down', true);
+
+    switch (msg.t) {
+      case 'ping':
+        return this._deliver(conn, { t: 'pong' });
+      case 'join':
+        return this._join(conn, m, msg);
+      case 'signal':
+        // A peer is "joined" once its welcome is out; until then it has nothing to signal about.
+        if (!m.id || m.pending) return this._fail(conn, 'not-joined', 'join first');
+        if (typeof msg.to !== 'string' || !this.peers.has(msg.to) || msg.to === m.id) {
+          return safeSend(conn, { t: 'error', code: 'no-such-peer', to: msg.to ?? null });
+        }
+        return this._deliver(this.peers.get(msg.to), { t: 'signal', from: m.id, data: msg.data ?? null });
+      case 'leave':
+        this.onClose(conn);
+        try {
+          conn.close(1000, 'left');
+        } catch {
+          /* already closed */
+        }
+        return;
+      default:
+        return this._fail(conn, 'bad-message', `unknown type "${msg.t}"`);
+    }
+  }
+
+  async _join(conn, m, msg) {
+    if (m.id) return this._fail(conn, 'already-joined', 'one join per connection');
+    if (msg.v !== undefined && msg.v !== 1) return this._fail(conn, 'bad-version', `server speaks ${PROTOCOL}`, true);
+    if (!ROOM_ID_RE.test(msg.room || '')) return this._fail(conn, 'bad-room', 'room id must be 16-64 base64url chars', true);
+    if (this.key && (await roomKey(msg.room)) !== this.key) return this._fail(conn, 'bad-room', 'room does not match its key', true);
+    if (!PEER_ID_RE.test(msg.id || '')) return this._fail(conn, 'bad-id', 'peer id must be 8-32 base64url chars', true);
+    if (this.peers.has(msg.id)) return this._fail(conn, 'id-taken', 'that peer id is in the room', true);
+    if (this.max === null || this.peers.size === 0) {
+      const want = Number.isInteger(msg.max) ? msg.max : DEFAULT_ROOM_CAP;
+      this.max = Math.max(2, Math.min(this.cap, want));
+    }
+    if (this.peers.size >= this.max) {
+      safeSend(conn, { t: 'full', max: this.max });
+      try {
+        conn.close(4003, 'room full');
+      } catch {
+        /* ignore */
+      }
+      return;
+    }
+    // Reserve the slot NOW (synchronously), so a burst cannot oversubscribe the room or mint TURN
+    // credentials for peers that will be turned away — and open the hold-back queue: nothing
+    // reaches this peer before its own welcome (see _deliver). Peers that are already welcomed do
+    // not know this one, so they are told here; peers still waiting for their welcome will find
+    // it in their roster, which is read at send time. Either way each pair hears of the other
+    // exactly once.
+    const first = this.peers.size === 0;
+    for (const [, other] of this.peers) {
+      const om = this.meta.get(other);
+      if (!om || !om.pending) safeSend(other, { t: 'peer-joined', id: msg.id });
+    }
+    m.id = msg.id;
+    m.pending = [];
+    this.peers.set(msg.id, conn);
+    const s = m.session;
+    // TURN: the admission decision (budget / tier / mint rate) says whether to mint at all and
+    // for how long; a server without TURN configured has no minter. The welcome always says
+    // which, so the SDK can tell "no relay this month" (`turn-cap`) from "self-hosted, no TURN".
+    let ice = null;
+    /** @type {{status: string, reason?: string, ttl?: number}} */
+    let turn = { status: 'off', reason: 'unconfigured' };
+    if (this.iceServers) {
+      const want = s && s.turn ? s.turn : { mint: true, ttl: 0, status: 'ok' };
+      if (!want.mint) turn = { status: want.status || 'off', reason: want.reason || 'budget' };
+      else {
+        try {
+          ice = await this.iceServers(s);
+          turn = ice ? { status: want.status || 'ok', ttl: want.ttl || undefined } : { status: 'off', reason: 'unconfigured' };
+        } catch {
+          ice = null; // TURN minting failed: the client falls back to STUN, the call may still work
+          turn = { status: want.status || 'ok', reason: 'mint-failed' };
+        }
+      }
+    }
+    // The peer may have gone (closed, expired) while the mint was in flight: then its slot is
+    // already released and the others already heard `peer-left`.
+    if (this.peers.get(msg.id) !== conn || m.id !== msg.id) return;
+    const held = m.pending || [];
+    m.pending = null;
+    // The roster is read HERE, not at reservation: it is everyone in the room as this welcome
+    // goes out, including peers that joined during the mint.
+    const others = [...this.peers.keys()].filter((id) => id !== msg.id);
+    const welcome = { t: 'welcome', v: 1, id: msg.id, peers: others, max: this.max, tier: s ? s.tier : 'anon', turn };
+    if (s && s.key) welcome.key = s.key;
+    if (ice) welcome.iceServers = ice;
+    safeSend(conn, welcome);
+    // What was held during the mint, minus what the roster already says: a `peer-joined` for
+    // someone listed in `peers` would announce them twice.
+    const listed = new Set(others);
+    for (const obj of held) {
+      if (obj && obj.t === 'peer-joined' && listed.has(obj.id)) continue;
+      safeSend(conn, obj);
+    }
+    if (first) this.hooks.onFirst?.(s);
+  }
+
+  /** The socket closed (or the peer left): tell the others. Idempotent. */
+  onClose(conn) {
+    const m = this.meta.get(conn);
+    if (!m || !m.id) return;
+    const id = m.id;
+    m.id = null;
+    if (this.peers.get(id) !== conn) return;
+    this.peers.delete(id);
+    for (const other of this.peers.values()) this._deliver(other, { t: 'peer-left', id });
+    if (this.peers.size === 0) {
+      this.max = null;
+      this.hooks.onEmpty?.();
+    }
+  }
+
+  /**
+   * The room's lifetime is up (RFC §5b: 2 h anonymous, 8 h keyed): every peer gets `expired`
+   * and is closed (4004). Media already flowing peer-to-peer is not touched by this; the peers
+   * simply have no signalling for that room any more.
+   */
+  expire() {
+    const conns = [...this.peers.values()];
+    this.peers.clear();
+    this.max = null;
+    for (const conn of conns) {
+      const m = this.meta.get(conn);
+      if (m) m.id = null;
+      safeSend(conn, { t: 'expired' });
+      try {
+        conn.close(CLOSE_CODES.expired, 'expired');
+      } catch {
+        /* ignore */
+      }
+    }
+    if (conns.length) this.hooks.onEmpty?.();
+  }
+
+  _fail(conn, code, message, close = false) {
+    safeSend(conn, { t: 'error', code, message });
+    if (close) {
+      this.onClose(conn);
+      try {
+        conn.close(CLOSE_CODES[code] || 4000, code);
+      } catch {
+        /* ignore */
+      }
+    }
+  }
+}
+
+/**
+ * Refuse a connection before it ever reaches a room (an admission failure, gate.mjs): one
+ * `error` message, then the close code for that error. The client learns why; nothing hangs.
+ */
+export function refuseConn(conn, { code, message, retryMs = 0, closeCode }) {
+  const err = { t: 'error', code, message };
+  if (retryMs > 0) err.retryMs = retryMs;
+  safeSend(conn, err);
+  try {
+    conn.close(closeCode || CLOSE_CODES[code] || 4000, code);
+  } catch {
+    /* ignore */
+  }
+}
+
+function safeSend(conn, obj) {
+  try {
+    conn.send(obj);
+  } catch {
+    /* the socket is going away; its close handler cleans up */
+  }
+}
+
+/**
+ * Mint short-lived TURN credentials with Cloudflare Realtime TURN. Returns the `iceServers` array
+ * or null when not configured. The key id and API token live in the Worker's env (a secret), and
+ * ONLY there — clients receive credentials that expire after `ttl` seconds.
+ *
+ * `customIdentifier` tags the credential with the session's key id ('anon' otherwise), which is
+ * how Cloudflare's TURN analytics attribute relay bytes per key (turn-budget.mjs readTurnUsage).
+ * If the API ever rejects that field, the mint is retried once without it.
+ *
+ * @param {{TURN_KEY_ID?: string, TURN_KEY_API_TOKEN?: string, TURN_TTL?: string}} env
+ * @param {typeof fetch} [fetchImpl]
+ * @param {{ ttl?: number, customIdentifier?: string }} [o]  `ttl` overrides env.TURN_TTL
+ */
+export async function mintTurnCredentials(env, fetchImpl = globalThis.fetch, o = {}) {
+  if (!env || !env.TURN_KEY_ID || !env.TURN_KEY_API_TOKEN) return null;
+  const ttl = Math.max(60, Math.min(86400, (o.ttl > 0 ? o.ttl | 0 : 0) || parseInt(env.TURN_TTL || '3600', 10) || 3600));
+  const url = `https://rtc.live.cloudflare.com/v1/turn/keys/${encodeURIComponent(env.TURN_KEY_ID)}/credentials/generate-ice-servers`;
+  const post = (body) =>
+    fetchImpl(url, {
+      method: 'POST',
+      headers: { Authorization: `Bearer ${env.TURN_KEY_API_TOKEN}`, 'Content-Type': 'application/json' },
+      body: JSON.stringify(body),
+    });
+  const tag = typeof o.customIdentifier === 'string' && o.customIdentifier ? o.customIdentifier.slice(0, 64) : '';
+  let res = await post(tag ? { ttl, customIdentifier: tag } : { ttl });
+  if (!res.ok && tag && res.status === 400) res = await post({ ttl });
+  if (!res.ok) throw new Error(`TURN credential mint failed: HTTP ${res.status}`);
+  const body = await res.json();
+  // Current API: { iceServers: [ {urls}, {urls, username, credential} ] }. The older
+  // `/credentials/generate` answered { iceServers: { urls, username, credential } } — accept both.
+  const s = body && body.iceServers;
+  if (Array.isArray(s)) return s;
+  if (s && s.urls) return [s];
+  return null;
+}

package/signaling/turn-budget.mjs

@@ -0,0 +1,254 @@
+// signaling/turn-budget.mjs — TURN metering and the monthly cost ceiling (RFC 0003 §5c).
+//
+// TURN relay is the only real cost of the hosted service. This module answers one question per
+// join: "may this session get TURN credentials, and for how long?" — from an org-wide monthly
+// budget with graduated shedding:
+//
+//   usage/budget   < 70%   ok        everyone gets TURN at the tier's TTL
+//   70% … 90%      degraded  anonymous mints get a 300 s TTL and a per-IP hourly cap of 5
+//   90% … 100%     degraded  anonymous mints STOP (reason 'budget'); keyed sessions keep TURN
+//   >= 100%        off       nobody gets new credentials (reason 'cap') → the SDK's `turn-cap`
+//
+// Direct P2P keeps working throughout (the welcome simply carries no `iceServers`), and relays
+// already allocated run until their credentials expire.
+//
+// Two usage figures, and which one counts:
+//   - ESTIMATED: every mint records (key, ttl). estimatedGB = Σ ttl-hours × EST_GB_PER_TTL_HOUR.
+//     Always available; crude on purpose (a credential may never relay a byte, or may relay for
+//     its whole TTL). The default 0.3 GB per TTL-hour assumes ~15% of sessions relay at ~3.5 Mbps
+//     both ways.
+//   - ACTUAL: Cloudflare exposes relay bytes per TURN key and per `customIdentifier` through the
+//     GraphQL analytics dataset `callsTurnUsageAdaptiveGroups`. A scheduled (cron) handler polls
+//     it and stores month-to-date GB (total and per key). When an ACTUAL figure is fresh (< 3 h),
+//     it is what counts; otherwise the estimate does. A test / operator OVERRIDE (admin endpoint
+//     or the TURN_FORCE_USAGE_GB var) beats both.
+//
+// Usage is aggregated PER KEY (plus 'anon') every month — the billing identity the business
+// model needs — while billing itself stays off: nothing here charges anyone.
+
+export const GB = 1e9;
+
+/** @typedef {{ freeGB: number, capUSD: number, pricePerGB: number, shedFrac: number, stopAnonFrac: number, estGBPerTtlHour: number, actualMaxAgeMs: number, forceUsageGB: number|null }} BudgetConfig */
+
+export const DEFAULT_BUDGET = Object.freeze({
+  freeGB: 1000, // Cloudflare Realtime TURN free tier, per month
+  capUSD: 100, // RFC 0003 Decision 2: the hard cap beyond the free tier
+  pricePerGB: 0.05, // verify against current Cloudflare pricing when it changes
+  shedFrac: 0.7,
+  stopAnonFrac: 0.9,
+  estGBPerTtlHour: 0.3,
+  actualMaxAgeMs: 3 * 3600_000,
+  forceUsageGB: null,
+});
+
+const num = (v, dflt) => {
+  if (v === undefined || v === null || v === '') return dflt;
+  const n = Number(v);
+  return Number.isFinite(n) && n >= 0 ? n : dflt;
+};
+
+/** Read the budget knobs from env (TURN_FREE_GB, TURN_CAP_USD, TURN_PRICE_PER_GB, TURN_SHED_FRAC, TURN_STOP_ANON_FRAC, TURN_EST_GB_PER_TTL_HOUR, TURN_FORCE_USAGE_GB). */
+export function budgetFromEnv(env = {}) {
+  return {
+    freeGB: num(env.TURN_FREE_GB, DEFAULT_BUDGET.freeGB),
+    capUSD: num(env.TURN_CAP_USD, DEFAULT_BUDGET.capUSD),
+    pricePerGB: num(env.TURN_PRICE_PER_GB, DEFAULT_BUDGET.pricePerGB) || DEFAULT_BUDGET.pricePerGB,
+    shedFrac: num(env.TURN_SHED_FRAC, DEFAULT_BUDGET.shedFrac),
+    stopAnonFrac: num(env.TURN_STOP_ANON_FRAC, DEFAULT_BUDGET.stopAnonFrac),
+    estGBPerTtlHour: num(env.TURN_EST_GB_PER_TTL_HOUR, DEFAULT_BUDGET.estGBPerTtlHour),
+    actualMaxAgeMs: DEFAULT_BUDGET.actualMaxAgeMs,
+    forceUsageGB: env.TURN_FORCE_USAGE_GB === undefined || env.TURN_FORCE_USAGE_GB === '' ? null : num(env.TURN_FORCE_USAGE_GB, null),
+  };
+}
+
+/** Total GB the month may use before the cap: free tier + what $cap buys. */
+export function budgetGB(cfg) {
+  return cfg.freeGB + cfg.capUSD / cfg.pricePerGB;
+}
+
+export function monthOf(ms) {
+  const d = new Date(ms);
+  return `${d.getUTCFullYear()}-${String(d.getUTCMonth() + 1).padStart(2, '0')}`;
+}
+
+/**
+ * Month-to-date usage state. Serialisable; one instance per deployment (a 'budget' Durable
+ * Object on Cloudflare, a field of the dev server).
+ */
+export class TurnBudget {
+  /** @param {{ cfg?: Partial<BudgetConfig>, now?: () => number, state?: any }} [o] */
+  constructor({ cfg = {}, now = () => Date.now(), state = null } = {}) {
+    this.cfg = { ...DEFAULT_BUDGET, ...cfg };
+    this.now = now;
+    this.month = monthOf(now());
+    /** per key id (or 'anon'): { joins, mints, ttlSeconds, actualGB? } */
+    this.byKey = {};
+    this.actualGB = null;
+    this.actualAt = 0;
+    this.overrideGB = null;
+    if (state) this._load(state);
+  }
+
+  _load(s) {
+    if (!s || typeof s !== 'object') return;
+    if (s.month === this.month) {
+      if (s.byKey && typeof s.byKey === 'object') this.byKey = JSON.parse(JSON.stringify(s.byKey));
+      if (Number.isFinite(s.actualGB)) this.actualGB = s.actualGB;
+      if (Number.isFinite(s.actualAt)) this.actualAt = s.actualAt;
+    }
+    // An override survives a month rollover on purpose (it is an operator's switch, not usage).
+    if (Number.isFinite(s.overrideGB)) this.overrideGB = s.overrideGB;
+  }
+
+  toJSON() {
+    return { month: this.month, byKey: this.byKey, actualGB: this.actualGB, actualAt: this.actualAt, overrideGB: this.overrideGB };
+  }
+
+  /** A new UTC month resets the counters (called before every read/write). */
+  _roll() {
+    const m = monthOf(this.now());
+    if (m !== this.month) {
+      this.month = m;
+      this.byKey = {};
+      this.actualGB = null;
+      this.actualAt = 0;
+    }
+  }
+
+  _bucket(keyId) {
+    const id = keyId || 'anon';
+    return (this.byKey[id] ??= { joins: 0, mints: 0, ttlSeconds: 0 });
+  }
+
+  recordJoin(keyId) {
+    this._roll();
+    this._bucket(keyId).joins++;
+  }
+
+  recordMint(keyId, ttlSeconds) {
+    this._roll();
+    const b = this._bucket(keyId);
+    b.mints++;
+    b.ttlSeconds += Math.max(0, ttlSeconds | 0);
+  }
+
+  /** The analytics poll result: total month-to-date relay GB, and per key if known. */
+  setActual(totalGB, { byKey = null, at = this.now() } = {}) {
+    this._roll();
+    this.actualGB = Number.isFinite(totalGB) ? totalGB : null;
+    this.actualAt = this.actualGB === null ? 0 : at;
+    if (byKey && typeof byKey === 'object') for (const [k, gb] of Object.entries(byKey)) if (Number.isFinite(gb)) this._bucket(k).actualGB = gb;
+  }
+
+  /** Operator / test override of the usage figure (null clears it). */
+  setOverride(gb) {
+    this.overrideGB = Number.isFinite(gb) ? gb : null;
+  }
+
+  get estimatedGB() {
+    let h = 0;
+    for (const b of Object.values(this.byKey)) h += (b.ttlSeconds || 0) / 3600;
+    return h * this.cfg.estGBPerTtlHour;
+  }
+
+  /** The figure that counts right now, and where it came from. */
+  usedGB() {
+    this._roll();
+    if (Number.isFinite(this.cfg.forceUsageGB)) return { gb: this.cfg.forceUsageGB, source: 'forced' };
+    if (this.overrideGB !== null) return { gb: this.overrideGB, source: 'override' };
+    if (this.actualGB !== null && this.now() - this.actualAt < this.cfg.actualMaxAgeMs) return { gb: this.actualGB, source: 'actual' };
+    return { gb: this.estimatedGB, source: 'estimate' };
+  }
+
+  /** Everything an operator wants to see (admin endpoint) and what `policy()` decides on. */
+  snapshot() {
+    const { gb, source } = this.usedGB();
+    const total = budgetGB(this.cfg);
+    const fraction = total > 0 ? gb / total : 1;
+    return {
+      month: this.month,
+      usedGB: round(gb),
+      source,
+      estimatedGB: round(this.estimatedGB),
+      actualGB: this.actualGB === null ? null : round(this.actualGB),
+      actualAt: this.actualAt || null,
+      overrideGB: this.overrideGB,
+      budgetGB: total,
+      freeGB: this.cfg.freeGB,
+      capUSD: this.cfg.capUSD,
+      fraction: Math.round(fraction * 1000) / 1000,
+      status: statusFor(fraction, this.cfg),
+      byKey: this.byKey,
+    };
+  }
+}
+
+function round(x) {
+  return Math.round(x * 1000) / 1000;
+}
+
+/** 'ok' | 'degraded' | 'off' for a usage fraction. */
+export function statusFor(fraction, cfg = DEFAULT_BUDGET) {
+  if (fraction >= 1) return 'off';
+  if (fraction >= cfg.shedFrac) return 'degraded';
+  return 'ok';
+}
+
+/**
+ * The per-session TURN decision. Pure: from a budget snapshot (`fraction`, or a `status` plus
+ * `fraction`) and the session's tier + limits.
+ * @param {{ fraction: number }} snap
+ * @param {'anon'|'key'} tier
+ * @param {{ turnTtl: number, mintsPerHour: number }} limits
+ * @param {BudgetConfig} [cfg]
+ * @returns {{ mint: boolean, ttl: number, mintsPerHour: number, status: 'ok'|'degraded'|'off', reason?: 'budget'|'cap' }}
+ */
+export function turnPolicy(snap, tier, limits, cfg = DEFAULT_BUDGET) {
+  const f = snap && Number.isFinite(snap.fraction) ? snap.fraction : 0;
+  const status = statusFor(f, cfg);
+  if (status === 'off') return { mint: false, ttl: 0, mintsPerHour: 0, status, reason: 'cap' };
+  if (tier !== 'key' && status === 'degraded') {
+    if (f >= cfg.stopAnonFrac) return { mint: false, ttl: 0, mintsPerHour: 0, status, reason: 'budget' };
+    return { mint: true, ttl: Math.min(300, limits.turnTtl), mintsPerHour: Math.min(5, limits.mintsPerHour), status };
+  }
+  return { mint: true, ttl: limits.turnTtl, mintsPerHour: limits.mintsPerHour, status };
+}
+
+/**
+ * Read month-to-date relay bytes from Cloudflare's GraphQL analytics (dataset
+ * `callsTurnUsageAdaptiveGroups`, filtered to this TURN key, grouped by `customIdentifier` — which
+ * `mintTurnCredentials` sets to the session's key id). Needs an API token with the account's
+ * "Account Analytics: Read" permission (`CF_ANALYTICS_API_TOKEN`, a Worker secret) and the
+ * account id (`CF_ACCOUNT_ID`). Returns null when not configured.
+ * @returns {Promise<null | { totalGB: number, byKey: Record<string, number>, from: string, to: string }>}
+ */
+export async function readTurnUsage(env, { fetchImpl = globalThis.fetch, now = Date.now() } = {}) {
+  if (!env || !env.CF_ANALYTICS_API_TOKEN || !env.CF_ACCOUNT_ID || !env.TURN_KEY_ID) return null;
+  const d = new Date(now);
+  const from = `${monthOf(now)}-01`;
+  const to = d.toISOString().slice(0, 10);
+  const query = `query ($account: string!, $key: string!, $from: Date!, $to: Date!) {
+    viewer { accounts(filter: { accountTag: $account }) {
+      callsTurnUsageAdaptiveGroups(limit: 1000, filter: { date_geq: $from, date_leq: $to, keyId: $key }) {
+        dimensions { customIdentifier }
+        sum { egressBytes ingressBytes }
+      } } } }`;
+  const res = await fetchImpl('https://api.cloudflare.com/client/v4/graphql', {
+    method: 'POST',
+    headers: { Authorization: `Bearer ${env.CF_ANALYTICS_API_TOKEN}`, 'Content-Type': 'application/json' },
+    body: JSON.stringify({ query, variables: { account: env.CF_ACCOUNT_ID, key: env.TURN_KEY_ID, from, to } }),
+  });
+  if (!res.ok) throw new Error(`TURN analytics: HTTP ${res.status}`);
+  const body = await res.json();
+  if (body.errors && body.errors.length) throw new Error(`TURN analytics: ${body.errors[0].message || 'GraphQL error'}`);
+  const groups = body?.data?.viewer?.accounts?.[0]?.callsTurnUsageAdaptiveGroups || [];
+  const byKey = {};
+  let total = 0;
+  for (const g of groups) {
+    const bytes = (g.sum?.egressBytes || 0) + (g.sum?.ingressBytes || 0);
+    const id = g.dimensions?.customIdentifier || 'anon';
+    byKey[id] = (byKey[id] || 0) + bytes / GB;
+    total += bytes / GB;
+  }
+  return { totalGB: total, byKey, from, to };
+}

package/splat.d.ts

@@ -1135,6 +1135,18 @@ export interface SplatHandle {
    * it after this resolves. Resolves the number of programs warmed. docs/playcanvas-adapter.md §warmEntity.
    */
   warmEntity(entity: unknown, opts?: { timeoutMs?: number }): Promise<number>;
+  /**
+   * `engine: 'playcanvas'` only (a no-op returning `{ programs: 0, container: null }` on Spark).
+   * Destroy `entity` — content you added under `handle.engine.root` — and release what it held on
+   * the GPU: the shader programs its materials linked (PlayCanvas never frees a program by itself:
+   * its ProgramLibrary caches every variant for the device's life, and `Material.destroy()` does
+   * not destroy them), and, with `asset`, the glTF container it was instantiated from (unloaded
+   * and taken out of the registry unless something else in the tile still draws from it). A
+   * program another material still uses is kept. Call it for whatever a content swap replaces.
+   * Returns the number of programs destroyed and what happened to the container.
+   * docs/content-lifecycle-rules.md.
+   */
+  releaseEntity(entity: unknown, opts?: { asset?: unknown }): { programs: number; container: 'unloaded' | 'in-use' | null };
   setStereo(opts: SplatStereoOptions | null): SplatHandle;
   /**
    * The `depth` option's comfort factor in force, in (0, 1]: what the display rig's ipdFactor and