@simpleplatform/sdk 2.0.0 → 2.1.0

package/README.md

@@ -39,7 +39,7 @@ The TypeScript SDK is organized into focused modules for different capabilities:
 | **HTTP**     | `@simpleplatform/sdk/http`     | External HTTP requests                         |
 | **Security** | `@simpleplatform/sdk/security` | Security policy authoring                      |
 | **Settings** | `@simpleplatform/sdk/settings` | Application settings retrieval                 |
-| **Storage**  | `@simpleplatform/sdk/storage`  | File upload and management                     |
+| **Storage**  | `@simpleplatform/sdk/storage`  | File upload, and reading a stored file's bytes |
 | **Space**    | `@simpleplatform/sdk/space`    | Behavior-aware record workflows in a Space     |
 
 ## Embedded Spaces
@@ -274,8 +274,23 @@ const response = await http.fetch(
   },
   request.context
 )
+
+// A browser request that carries the page's cookies
+const session = await http.fetch(
+  {
+    credentials: 'include',
+    url: 'https://api.example.com/session'
+  },
+  request.context
+)
 ```
 
+`credentials` is the browser's credentials mode for the request: `'omit'`,
+`'same-origin'` or `'include'`. A request that names none sends none, and the
+browser host then omits credentials. A cross-origin request that includes them
+still needs the endpoint to allow the page's origin and credentials through
+CORS. The server host has no browser credentials and ignores the option.
+
 ### Security Module
 
 Define declarative security policies with a fluent, global-style API:
@@ -370,6 +385,29 @@ console.log(documentHandle.mime_type) // "application/pdf"
 console.log(documentHandle.size) // File size in bytes
 ```
 
+The way back out takes the same handle and answers with the file's bytes:
+
+```typescript
+import { read, readRange, size } from '@simpleplatform/sdk/storage'
+
+const bytes: Uint8Array = await read(documentHandle, request.context)
+
+const length = await size(documentHandle, request.context) // without reading any of it
+const head = await readRange(documentHandle, 0, 1024, request.context) // the first kilobyte
+```
+
+The bytes cross from the host as they are, with no JSON and no base64. `read`
+asks for the size first and reads the file in ranges of at most
+`MAX_RANGE_BYTES` (16 MiB): a file that fits one range arrives as one array, and
+a larger one is read into a single buffer allocated once at exactly its size.
+`readRange` asks for the size first too, so a range that runs past the end of
+the file answers with exactly the bytes up to the end, and one that starts at or
+past the end is refused before any of it is read.
+
+Reading is for server actions; a browser action is refused. It needs a runtime
+plugin that provides `__host.callBytes`, and an older plugin is refused with a
+message saying so rather than handed bytes it would try to read as JSON.
+
 ### Type Definitions
 
 The TypeScript SDK is **fully typed** with comprehensive TypeScript definitions. Leverage IDE autocompletion and compile-time type checking:

package/dist/host.d.ts

@@ -7,6 +7,21 @@ import type { Context, SimpleResponse } from './types';
  * parsed response as a value.
  */
 export declare function execute<T = any>(actionName: string, params: any, context: Context): SimpleResponse<T>;
+/**
+ * Calls an action whose reply is a run of bytes, such as a range of a stored
+ * file, and returns them.
+ *
+ * The runtime hands the bytes over as a `Uint8Array` that owns them: no JSON,
+ * no base64, and no address. A host that refused answers with its ordinary
+ * envelope instead, returned here as a failed response, so a caller checks
+ * `ok` exactly as it does for `execute`. Its message names the call — `<action>
+ * failed: <the host's reason>` — worded as the Rust and Go SDKs word it.
+ *
+ * A runtime plugin released before this call existed does not provide it, and
+ * is refused here, before anything is sent, rather than handed a reply it
+ * would try to read as JSON.
+ */
+export declare function executeBytes(actionName: string, params: any, context: Context): SimpleResponse<Uint8Array>;
 /**
  * Calls an action on the host without waiting for it to answer.
  */

package/dist/host.js

@@ -11,6 +11,7 @@ function assertRuntimeAbi() {
         throw new Error(ABI_MISMATCH_MESSAGE);
     }
 }
