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

/**
 * Protocol-v0 push choreography (DESIGN §2.3, §3.6, §4) as pure functions.
 *
 * Request shape (`POST /git-receive-pack`):
 *
 * ```
 * *PKT-LINE("shallow" SP obj-id)                          ; shallow clients
 * PKT-LINE(old-oid SP new-oid SP refname NUL cap-list LF) ; first command
 * *PKT-LINE(old-oid SP new-oid SP refname LF)
 * flush-pkt
 * [raw PACK bytes]                                        ; NOT pkt-line framed
 * ```
 *
 * The pack follows the flush as raw bytes and is present iff any
 * create/update command exists (it may be an empty 0-object pack); it is
 * absent for delete-only pushes. Clients push **thin packs** over HTTP by
 * default — REF_DELTA bases resolve from the object store during ingest.
 *
 * The **empty-flush probe**: git sends a bare `0000` POST when the payload
 * exceeds `http.postBuffer`; the server replies with an empty 200 so the
 * client retries with the real body.
 *
 * The choreography splits so the Repo DO owns the transaction:
 * {@link parseReceivePackRequest} → {@link ingestPushPack} (staging sink) →
 * {@link checkConnectivity} → DO `transactionSync` CAS →
 * {@link reportStatus}.
 */
import * as Effect from "effect/Effect";
import {
  concatBytes,
  isOid,
  ObjectParseError,
  type ObjectType,
  type Oid,
  parseCommit,
  parseTag,
  parseTree,
  treeEntryKind,
  ZERO_OID,
} from "./ObjectCodec.ts";
import {
  bufferRandomAccess,
  ingestPack,
  type IngestSummary,
  type PackIngestError,
  type ResolvedEntry,
  type ThinBaseSource,
} from "./PackParser.ts";
import {
  flushPkt,
  PktLineError,
  pktPayloadText,
  pktText,
  ProtocolError,
  readPktLineAt,
} from "./Pkt.ts";
import { sidebandFrames } from "./Sideband.ts";
import { StoreError } from "./Store.ts";

// ─────────────────────────────────────────────────────────────────────────────
// Commands
// ─────────────────────────────────────────────────────────────────────────────

/**
 * One ref update command: `old-oid SP new-oid SP refname`. `old-oid` is the
 * client's expectation and the CAS token; zero-id old ⇒ create, zero-id new
 * ⇒ delete.
 */
export interface RefCommand {
  readonly oldOid: Oid;
  readonly newOid: Oid;
  readonly ref: string;
}

/** The kind of a ref command derived from its zero-id sides. */
export type CommandKind = "create" | "update" | "delete";

/**
 * Classifies a command: zero old-oid ⇒ `create`, zero new-oid ⇒ `delete`,
 * else `update`.
 */
export const commandKind = (command: RefCommand): CommandKind =>
  command.oldOid === ZERO_OID ? "create" : command.newOid === ZERO_OID ? "delete" : "update";

/**
 * A parsed `git-receive-pack` request.
 */
export interface ReceivePackRequest {
  /** Ref update commands, in request order. */
  readonly commands: ReadonlyArray<RefCommand>;
  /** Capabilities chosen by the client (after the NUL on the first command). */
  readonly capabilities: ReadonlySet<string>;
  /** `shallow` lines from shallow clients (v1: parsed, not honored). */
  readonly shallow: ReadonlyArray<Oid>;
  /** Byte offset of the raw pack in the body (position after the flush). */
  readonly packOffset: number;
  /** Whether raw pack bytes follow the flush. */
  readonly hasPack: boolean;
  /** `atomic` requested: all-or-nothing ref updates. */
  readonly atomic: boolean;
  /** `side-band-64k` requested: the report must be muxed on band 1. */
  readonly sideband: boolean;
  /** `report-status` or `report-status-v2` requested. */
  readonly reportStatus: boolean;
}

/**
 * The outcome of parsing a receive-pack body: the empty-flush probe (reply
 * with an empty 200) or a real request.
 */
export type ParsedReceivePack =
  | { readonly _tag: "probe" }
  | { readonly _tag: "request"; readonly request: ReceivePackRequest };

// control chars, space, DEL, and git's forbidden refname metacharacters
// oxlint-disable-next-line no-control-regex
const REFNAME_FORBIDDEN = new RegExp("[\\x00-\\x20\\x7f\\\\~^:?*\\[]");

const validRefName = (name: string): boolean =>
  name.startsWith("refs/") &&
  name.length > "refs/".length &&
  !name.endsWith("/") &&
  !name.includes("..") &&
  !name.endsWith(".lock") &&
  !REFNAME_FORBIDDEN.test(name);

