@firetail/finchly 0.0.10 → 0.0.11

package/CHANGELOG.md

@@ -4,6 +4,17 @@ All notable changes to `@firetail/finchly`. Versions follow semver.
 
 ## Unreleased
 
+## 0.0.11 - 2026-11-12
+
+- `blobs`: objects go straight to the object store and come straight from
+  it, at an address the platform signs for each read and write. An object
+  is no longer limited to 16 MiB. **Needs a platform that signs
+  addresses**; with one whose store signs none, objects pass through the
+  platform as before.
+- `blobs`: `presignGet(key)` and `presignPut(key, { size })` give an
+  address to hand on, for a browser to fetch or send one object.
+- `createBlobs` takes `fetch`, which is what reaches the object store.
+
 ## 0.0.10 - 2026-11-12
 
 - `createBlobs({ service })`: objects kept with the platform for each

package/README.md

@@ -278,7 +278,9 @@ other refusal is `secrets_unavailable`.
 
 A service whose manifest sets `permissions.blobs` keeps objects with the
 platform, separately for each tenant: receipts, exports, files. The service
-holds no credentials for the object store; the platform does.
+holds no credentials for the object store. For each read and write the
+platform signs an address for that one object, and the bytes go straight
+to the store or come straight from it.
 
 ```js
 import { createBlobs } from "@firetail/finchly";
@@ -300,7 +302,7 @@ await mine.delete(`receipts/${id}.pdf`);
 - A key is 1 to 512 letters, digits, dots, dashes and underscores, in
   segments divided by `/`. Do not use a key that is also the start of
   another followed by `/`, such as `a` and `a/b`.
-- An object is text or bytes, of at most 16 MiB.
+- An object is text or bytes, held in memory, of up to 5 GiB.
 - A tenant's objects are reached with that tenant's id and no other. Take
   the id from a verified identity, never from the request itself.
 - A listing is in key order. When `next` is not undefined there are more:
@@ -322,10 +324,34 @@ const written = await mine.putIfMatch("state.json", JSON.stringify(next), state.
 State that needs transactions or queries belongs in the service's
 database, not in an object.
 
+An address can be handed on, so that a file goes between a browser and the
+store without passing through the service:
+
+```js
+// To fetch one object with a plain GET.
+const url = await mine.presignGet(`receipts/${id}.pdf`, { expiresSeconds: 60 });
+
+// To send one object of a stated size: a PUT to `url` with exactly `headers`.
+const { url, headers } = await mine.presignPut(`uploads/${id}`, { size: file.size, contentType: file.type, expiresSeconds: 300 });
+```
+
+- An address is for that one object and that one use. One made to send
+  takes exactly that content type and that many bytes.
+- Whoever holds an address can use it until it runs out, with no sign-in:
+  1 to 3600 seconds, default 300. Ask for the shortest that will do, and do
+  not log one.
+- The same addresses serve to stream an object too large to hold in
+  memory.
+
 A manifest that does not ask for objects gets `blobs_not_granted`. Any
 other refusal, a deployment with no object store among them, is
 `blobs_unavailable`.
 
+A deployment whose store signs no addresses (a development store) passes
+objects through the platform instead: `get` and `put` work the same, up to
+16 MiB an object, and `presignGet` and `presignPut` reject with
+`blobs_unavailable`.
+
 ### The queue
 
 A message belongs to a tenant. The manifest lists the topics the service
@@ -410,7 +436,7 @@ not leak them.
 | `app` | Register with the platform, serve `/_platform/*`, renew keys, fetch settings | Self-registration and key renewal are done, through `service`. Serving `/_platform/*` and fetching settings are not |
 | `service` | Call other services through the gateway, as the service or for a user | Done, for built-in services and for apps |
 | `db` | PostgreSQL: queries, transactions, advisory locks, migrations | Done |
-| `blobs` | Objects, with conditional writes | Done. Objects over 16 MiB are not |
+| `blobs` | Objects, with conditional writes and addresses to hand on | Done |
 | `queue` | Publish, lease, ack, retry, dead-letter | Done |
 | `secrets` | Secrets, and encryption under the tenant's key | Done |
 | `llm` | Model calls through the platform | Planned |

package/dist/blobs.d.ts

@@ -26,6 +26,22 @@ export interface ListOptions {
     /** The most objects to list. 1 to 1000, default 100. */
     readonly limit?: number;
 }
