@swiftbrowser/native 0.18.3 → 0.21.0

package/src/bridge.ts

@@ -17,8 +17,27 @@ export interface NativeBridge {
   now(): number;
   setTimer(id: number, delayMs: number, repeats: boolean): void;
   clearTimer(id: number): void;
-  /** Starts a request; the answer arrives at `__sbFetchResult(id, result)`. */
-  fetch(id: number, request: string | NativeFetchRequest): void;
+  /**
+   * Starts a request; the answer arrives at `__sbFetchResult(id, result)`.
+   * A body may be a typed array after the request, which names it
+   * `{ $bytes: 0 }`, where the host has `hostRequestBytes`; or, where the
+   * host `fetchStreams()`, a list of `bodyParts`, each a typed array beside
+   * the request or a range of a file on disk, which the host streams in
+   * order without reading the files into memory.
+   */
+  fetch(id: number, request: string | NativeFetchRequest, ...views: ArrayBufferView[]): void;
+  /**
+   * Whether `fetch` takes `bodyParts` (a body streamed from files on disk,
+   * `InputStream` on the Swift side). Hosts before 0.20 lack it, and then
+   * a body holding a picked file is read into memory first.
+   */
+  fetchStreams?(): boolean;
+  /**
+   * Cancels request `id` (an `AbortController`'s abort): the `URLSession`
+   * task stops, its bytes stop coming, and no `__sbFetchResult` follows.
+   * Hosts before 0.20 lack it, and then only the promise is rejected.
+   */
+  fetchCancel?(id: number): void;
   /**
    * Starts loading the image at `url` for its pixel size (image.ts: the
    * runtime's `Image`), keeping the bytes for the `image` element that
@@ -34,6 +53,16 @@ export interface NativeBridge {
   storageClear(): void;
   /** Base64 of `count` random bytes. */
   randomBytes(count: number): string;
+  /**
+   * Typed arrays in and out where the host carries bytes (it has
+   * `hostRequestBytes`, 0.19): `randomBytes`, `digest` and `hmac` without
+   * base64, and UTF-8 for encoding.ts. Older hosts lack them.
+   */
+  randomValues?(count: number): Uint8Array;
+  digestBytes?(algorithm: string, data: ArrayBufferView): Uint8Array | null | undefined;
+  hmacBytes?(algorithm: string, key: ArrayBufferView, data: ArrayBufferView): Uint8Array | null | undefined;
+  decodeUTF8?(bytes: ArrayBufferView): string;
+  encodeUTF8?(text: string): Uint8Array;
   openURL(url: string): boolean;
   /** The viewer's locale identifier (`en_US`). */
   locale(): string;
@@ -67,9 +96,10 @@ export interface NativeBridge {
   pushRegister?(id: number, applicationServerKey?: string): void;
 
   // WebSockets (webSocket.ts) on `URLSessionWebSocketTask`; events come to `__sbWebSocketEvent(id, json)`. Hosts before 0.20 lack them.
-  wsOpen?(id: number, url: string, protocols: string[]): void;
+  /** `bytes`: binary messages come as a `Uint8Array` after the event's JSON (`{ binary: { $bytes: 0 } }`), not base64. */
+  wsOpen?(id: number, url: string, protocols: string[], bytes?: boolean): void;
   /** `{ text }` or `{ binary }` (base64), as JSON. */
-  wsSend?(id: number, json: string): void;
+  wsSend?(id: number, json: string, ...views: ArrayBufferView[]): void;
   wsClose?(id: number, code: number, reason: string): void;
 
   // `crypto.subtle` (subtle.ts) on CryptoKit, synchronously. Hosts before 0.20 lack them.
@@ -143,6 +173,15 @@ export interface NativeBridge {
    * Hosts before 0.20 lack it.
    */
   hostRequest?(id: number, kind: string, json: string): void;
+  /**
+   * `hostRequest` with bytes beside the JSON: each typed array (or
+   * `ArrayBuffer`) in the params is lifted out and sent as a further
+   * argument, and `{ "$bytes": n }` stands in its place in the JSON; an
+   * answer's bytes follow `__sbHostResponse`'s JSON the same way
+   * (docs/notes/bytes.md). A host without it (before 0.19) is given base64
+   * in the JSON instead, which `hostRequest` makes from the same views.
+   */
+  hostRequestBytes?(id: number, kind: string, json: string, ...views: ArrayBufferView[]): void;
 
   /**
    * The escape hatch's functions (nativeFunctions.ts): the names the Swift
@@ -221,8 +260,17 @@ export interface NativeFetchRequest {
   url: string;
   method: string;
   headers: Record<string, string>;
-  /** Base64, or null. */
-  body: string | null;
+  /** Base64, `{ $bytes: 0 }` naming the view after the request, or null. */
+  body: string | { $bytes: number } | null;
+  /**
+   * With `fetchStreams`: the body as parts in order, each a view beside the
+   * request or `[start, end)` of a file on disk (one the app may read: in
+   * its directories, or picked or dropped), sent as one stream of their
+   * total length; `body` is null then.
+   */
+  bodyParts?: ({ $bytes: number } | { url: string; start: number; end: number })[];
+  /** The response's body as a `Uint8Array` after the answer's JSON, not base64. */
+  bytes?: boolean;
 }
 
 export interface NativeImageProbeResult {
@@ -236,8 +284,8 @@ export interface NativeFetchResult {
   statusText?: string;
   headers?: Record<string, string>;
   url?: string;
-  /** Base64. */
-  body?: string;
+  /** Base64, or `{ $bytes: 0 }` naming the `Uint8Array` after the JSON. */
+  body?: string | { $bytes: number };
   error?: string;
 }
 

package/src/encoding.ts

@@ -4,7 +4,20 @@
  * base64 (fetch bodies). No dependencies, so the runtime can carry them.
  */
 
+/**
+ * The host's UTF-8, where it has it (`decodeUTF8` and `encodeUTF8`, a
+ * native function over a typed array): the loops below run interpreted in
+ * an iOS app, so text past a few dozen characters goes to the host instead.
+ */
+let nativeUTF8: { decode(bytes: Uint8Array): string; encode(text: string): Uint8Array } | null = null;
+const NATIVE_UTF8_FROM = 64;
+
+export function installNativeUTF8(utf8: typeof nativeUTF8): void {
+  nativeUTF8 = utf8;
+}
+
 export function utf8Encode(text: string): Uint8Array {
+  if (nativeUTF8 && text.length >= NATIVE_UTF8_FROM) return nativeUTF8.encode(text);
   const out: number[] = [];
   for (let i = 0; i < text.length; i++) {
     let code = text.charCodeAt(i);
@@ -24,6 +37,7 @@ export function utf8Encode(text: string): Uint8Array {
 }
 
 export function utf8Decode(bytes: Uint8Array): string {
+  if (nativeUTF8 && bytes.length >= NATIVE_UTF8_FROM) return nativeUTF8.decode(bytes);
   let out = '';
   for (let i = 0; i < bytes.length; ) {
     const a = bytes[i]!;
@@ -66,6 +80,14 @@ export function base64Encode(bytes: Uint8Array): string {
   return out;
 }
 
+/** Bytes that crossed the bridge: a view beside the JSON, or base64 from a host without them. */
+export function bridgedBytes(value: unknown): Uint8Array {
+  if (typeof value === 'string') return base64Decode(value);
+  if (value instanceof ArrayBuffer) return new Uint8Array(value);
+  if (ArrayBuffer.isView(value)) return new Uint8Array(value.buffer, value.byteOffset, value.byteLength);
+  return new Uint8Array(0);
+}
+
 export function base64Decode(text: string): Uint8Array {
   const clean = text.replace(/[^A-Za-z0-9+/]/g, '');
   const out: number[] = [];

package/src/fetch.ts

@@ -1,14 +1,16 @@
 /**
  * `fetch`, `Headers`, `Request`, `Response` and `AbortController` over the
- * bridge's `fetch` primitive (`URLSession` on the Swift side). Bodies cross
- * as base64; a `Response` reads them back as text, JSON, bytes or a `Blob`.
- * A `Blob` or `FormData` body (blob.ts) is sent whole, the form as
- * multipart; there are no streams.
+ * bridge's `fetch` primitive (`URLSession` on the Swift side). A request
+ * body is a list of parts (blob.ts): bytes here, or ranges of files on disk
+ * (picked or dropped files, and blobs and forms holding them), which a host
+ * with `fetchStreams` sends as one stream straight from disk, and an older
+ * host is given read into memory. A `Response` reads its body back as
+ * text, JSON, bytes or a `Blob`; responses are not streamed.
  */
 
-import type { NativeBridge, NativeFetchResult } from './bridge';
-import { encodeMultipart, SimpleBlob, SimpleFormData } from './blob';
-import { base64Decode, base64Encode, utf8Decode, utf8Encode } from './encoding';
+import type { NativeBridge, NativeFetchRequest, NativeFetchResult } from './bridge';
+import { encodeMultipart, partsAreLazy, partsBytes, partSize, SimpleBlob, SimpleFormData, type BodyPart } from './blob';
+import { base64Encode, bridgedBytes, utf8Decode, utf8Encode } from './encoding';
 
 type HeadersInitLike = SimpleHeaders | Record<string, string> | [string, string][];
 
@@ -129,50 +131,51 @@ export function setBodyRandomness(random: (count: number) => Uint8Array): void {
   randomBytes = random;
 }
 
-/** Bytes of a body, and the content type it implies when the caller set none. */
-function encodeBody(body: BodyInitLike): { bytes: Uint8Array | null; contentType: string | null } {
-  if (body === null || body === undefined) return { bytes: null, contentType: null };
-  if (typeof body === 'string') return { bytes: utf8Encode(body), contentType: 'text/plain;charset=UTF-8' };
-  if (body instanceof SimpleBlob) return { bytes: body.bytes(), contentType: body.type || null };
+/** The content type a body implies when the caller set none, and its parts. */
+function encodeBody(body: BodyInitLike): { parts: BodyPart[] | null; contentType: string | null } {
+  if (body === null || body === undefined) return { parts: null, contentType: null };
+  if (typeof body === 'string') return { parts: [{ bytes: utf8Encode(body) }], contentType: 'text/plain;charset=UTF-8' };
+  if (body instanceof SimpleBlob) return { parts: body.parts(), contentType: body.type || null };
   if (body instanceof SimpleFormData) return encodeMultipart(body, randomBytes);
-  if (body instanceof ArrayBuffer) return { bytes: new Uint8Array(body), contentType: null };
-  if (ArrayBuffer.isView(body)) return { bytes: new Uint8Array(body.buffer, body.byteOffset, body.byteLength), contentType: null };
+  if (body instanceof ArrayBuffer) return { parts: [{ bytes: new Uint8Array(body) }], contentType: null };
+  if (ArrayBuffer.isView(body)) return { parts: [{ bytes: new Uint8Array(body.buffer, body.byteOffset, body.byteLength) }], contentType: null };
   if (typeof body === 'object' && Symbol.iterator in body && typeof body.toString === 'function') {
-    return { bytes: utf8Encode(body.toString()), contentType: 'application/x-www-form-urlencoded;charset=UTF-8' };
+    return { parts: [{ bytes: utf8Encode(body.toString()) }], contentType: 'application/x-www-form-urlencoded;charset=UTF-8' };
   }
-  return { bytes: utf8Encode(String(body)), contentType: 'text/plain;charset=UTF-8' };
+  return { parts: [{ bytes: utf8Encode(String(body)) }], contentType: 'text/plain;charset=UTF-8' };
 }
 
 class Body {
-  protected bytes: Uint8Array | null;
+  /** The body's parts: in memory, or on disk until read. */
+  protected parts: BodyPart[] | null;
   bodyUsed = false;
-  constructor(bytes: Uint8Array | null) {
-    this.bytes = bytes;
+  constructor(parts: BodyPart[] | null) {
+    this.parts = parts;
   }
   get body(): null {
     // No streams; read the body whole with the methods below.
     return null;
   }
-  private take(): Uint8Array {
+  private async take(): Promise<Uint8Array> {
     if (this.bodyUsed) throw new TypeError('body used already');
     this.bodyUsed = true;
-    return this.bytes ?? new Uint8Array(0);
+    return this.parts ? partsBytes(this.parts) : new Uint8Array(0);
   }
   async arrayBuffer(): Promise<ArrayBuffer> {
-    const bytes = this.take();
+    const bytes = await this.take();
     return bytes.buffer.slice(bytes.byteOffset, bytes.byteOffset + bytes.byteLength) as ArrayBuffer;
   }
   async bytesArray(): Promise<Uint8Array> {
     return this.take();
   }
   async text(): Promise<string> {
-    return utf8Decode(this.take());
+    return utf8Decode(await this.take());
   }
   async json(): Promise<unknown> {
-    return JSON.parse(utf8Decode(this.take()));
+    return JSON.parse(utf8Decode(await this.take()));
   }
   async blob(): Promise<SimpleBlob> {
-    return new SimpleBlob([this.take()], { type: this.contentType() });
+    return new SimpleBlob([await this.take()], { type: this.contentType() });
   }
   /** The body's content type, for `blob()`; a Request or Response reads its headers. */
   protected contentType(): string {
@@ -196,24 +199,28 @@ export class SimpleRequest extends Body {
 
   constructor(input: string | SimpleRequest | { href: string }, init: RequestInitLike = {}) {
     const base = input instanceof SimpleRequest ? input : null;
-    const { bytes, contentType } = encodeBody(init.body);
-    super(bytes ?? base?.rawBytes() ?? null);
+    const { parts, contentType } = encodeBody(init.body);
+    super(parts ?? base?.rawBody() ?? null);
     this.url = typeof input === 'string' ? input : input instanceof SimpleRequest ? input.url : input.href;
     this.method = (init.method ?? base?.method ?? 'GET').toUpperCase();
     this.headers = new SimpleHeaders(init.headers ?? base?.headers);
     if (contentType && !this.headers.has('content-type')) this.headers.set('content-type', contentType);
     this.signal = init.signal ?? base?.signal ?? new SimpleAbortSignal();
   }
-  /** @internal */
-  rawBytes(): Uint8Array | null {
-    return this.bytes;
+  /** @internal The body's bytes, read from disk first where they come from there. */
+  async rawBytes(): Promise<Uint8Array | null> {
+    return this.parts === null ? null : await partsBytes(this.parts);
+  }
+  /** @internal The body's parts. */
+  rawBody(): BodyPart[] | null {
+    return this.parts;
   }
   protected override contentType(): string {
     return this.headers.get('content-type') ?? '';
   }
 
   clone(): SimpleRequest {
-    return new SimpleRequest(this, { body: this.bytes });
+    return new SimpleRequest(this, {});
   }
 }
 
@@ -233,8 +240,8 @@ export class SimpleResponse extends Body {
   readonly redirected = false;
 
   constructor(body: BodyInitLike = null, init: ResponseInitLike = {}) {
-    const { bytes, contentType } = encodeBody(body);
-    super(bytes);
+    const { parts, contentType } = encodeBody(body);
+    super(parts);
     this.status = init.status ?? 200;
     this.statusText = init.statusText ?? '';
     this.headers = new SimpleHeaders(init.headers);
@@ -249,7 +256,9 @@ export class SimpleResponse extends Body {
   }
 
   clone(): SimpleResponse {
-    return new SimpleResponse(this.bytes, { status: this.status, statusText: this.statusText, headers: this.headers, url: this.url });
+    const copy = new SimpleResponse(null, { status: this.status, statusText: this.statusText, headers: this.headers, url: this.url });
+    copy.parts = this.parts;
+    return copy;
   }
   static json(data: unknown, init: ResponseInitLike = {}): SimpleResponse {
     const response = new SimpleResponse(JSON.stringify(data), init);
@@ -261,6 +270,22 @@ export class SimpleResponse extends Body {
   }
 }
 
+/** In-memory parts as one array (none is on disk); one part is itself. */
+function joinBytes(parts: readonly BodyPart[]): Uint8Array {
+  const [only] = parts;
+  if (parts.length === 1 && only && 'bytes' in only) return only.bytes;
+  const total = parts.reduce((sum, part) => sum + partSize(part), 0);
+  const out = new Uint8Array(total);
+  let at = 0;
+  for (const part of parts) {
+    if ('bytes' in part) {
+      out.set(part.bytes, at);
+      at += part.bytes.byteLength;
+    }
+  }
+  return out;
+}
+
 export interface FetchGlobals {
   fetch: (input: string | SimpleRequest | { href: string }, init?: RequestInitLike) => Promise<SimpleResponse>;
   Headers: typeof SimpleHeaders;
@@ -268,12 +293,18 @@ export interface FetchGlobals {
   Response: typeof SimpleResponse;
   AbortController: typeof SimpleAbortController;
   AbortSignal: typeof SimpleAbortSignal;
-  /** The bridge's answer; Swift calls it as `__sbFetchResult(id, result)`. */
-  __sbFetchResult: (id: number, result: NativeFetchResult | string) => void;
+  /** The bridge's answer; Swift calls it as `__sbFetchResult(id, result, ...bytes)`. */
+  __sbFetchResult: (id: number, result: NativeFetchResult | string, ...buffers: ArrayBufferView[]) => void;
 }
 
-/** The fetch globals over the bridge. */
-export function createFetch(native: Pick<NativeBridge, 'fetch'>): FetchGlobals {
+/**
+ * The fetch globals over the bridge. With `bytes` (a host that carries
+ * typed arrays, docs/notes/bytes.md) bodies cross as views beside the JSON
+ * both ways; without, as base64. With `streams` (the host `fetchStreams()`,
+ * which needs `bytes`) a body holding files on disk goes as parts the host
+ * streams from there; without, such a body is read into memory first.
+ */
+export function createFetch(native: Pick<NativeBridge, 'fetch' | 'fetchCancel'>, options: { bytes?: boolean; streams?: boolean } = {}): FetchGlobals {
   let nextId = 1;
   const pending = new Map<number, { resolve: (response: SimpleResponse) => void; reject: (error: unknown) => void }>();
 
@@ -286,20 +317,52 @@ export function createFetch(native: Pick<NativeBridge, 'fetch'>): FetchGlobals {
       }
       const id = nextId++;
       pending.set(id, { resolve, reject });
+      let sent = false;
       request.signal.addEventListener('abort', () => {
-        if (pending.delete(id)) reject(request.signal.reason);
-      });
-      const bytes = request.rawBytes();
-      native.fetch(id, {
-        url: request.url,
-        method: request.method,
-        headers: request.headers.toObject(),
-        body: bytes ? base64Encode(bytes) : null,
+        if (!pending.delete(id)) return;
+        // The host stops the task where it can (0.20); an older host finishes it and its answer is ignored.
+        if (sent) native.fetchCancel?.(id);
+        reject(request.signal.reason);
       });
+      const head = { url: request.url, method: request.method, headers: request.headers.toObject() };
+      const send = (bytes: Uint8Array | null): void => {
+        if (!pending.has(id)) return; // aborted while the body was read
+        sent = true;
+        if (options.bytes) {
+          if (bytes) native.fetch(id, { ...head, body: { $bytes: 0 }, bytes: true }, bytes);
+          else native.fetch(id, { ...head, body: null, bytes: true });
+        } else {
+          native.fetch(id, { ...head, body: bytes ? base64Encode(bytes) : null });
+        }
+      };
+      const parts = request.rawBody();
+      if (parts === null || !partsAreLazy(parts)) {
+        // Bytes already here go out in this turn (tests and callers see the request at once).
+        send(parts === null ? null : joinBytes(parts));
+      } else if (options.streams && options.bytes) {
+        // Files on disk stay there: the host streams the parts in order, their total length known.
+        sent = true;
+        const views: Uint8Array[] = [];
+        const bodyParts: NonNullable<NativeFetchRequest['bodyParts']> = parts.map((part) => {
+          if ('bytes' in part) {
+            views.push(part.bytes);
+            return { $bytes: views.length - 1 };
+          }
+          return { url: part.file.url, start: part.file.start, end: part.file.end };
+        });
+        const headers = { ...head.headers };
+        if (!('content-length' in headers)) headers['content-length'] = String(parts.reduce((sum, part) => sum + partSize(part), 0));
+        native.fetch(id, { ...head, headers, body: null, bodyParts, bytes: true }, ...views);
+      } else {
+        // An older host: the files are read here first.
+        partsBytes(parts).then(send, (error: unknown) => {
+          if (pending.delete(id)) reject(error instanceof Error ? error : new TypeError(`fetch failed: ${String(error)}`));
+        });
+      }
     });
   };
 
-  const __sbFetchResult: FetchGlobals['__sbFetchResult'] = (id, raw) => {
+  const __sbFetchResult: FetchGlobals['__sbFetchResult'] = (id, raw, ...buffers) => {
     const waiting = pending.get(id);
     if (!waiting) return;
     pending.delete(id);
@@ -310,7 +373,7 @@ export function createFetch(native: Pick<NativeBridge, 'fetch'>): FetchGlobals {
       return;
     }
     waiting.resolve(
-      new SimpleResponse(result.body ? base64Decode(result.body) : null, {
+      new SimpleResponse(result.body ? bridgedBytes(typeof result.body === 'string' ? result.body : buffers[result.body.$bytes]) : null, {
         status: result.status ?? 200,
         statusText: result.statusText ?? '',
         headers: result.headers ?? {},