@intx/hub-api 0.1.2

package/src/git-http/receive-pack.test.ts

@@ -0,0 +1,397 @@
+import { describe, test, expect } from "bun:test";
+import type { Principal, RepoId, RepoStore } from "@intx/hub-sessions";
+
+import { handleReceivePack } from "./receive-pack";
+
+const REPO_ID: RepoId = { kind: "agent-state", id: "test" };
+const ZERO_OID = "0".repeat(40);
+
+function hex4(n: number): string {
+  return n.toString(16).padStart(4, "0");
+}
+
+function pkt(payload: string): Uint8Array {
+  const enc = new TextEncoder().encode(payload);
+  const header = new TextEncoder().encode(hex4(enc.length + 4));
+  const out = new Uint8Array(header.length + enc.length);
+  out.set(header, 0);
+  out.set(enc, header.length);
+  return out;
+}
+
+const FLUSH = new TextEncoder().encode("0000");
+
+function concat(...parts: Uint8Array[]): Uint8Array {
+  const total = parts.reduce((n, p) => n + p.length, 0);
+  const out = new Uint8Array(total);
+  let off = 0;
+  for (const p of parts) {
+    out.set(p, off);
+    off += p.length;
+  }
+  return out;
+}
+
+function buildBody(
+  commands: { oldSha: string; newSha: string; ref: string }[],
+  pack: Uint8Array,
+  capabilities?: string,
+): Uint8Array {
+  if (commands.length === 0) {
+    throw new Error("buildBody: need at least one command");
+  }
+  const parts: Uint8Array[] = [];
+  for (let i = 0; i < commands.length; i++) {
+    const cmd = commands[i];
+    if (cmd === undefined) {
+      throw new Error("unreachable");
+    }
+    let line = `${cmd.oldSha} ${cmd.newSha} ${cmd.ref}`;
+    if (i === 0 && capabilities !== undefined) {
+      line += `\0${capabilities}`;
+    }
+    line += "\n";
+    parts.push(pkt(line));
+  }
+  parts.push(FLUSH);
+  parts.push(pack);
+  return concat(...parts);
+}
+
+function buildRequest(body: Uint8Array): Request {
+  return new Request("http://hub.test/repo/git-receive-pack", {
+    method: "POST",
+    headers: { "content-type": "application/x-git-receive-pack-request" },
+    body,
+  });
+}
+
+async function readBody(response: Response): Promise<string> {
+  const buf = new Uint8Array(await response.arrayBuffer());
+  return new TextDecoder().decode(buf);
+}
+
+const PRINCIPAL: Principal = { kind: "user" };
+
+type ReceivePackCall = {
+  ref: string;
+  newSha: string;
+  expectedOldSha: string | null;
+  packLength: number;
+};
+
+type ReceivePackStub = (call: ReceivePackCall) => Promise<void> | void;
+
+function createStubStore(stub: ReceivePackStub): {
+  store: RepoStore;
+  calls: ReceivePackCall[];
+} {
+  const calls: ReceivePackCall[] = [];
+  const store: RepoStore = {
+    initRepo: async () => {
+      throw new Error("initRepo: not used in this test");
+    },
+    writeTree: async () => {
+      throw new Error("writeTree: not used in this test");
+    },
+    createPack: async () => {
+      throw new Error("createPack: not used in this test");
+    },
+    resolveRef: async () => {
+      throw new Error("resolveRef: not used in this test");
+    },
+    listRefs: async () => {
+      throw new Error("listRefs: not used in this test");
+    },
+    resolveHead: async () => {
+      throw new Error("resolveHead: not used in this test");
+    },
+    getRepoDir: () => {
+      throw new Error("getRepoDir: not used in this test");
+    },
+    receivePack: async (
+      _principal: Principal,
+      _repoId: RepoId,
+      ref: string,
+      pack: Uint8Array,
+      commitSha: string,
+      expectedOldSha: string | null,
+    ) => {
+      const call: ReceivePackCall = {
+        ref,
+        newSha: commitSha,
+        expectedOldSha,
+        packLength: pack.length,
+      };
+      calls.push(call);
+      await stub(call);
+    },
+  };
+  return { store, calls };
+}
+
+const PACK_BYTES = new Uint8Array([
+  0x50, 0x41, 0x43, 0x4b, 0x00, 0x00, 0x00, 0x02,
+]);
+
+describe("handleReceivePack response framing", () => {
+  test("Content-Type is application/x-git-receive-pack-result", async () => {
+    const { store } = createStubStore(() => undefined);
+    const body = buildBody(
+      [
+        {
+          oldSha: ZERO_OID,
+          newSha: "a".repeat(40),
+          ref: "refs/heads/main",
+        },
+      ],
+      PACK_BYTES,
+      "report-status side-band-64k",
+    );
+    const response = await handleReceivePack(
+      store,
+      PRINCIPAL,
+      REPO_ID,
+      buildRequest(body),
+    );
+    expect(response.headers.get("content-type")).toBe(
+      "application/x-git-receive-pack-result",
+    );
+  });
+});
+
+describe("handleReceivePack single-ref happy path", () => {
+  test("emits unpack ok and ok <ref>", async () => {
+    const { store, calls } = createStubStore(() => undefined);
+    const newSha = "1".repeat(40);
+    const body = buildBody(
+      [{ oldSha: ZERO_OID, newSha, ref: "refs/heads/main" }],
+      PACK_BYTES,
+      "report-status",
+    );
+    const response = await handleReceivePack(
+      store,
+      PRINCIPAL,
+      REPO_ID,
+      buildRequest(body),
+    );
+    const text = await readBody(response);
+    const expected =
+      pktText("unpack ok\n") + pktText("ok refs/heads/main\n") + "0000";
+    expect(text).toBe(expected);
+    expect(calls).toEqual([
+      {
+        ref: "refs/heads/main",
+        newSha,
+        expectedOldSha: null,
+        packLength: PACK_BYTES.length,
+      },
+    ]);
+  });
+
+  test("non-zero oldSha is forwarded as expectedOldSha", async () => {
+    const { store, calls } = createStubStore(() => undefined);
+    const oldSha = "a".repeat(40);
+    const newSha = "b".repeat(40);
+    const body = buildBody(
+      [{ oldSha, newSha, ref: "refs/heads/main" }],
+      PACK_BYTES,
+      "report-status",
+    );
+    await handleReceivePack(store, PRINCIPAL, REPO_ID, buildRequest(body));
+    expect(calls[0]?.expectedOldSha).toBe(oldSha);
+  });
+});
+
+describe("handleReceivePack multi-ref sequence", () => {
+  test("reports per-ref status in the order received", async () => {
+    const { store } = createStubStore(() => undefined);
+    const newShaA = "a".repeat(40);
+    const newShaB = "b".repeat(40);
+    const body = buildBody(
+      [
+        { oldSha: ZERO_OID, newSha: newShaA, ref: "refs/heads/main" },
+        { oldSha: ZERO_OID, newSha: newShaB, ref: "refs/heads/dev" },
+      ],
+      PACK_BYTES,
+      "report-status",
+    );
+    const response = await handleReceivePack(
+      store,
+      PRINCIPAL,
+      REPO_ID,
+      buildRequest(body),
+    );
+    const text = await readBody(response);
+    const expected =
+      pktText("unpack ok\n") +
+      pktText("ok refs/heads/main\n") +
+      pktText("ok refs/heads/dev\n") +
+      "0000";
+    expect(text).toBe(expected);
+  });
+
+  test("partial success produces mixed ok/ng status", async () => {
+    const { store } = createStubStore((call) => {
+      if (call.ref === "refs/heads/dev") {
+        throw new Error("path_violation: dev tree not allowed");
+      }
+    });
+    const newShaA = "a".repeat(40);
+    const newShaB = "b".repeat(40);
+    const body = buildBody(
+      [
+        { oldSha: ZERO_OID, newSha: newShaA, ref: "refs/heads/main" },
+        { oldSha: ZERO_OID, newSha: newShaB, ref: "refs/heads/dev" },
+      ],
+      PACK_BYTES,
+      "report-status",
+    );
+    const response = await handleReceivePack(
+      store,
+      PRINCIPAL,
+      REPO_ID,
+      buildRequest(body),
+    );
+    const text = await readBody(response);
+    const expected =
+      pktText("unpack ok\n") +
+      pktText("ok refs/heads/main\n") +
+      pktText("ng refs/heads/dev path-violation: dev tree not allowed\n") +
+      "0000";
+    expect(text).toBe(expected);
+  });
+});
+
+describe("handleReceivePack substrate error translations", () => {
+  test("non_fast_forward translates to ng <ref> non-fast-forward", async () => {
+    const { store } = createStubStore(() => {
+      throw new Error("non_fast_forward: stale oldSha");
+    });
+    const oldSha = "a".repeat(40);
+    const newSha = "b".repeat(40);
+    const body = buildBody(
+      [{ oldSha, newSha, ref: "refs/heads/main" }],
+      PACK_BYTES,
+      "report-status",
+    );
+    const response = await handleReceivePack(
+      store,
+      PRINCIPAL,
+      REPO_ID,
+      buildRequest(body),
+    );
+    const text = await readBody(response);
+    const expected =
+      pktText("unpack ok\n") +
+      pktText("ng refs/heads/main non-fast-forward\n") +
+      "0000";
+    expect(text).toBe(expected);
+  });
+
+  test("path_violation translates byte-correct with reason", async () => {
+    const { store } = createStubStore(() => {
+      throw new Error("path_violation: foo not under skill/");
+    });
+    const body = buildBody(
+      [
+        {
+          oldSha: ZERO_OID,
+          newSha: "a".repeat(40),
+          ref: "refs/heads/main",
+        },
+      ],
+      PACK_BYTES,
+      "report-status",
+    );
+    const response = await handleReceivePack(
+      store,
+      PRINCIPAL,
+      REPO_ID,
+      buildRequest(body),
+    );
+    const text = await readBody(response);
+    const expected =
+      pktText("unpack ok\n") +
+      pktText("ng refs/heads/main path-violation: foo not under skill/\n") +
+      "0000";
+    expect(text).toBe(expected);
+  });
+
+  test("authorize_denied translates byte-correct to forbidden", async () => {
+    const { store } = createStubStore(() => {
+      throw new Error("authorize_denied: refPattern mismatch");
+    });
+    const body = buildBody(
+      [
+        {
+          oldSha: ZERO_OID,
+          newSha: "a".repeat(40),
+          ref: "refs/heads/main",
+        },
+      ],
+      PACK_BYTES,
+      "report-status",
+    );
+    const response = await handleReceivePack(
+      store,
+      PRINCIPAL,
+      REPO_ID,
+      buildRequest(body),
+    );
+    const text = await readBody(response);
+    const expected =
+      pktText("unpack ok\n") +
+      pktText("ng refs/heads/main forbidden\n") +
+      "0000";
+    expect(text).toBe(expected);
+  });
+
+  test("sha_mismatch translates to ng <ref> sha-mismatch", async () => {
+    const { store } = createStubStore(() => {
+      throw new Error("sha_mismatch: pack tip != claimed newSha");
+    });
+    const body = buildBody(
+      [
+        {
+          oldSha: ZERO_OID,
+          newSha: "a".repeat(40),
+          ref: "refs/heads/main",
+        },
+      ],
+      PACK_BYTES,
+      "report-status",
+    );
+    const response = await handleReceivePack(
+      store,
+      PRINCIPAL,
+      REPO_ID,
+      buildRequest(body),
+    );
+    const text = await readBody(response);
+    const expected =
+      pktText("unpack ok\n") +
+      pktText("ng refs/heads/main sha-mismatch\n") +
+      "0000";
+    expect(text).toBe(expected);
+  });
+});
+
+describe("handleReceivePack capability parsing", () => {
+  test("strips NUL-separated capabilities from the first command line", async () => {
+    const { store, calls } = createStubStore(() => undefined);
+    const newSha = "a".repeat(40);
+    const body = buildBody(
+      [{ oldSha: ZERO_OID, newSha, ref: "refs/heads/main" }],
+      PACK_BYTES,
+      "report-status side-band-64k agent=git/2.40.0",
+    );
+    await handleReceivePack(store, PRINCIPAL, REPO_ID, buildRequest(body));
+    expect(calls[0]?.ref).toBe("refs/heads/main");
+  });
+});
+
+function pktText(payload: string): string {
+  const enc = new TextEncoder().encode(payload);
+  return hex4(enc.length + 4) + payload;
+}