const parseCommandLine = (line: string): Effect.Effect<RefCommand, ProtocolError> =>
  Effect.suspend(() => {
    const oldOid = line.slice(0, 40);
    const newOid = line.slice(41, 81);
    const ref = line.slice(82);
    if (
      !isOid(oldOid) ||
      line[40] !== " " ||
      !isOid(newOid) ||
      line[81] !== " " ||
      ref.length === 0
    ) {
      return Effect.fail(ProtocolError.make({ reason: `malformed command line: ${line}` }));
    }
    if (!validRefName(ref)) {
      return Effect.fail(ProtocolError.make({ reason: `invalid refname: ${ref}` }));
    }
    if (oldOid === ZERO_OID && newOid === ZERO_OID) {
      return Effect.fail(ProtocolError.make({ reason: `zero-to-zero command for ${ref}` }));
    }
    return Effect.succeed({ oldOid, newOid, ref });
  });

/**
 * Parses a `git-receive-pack` request body (already gunzipped): shallow
 * lines, the command list (NUL-separated caps on the first command), the
 * flush, and the position of the raw pack payload. A body containing no
 * commands is the **empty-flush probe**.
 */
export const parseReceivePackRequest = Effect.fn(function* (body: Uint8Array) {
  const commands: Array<RefCommand> = [];
  const capabilities = new Set<string>();
  const shallow: Array<Oid> = [];
  let pos = 0;

  for (;;) {
    const result = readPktLineAt(body, pos);
    if (result._tag === "incomplete") {
      return yield* PktLineError.make({
        reason: `truncated receive-pack request at offset ${pos}`,
      });
    }
    if (result._tag === "invalid") {
      return yield* PktLineError.make({ reason: result.reason });
    }
    const pkt = result.pkt;
    if (pkt._tag === "flush") {
      pos = result.next;
      break;
    }
    if (pkt._tag !== "data") {
      return yield* ProtocolError.make({
        reason: `unexpected ${pkt._tag} packet in receive-pack request`,
      });
    }
    const text = pktPayloadText(pkt.payload);
    if (text.startsWith("shallow ")) {
      const oid = text.slice(8);
      if (!isOid(oid)) {
        return yield* ProtocolError.make({
          reason: `malformed shallow line: ${text}`,
        });
      }
      shallow.push(oid);
    } else {
      const nul = text.indexOf("\0");
      const line = nul === -1 ? text : text.slice(0, nul);
      if (nul !== -1) {
        for (const cap of text.slice(nul + 1).split(" ")) {
          if (cap.length > 0) capabilities.add(cap);
        }
      }
      commands.push(yield* parseCommandLine(line));
    }
    pos = result.next;
  }

  if (commands.length === 0) {
    return { _tag: "probe" } as ParsedReceivePack;
  }

  const request: ReceivePackRequest = {
    commands,
    capabilities,
    shallow,
    packOffset: pos,
    hasPack: pos < body.length,
    atomic: capabilities.has("atomic"),
    sideband: capabilities.has("side-band-64k"),
    reportStatus: capabilities.has("report-status") || capabilities.has("report-status-v2"),
  };
  return { _tag: "request", request } as ParsedReceivePack;
});

// ─────────────────────────────────────────────────────────────────────────────
// Ingest driver
// ─────────────────────────────────────────────────────────────────────────────

/**
 * Options for {@link ingestPushPack}.
 */
export interface IngestPushOptions<E, R> {
  /** The full (gunzipped, buffered) request body. */
  readonly body: Uint8Array;
  /** `request.packOffset` from {@link parseReceivePackRequest}. */
  readonly packOffset: number;
  /** Live objects — resolves thin REF_DELTA bases. */
  readonly store: ThinBaseSource;
  /** Receives each resolved entry (the DO stages it under the push id). */
  readonly sink: (entry: ResolvedEntry) => Effect.Effect<void, E, R>;
  /** Per-object uncompressed cap; defaults to the parser's 64 MiB. */
  readonly maxObjectSize?: number | undefined;
}

/**
 * Drives {@link ingestPack} over the pack payload of a push body. A
 * delete-only push (no pack bytes) yields an empty summary without touching
 * the parser.
 */
export const ingestPushPack = <E, R>(
  options: IngestPushOptions<E, R>,
): Effect.Effect<IngestSummary, PackIngestError | E, R> =>
  options.packOffset >= options.body.length
    ? Effect.succeed({ count: 0, oids: [] })
    : ingestPack({
        source: bufferRandomAccess(options.body.subarray(options.packOffset)),
        store: options.store,
        sink: options.sink,
        maxObjectSize: options.maxObjectSize,
      });

// ─────────────────────────────────────────────────────────────────────────────
// Connectivity check
// ─────────────────────────────────────────────────────────────────────────────

/**
 * A staged object's identity, as needed by the connectivity walk.
 */
export interface StagedObjectRef {
  readonly oid: Oid;
  readonly type: ObjectType;
}

/**
 * The membership oracle and content reader the connectivity check needs —
 * implemented by the Repo DO over batched SQL.
 */
export interface ConnectivityDeps {
  /** Reads a staged object's inflated content. */
  readonly readStagedContent: (oid: Oid) => Effect.Effect<Uint8Array, StoreError>;
  /**
   * Filters oids down to those existing among **live** objects (batched,
   * chunked `IN` lists; order not guaranteed).
   */
  readonly filterLiveExisting: (
    oids: ReadonlyArray<Oid>,
  ) => Effect.Effect<ReadonlyArray<Oid>, StoreError>;
}