+const BYTES_ABI_MISSING_MESSAGE = 'Reading a reply as bytes needs __host.callBytes, which this runtime plugin does not provide. Install a runtime plugin released with the matching SDK.';
 /**
  * Calls an action on the host and returns its response.
  *
@@ -23,6 +24,40 @@ export function execute(actionName, params, context) {
     void context;
     return __host.call(actionName, params ?? null);
 }
+/**
+ * Calls an action whose reply is a run of bytes, such as a range of a stored
+ * file, and returns them.
+ *
+ * The runtime hands the bytes over as a `Uint8Array` that owns them: no JSON,
+ * no base64, and no address. A host that refused answers with its ordinary
+ * envelope instead, returned here as a failed response, so a caller checks
+ * `ok` exactly as it does for `execute`. Its message names the call — `<action>
+ * failed: <the host's reason>` — worded as the Rust and Go SDKs word it.
+ *
+ * A runtime plugin released before this call existed does not provide it, and
+ * is refused here, before anything is sent, rather than handed a reply it
+ * would try to read as JSON.
+ */
+export function executeBytes(actionName, params, context) {
+    assertRuntimeAbi();
+    void context;
+    if (typeof __host.callBytes !== 'function') {
+        throw new TypeError(BYTES_ABI_MISSING_MESSAGE);
+    }
+    const reply = __host.callBytes(actionName, params ?? null);
+    if (reply instanceof Uint8Array) {
+        return { data: reply, ok: true };
+    }
+    // The runtime answers with bytes or with the host's refusal, and nothing
+    // else. A refusal that says it succeeded is still a refusal: no bytes came.
+    const refusal = reply;
+    if (refusal?.ok !== false)
+        return { error: { message: `${actionName} was refused and gave no reason.` }, ok: false };
+    const reason = refusal.error?.message;
+    if (typeof reason !== 'string' || reason.trim() === '')
+        return { error: { message: `${actionName} failed: The host refused the call and gave no reason.` }, ok: false };
+    return { error: { message: `${actionName} failed: ${reason}` }, ok: false };
+}
 /**
  * Calls an action on the host without waiting for it to answer.
  */

package/dist/http.d.ts

