@thomasfosterau/pulpit 0.0.0-stage → 0.1.0

package/dist/blobs.d.ts

@@ -0,0 +1,249 @@
+/**
+ * **File and media leaves** — the blob-store seam a file leaf's bytes live
+ * behind, the field spread a file version carries, the commit-ordered byte
+ * write, and the usage index as an edge family.
+ *
+ * The behavioural spec is gardeneria's `apps/api/src/operations/media.ts`
+ * (bytes written only after the transaction commits) and `apps/api/src/files.ts`
+ * (the content hash), and website's `apps/api/src/operations/file-chain.ts`.
+ *
+ * ## The model (owner decisions on pulpit#55)
+ *
+ * - **Bytes are keyed by their content hash** ({@link blobKey}), so a
+ *   version's bytes are immutable: new bytes are a new hash and a new
+ *   version, and `restoreVersion` restores the reference to the old bytes,
+ *   which are still there. Equal bytes are stored once.
+ * - **Bytes are written after the chain commits.** {@link defineFileWrites}
+ *   appends the version first, marked `bytesPending: true` unless the store
+ *   already holds the bytes, puts the bytes once the transaction has
+ *   returned, and then appends `bytesPending: false`. A byte write that
+ *   fails leaves the node visibly incomplete: `bytesPending` stays `true`
+ *   and {@link fileUrl} gives no URL, so no reader is ever pointed at
+ *   missing bytes. `confirmBytes` finishes it later, once the bytes are
+ *   there.
+ * - **Nothing garbage-collects bytes.** They stay for as long as any
+ *   version references them; purge (pulpit#58) is the only removal path,
+ *   which is what {@link BlobStore.delete} is for.
+ * - **"Where is this file used" is an edge family** ({@link fileUsageEnds}),
+ *   so the endpoint-visibility gate (`EDGE-001`) applies: a "used by" list
+ *   never reveals content the viewer can't see. Maintaining those edges is
+ *   the referencing leaf's job (or an after hook's).
+ *
+ * The adapters (R2, S3), image transforms, EXIF extraction and video
+ * streaming are the application's.
+ *
+ * @copyright Thomas Foster
+ * @module pulpit/blobs
+ * @since 0.1.0
+ */
+import { Resource } from "@thomasfosterau/effect-jsonapi";
+import * as Effect from "effect/Effect";
+import * as Option from "effect/Option";
+import * as Schema from "effect/Schema";
+import type { EdgeEnd, EdgeEnds } from "./edges.ts";
+import type { Forbidden, SubtypeOps, Unauthorized, WriteRejected } from "./subtype.ts";
+import type { ChainState, ChainWrite, NodeAlreadyExists, NodeNotFound, Precondition, StaleVersion, VersionConflict } from "./version-chain.ts";
+/**
+ * A file's content hash: the SHA-256 digest of its bytes as 64 lowercase
+ * hexadecimal characters ({@link sha256Hex}).
+ *
+ * @since 0.1.0
+ */
+export declare const ContentHash: Schema.String;
+/**
+ * The {@link ContentHash} string.
+ *
+ * @since 0.1.0
+ */
+export type ContentHash = typeof ContentHash.Type;
+/**
+ * The SHA-256 content hash of `bytes`, through the platform's Web Crypto
+ * (`globalThis.crypto.subtle`, in browsers, Node 22+ and Workers alike).
+ *
+ * @example
+ * ```ts
+ * import { strictEqual } from "node:assert";
+ * import * as Effect from "effect/Effect";
+ * import { sha256Hex } from "@thomasfosterau/pulpit/blobs";
+ *
+ * strictEqual(
+ *   await Effect.runPromise(sha256Hex(new TextEncoder().encode("abc"))),
+ *   "ba7816bf8f01cfea414140de5dae2223b00361a396177a9cb410ff61f20015ad",
+ * );
+ * ```
+ *
+ * @since 0.1.0
+ */
+export declare const sha256Hex: (bytes: Uint8Array) => Effect.Effect<ContentHash>;
+/**
+ * The blob-store key for a content hash: `sha256/<hash>`. The key is
+ * derived from the bytes alone, never from a node id, so a node's history
+ * can point at every set of bytes it has ever had.
+ *
+ * @since 0.1.0
+ */
+export declare const blobKey: (hash: ContentHash) => string;
+/**
+ * What the blob store knows of one stored object.
+ *
+ * @since 0.1.0
+ */
+export interface BlobHead {
+    readonly byteSize: number;
+    readonly mediaType: string;
+}
+/**
+ * The byte store an application supplies (R2, S3, a local directory). It
+ * applies no policy and fails only with its `E`. Keys come from
+ * {@link blobKey}; see the package README → Seams for the contract.
+ *
+ * @since 0.1.0
+ */
+export interface BlobStore<E, R> {
+    /** Store `bytes` at `key`. Idempotent: the same key always holds the same bytes. */
+    readonly put: (key: string, bytes: Uint8Array, head: BlobHead) => Effect.Effect<void, E, R>;
+    /** The bytes at `key`, or none. */
+    readonly get: (key: string) => Effect.Effect<Option.Option<Uint8Array>, E, R>;
+    /** The object's size and media type, or none when nothing is stored at `key`. */
+    readonly head: (key: string) => Effect.Effect<Option.Option<BlobHead>, E, R>;
+    /** Remove the object at `key`. Purge's alone (pulpit#58): nothing else deletes bytes. */
+    readonly delete: (key: string) => Effect.Effect<void, E, R>;
+    /** The URL a reader fetches `key` from, when the store serves one. */
+    readonly publicUrl: (key: string) => Option.Option<string>;
+    /** A signed URL a client may upload `key`'s bytes to directly, when the store offers one. */
+    readonly signedUploadUrl: Option.Option<(key: string, head: BlobHead) => Effect.Effect<string, E, R>>;
+}
+/**
+ * The attributes every file version carries, all server-computed from the
+ * upload and present on the resource only (`readOnlyAttribute`): the
+ * `contentHash` its bytes are stored under, their `byteSize` and
+ * `mediaType`, the original `filename`, and `bytesPending`, `true` while the
+ * bytes are not yet confirmed in the blob store. Spread into a file leaf's
+ * `Resource.make({ attributes })`.
+ *
+ * @since 0.1.0
+ */
+export declare const fileResourceFields: {
+    readonly contentHash: Resource.ReadOnlyAttribute<Schema.String>;
+    readonly byteSize: Resource.ReadOnlyAttribute<Schema.Finite>;
+    readonly mediaType: Resource.ReadOnlyAttribute<Schema.String>;
+    readonly filename: Resource.ReadOnlyAttribute<Schema.String>;
+    readonly bytesPending: Resource.ReadOnlyAttribute<Schema.Boolean>;
+};
+/**
+ * A file version's columns, as {@link defineFileWrites} writes them.
+ *
+ * @since 0.1.0
+ */
+export interface FileColumns {
+    readonly contentHash: ContentHash;
+    readonly byteSize: number;
+    readonly mediaType: string;
+    readonly filename: string;
+    readonly bytesPending: boolean;
+}
+/**
+ * The URL a file version's bytes are read from: none while `bytesPending`
+ * (anything but an explicit `false`), and none when the store serves no
+ * URL, so no reader is pointed at bytes that may not be there.
+ *
+ * @since 0.1.0
+ */
+export declare const fileUrl: <E, R>(file: {
+    readonly contentHash: ContentHash;
+    readonly bytesPending: boolean;
+}, blobs: Pick<BlobStore<E, R>, "publicUrl">) => Option.Option<string>;
+/**
+ * An upload: the bytes and what the client said they are.
+ *
+ * @since 0.1.0
+ */
+export interface Upload {
+    readonly bytes: Uint8Array;
+    readonly mediaType: string;
+    readonly filename: string;
+}
+/**
+ * What a file write reports: the version it landed at, its content hash,
+ * and whether its bytes are still pending (the post-commit byte write
+ * failed, or its confirmation did).
+ *
+ * @since 0.1.0
+ */
+export interface FileWrite extends ChainWrite {
+    readonly contentHash: ContentHash;
+    readonly bytesPending: boolean;
+}
+type WriteFailure = Unauthorized | Forbidden | WriteRejected | VersionConflict;
+/**
+ * The operations {@link defineFileWrites} produces.
+ *
+ * @since 0.1.0
+ */
+export interface FileWriteOps<E, R> {
+    /**
+     * Create a file node from an upload, with the leaf's other columns in
+     * `state`. Fails as the leaf's `create` does; a failure to store the
+     * bytes after the commit does not fail it (the node is left
+     * `bytesPending`).
+     */
+    readonly create: (input: {
+        readonly id: Option.Option<string>;
+        readonly state: ChainState;
+        readonly upload: Upload;
+    }) => Effect.Effect<FileWrite, WriteFailure | NodeAlreadyExists | E, R>;
+    /**
+     * Replace a file node's bytes with a new version. Fails as the leaf's
+     * `update` does (`StaleVersion` against `expectedVersion`, `NodeNotFound`
+     * for a missing or tombstoned node).
+     */
+    readonly replace: (input: {
+        readonly id: string;
+        readonly upload: Upload;
+    } & Precondition) => Effect.Effect<FileWrite, WriteFailure | NodeNotFound | StaleVersion | E, R>;
+    /**
+     * Finish a pending version (`version`, whose bytes `contentHash` names,
+     * as a {@link FileWrite} reports them): when the store now holds those
+     * bytes, append `bytesPending: false` over exactly that version and
+     * report `false`; otherwise write nothing and report `true`. Gated as the
+     * leaf's `update` is; `StaleVersion` when the node has moved past
+     * `version` (its head names other bytes).
+     */
+    readonly confirmBytes: (input: {
+        readonly id: string;
+        readonly version: bigint;
+        readonly contentHash: ContentHash;
+    }) => Effect.Effect<boolean, WriteFailure | NodeNotFound | StaleVersion | E, R>;
+}
+/**
+ * Bind a file leaf's commit-ordered writes: the version is appended (in
+ * `transact`, the caller's write boundary) before any byte is written, and
+ * the bytes go to the blob store only once it has returned. Each version
+ * write goes through the leaf's own operations, so their gates,
+ * preconditions and before hooks apply; the cache write-through and after
+ * hooks are `subtypeHandlers`', which an application that caches the leaf
+ * runs itself.
+ *
+ * @since 0.1.0
+ */
+export declare const defineFileWrites: <Resource, E, R>(definition: {
+    readonly leaf: SubtypeOps<Resource, E, R>;
+    readonly blobs: BlobStore<E, R>;
+    readonly transact: <A, E2>(effect: Effect.Effect<A, E2, R>) => Effect.Effect<A, E2, R>;
+}) => FileWriteOps<E, R>;
+/**
+ * The ends of a file-usage edge family: `user` (the content node that uses
+ * the file) and `file` (the file node), each declared with its own leaf's
+ * access and view, for `./edges`' `defineEdgeOps`. The family's edge table
+ * keys `(user_id, file_id)` uniquely, so a re-asserted use is a no-op under
+ * `onConflict: "ignore"`. A "used by" list is then an edge list at the file
+ * end, and `EDGE-001` hides every use whose content the viewer can't read.
+ *
+ * @since 0.1.0
+ */
+export declare const fileUsageEnds: <E, R>(ends: {
+    readonly user: Omit<EdgeEnd<E, R>, "column">;
+    readonly file: Omit<EdgeEnd<E, R>, "column">;
+}) => EdgeEnds<E, R>;
+export {};
+//# sourceMappingURL=blobs.d.ts.map

