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

/**
 * Abstract storage interfaces the protocol choreography is written against.
 *
 * The concrete implementations live in `src/store/` (DO SQLite + R2); the
 * protocol layer (`UploadPack`, `ReceivePack`, `PackParser`, `PackWriter`,
 * `Advertise`) depends only on these data-shaped contracts, which keeps the
 * entire `src/Protocol/` layer unit-testable in plain bun with in-memory fakes.
 */
import type * as Effect from "effect/Effect";
import * as Schema from "effect/Schema";
import type * as Stream from "effect/Stream";
import type { ObjectType, Oid } from "./ObjectCodec.ts";

/**
 * Error produced by any of the abstract store interfaces. Concrete
 * implementations wrap their own failures (SQL, R2) into this tag so the
 * protocol layer's error unions stay closed.
 */
export class StoreError extends Schema.TaggedError<StoreError>()("StoreError", {
  reason: Schema.String,
}) {}

/**
 * Where an object's compressed bytes live (mirrors the `objects.location`
 * column): `row` = SQLite BLOB, `r2` = oversize loose object in R2,
 * `pack` = v1.1 compacted pack in R2.
 */
export type ObjectLocation = "row" | "r2" | "pack";

/**
 * Metadata for one stored object — also the shape of a pack manifest entry
 * (the fetch closure materializes a list of these, and `PackWriter` streams
 * from it).
 */
export interface ObjectMeta {
  readonly oid: Oid;
  readonly type: ObjectType;
  /** Uncompressed size in bytes. */
  readonly size: number;
  /** Stored (zlib-compressed) size in bytes. */
  readonly zsize: number;
  /** Storage tier the zdata lives in. */
  readonly location: ObjectLocation;
}

/**
 * One entry of a fetch-pack manifest. Alias of {@link ObjectMeta} — the
 * closure walk produces exactly the metadata the pack emitter needs.
 */
export type ManifestEntry = ObjectMeta;

/**
 * Read access to the object store, as needed by pack parsing (thin-pack base
 * resolution), pack writing (zdata streaming), negotiation (have existence),
 * and the push connectivity check.
 *
 * All byte payloads are `zlib(content)` **without** the loose header, so pack
 * emission is `varint(type,size) + zdata` verbatim.
 */
export interface ObjectSource {
  /** Whether an object exists (live objects only, not staged). */
  readonly has: (oid: Oid) => Effect.Effect<boolean, StoreError>;
  /**
   * Filters the given oids down to the subset that exists in the store.
   * Implementations batch with chunked `IN` lists; order is not guaranteed.
   */
  readonly filterExisting: (
    oids: ReadonlyArray<Oid>,
  ) => Effect.Effect<ReadonlyArray<Oid>, StoreError>;
  /** Object metadata, or `undefined` when the object does not exist. */
  readonly getMeta: (oid: Oid) => Effect.Effect<ObjectMeta | undefined, StoreError>;
  /**
   * Streams the stored compressed bytes (`zlib(content)`, no loose header)
   * regardless of location (row BLOB, R2 get, v1.1 ranged pack read).
   */
  readonly readZData: (oid: Oid) => Stream.Stream<Uint8Array, StoreError>;
  /**
   * Reads and inflates the full object content. Used for thin-pack base
   * resolution and tree/commit walks; callers must respect the per-object
   * size cap before requesting.
   */
  readonly readContent: (oid: Oid) => Effect.Effect<Uint8Array, StoreError>;
  /**
   * Emits `varint(type,size) + zdata` for every entry as a stream of LARGE
   * chunks: objects are read in batches (one statement per ~256) and
   * concatenated, and pack-resident objects are visited in pack order so
   * the window cache is sequential. Optional — sources without batching
   * fall back to one `readZData` per entry (DESIGN §22).
   */
  readonly packEntries?:
    | ((entries: ReadonlyArray<ManifestEntry>) => Stream.Stream<Uint8Array, StoreError>)
    | undefined;
}

/**
 * One advertised ref: full name, tip oid, and — for annotated tags — the
 * peeled target commit oid (advertised as a `^{}` line).
 */
export interface RefRecord {
  /** Full ref name, e.g. `refs/heads/main`, `refs/tags/v1`. */
  readonly name: string;
  readonly oid: Oid;
  /** Peeled target for annotated tags (`refs/tags/x^{}` advertisement). */
  readonly peeled?: Oid | undefined;
}

/**
 * A point-in-time snapshot of the ref namespace used to build the v0
 * advertisement. `HEAD` is virtual: it resolves to
 * `refs/heads/<defaultBranch>` when that ref exists.
 */
export interface RefsSnapshot {
  /** The repo's default branch short name, e.g. `main`. */
  readonly defaultBranch: string;
  /** All refs, sorted by name (the advertisement preserves this order). */
  readonly refs: ReadonlyArray<RefRecord>;
}

/**
 * Inputs to the fetch closure computation (implemented over the commit graph
 * in `src/Store/Closure.ts`).
 */
export interface ClosureRequest {
  /** Requested tips (from `want` lines). */
  readonly wants: ReadonlyArray<Oid>;
  /**
   * Common commits negotiated with the client (the ACKed haves). The walk
   * stops at these boundaries.
   */
  readonly haves: ReadonlyArray<Oid>;
  /** Depth bound from `deepen <n>`, when the client requested a shallow fetch. */
  readonly depth?: number | undefined;
  /** The client's existing shallow tips (additional walk boundaries). */
  readonly clientShallow: ReadonlyArray<Oid>;
  /**
   * The REPO's own shallow boundary (commits whose parents were never
   * ingested — a depth-limited import). These never expand in any walk and
   * always surface as `shallow <oid>` lines when included in a pack, so
   * clones of a shallow repo are themselves shallow (and fsck-clean).
   */
  readonly repoShallow?: ReadonlyArray<Oid> | undefined;
}

/**
 * The result of a closure computation: the pack manifest plus the shallow
 * boundary bookkeeping for the response's shallow section.
 */
export interface ClosureResult {
  /**
   * Every object to pack (commits + trees + blobs + tags), each exactly once.
   * Materialized before streaming so the pack header count is known upfront.
   */
  readonly entries: ReadonlyArray<ManifestEntry>;
  /** Commits that became shallow boundaries (`shallow <oid>` lines). */
  readonly shallow: ReadonlyArray<Oid>;
  /**
   * Previously-shallow client tips that are now complete
   * (`unshallow <oid>` lines).
   */
  readonly unshallow: ReadonlyArray<Oid>;
}

/**
 * Computes the object closure for a fetch: BFS from wants over the commit
 * graph stopping at haves (generation-bounded), depth-bounded when shallow,
 * plus the full tree/blob closure of the frontier commits.
 */
export interface ClosureSource {
  readonly commitClosure: (request: ClosureRequest) => Effect.Effect<ClosureResult, StoreError>;
}