sailfork / t3code-github / .repos/ alchemy-effect/ packages/ git/ src/ BlobStore.ts

/**
 * `Git.BlobStore` — the swappable bulk-byte store (RFC "Git Building
 * Blocks" §3.1).
 *
 * Immutable, content-addressed bulk bytes: compacted packs, clone
 * bundles, oversize loose objects, and spilled push bodies. The contract
 * is everything the pack plane needs and nothing more — ranged reads,
 * whole-object writes with a known length, multipart writes of unknown
 * length, delete, and prefix listing (GC only, never on a serving path).
 *
 * Implementations shipped:
 *
 * - `Git.BlobStoreR2` — Cloudflare R2 over the existing
 *   `ReadWriteBucket` capability (the default).
 * - `Git.BlobStoreS3` — AWS S3 over the S3 object bindings.
 *
 * Multipart rules are the R2/S3 intersection: uniform part sizes
 * (≥ 5 MiB) except the last part.
 *
 * ### Providing the store
 * **Example:** R2 (the default)
 * ```typescript
 * const GitLive = Git.ApiLive.pipe(
 *   Layer.provide(Git.ApiHandlersLive),
 *   Layer.provide(Git.BlobStoreR2(MyBucket)),
 *   // ...
 * );
 *
 * // The Worker picks the ReadWriteBucket implementation.
 * export default class GitHost extends Cloudflare.Worker<GitHost>()(
 *   "GitHost",
 *   { main: import.meta.url, ...Git.GIT_WORKER_OPTIONS },
 *   Effect.gen(function* () {
 *     return { fetch: yield* HttpRouter.toHttpEffect(GitLive) };
 *   }).pipe(Effect.provide(Cloudflare.R2.ReadWriteBucketBinding)),
 * ) {}
 * ```
 */
import type { RuntimeContext } from "alchemy/RuntimeContext";
import * as Context from "effect/Context";
import * as Data from "effect/Data";
import * as Effect from "effect/Effect";
import * as Stream from "effect/Stream";

/** Failure of a {@link BlobStore} operation. */
export class BlobStoreError extends Data.TaggedError("BlobStoreError")<{
  readonly reason: string;
}> {}

/** A read blob: size plus the bytes as a one-shot buffer or a stream. */
export interface BlobBody {
  readonly size: number;
  readonly bytes: Effect.Effect<Uint8Array, BlobStoreError>;
  readonly stream: Stream.Stream<Uint8Array, BlobStoreError>;
  /**
   * The store's native body stream when it has one, for serving paths
   * that pipe bytes to the client with no per-chunk Effect work (DESIGN
   * §22). Consume either this or `stream`, never both.
   */
  readonly readable?: ReadableStream<Uint8Array> | undefined;
}

/** One uploaded part of a multipart write, as the store identifies it. */
export interface UploadedPart {
  readonly partNumber: number;
  readonly etag: string;
}

/**
 * An in-flight multipart write. Parts must be uniform in size (≥ 5 MiB)
 * except the last — the R2/S3 intersection. Parts may be uploaded from
 * ANY isolate that knows the key and `uploadId` (`BlobStoreShape.uploadPart`
 * — the push pipeline's hasher isolates do, DESIGN §22.10); the creator
 * completes with the collected parts, in any order.
 */
export interface BlobMultipart {
  readonly uploadId: string;
  readonly uploadPart: (
    partNumber: number,
    part: Uint8Array,
  ) => Effect.Effect<UploadedPart, BlobStoreError>;
  readonly complete: (parts: ReadonlyArray<UploadedPart>) => Effect.Effect<void, BlobStoreError>;
  readonly abort: Effect.Effect<void, BlobStoreError>;
}

/** Sorts parts by number: stores validate the uniform-part rule against the list as given. */
export const orderedParts = (parts: ReadonlyArray<UploadedPart>): Array<UploadedPart> =>
  [...parts].sort((a, b) => a.partNumber - b.partNumber);

/** One listed blob (GC/purge walks). */
export interface BlobMeta {
  readonly key: string;
  readonly size: number;
}

/** The service shape — see the module doc for semantics. */
export interface BlobStoreShape {
  /** Ranged read; omit `range` for the whole object. `null` = missing. */
  readonly get: (
    key: string,
    range?: { readonly offset: number; readonly length: number },
  ) => Effect.Effect<BlobBody | null, BlobStoreError, RuntimeContext>;
  /** Whole-object write. `contentLength` is required for streams. */
  readonly put: (
    key: string,
    body: Uint8Array | Stream.Stream<Uint8Array, BlobStoreError>,
    options?: { readonly contentLength?: number | undefined },
  ) => Effect.Effect<void, BlobStoreError, RuntimeContext>;
  /** Existence/size check without reading the body. */
  readonly head: (key: string) => Effect.Effect<BlobMeta | null, BlobStoreError, RuntimeContext>;
  /** Begin a multipart write (spilled push bodies of unknown length). */
  readonly multipart: (key: string) => Effect.Effect<BlobMultipart, BlobStoreError, RuntimeContext>;
  /**
   * Uploads one part of a multipart write created elsewhere (by key and
   * `uploadId`) — the resume path the push pipeline's hasher isolates use.
   */
  readonly uploadPart: (
    key: string,
    uploadId: string,
    partNumber: number,
    part: Uint8Array,
  ) => Effect.Effect<UploadedPart, BlobStoreError, RuntimeContext>;
  readonly delete: (
    keys: string | ReadonlyArray<string>,
  ) => Effect.Effect<void, BlobStoreError, RuntimeContext>;
  /** Prefix listing — GC/purge only, never on a serving path. */
  readonly list: (prefix: string) => Stream.Stream<BlobMeta, BlobStoreError, RuntimeContext>;
}

/**
 * The swappable bulk-byte store of the git service.
 *
 * @binding
 */
export class BlobStore extends Context.Service<BlobStore, BlobStoreShape>()(
  "alchemy/Git/BlobStore",
) {}