package/src/git-http/receive-pack.ts

@@ -0,0 +1,261 @@
+/**
+ * Smart-HTTP `git-receive-pack` request handler. Parses the client's
+ * ref-update commands followed by a packfile, drives the substrate's
+ * `receivePack` primitive for each command, and emits a
+ * `report-status` pkt-line stream as the response body.
+ *
+ * Request body shape (see `Documentation/technical/pack-protocol.txt`
+ * in the git source tree):
+ *
+ *   <pkt><old-sha> <new-sha> <ref>\0<caps>\n</pkt>   // first command
+ *   <pkt><old-sha> <new-sha> <ref>\n</pkt>           // subsequent commands
+ *   ...
+ *   0000
+ *   <raw packfile bytes>
+ *
+ * Response body shape (`report-status`):
+ *
+ *   <pkt>unpack ok\n</pkt>
+ *   <pkt>ok <ref>\n</pkt>      // per-ref success
+ *   <pkt>ng <ref> <reason>\n</pkt>  // per-ref failure
+ *   ...
+ *   0000
+ *
+ * Substrate error prefixes are translated to the report-status
+ * `ng <ref> <reason>` vocabulary. The substrate's `non_fast_forward:`
+ * prefix covers both stale-oldSha CAS failures and pure
+ * non-fast-forward rejections, both of which surface to the client as
+ * `non-fast-forward`.
+ */
+
+import type { Principal, RepoId, RepoStore } from "@intx/hub-sessions";
+
+import { writePktLine, writeFlush } from "./pkt-line";
+
+const RECEIVE_PACK_CONTENT_TYPE = "application/x-git-receive-pack-result";
+const ZERO_OID = "0".repeat(40);
+
+type RefCommand = {
+  readonly oldSha: string;
+  readonly newSha: string;
+  readonly ref: string;
+};
+
+type ParsedRequest = {
+  readonly commands: readonly RefCommand[];
+  readonly pack: Uint8Array;
+};
+
+function parseHex4(buf: Uint8Array, off: number): number {
+  let v = 0;
+  for (let i = 0; i < 4; i++) {
+    const c = buf[off + i];
+    if (c === undefined) {
+      throw new Error("truncated pkt-line: short header");
+    }
+    let d: number;
+    if (c >= 0x30 && c <= 0x39) {
+      d = c - 0x30;
+    } else if (c >= 0x61 && c <= 0x66) {
+      d = c - 0x61 + 10;
+    } else if (c >= 0x41 && c <= 0x46) {
+      d = c - 0x41 + 10;
+    } else {
+      throw new Error("malformed pkt-line length");
+    }
+    v = (v << 4) | d;
+  }
+  return v;
+}
+
+function parseCommandLine(line: string): RefCommand {
+  // A command line is `<old-sha> <new-sha> <ref>`. The first command
+  // may carry capabilities after a NUL byte; the trailing `\n` is
+  // optional in some clients but is present in all stock git versions.
+  // Strip the trailer and the capabilities tail before parsing.
+  const nulIdx = line.indexOf("\0");
+  const head = nulIdx === -1 ? line : line.substring(0, nulIdx);
+  const trimmed = head.endsWith("\n") ? head.slice(0, -1) : head;
+  const parts = trimmed.split(" ");
+  if (parts.length < 3) {
+    throw new Error(`malformed receive-pack command: ${JSON.stringify(line)}`);
+  }
+  const oldSha = parts[0];
+  const newSha = parts[1];
+  // The ref may not contain a space, but split() guarantees it does
+  // not; everything after the second space is the ref.
+  const ref = parts.slice(2).join(" ");
+  if (oldSha === undefined || newSha === undefined || ref.length === 0) {
+    throw new Error(`malformed receive-pack command: ${JSON.stringify(line)}`);
+  }
+  return { oldSha, newSha, ref };
+}
+
+function parseRequestBody(body: Uint8Array): ParsedRequest {
+  const decoder = new TextDecoder();
+  const commands: RefCommand[] = [];
+  let off = 0;
+  for (;;) {
+    if (off + 4 > body.length) {
+      throw new Error("truncated receive-pack request: incomplete header");
+    }
+    const length = parseHex4(body, off);
+    off += 4;
+    if (length === 0) {
+      // Flush packet marks end of command list; rest of body is the
+      // packfile (or empty when the client only deleted refs, which
+      // this hub does not support yet).
+      break;
+    }
+    if (length === 1) {
+      throw new Error("unexpected delim pkt-line in receive-pack commands");
+    }
+    if (length < 4) {
+      throw new Error(`reserved pkt-line length: ${length}`);
+    }
+    const bodyLen = length - 4;
+    if (off + bodyLen > body.length) {
+      throw new Error(
+        "truncated receive-pack request: incomplete pkt-line body",
+      );
+    }
+    const line = decoder.decode(body.subarray(off, off + bodyLen));
+    off += bodyLen;
+    commands.push(parseCommandLine(line));
+  }
+  const pack = body.subarray(off);
+  return { commands, pack };
+}
+
+type RefStatus =
+  | { readonly kind: "ok"; readonly ref: string }
+  | { readonly kind: "ng"; readonly ref: string; readonly reason: string };
+
+const ERROR_PREFIXES = [
+  "non_fast_forward:",
+  "path_violation:",
+  "authorize_denied:",
+  "sha_mismatch:",
+] as const;
+
+type SubstrateErrorPrefix = (typeof ERROR_PREFIXES)[number];
+
+function classifyError(err: unknown): {
+  prefix: SubstrateErrorPrefix;
+  detail: string;
+} | null {
+  if (!(err instanceof Error)) return null;
+  for (const prefix of ERROR_PREFIXES) {
+    if (err.message.startsWith(prefix)) {
+      const detail = err.message.substring(prefix.length).trimStart();
+      return { prefix, detail };
+    }
+  }
+  return null;
+}
+
+function translateError(err: unknown, ref: string): RefStatus {
+  const classified = classifyError(err);
+  if (classified === null) {
+    throw err;
+  }
+  switch (classified.prefix) {
+    case "non_fast_forward:":
+      return { kind: "ng", ref, reason: "non-fast-forward" };
+    case "path_violation:":
+      return {
+        kind: "ng",
+        ref,
+        reason: `path-violation: ${classified.detail}`,
+      };
+    case "authorize_denied:":
+      return { kind: "ng", ref, reason: "forbidden" };
+    case "sha_mismatch:":
+      return { kind: "ng", ref, reason: "sha-mismatch" };
+  }
+}
+
+async function runCommand(
+  repoStore: RepoStore,
+  principal: Principal,
+  repoId: RepoId,
+  command: RefCommand,
+  pack: Uint8Array,
+): Promise<RefStatus> {
+  const expectedOldSha = command.oldSha === ZERO_OID ? null : command.oldSha;
+  try {
+    await repoStore.receivePack(
+      principal,
+      repoId,
+      command.ref,
+      pack,
+      command.newSha,
+      expectedOldSha,
+    );
+    return { kind: "ok", ref: command.ref };
+  } catch (err) {
+    return translateError(err, command.ref);
+  }
+}
+
+async function writeReport(
+  writer: WritableStreamDefaultWriter<Uint8Array>,
+  unpackStatus: string,
+  statuses: readonly RefStatus[],
+): Promise<void> {
+  await writePktLine(writer, `unpack ${unpackStatus}\n`);
+  for (const status of statuses) {
+    if (status.kind === "ok") {
+      await writePktLine(writer, `ok ${status.ref}\n`);
+    } else {
+      await writePktLine(writer, `ng ${status.ref} ${status.reason}\n`);
+    }
+  }
+  await writeFlush(writer);
+}
+
+export async function handleReceivePack(
+  repoStore: RepoStore,
+  principal: Principal,
+  repoId: RepoId,
+  request: Request,
+): Promise<Response> {
+  const body = new Uint8Array(await request.arrayBuffer());
+  const parsed = parseRequestBody(body);
+
+  const statuses: RefStatus[] = [];
+  for (const command of parsed.commands) {
+    const status = await runCommand(
+      repoStore,
+      principal,
+      repoId,
+      command,
+      parsed.pack,
+    );
+    statuses.push(status);
+  }
+
+  const stream = new ReadableStream<Uint8Array>({
+    async start(controller) {
+      const sink = new WritableStream<Uint8Array>({
+        write(chunk) {
+          controller.enqueue(chunk);
+        },
+      });
+      const writer = sink.getWriter();
+      try {
+        await writeReport(writer, "ok", statuses);
+        await writer.close();
+        controller.close();
+      } catch (cause) {
+        await writer.abort(cause).catch(() => undefined);
+        controller.error(cause);
+      }
+    },
+  });
+
+  return new Response(stream, {
+    status: 200,
+    headers: { "content-type": RECEIVE_PACK_CONTENT_TYPE },
+  });
+}