@siafoundation/sia-storage 0.1.0 → 0.1.2

package/README.md

@@ -70,11 +70,85 @@ await packed.add(fileB.stream())
 for (const obj of await packed.finalize()) await sdk.pinObject(obj)
 ```
 
+## Streaming files
+
+Play video and audio without loading the whole file first, and save large files without holding them in memory. A service worker reads each object in ranges and answers the page with an ordinary URL, so `<video>` seeks on its own and a download goes to the browser's download manager. Where service workers are unavailable, the same calls read the object in the page instead, so the code is the same everywhere.
+
+```ts
+import { openStreams } from '@siafoundation/sia-storage'
+
+// An Sdk, with the indexer URL and app metadata its Builder was made with.
+const streams = openStreams(sdk, { indexerUrl, appMeta })
+
+// Or a SharedSdk, with the indexer URL and seed it was connected with.
+const sharedStreams = openStreams(sharedSdk, { indexerUrl, seed })
+
+// Any element or fetch that takes a URL.
+const video = await streams.url(object, { name: 'clip.mp4', type: 'video/mp4' })
+videoElement.src = video.url
+// When the element goes away:
+video.release()
+
+// From a click handler, so the browser allows the save.
+button.onclick = () => streams.download(object, { name: 'clip.mp4' })
+
+// When you're done with the SDK:
+streams.close()
+```
+
+### Serve the worker
+
+The worker is one file, `sia-storage-sw.js`, served from your site's root. Use the line for your setup.
+
+**Vite** (React, Vue, Svelte, Solid and others): add the plugin. It serves the worker in `vite dev`, emits it with the build, and excludes the SDK from dependency pre-bundling.
+
+```js
+// vite.config.js
+import { siaStorage } from '@siafoundation/sia-storage/vite'
+
+export default defineConfig({ plugins: [siaStorage()] })
+```
+
+**Next.js (App Router)**: add one route file.
+
+```ts
+// app/sia-storage-sw.js/route.ts
+export { GET } from '@siafoundation/sia-storage/next'
+export const dynamic = 'force-static'
+```
+
+**Anything else** (webpack, Rollup, esbuild, Parcel, the Next.js Pages Router, a static host): copy the worker into the folder served at your site's root. The file changes with each SDK version, so copy it on every install and leave it out of git.
+
+```json
+// package.json
+"scripts": { "postinstall": "sia-storage-worker public" }
+```
+
+### Good to know
+
+- **HTTPS or localhost.** Browsers only run service workers there. Anywhere else the page reads objects itself.
+- **A site served from a sub-path**, such as `/app/`, serves the worker there too and says where, before the first `openStreams`: `enableStreaming({ workerUrl: '/app/sia-storage-sw.js' })`.
+- **A site with its own service worker** can't add a second one, since a page has only one. Call `installStreams(self)` from `@siafoundation/sia-storage/stream-worker` inside yours, and point `enableStreaming` at it: `enableStreaming({ workerUrl: '/sw.js', type: 'module' })`.
+- **A Content Security Policy** needs `worker-src 'self'`.
+- **The credentials stay in memory.** The worker connects its own SDK, so it needs what yours was made with: a `SharedSdk`'s seed, or an `Sdk`'s app key, which it takes from `sdk.appKey()`. The page hands them over a message port, and the worker never writes them anywhere.
+- **Keep the tab open** until a download finishes. If the browser restarts the worker, it gets the credentials back from the page.
+- **The first download click** within a few seconds of `openStreams`, before the worker is ready, uses the save picker or an in-memory save instead.
+
+## iCloud Private Relay
+
+The SDK does not work through iCloud Private Relay. `detectPrivateRelay()` resolves true for a Safari visitor on it, so you can ask them to turn it off in iCloud settings. Other browsers resolve false without a request.
+
+```ts
+import { detectPrivateRelay } from '@siafoundation/sia-storage'
+
+if (await detectPrivateRelay()) showRelayNotice()
+```
+
 ## Framework notes
 
 The browser build is WebAssembly — most bundlers handle it directly, a few need a small hint.
 
-**Vite** — production builds work as-is. For `vite dev`, exclude the package from the dep pre-bundler so its `import.meta.url`-relative WASM path resolves correctly:
+**Vite**: the `siaStorage()` plugin from [Serve the worker](#serve-the-worker) covers this. Without it, production builds work as-is, and `vite dev` needs the package excluded from the dep pre-bundler so its `import.meta.url`-relative WASM path resolves correctly:
 
 ```js
 // vite.config.js
@@ -116,6 +190,7 @@ Near-identical surfaces. Real differences:
 - Sharing key seeds are hex `string` on browser, `Buffer` on Node. This covers `SharingKey.seed()`, `SharingKey.fromSeed(seed)`, and `SharedSdk.connect(indexerUrl, seed)`.
 - `sdk.unshareObject(key, object)` takes a `PinnedObject` on browser and an object id `string` on Node.
 - `sdk.hosts(query?)` and `sharedSdk.hosts(query?)` accept a `HostQuery` on browser; on Node they take no arguments.
