@swiftbrowser/web 0.1.0 → 0.3.0

package/src/hostRequests.ts

@@ -0,0 +1,426 @@
+/**
+ * Phase 13: what the Wasm app asks the page to do on its behalf. The app has
+ * no network of its own; `URLSession` sends a `request` op of kind `fetch`
+ * and `AsyncImage` one of kind `image` (see docs/ops-protocol.md, "Phase
+ * 13"); `ShareLink` sends `share` and `PhotosPicker` `pickFiles`. The
+ * loader (wasm.ts) hands each op to `performHostRequest` and delivers the
+ * result as a `response` event with the same id.
+ *
+ * Bodies cross the boundary as base64 (JSON has no bytes). An image is never
+ * copied into Wasm: the page decodes it once, reports the pixel size, and the
+ * `<img>` the renderer creates later finds it in the browser's cache.
+ *
+ * The stand-in frameworks use the same channel: UserNotifications sends
+ * `notification` requests (notifications.ts), AVFoundation's capture sessions
+ * `scanner` requests (scanner.ts), AuthenticationServices `webAuth`
+ * requests (webAuth.ts). Saving to the photo library sends `download`, and
+ * `UIPasteboard` `clipboard` (clipboard.ts).
+ */
+
+import { base64Decode, base64Encode } from './base64';
+import { browserNotificationHost, performNotification, type NotificationHost, type NotificationResult } from './notifications';
+import type {
+  BitmapRecipe,
+  FetchRequestParams,
+  ImageRequestParams,
+  NotificationRequestParams,
+  PickFilesRequestParams,
+  RequestOp,
+  ScannerRequestParams,
+  ShareRequestParams,
+  WebSocketRequestParams,
+  OpenURLRequestParams,
+  WebAuthRequestParams,
+  MediaRequestParams,
+  DownloadRequestParams,
+  ClipboardRequestParams,
+  TranslateRequestParams,
+  PickColorRequestParams,
+  SharedFile,
+} from './protocol';
+import { browserClipboardHost, performClipboard, type ClipboardHost } from './clipboard';
+import { browserMediaHost, performMedia, type MediaHost } from './media';
+import { browserScannerHost, performScanner, type ScannerHost, type ScannerResult } from './scanner';
+import { browserTranslationHost, performTranslate, type TranslationHost } from './translation';
+import { chooseColor, performPickColor, type ColorChooser } from './colorPicker';
+import { WebSocketHost, type WebSocketLike } from './webSocket';
+import { browserWebAuthHost, WebAuthSessions, type WebAuthResult } from './webAuth';
+
+export interface FetchResult {
+  status: number;
+  statusText: string;
+  /** Header names lower-cased, as `Headers` yields them. */
+  headers: Record<string, string>;
+  /**
+   * The body. It reaches Swift through linear memory (`sb_bytes`), or as
+   * base64 from a module without that export (src/wasm.ts).
+   */
+  body: Uint8Array;
+  /** The final URL after redirects. */
+  url: string;
+}
+
+export interface ImageResult {
+  width: number;
+  height: number;
+}
+
+/** How a `share` request ended: shared, saved as a download, or dismissed by the viewer. */
+export interface ShareResult {
+  outcome: 'shared' | 'downloaded' | 'cancelled';
+}
+
+/** One file the viewer picked (`pickFiles`), with its bytes. */
+export interface PickedFile {
+  name: string;
+  /** The MIME type the browser reports; empty when it does not know it. */
+  type: string;
+  /** The bytes, base64. */
+  data: string;
+  /** For a picture: an object URL the app's `Image` shows, and its pixel size. */
+  url?: string;
+  width?: number;
+  height?: number;
+}
+
+/** The files a `pickFiles` request chose; none when the viewer dismissed the chooser. */
+export interface PickFilesResult {
+  items: PickedFile[];
+}
+
+/** The browser facilities a request handler uses; tests substitute them. */
+export interface HostRequestEnvironment {
+  fetch: typeof fetch;
+  /** Decodes an image and resolves with its natural size; rejects when it cannot be loaded. */
+  loadImage: (url: string) => Promise<ImageResult>;
+  /** The Web Share API (`navigator.share`), where the browser has it. */
+  share?: (data: ShareData) => Promise<void>;
+  /** `navigator.canShare`, where the browser has it. */
+  canShare?: (data: ShareData) => boolean;
+  /** Saves a file the way a download link does. */
+  download?: (blob: Blob, filename: string) => void;
+  /** An asset-catalog image's URL (the page knows the catalog), to share it as a file. */
+  assetURL?: (name: string) => string | undefined;
+  /**
+   * Opens a file chooser and resolves with the chosen files, or none when the
+   * viewer dismisses it. It must open the chooser before it returns: browsers
+   * only show one during the tap that asked (user activation).
+   */
+  pickFiles?: (options: { accept: string; multiple: boolean }) => Promise<File[]>;
+  /** A URL the page can show a picked file at (`URL.createObjectURL`). */
+  objectURL?: (file: File) => string;
+  /** A `UIImage` bitmap drawn into a PNG file (src/bitmapStore.ts), to share it as a file. */
+  bitmapFile?: (recipe: BitmapRecipe) => Promise<Blob | null>;
+  /** The Notification API (UserNotifications), where the browser has it. */
+  notifications?: NotificationHost;
+  /** The camera and `BarcodeDetector`, or a typed code, for AVFoundation's capture sessions (scanner.ts). */
+  scanner?: ScannerHost;
+  /** The page's WebSockets (`URLSessionWebSocketTask`). */
+  webSockets?: WebSocketHost;
+  /** Opens a web or mail URL in a new tab (`openURL`). */
+  openURL?: (url: string) => void;
+  /** Sign-in windows (`webAuth`, webAuth.ts). */
+  webAuth?: WebAuthSessions;
+  /** AVFoundation's media files and probes, QuickLook's previews (`media`, media.ts). */
+  media?: MediaHost;
+  /** The system clipboard (`clipboard`, clipboard.ts). */
+  clipboard?: ClipboardHost;
+  /** The browser's built-in translator (`translate`, translation.ts), where it has one. */
+  translation?: TranslationHost;
+  /** The browser's color chooser (`pickColor`, colorPicker.ts); it must open before it returns. */
+  pickColor?: ColorChooser;
+}
+
+/**
+ * The browser's file chooser: a hidden `<input type="file">` clicked at once,
+ * inside the tap that sent the request (the loader performs the request while
+ * the tap's click handler is still running; see wasm.ts). Resolves on
+ * `change` with the files, or on `cancel` (the viewer closed the chooser)
+ * with none. A browser without the `cancel` event never answers a dismissal;
+ * the app's selection then just stays as it was.
+ */
+function chooseFiles(options: { accept: string; multiple: boolean }): Promise<File[]> {
+  const input = document.createElement('input');
+  input.type = 'file';
+  if (options.accept) input.accept = options.accept;
+  input.multiple = options.multiple;
+  // In the document (some browsers only open a chooser for an attached
+  // input), but invisible and out of the way.
+  input.style.cssText = 'position:fixed;left:-1000px;top:0;width:1px;height:1px;opacity:0';
+  input.dataset['sbPicker'] = '';
+  document.body.append(input);
+  const result = new Promise<File[]>((resolve) => {
+    const finish = (files: File[]): void => {
+      input.remove();
+      resolve(files);
+    };
+    input.addEventListener('change', () => finish(Array.from(input.files ?? [])), { once: true });
+    input.addEventListener('cancel', () => finish([]), { once: true });
+  });
+  input.click();
+  return result;
+}
+
+function downloadBlob(blob: Blob, filename: string): void {
+  const url = URL.createObjectURL(blob);
+  const link = document.createElement('a');
+  link.href = url;
+  link.download = filename;
+  link.style.display = 'none';
+  document.body.append(link);
+  link.click();
+  link.remove();
+  setTimeout(() => URL.revokeObjectURL(url), 60_000);
+}
+
+const notificationHost = browserNotificationHost();
+const scannerHost = browserScannerHost();
+const webAuthHost = browserWebAuthHost();
+const mediaHost = browserMediaHost(typeof document !== 'undefined' ? downloadBlob : undefined);
+const clipboardHost = browserClipboardHost();
+const translationHost = browserTranslationHost();
+
+export const browserEnvironment: HostRequestEnvironment = {
+  fetch: (input, init) => fetch(input, init),
+  loadImage: (url) =>
+    new Promise((resolve, reject) => {
+      const img = new Image();
+      img.onload = () => resolve({ width: img.naturalWidth, height: img.naturalHeight });
+      img.onerror = () => reject(new Error(`network: could not load ${url}`));
+      img.src = url;
+    }),
+  ...(typeof navigator !== 'undefined' && typeof navigator.share === 'function'
+    ? { share: (data: ShareData) => navigator.share(data) }
+    : {}),
+  ...(typeof navigator !== 'undefined' && typeof navigator.canShare === 'function'
+    ? { canShare: (data: ShareData) => navigator.canShare(data) }
+    : {}),
+  ...(typeof document !== 'undefined' ? { download: downloadBlob, pickFiles: chooseFiles } : {}),
+  ...(typeof URL !== 'undefined' && typeof URL.createObjectURL === 'function'
+    ? { objectURL: (file: File) => URL.createObjectURL(file) }
+    : {}),
+  ...(notificationHost ? { notifications: notificationHost } : {}),
+  ...(scannerHost ? { scanner: scannerHost } : {}),
+  ...(typeof window !== 'undefined' && typeof window.open === 'function'
+    ? { openURL: (url: string) => void window.open(url, '_blank', 'noopener') }
+    : {}),
+  ...(typeof WebSocket !== 'undefined'
+    ? { webSockets: new WebSocketHost((url, protocols) => new WebSocket(url, protocols) as unknown as WebSocketLike) }
+    : {}),
+  ...(webAuthHost ? { webAuth: new WebAuthSessions(webAuthHost) } : {}),
+  ...(mediaHost ? { media: mediaHost } : {}),
+  ...(clipboardHost ? { clipboard: clipboardHost } : {}),
+  ...(translationHost ? { translation: translationHost } : {}),
+  ...(typeof document !== 'undefined' ? { pickColor: chooseColor } : {}),
+};
+
+/**
+ * Performs one request. Resolves with the result the app expects for the
+ * op's kind; rejects with an `Error` whose message starts with a short tag
+ * the app maps to a `URLError` (`timeout`, `abort`, `offline`, `network`).
+ */
+export async function performHostRequest(
+  op: RequestOp,
+  env: HostRequestEnvironment = browserEnvironment,
+): Promise<FetchResult | ImageResult | ShareResult | PickFilesResult | NotificationResult | ScannerResult | WebAuthResult | Record<string, unknown>> {
+  switch (op.kind) {
+    case 'fetch':
+      return performFetch(op.params as FetchRequestParams, env);
+    case 'image':
+      return env.loadImage((op.params as ImageRequestParams).url);
+    case 'share':
+      return performShare(op.params as ShareRequestParams, env);
+    case 'pickFiles':
+      // Not awaited before the chooser opens: `performPickFiles` calls
+      // `env.pickFiles` synchronously, inside the tap that sent the request.
+      return performPickFiles(op.params as PickFilesRequestParams, env);
+    case 'notification':
+      return performNotification(op.params as NotificationRequestParams, env.notifications);
+    case 'scanner':
+      return performScanner(op.params as ScannerRequestParams, env.scanner);
+    case 'openURL': {
+      const { url } = op.params as OpenURLRequestParams;
+      if (!/^(https?|mailto|tel|sms):/i.test(url)) throw new Error(`unsupported: cannot open ${url}`);
+      if (!env.openURL) throw new Error('unsupported: this page cannot open URLs');
+      env.openURL(url);
+      return {};
+    }
+    case 'websocket':
+      if (!env.webSockets) throw new Error('unsupported: this browser has no WebSocket');
+      return env.webSockets.perform(op.params as WebSocketRequestParams);
+    case 'webAuth':
+      // Not awaited before the popup opens: `perform` calls `window.open`
+      // synchronously, while the tap's activation may still count.
+      if (!env.webAuth) throw new Error('unsupported: this page cannot open a sign-in window');
+      return env.webAuth.perform(op.params as WebAuthRequestParams);
+    case 'media':
+      // `open` is called before any await, while the tap's activation may still count.
+      return performMedia(op.params as MediaRequestParams, env.media);
+    case 'download':
+      return performDownload(op.params as DownloadRequestParams, env);
+    case 'clipboard': {
+      // The write starts before any await, while the tap's activation may still count.
+      const params = op.params as ClipboardRequestParams;
+      return performClipboard(params, env.clipboard, () => collectFiles(params, env, 'Image'));
+    }
+    case 'translate':
+      return performTranslate(op.params as TranslateRequestParams, env.translation);
+    case 'pickColor':
+      // Not awaited before the chooser opens: it is clicked inside the tap that sent the request.
+      return performPickColor(op.params as PickColorRequestParams, env.pickColor);
+    default:
+      throw new Error(`unsupported: request kind ${String((op as { kind: unknown }).kind)}`);
+  }
+}
+
+/**
+ * `ShareLink`: the Web Share API when the browser has it (and can share the
+ * files, if any); otherwise, or when the browser refuses (no user
+ * activation, unsupported data), a download: each image as its file, else
+ * the title, text and link as a `.txt`. A share the viewer dismisses is not
+ * downloaded.
+ */
+async function performShare(params: ShareRequestParams, env: HostRequestEnvironment): Promise<ShareResult> {
+  const files = await collectFiles(params, env, 'Image');
+  const data: ShareData = {};
+  if (params.title) data.title = params.title;
+  if (params.text) data.text = params.text;
+  if (params.url) data.url = params.url;
+  if (files.length) data.files = files;
+  const canShareFiles = !files.length || (env.canShare?.({ files }) ?? false);
+  if (env.share && canShareFiles) {
+    try {
+      await env.share(data);
+      return { outcome: 'shared' };
+    } catch (error) {
+      if (error instanceof Error && error.name === 'AbortError') return { outcome: 'cancelled' };
+      // NotAllowedError (no user activation), TypeError (unsupported data): download instead.
+    }
+  }
+  if (!env.download) throw new Error('unsupported: this browser can neither share nor download');
+  if (files.length) {
+    for (const file of files) env.download(file, file.name);
+  } else {
+    const body = [params.title, params.text, params.url].filter(Boolean).join('\n');
+    env.download(new Blob([`${body}\n`], { type: 'text/plain' }), `${safeFilename(params.title || 'Shared')}.txt`);
+  }
+  return { outcome: 'downloaded' };
+}
+
+/**
+ * `PhotosPicker`: the browser's file chooser stands in for the photo
+ * library. Every chosen file comes back with its bytes (the app loads them
+ * with `loadTransferable(type: Data.self)` without asking again); a picture
+ * the browser can decode also gets an object URL and its pixel size, for
+ * `loadTransferable(type: Image.self)`. A dismissed chooser answers with no
+ * items.
+ */
+async function performPickFiles(params: PickFilesRequestParams, env: HostRequestEnvironment): Promise<PickFilesResult> {
+  if (!env.pickFiles) throw new Error('unsupported: this page cannot open a file chooser');
+  // Called before any `await`, so the chooser opens within the tap.
+  const files = await env.pickFiles({ accept: params.accept ?? '', multiple: params.multiple === true });
+  const items: PickedFile[] = [];
+  for (const file of files) {
+    const item: PickedFile = {
+      name: file.name,
+      type: file.type,
+      data: base64Encode(new Uint8Array(await file.arrayBuffer())),
+    };
+    if (file.type.startsWith('image/') && env.objectURL) {
+      const url = env.objectURL(file);
+      try {
+        const size = await env.loadImage(url);
+        Object.assign(item, { url, width: size.width, height: size.height });
+      } catch {
+        // A format this browser cannot draw (HEIC outside Safari): the bytes still go.
+        if (typeof URL !== 'undefined' && url.startsWith('blob:')) URL.revokeObjectURL(url);
+      }
+    }
+    items.push(item);
+  }
+  return { items };
+}
+
+/**
+ * The files a `share`, `download` or `clipboard` request carries: asset
+ * images (fetched from the catalog), `UIImage` bitmaps (drawn into PNGs
+ * named after the title, or `fallbackTitle`), and files the app made
+ * (`files`: a `Transferable` item's bytes, a `UIImage`'s own file).
+ */
+async function collectFiles(
+  params: { title?: string; images?: string[]; bitmaps?: BitmapRecipe[]; files?: SharedFile[] },
+  env: HostRequestEnvironment,
+  fallbackTitle: string,
+): Promise<File[]> {
+  const files: File[] = [];
+  for (const name of params.images ?? []) {
+    const src = env.assetURL?.(name);
+    if (!src) continue;
+    const blob = await (await env.fetch(src)).blob();
+    const extension = blob.type.split('/')[1]?.replace('svg+xml', 'svg') ?? 'png';
+    files.push(new File([blob], `${safeFilename(name)}.${extension}`, { type: blob.type }));
+  }
+  for (const [index, recipe] of (params.bitmaps ?? []).entries()) {
+    const blob = await env.bitmapFile?.(recipe);
+    if (!blob) continue;
+    const name = safeFilename(params.title || fallbackTitle) + (index > 0 ? ` ${index + 1}` : '');
+    files.push(new File([blob], `${name}.png`, { type: 'image/png' }));
+  }
+  for (const file of params.files ?? []) {
+    const bytes = base64Decode(file.data);
+    files.push(new File([bytes as Uint8Array<ArrayBuffer>], safeFilename(file.name), { type: file.type }));
+  }
+  return files;
+}
+
+/**
+ * Saving to the photo library (Photos, UIKit): every file the request
+ * carries is downloaded, as the browser saves any download.
+ */
+async function performDownload(params: DownloadRequestParams, env: HostRequestEnvironment): Promise<ShareResult> {
+  if (!env.download) throw new Error('unsupported: this page cannot download files');
+  const files = await collectFiles(params, env, 'Photo');
+  if (!files.length) throw new Error('unsupported: nothing to download');
+  for (const file of files) env.download(file, file.name);
+  return { outcome: 'downloaded' };
+}
+
+/** A file name from a title: no path separators or characters filesystems reject. */
+function safeFilename(name: string): string {
+  return name.replace(/[\\/:*?"<>|]+/g, '-').trim() || 'Shared';
+}
+
+async function performFetch(params: FetchRequestParams, env: HostRequestEnvironment): Promise<FetchResult> {
+  if (typeof navigator !== 'undefined' && navigator.onLine === false) throw new Error('offline');
+  const controller = typeof AbortController === 'function' ? new AbortController() : null;
+  const timeout = typeof params.timeout === 'number' && params.timeout > 0 ? params.timeout : 0;
+  const timer = controller && timeout > 0 ? setTimeout(() => controller.abort('timeout'), timeout) : null;
+  const init: RequestInit = { method: params.method || 'GET', headers: params.headers ?? {} };
+  if (params.body) init.body = base64Decode(params.body) as BodyInit;
+  if (controller) init.signal = controller.signal;
+  let response: Response;
+  try {
+    response = await env.fetch(params.url, init);
+  } catch (error) {
+    if (controller?.signal.aborted) {
+      throw new Error(controller.signal.reason === 'timeout' ? `timeout: ${params.url}` : `abort: ${params.url}`);
+    }
+    throw new Error(`network: ${error instanceof Error ? error.message : String(error)}`);
+  } finally {
+    if (timer !== null) clearTimeout(timer);
+  }
+  const headers: Record<string, string> = {};
+  response.headers.forEach((value, key) => {
+    headers[key] = value;
+  });
+  const bytes = new Uint8Array(await response.arrayBuffer());
+  return {
+    status: response.status,
+    statusText: response.statusText,
+    headers,
+    body: bytes,
+    url: response.url || params.url,
+  };
+}
+
+export { base64Decode, base64Encode } from './base64';