package/dist/blobs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"blobs.d.ts","sourceRoot":"","sources":["../src/blobs.ts"],"names":[],"mappings":"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"}

package/dist/blobs.js

@@ -0,0 +1,193 @@
+/**
+ * **File and media leaves** — the blob-store seam a file leaf's bytes live
+ * behind, the field spread a file version carries, the commit-ordered byte
+ * write, and the usage index as an edge family.
+ *
+ * The behavioural spec is gardeneria's `apps/api/src/operations/media.ts`
+ * (bytes written only after the transaction commits) and `apps/api/src/files.ts`
+ * (the content hash), and website's `apps/api/src/operations/file-chain.ts`.
+ *
+ * ## The model (owner decisions on pulpit#55)
+ *
+ * - **Bytes are keyed by their content hash** ({@link blobKey}), so a
+ *   version's bytes are immutable: new bytes are a new hash and a new
+ *   version, and `restoreVersion` restores the reference to the old bytes,
+ *   which are still there. Equal bytes are stored once.
+ * - **Bytes are written after the chain commits.** {@link defineFileWrites}
+ *   appends the version first, marked `bytesPending: true` unless the store
+ *   already holds the bytes, puts the bytes once the transaction has
+ *   returned, and then appends `bytesPending: false`. A byte write that
+ *   fails leaves the node visibly incomplete: `bytesPending` stays `true`
+ *   and {@link fileUrl} gives no URL, so no reader is ever pointed at
+ *   missing bytes. `confirmBytes` finishes it later, once the bytes are
+ *   there.
+ * - **Nothing garbage-collects bytes.** They stay for as long as any
+ *   version references them; purge (pulpit#58) is the only removal path,
+ *   which is what {@link BlobStore.delete} is for.
+ * - **"Where is this file used" is an edge family** ({@link fileUsageEnds}),
+ *   so the endpoint-visibility gate (`EDGE-001`) applies: a "used by" list
+ *   never reveals content the viewer can't see. Maintaining those edges is
+ *   the referencing leaf's job (or an after hook's).
+ *
+ * The adapters (R2, S3), image transforms, EXIF extraction and video
+ * streaming are the application's.
+ *
+ * @copyright Thomas Foster
+ * @module pulpit/blobs
+ * @since 0.1.0
+ */
+import { Resource } from "@thomasfosterau/effect-jsonapi";
+import * as Arr from "effect/Array";
+import * as Effect from "effect/Effect";
+import * as Exit from "effect/Exit";
+import * as Option from "effect/Option";
+import * as Schema from "effect/Schema";
+// ── Vocabulary ────────────────────────────────────────────────────────
+/**
+ * A file's content hash: the SHA-256 digest of its bytes as 64 lowercase
+ * hexadecimal characters ({@link sha256Hex}).
+ *
+ * @since 0.1.0
+ */
+export const ContentHash = Schema.String.check(Schema.isPattern(/^[0-9a-f]{64}$/, {
+    description: "a SHA-256 content hash as 64 lowercase hexadecimal characters",
+}));
+/**
+ * The SHA-256 content hash of `bytes`, through the platform's Web Crypto
+ * (`globalThis.crypto.subtle`, in browsers, Node 22+ and Workers alike).
+ *
+ * @example
+ * ```ts
+ * import { strictEqual } from "node:assert";
+ * import * as Effect from "effect/Effect";
+ * import { sha256Hex } from "@thomasfosterau/pulpit/blobs";
+ *
+ * strictEqual(
+ *   await Effect.runPromise(sha256Hex(new TextEncoder().encode("abc"))),
+ *   "ba7816bf8f01cfea414140de5dae2223b00361a396177a9cb410ff61f20015ad",
+ * );
+ * ```
+ *
+ * @since 0.1.0
+ */
+export const sha256Hex = (bytes) => Effect.tryPromise(() => globalThis.crypto.subtle.digest("SHA-256", Uint8Array.from(bytes))).pipe(
+// Web Crypto's SHA-256 over bytes has no failure a caller could act on.
+Effect.orDie, Effect.map((digest) => Arr.map(Arr.fromIterable(new Uint8Array(digest)), (byte) => byte.toString(16).padStart(2, "0")).join("")));
+/**
+ * The blob-store key for a content hash: `sha256/<hash>`. The key is
+ * derived from the bytes alone, never from a node id, so a node's history
+ * can point at every set of bytes it has ever had.
+ *
+ * @since 0.1.0
+ */
+export const blobKey = (hash) => `sha256/${hash}`;
+// ── The field spread ──────────────────────────────────────────────────
+/**
+ * The attributes every file version carries, all server-computed from the
+ * upload and present on the resource only (`readOnlyAttribute`): the
+ * `contentHash` its bytes are stored under, their `byteSize` and
+ * `mediaType`, the original `filename`, and `bytesPending`, `true` while the
+ * bytes are not yet confirmed in the blob store. Spread into a file leaf's
+ * `Resource.make({ attributes })`.
+ *
+ * @since 0.1.0
+ */
+export const fileResourceFields = {
+    contentHash: Resource.readOnlyAttribute(ContentHash),
+    byteSize: Resource.readOnlyAttribute(Schema.Finite),
+    mediaType: Resource.readOnlyAttribute(Schema.String),
+    filename: Resource.readOnlyAttribute(Schema.String),
+    bytesPending: Resource.readOnlyAttribute(Schema.Boolean),
+};
+/**
+ * The URL a file version's bytes are read from: none while `bytesPending`
+ * (anything but an explicit `false`), and none when the store serves no
+ * URL, so no reader is pointed at bytes that may not be there.
+ *
+ * @since 0.1.0
+ */
+export const fileUrl = (file, blobs) => !file.bytesPending ? blobs.publicUrl(blobKey(file.contentHash)) : Option.none();
+/**
+ * Bind a file leaf's commit-ordered writes: the version is appended (in
+ * `transact`, the caller's write boundary) before any byte is written, and
+ * the bytes go to the blob store only once it has returned. Each version
+ * write goes through the leaf's own operations, so their gates,
+ * preconditions and before hooks apply; the cache write-through and after
+ * hooks are `subtypeHandlers`', which an application that caches the leaf
+ * runs itself.
+ *
+ * @since 0.1.0
+ */
+export const defineFileWrites = (definition) => {
+    const { leaf, blobs, transact } = definition;
+    /** The upload's columns, pending unless the store already holds its bytes. */
+    const columnsOf = (upload) => Effect.gen(function* () {
+        const contentHash = yield* sha256Hex(upload.bytes);
+        const stored = yield* blobs.head(blobKey(contentHash));
+        const columns = {
+            contentHash,
+            byteSize: upload.bytes.byteLength,
+            mediaType: upload.mediaType,
+            filename: upload.filename,
+            bytesPending: Option.isNone(stored),
+        };
+        return columns;
+    });
+    /**
+     * `bytesPending: false`, appended in its own transaction over exactly the
+     * pending version: if another write has landed since, it names other
+     * bytes, so the confirmation fails `StaleVersion` and confirms nothing.
+     */
+    const confirm = (id, pending) => transact(leaf.update({ id, patch: { bytesPending: false }, expectedVersion: pending }));
+    /**
+     * After the commit: put the bytes and confirm them. A failure of either
+     * leaves the node pending, never failing the write that committed.
+     */
+    const afterCommit = (written, columns, upload) => Effect.gen(function* () {
+        if (!columns.bytesPending) {
+            return { ...written, contentHash: columns.contentHash, bytesPending: false };
+        }
+        const confirmed = yield* Effect.exit(Effect.andThen(blobs.put(blobKey(columns.contentHash), upload.bytes, {
+            byteSize: columns.byteSize,
+            mediaType: columns.mediaType,
+        }), confirm(written.id, written.version)));
+        if (Exit.isFailure(confirmed)) {
+            yield* Effect.logWarning(`${leaf.type} ${written.id}: bytes left pending`, confirmed.cause);
+            return { ...written, contentHash: columns.contentHash, bytesPending: true };
+        }
+        return { ...confirmed.value, contentHash: columns.contentHash, bytesPending: false };
+    });
+    const create = Effect.fn(`${leaf.type}.files.create`)(function* (input) {
+        const columns = yield* columnsOf(input.upload);
+        const written = yield* transact(leaf.create({ id: input.id, state: { ...input.state, ...columns } }));
+        return yield* afterCommit(written, columns, input.upload);
+    });
+    const replace = Effect.fn(`${leaf.type}.files.replace`)(function* (input) {
+        const columns = yield* columnsOf(input.upload);
+        const written = yield* transact(leaf.update({ id: input.id, patch: { ...columns }, expectedVersion: input.expectedVersion }));
+        return yield* afterCommit(written, columns, input.upload);
+    });
+    const confirmBytes = Effect.fn(`${leaf.type}.files.confirmBytes`)(function* (input) {
+        if (Option.isNone(yield* blobs.head(blobKey(input.contentHash))))
+            return true;
+        yield* confirm(input.id, input.version);
+        return false;
+    });
+    return { create, replace, confirmBytes };
+};
+// ── The usage index ───────────────────────────────────────────────────
+/**
+ * The ends of a file-usage edge family: `user` (the content node that uses
+ * the file) and `file` (the file node), each declared with its own leaf's
+ * access and view, for `./edges`' `defineEdgeOps`. The family's edge table
+ * keys `(user_id, file_id)` uniquely, so a re-asserted use is a no-op under
+ * `onConflict: "ignore"`. A "used by" list is then an edge list at the file
+ * end, and `EDGE-001` hides every use whose content the viewer can't read.
+ *
+ * @since 0.1.0
+ */
+export const fileUsageEnds = (ends) => ({
+    user: { ...ends.user, column: "userId" },
+    file: { ...ends.file, column: "fileId" },
+});
+//# sourceMappingURL=blobs.js.map

package/dist/blobs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"blobs.js","sourceRoot":"","sources":["../src/blobs.ts"],"names":[],"mappings":"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"}