+- `openStreams` gives a browser page URLs that a service worker serves. Node reads objects with `sdk.download(object, { offset, length })`, which already streams a range, so it needs no worker. On Node, `enableStreaming()` resolves false, and `url` and `download` on an `openStreams` handle reject.
 
 ## API
 
@@ -128,6 +203,7 @@ Near-identical surfaces. Real differences:
 | `validateRecoveryPhrase(phrase)` | Throws on invalid. |
 | `setLogger(callback, level)` | Receive SDK logs. |
 | `encodedSize(size, dataShards, parityShards)` | Encoded size after erasure coding. |
+| `detectPrivateRelay()` | Whether a Safari visitor is on iCloud Private Relay, which the SDK does not work through. |
 
 ### `Sdk`
 
@@ -207,6 +283,22 @@ sharing key's seed. Downloads are paid for by the key's owner.
 | `download(object, options?)` | Returns a `ReadableStream`. |
 | `hosts(query?)` | Hosts serving this key's objects. |
 
+### Streaming
+
+| | |
+|---|---|
+| `openStreams(sdk, credentials)` | `Streams` for one SDK's objects. An `Sdk` takes `{ indexerUrl, appMeta }` and a `SharedSdk` takes `{ indexerUrl, seed }`, typed by which one you pass. |
+| `streams.url(object, options)` | `{ url, blob?, release() }`. Streams where it can, else reads the whole object into `blob`. |
+| `streams.download(object, options)` | Saves the object. Resolves `'streaming'`, `'saved'` or `'cancelled'`. Call it from a click handler. |
+| `streams.close()` | Cancels this handle's streams. Other handles on the same SDK keep theirs. |
+| `enableStreaming(options?)` | Registers the worker and resolves whether streaming is on. `openStreams` calls it for you, so call it only to pass `workerUrl`, `scope` or `type`. |
+
+`options` for `url` and `download`: `name`, `type` (MIME), `onError(message)` for failures after streaming starts (logged when omitted), `onProgress(bytes)` when the page reads the object itself, and `signal` for `url`.
+
+### `@siafoundation/sia-storage/stream-worker`
+
+`installStreams(self, { wasm? })` adds streaming to a service worker of your own. `wasm` is the SDK's WebAssembly as a URL, bytes or module, for bundlers that don't emit it.
+
 ## License
 
 MIT

package/dist/chunk-QYQQIWFH.js