@@ -4,6 +4,13 @@ import type { Context } from './types';
  */
 export interface HttpRequest {
     body?: any;
+    /**
+     * The browser's credentials mode for the request: whether it carries the
+     * page's cookies and HTTP authentication. A request that names none sends
+     * none, and the browser host then omits credentials. The server host has no
+     * browser credentials and ignores it.
+     */
+    credentials?: 'include' | 'omit' | 'same-origin';
     headers?: Record<string, string>;
     method?: 'DELETE' | 'GET' | 'PATCH' | 'POST' | 'PUT';
     url: string;

package/dist/http.js

@@ -18,6 +18,7 @@ export async function fetch(request, context) {
     }
     const hostRequest = {
         body: request.body ? JSON.stringify(request.body) : undefined,
+        credentials: request.credentials,
         headers: request.headers,
         method: request.method ?? 'GET',
         url: request.url,

package/dist/index.js

@@ -88,12 +88,11 @@ async function handle(handler) {
     // All other contexts (WASM Loader, Elixir Backend) are handled below.
     let context;
     try {
-        const inputText = readInputFromHost();
-        if (!inputText) {
+        const simpleReq = readRequestFromHost();
+        if (simpleReq === undefined) {
             returnError('no input payload provided by the host environment', undefined);
             return;
         }
-        const simpleReq = JSON.parse(inputText);
         context = simpleReq.context;
         // Context 1: This is the initial WASM loader running in the browser.
         // Its only job is to start the script worker.
@@ -141,8 +140,43 @@ function readInputFromHost() {
         return JSON.stringify(globalThis.__SIMPLE_INITIAL_PAYLOAD__.request);
     }
     // Otherwise, we are in the main WASM module and must read from the host ABI.
-    const buffer = host.getContext();
-    return new TextDecoder().decode(buffer);
+    // The runtime parses the context on its own side now, so what comes back is a
+    // value rather than bytes. Both branches of this function still answer with
+    // text because that is what its callers parse.
+    return JSON.stringify(host.getContext());
+}
+/**
+ * Reads the request the host sent, or `undefined` when it sent none.
+ *
+ * Inside a WASM module the request is handed over as a value the runtime
+ * parsed from the host's own JSON, so it is read as it arrived. It used to be
+ * serialised and parsed again, which cost the whole payload twice over — the
+ * data is one string holding all of it, so ten megabytes were escaped into a
+ * new string and unescaped into another — and gave back what it started with,
+ * apart from the two values JSON cannot write: a negative zero came back as
+ * zero, and an infinite number as null. An action now sees what the host sent,
+ * those two included.
+ *
+ * Nothing here writes to the value. It belongs to the host, which stays free to
+ * hand over a frozen envelope, to answer `data` from a getter, or to read its
+ * own envelope back — as an action does when it calls `getContext` itself.
+ *
+ * The script worker in the browser reads a different thing. There the host
+ * leaves the request on the global as a JavaScript object of its own making,
+ * which reached the worker as a structured clone and can hold what JSON has no
+ * form for, such as a `Date` or an `undefined`. The round trip is what turns
+ * that into the request an action expects, so that path keeps it until a sweep
+ * of its own decides otherwise.
+ */
+function readRequestFromHost() {
+    if (globalThis.__SIMPLE_INITIAL_PAYLOAD__) {
+        const inputText = readInputFromHost();
+        return inputText ? JSON.parse(inputText) : undefined;
+    }
+    // `undefined` is what the runtime answers when the host sent no input at all,
+    // and it is the one thing a parsed JSON document can never be, so no request
+    // is mistaken for a missing one.
+    return host.getContext();
 }
 function returnError(message, context) {
     const response = { data: null, errors: [message], ok: false };

package/dist/storage.d.ts

@@ -1,4 +1,12 @@
 import type { Context, DocumentHandle, ExternalFileSource, StorageTarget } from './types';
+/**
+ * The longest range the host answers one read with.
+ *
+ * `read` and `readRange` cover anything longer in ranges of this size, into one
+ * buffer, so it bounds what the host holds for one call rather than what an
+ * action can read.
+ */
+export declare const MAX_RANGE_BYTES: number;
 /**
  * Uploads an in-memory binary buffer as a document to the platform's storage system.
  *
@@ -58,3 +66,71 @@ export declare function uploadBuffer(buffer: ArrayBuffer | Uint8Array, filename:
  * ```
  */
 export declare function uploadExternal(source: ExternalFileSource, target: StorageTarget, context: Context): Promise<DocumentHandle>;
+/**
+ * Returns how many bytes a stored file holds, from the store's own record of it
+ * rather than the handle's `size`.
+ *
+ * @param handle The document handle, exactly as a `:document` field holds it.
+ * @param context The execution context for the request.
+ * @returns A promise that resolves with the file's size in bytes.
+ * @throws If the handle does not name a stored file, or the host refuses.
+ *
+ * @example
+ * ```typescript
+ * const bytes = await size(record.attachment, request.context)
+ * ```
+ */
+export declare function size(handle: DocumentHandle, context: Context): Promise<number>;
+/**
+ * Returns the whole of a stored file, as its bytes.
+ *
+ * The size is asked for first, and the file arrives in ranges of at most
+ * `MAX_RANGE_BYTES`, each handed over by the host as it is — no JSON and no
+ * base64. A file that fits one range arrives as one array holding exactly its
+ * bytes. A larger one is read into a single buffer allocated once at exactly
+ * the file's size, and is refused before any range is read when this action
+ * has no memory for it. A range answered short — a file that changed while it
+ * was read — is refused rather than handed over incomplete.
+ *
+ * Reading is for server actions; a browser action is refused.
+ *
+ * @param handle The document handle, exactly as a `:document` field holds it.
+ * @param context The execution context for the request.
+ * @returns A promise that resolves with the file's bytes.
+ * @throws If the handle does not name a stored file, the host refuses, or the
+ * file changed while it was read.
+ *
+ * @example
+ * ```typescript
+ * const bytes = await read(record.attachment, request.context)
+ * const text = new TextDecoder().decode(bytes)
+ * ```
+ */
+export declare function read(handle: DocumentHandle, context: Context): Promise<Uint8Array>;
+/**
+ * Returns up to `length` bytes of a stored file, starting `offset` bytes in.
+ *
+ * The size is asked for first, so the range is held at what the file has past
+ * `offset`: one that runs past the end answers with exactly the bytes up to
+ * the end, and one that starts at or past the end is refused before any range
+ * is read. What is left is read as `read` reads a whole file — in ranges of at
+ * most `MAX_RANGE_BYTES`, into one buffer, each range answered in full or
+ * refused.
+ *
+ * Asking for the size first is also what makes a host that cannot read stored
+ * files refuse in its own words, before any range is asked of it.
+ *
+ * @param handle The document handle, exactly as a `:document` field holds it.
+ * @param offset How many bytes into the file the range starts, zero or more.
+ * @param length How many bytes to read, one or more.
+ * @param context The execution context for the request.
+ * @returns A promise that resolves with the range's bytes.
+ * @throws If the handle or the range is not valid, the range starts at or past
+ * the end of the file, or the host refuses.
+ *
+ * @example
+ * ```typescript
+ * const head = await readRange(record.attachment, 0, 1024, request.context)
+ * ```
+ */
+export declare function readRange(handle: DocumentHandle, offset: number, length: number, context: Context): Promise<Uint8Array>;

package/dist/storage.js

@@ -1,4 +1,16 @@
-import { execute as hostExecute } from './host';
+import { execute as hostExecute, executeBytes as hostExecuteBytes } from './host';
+/** The host action that answers a stored file's size. */
+const STAT = 'action:storage/stat';
+/** The host action that answers one range of a stored file as its bytes. */
+const READ = 'action:storage/read';
+/**
+ * The longest range the host answers one read with.
+ *
+ * `read` and `readRange` cover anything longer in ranges of this size, into one
+ * buffer, so it bounds what the host holds for one call rather than what an
+ * action can read.
+ */
+export const MAX_RANGE_BYTES = 16 * 1024 * 1024;
 /**
  * Uploads an in-memory binary buffer as a document to the platform's storage system.
  *
@@ -115,3 +127,142 @@ export async function uploadExternal(source, target, context) {
     }
     return response.data;
 }
+/**
+ * Returns how many bytes a stored file holds, from the store's own record of it
+ * rather than the handle's `size`.
+ *
+ * @param handle The document handle, exactly as a `:document` field holds it.
+ * @param context The execution context for the request.
+ * @returns A promise that resolves with the file's size in bytes.
+ * @throws If the handle does not name a stored file, or the host refuses.
+ *
+ * @example
+ * ```typescript
+ * const bytes = await size(record.attachment, request.context)
+ * ```
+ */
+export async function size(handle, context) {
+    checkHandle(handle);
+    const response = await hostExecute(STAT, { handle }, context);
+    if (!response.ok)
+        throw refused(STAT, response.error?.message);
+    const answered = response.data?.size;
+    if (typeof answered !== 'number' || !Number.isSafeInteger(answered) || answered < 0)
+        throw new Error(`${STAT} answered without a size: ${JSON.stringify(response.data ?? null)}`);
+    return answered;
+}
+/**
+ * Returns the whole of a stored file, as its bytes.
+ *
+ * The size is asked for first, and the file arrives in ranges of at most
+ * `MAX_RANGE_BYTES`, each handed over by the host as it is — no JSON and no
+ * base64. A file that fits one range arrives as one array holding exactly its
+ * bytes. A larger one is read into a single buffer allocated once at exactly
+ * the file's size, and is refused before any range is read when this action
+ * has no memory for it. A range answered short — a file that changed while it
+ * was read — is refused rather than handed over incomplete.
+ *
+ * Reading is for server actions; a browser action is refused.
+ *
+ * @param handle The document handle, exactly as a `:document` field holds it.
+ * @param context The execution context for the request.
+ * @returns A promise that resolves with the file's bytes.
+ * @throws If the handle does not name a stored file, the host refuses, or the
+ * file changed while it was read.
+ *
+ * @example
+ * ```typescript
+ * const bytes = await read(record.attachment, request.context)
+ * const text = new TextDecoder().decode(bytes)
+ * ```
+ */
+export async function read(handle, context) {
+    const total = await size(handle, context);
+    return total === 0 ? new Uint8Array(0) : readSpan(handle, 0, total, context);
+}
+/**
+ * Returns up to `length` bytes of a stored file, starting `offset` bytes in.
+ *
+ * The size is asked for first, so the range is held at what the file has past
+ * `offset`: one that runs past the end answers with exactly the bytes up to
+ * the end, and one that starts at or past the end is refused before any range
+ * is read. What is left is read as `read` reads a whole file — in ranges of at
+ * most `MAX_RANGE_BYTES`, into one buffer, each range answered in full or
+ * refused.
+ *
+ * Asking for the size first is also what makes a host that cannot read stored
+ * files refuse in its own words, before any range is asked of it.
+ *
+ * @param handle The document handle, exactly as a `:document` field holds it.
+ * @param offset How many bytes into the file the range starts, zero or more.
+ * @param length How many bytes to read, one or more.
+ * @param context The execution context for the request.
+ * @returns A promise that resolves with the range's bytes.
+ * @throws If the handle or the range is not valid, the range starts at or past
+ * the end of the file, or the host refuses.
+ *
+ * @example
+ * ```typescript
+ * const head = await readRange(record.attachment, 0, 1024, request.context)
+ * ```
+ */
+export async function readRange(handle, offset, length, context) {
+    checkHandle(handle);
+    if (!Number.isSafeInteger(offset) || offset < 0)
+        throw new Error('A range needs an offset that is a whole number of bytes, zero or more.');
+    if (!Number.isSafeInteger(length) || length < 1)
+        throw new Error('A range needs at least one byte. Pass a length of one or more, or ask size() how large the file is.');
+    const total = await size(handle, context);
+    if (offset >= total)
+        throw new Error(`The range starts at byte ${offset}, at or past the end of the file, which is ${total} bytes. Ask size() how large the file is, and start the range before its end.`);
+    return readSpan(handle, offset, Math.min(length, total - offset), context);
+}
+/**
+ * Exactly `length` bytes from `offset`, which the file's size says are there.
+ *
+ * One range is returned as the host handed it over. More are read into one
+ * buffer, allocated once at exactly `length` before any of them is asked for.
+ */
+async function readSpan(handle, offset, length, context) {
+    if (length <= MAX_RANGE_BYTES)
+        return readExactly(handle, offset, length, context);
+    const bytes = allocate(length);
+    for (let done = 0; done < length; done += MAX_RANGE_BYTES) {
+        const part = await readExactly(handle, offset + done, Math.min(MAX_RANGE_BYTES, length - done), context);
+        bytes.set(part, done);
+    }
+    return bytes;
+}
+/** One range, which must be answered in full. */
+async function readExactly(handle, offset, length, context) {
+    const response = await hostExecuteBytes(READ, { handle, length, offset }, context);
+    if (!response.ok)
+        throw new Error(response.error?.message ?? `${READ} failed: The host refused the call and gave no reason.`);
+    const part = response.data;
+    if (part.length !== length)
+        throw new Error(`The file answered ${part.length} bytes for the ${length} at offset ${offset}, so it is not the size it was when the read began. Read it again.`);
+    return part;
+}
+/** The error for a call the host refused in its envelope, naming the call. */
+function refused(actionName, message) {
+    if (message === undefined || message.trim() === '')
+        return new Error(`${actionName} failed: The host refused the call and gave no reason.`);
+    return new Error(`${actionName} failed: ${message}`);
+}
+/** A buffer of exactly `length` bytes, or a refusal saying there is no room. */
+function allocate(length) {
+    try {
+        return new Uint8Array(length);
+    }
+    catch {
+        throw new Error(`Reading ${length} bytes needs more memory than this action has. Raise the action's mem_limit, or read the file in parts with readRange.`);
+    }
+}
+/** Whether a handle carries what the host locates a stored file by. */
+function checkHandle(handle) {
+    for (const member of ['storage_path', 'filename', 'file_hash']) {
+        const value = handle?.[member];
+        if (typeof value !== 'string' || value.trim() === '')
+            throw new Error(`A document handle needs ${member}. Pass the handle exactly as the :document field holds it.`);
+    }
+}

package/dist/worker-override.js

@@ -56,6 +56,18 @@ export function execute(actionName, params, context) {
   })
 }
 
+/**
+ * A reply that is a run of bytes reaches only a server action: the browser
+ * runtime has no way to hand one over. Refused here, before anything is sent.
+ * @returns {Promise<import('./types').SimpleResponse<Uint8Array>>} A promise that rejects
+ */
+export function executeBytes(actionName) {
+  return Promise.reject(new Error(
+    `${actionName} answers with bytes, which only a server action can receive. `
+    + 'Set the action\'s execution environment to server.',
+  ))
+}
+
 /**
  * Worker-compatible fire-and-forget implementation.
  */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@simpleplatform/sdk",
-  "version": "2.0.0",
+  "version": "2.1.0",
   "description": "Simple Platform Typescript SDK",
   "license": "Apache-2.0",
   "homepage": "https://docs.simple.dev",
@@ -45,6 +45,10 @@
       "types": "./dist/security.d.ts",
       "default": "./dist/security.js"
     },
+    "./storage": {
+      "types": "./dist/storage.d.ts",
+      "default": "./dist/storage.js"
+    },
     "./host": {
       "types": "./dist/host.d.ts",
       "default": "./dist/host.js"