+export interface AddressOptions {
+    /** How long the address lasts, in seconds. 1 to 3600, default 300. Ask for the shortest that will do. */
+    readonly expiresSeconds?: number;
+}
+export interface PutAddressOptions extends AddressOptions {
+    /** The length of what will be sent, in bytes. The address takes exactly that many. */
+    readonly size: number;
+    /** Kept with the object, and must be sent as given. Default application/octet-stream. */
+    readonly contentType?: string;
+}
+/** Where to send one object: a `PUT` to `url` with exactly these `headers`. */
+export interface PutAddress {
+    readonly url: string;
+    readonly method: "PUT";
+    readonly headers: Record<string, string>;
+}
 export interface BlobPage {
     /** In key order. */
     readonly objects: BlobInfo[];
@@ -37,7 +53,7 @@ export interface TenantBlobs {
     readonly tenantId: string;
     /** The object, or undefined if there is none by that key. */
     get(key: string): Promise<StoredBlob | undefined>;
-    /** Write an object, replacing any there was. At most 16 MiB. Resolves with its etag. */
+    /** Write an object, replacing any there was. Resolves with its etag. */
     put(key: string, data: string | Uint8Array, options?: PutOptions): Promise<string>;
     /**
      * Write an object only if there is none by that key. Resolves with its
@@ -55,6 +71,18 @@ export interface TenantBlobs {
     delete(key: string): Promise<void>;
     /** The service's objects in this tenant, a page at a time. */
     list(options?: ListOptions): Promise<BlobPage>;
+    /**
+     * An address the object can be fetched from with a plain GET, by whoever
+     * holds it, until it runs out: to hand to a browser, or to stream a
+     * large object. It is for this one object. Do not log it.
+     */
+    presignGet(key: string, options?: AddressOptions): Promise<string>;
+    /**
+     * An address one object of a stated size can be sent to, by whoever
+     * holds it, until it runs out: to let a browser send a file without it
+     * passing through the service. Do not log it.
+     */
+    presignPut(key: string, options: PutAddressOptions): Promise<PutAddress>;
 }
 export interface Blobs {
     /**
@@ -65,7 +93,9 @@ export interface Blobs {
     forTenant(tenantId: string): TenantBlobs;
 }
 export interface BlobsOptions {
-    /** The service's client. Every call goes through it. */
+    /** The service's client. Every call to the platform goes through it. */
     readonly service: Pick<ServiceClient, "call">;
+    /** What reaches the object store. Default: the global `fetch`. */
+    readonly fetch?: typeof fetch;
 }
 export declare function createBlobs(options: BlobsOptions): Blobs;

package/dist/blobs.js

@@ -4,14 +4,20 @@
 // The manifest must set permissions.blobs. Everything here is for one
 // tenant: the handle that reads and writes is made with `forTenant`. The
 // service holds no credentials for the object store; the platform does.
+//
+// To read or write, the platform is asked for an address signed for that
+// one object, and the bytes go straight to the store or come straight from
+// it. Where the deployment's store signs no addresses (a development
+// store), they pass through the platform instead, at most 16 MiB an object.
 import { FinchlyError } from "./errors.js";
 const TENANT_ID = /^t_[a-z2-7]{16}$/;
 const KEY = /^[A-Za-z0-9._-]+(\/[A-Za-z0-9._-]+)*$/;
 const PREFIX = /^[A-Za-z0-9._/-]*$/;
 const MAX_KEY_LENGTH = 512;
-/** The largest object the platform takes. */
-const MAX_BYTES = 16 * 1024 * 1024;
+/** The largest object that can pass through the platform, where the store signs no addresses. */
+const MAX_THROUGH_PLATFORM = 16 * 1024 * 1024;
 const BASE = "/api/apps/self/blobs";
+const ADDRESSES = "/api/apps/self/blob-urls";
 const unavailable = (message) => new FinchlyError("blobs_unavailable", message);
 function isKey(key) {
     return typeof key === "string" && key.length <= MAX_KEY_LENGTH && KEY.test(key) && !key.split("/").some((segment) => segment === "." || segment === "..");
@@ -35,11 +41,57 @@ async function failure(response, what) {
 }
 export function createBlobs(options) {
     const { service } = options;
+    const doFetch = options.fetch ?? fetch;
+    // Whether the deployment's store signs addresses. Not known until asked;
+    // once it has said no, it is not asked again.
+    let signsAddresses = true;
     return {
         forTenant(tenantId) {
             if (typeof tenantId !== "string" || !TENANT_ID.test(tenantId)) {
                 throw unavailable("forTenant needs a tenant id, as in caller.tenantId");
             }
+            /**
+             * Ask the platform for an address for one object. "none" if the store
+             * signs none; "unmet" if it is to write on a condition that already
+             * cannot hold.
+             */
+            async function address(asked) {
+                const response = await service.call("core", ADDRESSES, {
+                    tenantId,
+                    method: "POST",
+                    headers: { "content-type": "application/json" },
+                    body: JSON.stringify(asked),
+                });
+                if (response.status === 501) {
+                    await response.body?.cancel();
+                    signsAddresses = false;
+                    return "none";
+                }
+                if (response.status === 412) {
+                    await response.body?.cancel();
+                    return "unmet";
+                }
+                if (response.status !== 200)
+                    throw await failure(response, "give an address for the object");
+                const { url, headers } = (await response.json());
+                return { url, headers };
+            }
+            /** Make a request to the store, at an address. The address itself is never part of an error. */
+            async function atStore(to, init) {
+                try {
+                    return await doFetch(to.url, { ...init, headers: to.headers });
+                }
+                catch (err) {
+                    const cause = err.cause;
+                    throw new FinchlyError("blobs_unavailable", "Cannot reach the object store", [
+                        typeof cause?.code === "string" ? cause.code : "the request failed",
+                    ]);
+                }
+            }
+            const refusedByStore = async (response, what) => {
+                await response.body?.cancel();
+                return new FinchlyError("blobs_unavailable", `The object store did not ${what}`, [`it answered ${response.status}`]);
+            };
             /** Write, with a condition or none. Undefined if the condition did not hold. */
             async function write(key, data, condition, putOptions = {}) {
                 checkKey(key);
@@ -47,15 +99,39 @@ export function createBlobs(options) {
                 if (!text && !(data instanceof Uint8Array))
                     throw unavailable("An object is text or bytes");
                 const bytes = text ? Buffer.from(data, "utf8") : data;
-                if (bytes.byteLength > MAX_BYTES)
-                    throw unavailable("An object is at most 16 MiB");
                 const contentType = putOptions.contentType ?? (text ? "text/plain; charset=utf-8" : "application/octet-stream");
                 if (typeof contentType !== "string" || !/^[\x20-\x7e]{1,200}$/.test(contentType))
                     throw unavailable("The content type is not one");
+                if (signsAddresses) {
+                    const to = await address({ key, method: "PUT", contentType, size: bytes.byteLength, ...condition });
+                    if (to === "unmet")
+                        return undefined;
+                    if (to !== "none") {
+                        const response = await atStore(to, { method: "PUT", body: bytes });
+                        const conditional = condition.ifAbsent === true || condition.ifMatch !== undefined;
+                        // 412: the condition did not hold. 409: another write to the same key was under way.
+                        if (conditional && (response.status === 412 || response.status === 409)) {
+                            await response.body?.cancel();
+                            return undefined;
+                        }
+                        if (response.status !== 200)
+                            throw await refusedByStore(response, "take the object");
+                        await response.body?.cancel();
+                        return response.headers.get("etag") ?? "";
+                    }
+                }
+                // Through the platform: the store signs no addresses.
+                if (bytes.byteLength > MAX_THROUGH_PLATFORM) {
+                    throw unavailable("This deployment's object store takes objects through the platform only, at most 16 MiB each");
+                }
                 const response = await service.call("core", `${BASE}/${key}`, {
                     tenantId,
                     method: "PUT",
-                    headers: { "content-type": contentType, ...condition },
+                    headers: {
+                        "content-type": contentType,
+                        ...(condition.ifAbsent ? { "if-none-match": "*" } : {}),
+                        ...(condition.ifMatch !== undefined ? { "if-match": condition.ifMatch } : {}),
+                    },
                     body: bytes,
                 });
                 if (response.status === 412) {
@@ -66,10 +142,43 @@ export function createBlobs(options) {
                     throw await failure(response, "keep the object");
                 return (await response.json()).etag;
             }
+            const read = async (response) => ({
+                data: new Uint8Array(await response.arrayBuffer()),
+                etag: response.headers.get("etag") ?? "",
+                contentType: response.headers.get("content-type") ?? "application/octet-stream",
+            });
+            const seconds = (addressOptions) => {
+                const expiresSeconds = addressOptions?.expiresSeconds;
+                if (expiresSeconds === undefined)
+                    return {};
+                if (!Number.isInteger(expiresSeconds) || expiresSeconds < 1 || expiresSeconds > 3600)
+                    throw unavailable("expiresSeconds is 1 to 3600");
+                return { expiresSeconds };
+            };
+            /** An address to hand on. There is none where the store signs none. */
+            async function handOn(asked) {
+                const to = await address(asked);
+                if (to === "none" || to === "unmet")
+                    throw unavailable("This deployment's object store gives no addresses");
+                return to;
+            }
             return {
                 tenantId,
                 async get(key) {
                     checkKey(key);
+                    if (signsAddresses) {
+                        const from = await address({ key, method: "GET" });
+                        if (from !== "none" && from !== "unmet") {
+                            const response = await atStore(from, {});
+                            if (response.status === 404) {
+                                await response.body?.cancel();
+                                return undefined;
+                            }
+                            if (response.status !== 200)
+                                throw await refusedByStore(response, "give the object");
+                            return read(response);
+                        }
+                    }
                     const response = await service.call("core", `${BASE}/${key}`, { tenantId });
                     if (response.status === 404) {
                         await response.body?.cancel();
@@ -77,24 +186,20 @@ export function createBlobs(options) {
                     }
                     if (response.status !== 200)
                         throw await failure(response, "give the object");
-                    return {
-                        data: new Uint8Array(await response.arrayBuffer()),
-                        etag: response.headers.get("etag") ?? "",
-                        contentType: response.headers.get("content-type") ?? "application/octet-stream",
-                    };
+                    return read(response);
                 },
                 async put(key, data, putOptions) {
                     // With no condition there is nothing not to hold.
                     return (await write(key, data, {}, putOptions));
                 },
                 putIfAbsent(key, data, putOptions) {
-                    return write(key, data, { "if-none-match": "*" }, putOptions);
+                    return write(key, data, { ifAbsent: true }, putOptions);
                 },
                 async putIfMatch(key, data, etag, putOptions) {
                     if (typeof etag !== "string" || etag === "" || etag.length > 200) {
                         throw unavailable("putIfMatch needs the etag the object was read with");
                     }
-                    return write(key, data, { "if-match": etag }, putOptions);
+                    return write(key, data, { ifMatch: etag }, putOptions);
                 },
                 async delete(key) {
                     checkKey(key);
@@ -128,6 +233,20 @@ export function createBlobs(options) {
                         next: page.next ?? undefined,
                     };
                 },
+                async presignGet(key, addressOptions) {
+                    checkKey(key);
+                    return (await handOn({ key, method: "GET", ...seconds(addressOptions) })).url;
+                },
+                async presignPut(key, addressOptions) {
+                    checkKey(key);
+                    const { size, contentType = "application/octet-stream" } = addressOptions ?? {};
+                    if (!Number.isInteger(size) || size < 0)
+                        throw unavailable("presignPut needs the size of what will be sent, in bytes");
+                    if (typeof contentType !== "string" || !/^[\x20-\x7e]{1,200}$/.test(contentType))
+                        throw unavailable("The content type is not one");
+                    const to = await handOn({ key, method: "PUT", contentType, size, ...seconds(addressOptions) });
+                    return { url: to.url, method: "PUT", headers: to.headers };
+                },
             };
         },
     };

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 export { createBlobs } from "./blobs.js";
-export type { BlobInfo, BlobPage, Blobs, BlobsOptions, ListOptions, PutOptions, StoredBlob, TenantBlobs } from "./blobs.js";
+export type { AddressOptions, BlobInfo, BlobPage, Blobs, BlobsOptions, ListOptions, PutAddress, PutAddressOptions, PutOptions, StoredBlob, TenantBlobs, } from "./blobs.js";
 export { DEFAULT_MANIFEST_PATH, loadConfig } from "./config.js";
 export type { PlatformConfig } from "./config.js";
 export { connectDatabase, fetchSettings } from "./db.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@firetail/finchly",
-  "version": "0.0.10",
+  "version": "0.0.11",
   "description": "Node SDK for the Finchly platform",
   "type": "module",
   "main": "./dist/index.js",