@@ -0,0 +1,74 @@
+// src/stream/errors.ts
+function streamErrorMessage(error) {
+  const message = error instanceof Error ? error.message : typeof error === "string" ? error : "Unknown streaming failure";
+  return message.replace(/\b(?:https?|wss?|sia):\/\/[^\s"'<>]+/gi, "[URL redacted]").replace(/(?:bearer\s+)[^\s,;]+/gi, "Bearer [redacted]").replace(
+    /((?:seed|share|token|key|authorization)\s*[=:]\s*)[^\s,;]+/gi,
+    "$1[redacted]"
+  ).replace(/[a-f0-9]{64,}/gi, "[redacted]").replace(/[\r\n\t]/g, " ").slice(0, 1e3);
+}
+function reportStreamError(error, name, range) {
+  const message = streamErrorMessage(error);
+  const bytes = range ? ` bytes ${range.offset}-${range.offset + range.length - 1}` : "";
+  console.error(`[Sia stream] ${streamErrorMessage(name)}${bytes}: ${message}`);
+  return message;
+}
+
+// src/stream/protocol.ts
+var STREAM_PATH = /\/__sia_stream__\/([^/]+)\/([^/]+)\/[^/]+$/;
+function streamPath(scope, clientId, token) {
+  return `${scope}__sia_stream__/${clientId}/${token}/file`;
+}
+function parseStreamPath(pathname) {
+  const match = STREAM_PATH.exec(pathname);
+  return match ? { clientId: match[1], token: match[2] } : void 0;
+}
+var strings = (data, fields) => fields.every((field) => typeof data?.[field] === "string");
+function isAppMetadata(value) {
+  return strings(value, ["appId", "name", "description", "serviceUrl"]);
+}
+function isConnection(value) {
+  const data = value;
+  if (data?.kind === "shared") return strings(data, ["indexerUrl", "seed"]);
+  return data?.kind === "app" && strings(data, ["indexerUrl", "appKey"]) && isAppMetadata(data.appMeta);
+}
+function isSourceReply(reply) {
+  const data = reply;
+  return data?.type === "source" && strings(data, ["session", "objectId", "name", "mime"]) && isConnection(data.connection) && (data.connection.kind === "shared" || typeof data.sealed === "object" && data.sealed !== null) && Number.isSafeInteger(data.size) && data.size >= 0;
+}
+function requestReply(target, message, { timeout, signal }) {
+  return new Promise((resolve, reject) => {
+    const { port1, port2 } = new MessageChannel();
+    const timer = timeout === void 0 ? void 0 : setTimeout(
+      () => settle(() => reject(new Error("No reply in time."))),
+      timeout
+    );
+    const abort = () => settle(() => reject(signal?.reason));
+    function settle(outcome) {
+      clearTimeout(timer);
+      signal?.removeEventListener("abort", abort);
+      port1.close();
+      port2.close();
+      outcome();
+    }
+    if (signal?.aborted) return abort();
+    signal?.addEventListener("abort", abort, { once: true });
+    port1.onmessage = ({ data }) => settle(() => resolve(data));
+    port1.onmessageerror = () => settle(() => reject(new Error("Unreadable reply.")));
+    try {
+      target.postMessage(message, [port2]);
+    } catch (error) {
+      settle(() => reject(error));
+    }
+  });
+}
+
+export {
+  streamErrorMessage,
+  reportStreamError,
+  streamPath,
+  parseStreamPath,
+  isAppMetadata,
+  isSourceReply,
+  requestReply
+};
+//# sourceMappingURL=chunk-QYQQIWFH.js.map

package/dist/chunk-QYQQIWFH.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/stream/errors.ts","../src/stream/protocol.ts"],"sourcesContent":["/** Only sanitized strings cross the diagnostic boundary, never raw SDK objects. */\nexport function streamErrorMessage(error: unknown): string {\n  const message =\n    error instanceof Error\n      ? error.message\n      : typeof error === 'string'\n        ? error\n        : 'Unknown streaming failure'\n  return message\n    .replace(/\\b(?:https?|wss?|sia):\\/\\/[^\\s\"'<>]+/gi, '[URL redacted]')\n    .replace(/(?:bearer\\s+)[^\\s,;]+/gi, 'Bearer [redacted]')\n    .replace(\n      /((?:seed|share|token|key|authorization)\\s*[=:]\\s*)[^\\s,;]+/gi,\n      '$1[redacted]',\n    )\n    .replace(/[a-f0-9]{64,}/gi, '[redacted]')\n    .replace(/[\\r\\n\\t]/g, ' ')\n    .slice(0, 1000)\n}\n\nexport function reportStreamError(\n  error: unknown,\n  name: string,\n  range: { offset: number; length: number } | undefined,\n) {\n  const message = streamErrorMessage(error)\n  // One string rather than an object, so it reads the same in every console.\n  const bytes = range\n    ? ` bytes ${range.offset}-${range.offset + range.length - 1}`\n    : ''\n  console.error(`[Sia stream] ${streamErrorMessage(name)}${bytes}: ${message}`)\n  return message\n}\n","/**\n * Messages between a page and its streaming service worker.\n *\n * Stream URLs carry only the page's client id and a random token. When the\n * worker meets a token it does not know, it asks the page that made it for the\n * file and the share's credentials. The page and a worker can come from\n * different deployed versions, so the worker checks the page's reply before\n * using it.\n */\nimport type {\n  AppMetadata,\n  SealedObject,\n} from '../../wasm/sia_storage_wasm.js'\n\n/**\n * What the worker connects its own SDK with. A `SharedSdk` reconnects from its\n * sharing key's seed, and an `Sdk` from its app key, as hex, and app metadata.\n */\nexport type Connection =\n  | { kind: 'shared'; indexerUrl: string; seed: string }\n  | { kind: 'app'; indexerUrl: string; appKey: string; appMeta: AppMetadata }\n\nexport type SourceDetails = {\n  // One per opened SDK, so the worker can release it as a whole.\n  session: string\n  connection: Connection\n  objectId: string\n  // An `Sdk`'s object, sealed with its app key, so the worker can open it\n  // without a lookup. A `SharedSdk`'s object is looked up by `objectId`.\n  sealed?: SealedObject\n  name: string\n  mime: string\n  size: number\n}\n\n/** Page to worker. */\nexport type PageMessage =\n  | { type: 'sia-client' }\n  | { type: 'sia-release'; token: string }\n  | { type: 'sia-release-share'; session: string }\n\n/** Worker to page. */\nexport type WorkerMessage =\n  | { type: 'sia-source'; token: string }\n  | {\n      type: 'sia-stream-error'\n      token: string\n      message: string\n      offset?: number\n      length?: number\n    }\n\n/** The worker's answer to `sia-client`. */\nexport type ClientReply = { clientId: string; supported: boolean }\n\n/** The page's answer to `sia-source`. */\nexport type SourceReply =\n  | ({ type: 'source' } & SourceDetails)\n  | { type: 'error' }\n\n// Stream URLs sit under the worker's scope, so a download's navigation, which\n// only a worker whose scope covers the URL can answer, reaches it on sites\n// served from a sub-path too.\nconst STREAM_PATH = /\\/__sia_stream__\\/([^/]+)\\/([^/]+)\\/[^/]+$/\n\n/** `scope` is the worker registration's scope URL, which ends in a slash. */\nexport function streamPath(scope: string, clientId: string, token: string) {\n  return `${scope}__sia_stream__/${clientId}/${token}/file`\n}\n\nexport function parseStreamPath(pathname: string) {\n  const match = STREAM_PATH.exec(pathname)\n  return match ? { clientId: match[1]!, token: match[2]! } : undefined\n}\n\ntype Fields = Record<string, unknown> | null | undefined\n\nconst strings = (data: Fields, fields: string[]) =>\n  fields.every((field) => typeof data?.[field] === 'string')\n\n/** Checked on both sides, so bad metadata fails in `openStreams`, not per request. */\nexport function isAppMetadata(value: unknown): value is AppMetadata {\n  return strings(value as Fields, ['appId', 'name', 'description', 'serviceUrl'])\n}\n\nfunction isConnection(value: unknown): value is Connection {\n  const data = value as Fields\n  if (data?.kind === 'shared') return strings(data, ['indexerUrl', 'seed'])\n  return (\n    data?.kind === 'app' &&\n    strings(data, ['indexerUrl', 'appKey']) &&\n    isAppMetadata(data.appMeta)\n  )\n}\n\nexport function isSourceReply(\n  reply: unknown,\n): reply is { type: 'source' } & SourceDetails {\n  const data = reply as Fields\n  return (\n    data?.type === 'source' &&\n    strings(data, ['session', 'objectId', 'name', 'mime']) &&\n    isConnection(data.connection) &&\n    (data.connection.kind === 'shared' ||\n      (typeof data.sealed === 'object' && data.sealed !== null)) &&\n    Number.isSafeInteger(data.size) &&\n    (data.size as number) >= 0\n  )\n}\n\n/**\n * Posts `message` with a reply port and resolves with the first reply. Rejects\n * after `timeout` ms, or when `signal` aborts.\n */\nexport function requestReply(\n  target: { postMessage(message: unknown, transfer: Transferable[]): void },\n  message: unknown,\n  { timeout, signal }: { timeout?: number; signal?: AbortSignal },\n): Promise<unknown> {\n  return new Promise((resolve, reject) => {\n    const { port1, port2 } = new MessageChannel()\n    const timer =\n      timeout === undefined\n        ? undefined\n        : setTimeout(\n            () => settle(() => reject(new Error('No reply in time.'))),\n            timeout,\n          )\n    const abort = () => settle(() => reject(signal?.reason))\n    function settle(outcome: () => void) {\n      clearTimeout(timer)\n      signal?.removeEventListener('abort', abort)\n      port1.close()\n      port2.close()\n      outcome()\n    }\n    if (signal?.aborted) return abort()\n    signal?.addEventListener('abort', abort, { once: true })\n    port1.onmessage = ({ data }) => settle(() => resolve(data))\n    port1.onmessageerror = () =>\n      settle(() => reject(new Error('Unreadable reply.')))\n    try {\n      target.postMessage(message, [port2])\n    } catch (error) {\n      settle(() => reject(error))\n    }\n  })\n}\n"],"mappings":";AACO,SAAS,mBAAmB,OAAwB;AACzD,QAAM,UACJ,iBAAiB,QACb,MAAM,UACN,OAAO,UAAU,WACf,QACA;AACR,SAAO,QACJ,QAAQ,0CAA0C,gBAAgB,EAClE,QAAQ,2BAA2B,mBAAmB,EACtD;AAAA,IACC;AAAA,IACA;AAAA,EACF,EACC,QAAQ,mBAAmB,YAAY,EACvC,QAAQ,aAAa,GAAG,EACxB,MAAM,GAAG,GAAI;AAClB;AAEO,SAAS,kBACd,OACA,MACA,OACA;AACA,QAAM,UAAU,mBAAmB,KAAK;AAExC,QAAM,QAAQ,QACV,UAAU,MAAM,MAAM,IAAI,MAAM,SAAS,MAAM,SAAS,CAAC,KACzD;AACJ,UAAQ,MAAM,gBAAgB,mBAAmB,IAAI,CAAC,GAAG,KAAK,KAAK,OAAO,EAAE;AAC5E,SAAO;AACT;;;AC+BA,IAAM,cAAc;AAGb,SAAS,WAAW,OAAe,UAAkB,OAAe;AACzE,SAAO,GAAG,KAAK,kBAAkB,QAAQ,IAAI,KAAK;AACpD;AAEO,SAAS,gBAAgB,UAAkB;AAChD,QAAM,QAAQ,YAAY,KAAK,QAAQ;AACvC,SAAO,QAAQ,EAAE,UAAU,MAAM,CAAC,GAAI,OAAO,MAAM,CAAC,EAAG,IAAI;AAC7D;AAIA,IAAM,UAAU,CAAC,MAAc,WAC7B,OAAO,MAAM,CAAC,UAAU,OAAO,OAAO,KAAK,MAAM,QAAQ;AAGpD,SAAS,cAAc,OAAsC;AAClE,SAAO,QAAQ,OAAiB,CAAC,SAAS,QAAQ,eAAe,YAAY,CAAC;AAChF;AAEA,SAAS,aAAa,OAAqC;AACzD,QAAM,OAAO;AACb,MAAI,MAAM,SAAS,SAAU,QAAO,QAAQ,MAAM,CAAC,cAAc,MAAM,CAAC;AACxE,SACE,MAAM,SAAS,SACf,QAAQ,MAAM,CAAC,cAAc,QAAQ,CAAC,KACtC,cAAc,KAAK,OAAO;AAE9B;AAEO,SAAS,cACd,OAC6C;AAC7C,QAAM,OAAO;AACb,SACE,MAAM,SAAS,YACf,QAAQ,MAAM,CAAC,WAAW,YAAY,QAAQ,MAAM,CAAC,KACrD,aAAa,KAAK,UAAU,MAC3B,KAAK,WAAW,SAAS,YACvB,OAAO,KAAK,WAAW,YAAY,KAAK,WAAW,SACtD,OAAO,cAAc,KAAK,IAAI,KAC7B,KAAK,QAAmB;AAE7B;AAMO,SAAS,aACd,QACA,SACA,EAAE,SAAS,OAAO,GACA;AAClB,SAAO,IAAI,QAAQ,CAAC,SAAS,WAAW;AACtC,UAAM,EAAE,OAAO,MAAM,IAAI,IAAI,eAAe;AAC5C,UAAM,QACJ,YAAY,SACR,SACA;AAAA,MACE,MAAM,OAAO,MAAM,OAAO,IAAI,MAAM,mBAAmB,CAAC,CAAC;AAAA,MACzD;AAAA,IACF;AACN,UAAM,QAAQ,MAAM,OAAO,MAAM,OAAO,QAAQ,MAAM,CAAC;AACvD,aAAS,OAAO,SAAqB;AACnC,mBAAa,KAAK;AAClB,cAAQ,oBAAoB,SAAS,KAAK;AAC1C,YAAM,MAAM;AACZ,YAAM,MAAM;AACZ,cAAQ;AAAA,IACV;AACA,QAAI,QAAQ,QAAS,QAAO,MAAM;AAClC,YAAQ,iBAAiB,SAAS,OAAO,EAAE,MAAM,KAAK,CAAC;AACvD,UAAM,YAAY,CAAC,EAAE,KAAK,MAAM,OAAO,MAAM,QAAQ,IAAI,CAAC;AAC1D,UAAM,iBAAiB,MACrB,OAAO,MAAM,OAAO,IAAI,MAAM,mBAAmB,CAAC,CAAC;AACrD,QAAI;AACF,aAAO,YAAY,SAAS,CAAC,KAAK,CAAC;AAAA,IACrC,SAAS,OAAO;AACd,aAAO,MAAM,OAAO,KAAK,CAAC;AAAA,IAC5B;AAAA,EACF,CAAC;AACH;","names":[]}

package/dist/cli.js

@@ -0,0 +1,13 @@
+#!/usr/bin/env node
+
+// src/cli.ts
+import { copyFileSync, mkdirSync } from "fs";
+import { join } from "path";
+var WORKER_FILE = "sia-storage-sw.js";
+var dir = process.argv[2] ?? "public";
+mkdirSync(dir, { recursive: true });
+copyFileSync(
+  new URL(`./${WORKER_FILE}`, import.meta.url),
+  join(dir, WORKER_FILE)
+);
+console.log(`Copied ${WORKER_FILE} into ${dir}/`);

package/dist/index.d.ts

@@ -1,6 +1,94 @@
+import { AppMetadata, Sdk, SharedSdk, PinnedObject } from '../wasm/sia_storage_wasm.js';
 export { Account, AppKey, AppMetadata, Builder, DownloadOptions, Host, HostQuery, KeyRecord, KeyStats, ObjectEvent, PackedUpload, PinnedObject, PinnedSlab, Sdk, SealedObject, Sector, ShardProgress, SharedSdk, SharingKey, Slab, UploadOptions, encodedSize, generateRecoveryPhrase, setLogger, validateRecoveryPhrase } from '../wasm/sia_storage_wasm.js';
 
+declare function detectPrivateRelay(): Promise<boolean>;
+
+/**
+ * The page side of streaming.
+ *
+ * `openStreams` hands out same-origin URLs that the library's service worker
+ * answers with ranged reads of an object, so a `<video>` seeks without loading
+ * the whole file and a download goes to the browser's download manager instead
+ * of the page's memory. The worker connects its own SDK of the same kind, with
+ * credentials this page hands it over a message port and it keeps in memory.
+ * Where the worker is unavailable, the same calls read the object in the page.
+ */
+
+type StreamingOptions = {
+    /** Where the site serves the worker file. Defaults to `/sia-storage-sw.js`. */
+    workerUrl?: string;
+    /** The worker's scope. Defaults to the directory `workerUrl` is in. */
+    scope?: string;
+    /** `'module'` when `workerUrl` is an ES module worker of your own. */
+    type?: WorkerType;
+};
+/** What a `SharedSdk` was connected with. */
+type SharedCredentials = {
+    indexerUrl: string;
+    seed: string;
+};
+/** What an `Sdk`'s `Builder` was made with. The key comes from `sdk.appKey()`. */
+type AppCredentials = {
+    indexerUrl: string;
+    appMeta: AppMetadata;
+};
+/** The credentials `openStreams` takes for each kind of SDK. */
+type CredentialsFor<S extends Sdk | SharedSdk> = S extends SharedSdk ? SharedCredentials : AppCredentials;
+type FileOptions = {
+    /** Used for downloads and for the browser's media handling. */
+    name: string;
+    /** The MIME type. Defaults to `application/octet-stream`. */
+    type?: string;
+    /** A failure after streaming started. Without it, failures are logged. */
+    onError?: (message: string) => void;
+    /** Bytes read so far, when the page reads the object itself. */
+    onProgress?: (bytesDownloaded: number) => void;
+};
+/** A URL for an `<img>`, `<video>`, `<audio>`, `<iframe>` or `fetch`. */
+type StreamedFile = {
+    url: string;
+    /** The whole file, when the page read it itself instead of streaming. */
+    blob?: Blob;
+    /** Frees the URL. Call it when the element showing it goes away. */
+    release(): void;
+};
+type Streams = {
+    /** A URL serving the object. Streams where it can, else reads it whole. */
+    url(object: PinnedObject, options: FileOptions & {
+        signal?: AbortSignal;
+    }): Promise<StreamedFile>;
+    /**
+     * Saves the object, from a click handler. Streams to the browser's download
+     * manager where it can, else opens the save picker, else saves a Blob.
+     * Awaits nothing before the picker opens, so the browser still counts it as
+     * part of the click.
+     */
+    download(object: PinnedObject, options: FileOptions): Promise<'streaming' | 'saved' | 'cancelled'>;
+    /**
+     * Cancels the streams this handle made. Other handles on the same SDK keep
+     * theirs. Call it when you stop using the handle.
+     */
+    close(): void;
+};
+/**
+ * Registers the streaming worker and resolves whether this page can stream.
+ * `openStreams` calls it with the defaults, so call it yourself only to pass
+ * options, and before the first `openStreams`. Later calls return the first
+ * call's answer, except when setup failed or timed out and a different worker
+ * has since taken control of the page. Then the next call tries again, with
+ * the first call's options.
+ */
+declare function enableStreaming(options?: StreamingOptions): Promise<boolean>;
+/**
+ * Previews and downloads for one SDK's objects, from an `Sdk` or a `SharedSdk`.
+ *
+ * The worker cannot use this page's SDK, so it connects its own with
+ * `credentials`: the indexer URL and seed a `SharedSdk` was connected with, or
+ * the indexer URL and app metadata an `Sdk`'s `Builder` was made with.
+ */
+declare function openStreams<S extends Sdk | SharedSdk>(sdk: S, credentials: CredentialsFor<S>): Streams;
+
 /** Initialize the WASM module. Safe to call multiple times. */
 declare function initSia(): Promise<void>;
 
-export { initSia };
+export { type AppCredentials, type CredentialsFor, type FileOptions, type SharedCredentials, type StreamedFile, type StreamingOptions, type Streams, detectPrivateRelay, enableStreaming, initSia, openStreams };

package/dist/index.js

@@ -1,5 +1,305 @@
+import {
+  isAppMetadata,
+  reportStreamError,
+  requestReply,
+  streamErrorMessage,
+  streamPath
+} from "./chunk-QYQQIWFH.js";
+
 // src/index.ts
 import wasmInit from "../wasm/sia_storage_wasm.js";
+
+// src/relay.ts
+var RELAY_CHECK_URL = "https://check-relay.sia.storage";
+var TIMEOUT = 5e3;
+var answer;
+function detectPrivateRelay() {
+  answer ??= typeof navigator === "undefined" ? Promise.resolve(false) : checkPrivateRelay(navigator.userAgent, fetch);
+  return answer;
+}
+async function checkPrivateRelay(userAgent, request) {
+  const safari = /Version\/\S+.*Safari\//.test(userAgent) && !/Chrome|Chromium|CriOS|FxiOS|Edg|OPR|OPiOS|Ddg\/|Android/.test(userAgent);
+  if (!safari) return false;
+  try {
+    const response = await request(RELAY_CHECK_URL, {
+      signal: AbortSignal.timeout(TIMEOUT)
+    });
+    const body = await response.json();
+    return body.relay === true;
+  } catch {
+    return false;
+  }
+}
+
+// src/stream/fallback.ts
+function chunks(stream) {
+  return stream.getReader();
+}
+async function readBlob(sdk, object, type, onProgress, signal) {
+  const reader = chunks(sdk.download(object));
+  const onAbort = () => void reader.cancel();
+  signal.addEventListener("abort", onAbort);
+  const parts = [];
+  let bytesDownloaded = 0;
+  try {
+    while (true) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      parts.push(value);
+      bytesDownloaded += value.length;
+      onProgress(bytesDownloaded);
+    }
+  } finally {
+    signal.removeEventListener("abort", onAbort);
+  }
+  signal.throwIfAborted();
+  return new Blob(parts, type ? { type } : {});
+}
+function saveBlob(blob, name) {
+  const url = URL.createObjectURL(blob);
+  const a = document.createElement("a");
+  a.href = url;
+  a.download = name;
+  a.click();
+  setTimeout(() => URL.revokeObjectURL(url), 0);
+}
+async function saveToDisk(sdk, object, name, type, onProgress) {
+  const picker = window.showSaveFilePicker;
+  if (!picker) {
+    const blob = await readBlob(
+      sdk,
+      object,
+      type,
+      onProgress,
+      new AbortController().signal
+    );
+    saveBlob(blob, name);
+    return true;
+  }
+  let handle;
+  try {
+    handle = await picker.call(window, { suggestedName: name });
+  } catch (e) {
+    if (e instanceof DOMException && e.name === "AbortError") return false;
+    throw e;
+  }
+  let bytesDownloaded = 0;
+  const progress = new TransformStream({
+    transform(chunk, controller) {
+      bytesDownloaded += chunk.length;
+      onProgress(bytesDownloaded);
+      controller.enqueue(chunk);
+    }
+  });
+  const file = await handle.createWritable();
+  await sdk.download(object).pipeThrough(progress).pipeTo(file);
+  return true;
+}
+
+// src/stream/page.ts
+var DEFAULT_WORKER_URL = "/sia-storage-sw.js";
+var SETUP_TIMEOUT = 5e3;
+var entries = /* @__PURE__ */ new Map();
+var opened = /* @__PURE__ */ new Set();
+var worker;
+var initialization;
+var initOptions = {};
+var failedController;
+function enableStreaming(options = {}) {
+  if (!initialization) {
+    initOptions = options;
+  } else if (failedController === void 0) {
+    return initialization;
+  } else {
+    const controller = navigator.serviceWorker.controller;
+    if (!controller || controller === failedController) return initialization;
+  }
+  failedController = void 0;
+  initialization = initialize(initOptions).catch(() => {
+    failedController = navigator.serviceWorker.controller;
+    return false;
+  });
+  return initialization;
+}
+async function initialize({
+  workerUrl = DEFAULT_WORKER_URL,
+  scope,
+  type
+}) {
+  if (typeof window === "undefined" || !("serviceWorker" in navigator) || !window.isSecureContext) {
+    return false;
+  }
+  const { serviceWorker } = navigator;
+  serviceWorker.addEventListener("message", onWorkerMessage);
+  const deadline = AbortSignal.timeout(SETUP_TIMEOUT);
+  const existing = await within(serviceWorker.getRegistration(), deadline);
+  if (existing?.active && !serviceWorker.controller) return false;
+  const registration = await within(
+    serviceWorker.register(workerUrl, { ...scope && { scope }, ...type && { type } }).then(() => serviceWorker.ready),
+    deadline
+  );
+  if (!serviceWorker.controller) {
+    await within(
+      new Promise(
+        (resolve) => serviceWorker.addEventListener("controllerchange", resolve, {
+          once: true
+        })
+      ),
+      deadline
+    );
+  }
+  const controller = serviceWorker.controller;
+  if (!controller) return false;
+  const request = { type: "sia-client" };
+  const reply = await requestReply(controller, request, {
+    signal: deadline
+  });
+  if (!reply.supported) return false;
+  worker = { clientId: reply.clientId, scope: registration.scope };
+  return true;
+}
+function within(promise, signal) {
+  return new Promise((resolve, reject) => {
+    signal.throwIfAborted();
+    signal.addEventListener("abort", () => reject(signal.reason), {
+      once: true
+    });
+    promise.then(resolve, reject);
+  });
+}
+function openStreams(sdk, credentials) {
+  const handle = openedFor(sdk, credentials);
+  opened.add(handle);
+  void enableStreaming();
+  return {
+    async url(object, options) {
+      await enableStreaming();
+      options.signal?.throwIfAborted();
+      const stream = streamUrl(handle, object, options);
+      if (stream) return stream;
+      const blob = await readBlob(
+        sdk,
+        object,
+        options.type,
+        options.onProgress ?? (() => {
+        }),
+        options.signal ?? new AbortController().signal
+      );
+      const url = URL.createObjectURL(blob);
+      return { url, blob, release: () => URL.revokeObjectURL(url) };
+    },
+    async download(object, options) {
+      const stream = streamUrl(handle, object, options);
+      if (stream) {
+        const frame = document.createElement("iframe");
+        frame.hidden = true;
+        frame.src = `${stream.url}?download=1`;
+        document.body.append(frame);
+        return "streaming";
+      }
+      const saved = await saveToDisk(
+        sdk,
+        object,
+        options.name,
+        options.type,
+        options.onProgress ?? (() => {
+        })
+      );
+      return saved ? "saved" : "cancelled";
+    },
+    close() {
+      releaseStreams(handle);
+    }
+  };
+}
+function openedFor(sdk, credentials) {
+  const { indexerUrl, seed, appMeta } = credentials ?? {};
+  const session = crypto.randomUUID();
+  if (typeof sdk.appKey === "function") {
+    if (typeof indexerUrl !== "string" || !isAppMetadata(appMeta)) {
+      throw new TypeError("openStreams(Sdk) needs { indexerUrl, appMeta }.");
+    }
+    const appKey = sdk.appKey();
+    const connection = {
+      kind: "app",
+      indexerUrl,
+      appKey: toHex(appKey.export()),
+      appMeta
+    };
+    return { session, connection, appKey };
+  }
+  if (typeof indexerUrl !== "string" || typeof seed !== "string") {
+    throw new TypeError("openStreams(SharedSdk) needs { indexerUrl, seed }.");
+  }
+  return { session, connection: { kind: "shared", indexerUrl, seed } };
+}
+function toHex(bytes) {
+  return Array.from(bytes, (byte) => byte.toString(16).padStart(2, "0")).join("");
+}
+function streamUrl(handle, object, { name, type, onError }) {
+  if (!worker || !navigator.serviceWorker.controller || !opened.has(handle)) {
+    return void 0;
+  }
+  const token = crypto.randomUUID();
+  entries.set(token, {
+    handle,
+    objectId: object.id(),
+    sealed: handle.appKey && object.seal(handle.appKey),
+    size: object.size(),
+    name,
+    mime: type || "application/octet-stream",
+    onError
+  });
+  return {
+    url: streamPath(worker.scope, worker.clientId, token),
+    release() {
+      entries.delete(token);
+      const message = { type: "sia-release", token };
+      navigator.serviceWorker.controller?.postMessage(message);
+    }
+  };
+}
+function releaseStreams(handle) {
+  for (const [token, entry] of entries) {
+    if (entry.handle === handle) entries.delete(token);
+  }
+  if (!opened.delete(handle)) return;
+  const message = {
+    type: "sia-release-share",
+    session: handle.session
+  };
+  navigator.serviceWorker.controller?.postMessage(message);
+}
+function onWorkerMessage(event) {
+  if (event.source !== navigator.serviceWorker.controller) return;
+  const data = event.data;
+  if (data?.type === "sia-stream-error") {
+    const entry = entries.get(data.token);
+    if (!entry) return;
+    const { offset, length } = data;
+    const range = offset !== void 0 && length !== void 0 ? { offset, length } : void 0;
+    if (entry.onError) entry.onError(streamErrorMessage(data.message));
+    else reportStreamError(data.message, entry.name, range);
+  } else if (data?.type === "sia-source") {
+    const port = event.ports[0];
+    if (!port) return;
+    const entry = entries.get(data.token);
+    const reply = entry ? {
+      type: "source",
+      session: entry.handle.session,
+      connection: entry.handle.connection,
+      objectId: entry.objectId,
+      ...entry.sealed && { sealed: entry.sealed },
+      size: entry.size,
+      mime: entry.mime,
+      name: entry.name
+    } : { type: "error" };
+    port.postMessage(reply);
+    port.close();
+  }
+}
+
+// src/index.ts
 import {
   AppKey,
   Builder,
@@ -30,9 +330,12 @@ export {
   Sdk,
   SharedSdk,
   SharingKey,
+  detectPrivateRelay,
+  enableStreaming,
   encodedSize,
   generateRecoveryPhrase,
   initSia,
+  openStreams,
   setLogger,
   validateRecoveryPhrase
 };