/**
 * The full connectivity check (DESIGN §3.6 step 5): collects every oid
 * referenced by staged commits (tree, parents), staged trees (entries —
 * gitlinks excluded, they point outside the repo), staged tags (target),
 * plus every command's non-zero `new-oid`; then verifies membership against
 * staged ∪ live objects. Returns the missing oids (empty = connected).
 *
 * This is the difference between "corrupt client" and "corrupt repo": any
 * miss fails the push with `unpack missing objects` + all-`ng`.
 */
export const checkConnectivity = Effect.fn(function* (
  staged: ReadonlyArray<StagedObjectRef>,
  commandNewOids: ReadonlyArray<Oid>,
  deps: ConnectivityDeps,
) {
  const stagedSet = new Set(staged.map((s) => s.oid));
  const referenced = new Set<Oid>();

  for (const object of staged) {
    switch (object.type) {
      case 1: {
        const content = yield* deps.readStagedContent(object.oid);
        const commit = yield* parseCommit(content);
        referenced.add(commit.tree);
        for (const parent of commit.parents) referenced.add(parent);
        break;
      }
      case 2: {
        const content = yield* deps.readStagedContent(object.oid);
        const entries = yield* parseTree(content);
        for (const entry of entries) {
          // gitlinks (mode 160000) reference commits in other repos — skip
          if (treeEntryKind(entry.mode) !== "commit") {
            referenced.add(entry.oid);
          }
        }
        break;
      }
      case 4: {
        const content = yield* deps.readStagedContent(object.oid);
        const tag = yield* parseTag(content);
        referenced.add(tag.object);
        break;
      }
      default:
        break; // blobs reference nothing
    }
  }
  for (const oid of commandNewOids) {
    if (oid !== ZERO_OID) referenced.add(oid);
  }

  const candidates = [...referenced].filter((oid) => !stagedSet.has(oid));
  if (candidates.length === 0) return [] as ReadonlyArray<Oid>;
  const live = new Set(yield* deps.filterLiveExisting(candidates));
  return candidates.filter((oid) => !live.has(oid)).sort();
});

// ─────────────────────────────────────────────────────────────────────────────
// report-status
// ─────────────────────────────────────────────────────────────────────────────

/**
 * The per-ref outcome of the CAS transaction, produced by the Repo DO and
 * rendered by {@link reportStatus}.
 */
export interface CommandResult {
  readonly ref: string;
  readonly ok: boolean;
  /** Failure reason for `ng` lines (e.g. `fetch first`). */
  readonly reason?: string | undefined;
}

/** Builds an `ok <ref>` result. */
export const okResult = (ref: string): CommandResult => ({ ref, ok: true });

/** Builds an `ng <ref> <reason>` result. */
export const ngResult = (ref: string, reason: string): CommandResult => ({
  ref,
  ok: false,
  reason,
});

/**
 * Options for {@link reportStatus}.
 */
export interface ReportStatusOptions {
  /** `"ok"` when the pack ingested cleanly, else the unpack error message. */
  readonly unpack: string;
  /** Per-ref results in command order. */
  readonly results: ReadonlyArray<CommandResult>;
  /** Wrap the report in side-band band 1 (mandatory when negotiated). */
  readonly sideband: boolean;
}

/**
 * Renders the `report-status` (and `report-status-v2` — implemented
 * identically, with no `option` lines, which is valid) response:
 *
 * ```
 * unpack ok|<error>
 * ok <ref> | ng <ref> <reason>   (per command)
 * flush
 * ```
 *
 * When the client negotiated `side-band-64k` the entire report (including
 * its flush) is wrapped in band-1 frames followed by the outer flush —
 * sending it unmuxed while side-band is active breaks the client.
 */
export const reportStatus = (options: ReportStatusOptions): Uint8Array => {
  const inner = concatBytes([
    pktText(`unpack ${options.unpack}`),
    ...options.results.map((result) =>
      pktText(result.ok ? `ok ${result.ref}` : `ng ${result.ref} ${result.reason ?? "failed"}`),
    ),
    flushPkt,
  ]);
  return options.sideband ? concatBytes([...sidebandFrames(1, inner), flushPkt]) : inner;
};

/**
 * Renders the all-failed report used for whole-push rejections: pack too
 * large, checksum mismatch, missing objects, read-only repo. `unpack` carries
 * the reason and every command gets an `ng` with the same reason.
 */
export const failAllReport = (
  commands: ReadonlyArray<RefCommand>,
  reason: string,
  sideband: boolean,
): Uint8Array =>
  reportStatus({
    unpack: reason,
    results: commands.map((command) => ngResult(command.ref, reason)),
    sideband,
  });

/** Errors the parse phase of receive-pack can produce. */
export type ReceivePackParseError = PktLineError | ProtocolError;

/** Errors the connectivity check can produce. */
export type ConnectivityError = StoreError | ObjectParseError;