@volter/twin-github 0.1.0 → 0.1.1

package/src/github-events.ts

@@ -10,7 +10,7 @@
 import { createHmac } from 'node:crypto';
 import type { GithubWriteEvent } from './github-twin.ts';
 
-export type GithubWebhook = { event: string; action: string; number: number; repository: { full_name: string }; pull_request?: Record<string, unknown>; issue?: { number: number }; comment?: { body: string }; review?: { body: string } };
+export type GithubWebhook = { event: string; action: string; number: number; repository: { full_name: string }; pull_request?: Record<string, unknown>; issue?: { number: number }; comment?: { body: string }; review?: { body: string }; ref?: string; before?: string; after?: string; created?: boolean; deleted?: boolean };
 // Delivery receives the resolved headers too (X-GitHub-Event, X-GitHub-Delivery,
 // X-Hub-Signature-256) so a faithful consumer can verify the signature.
 export type GithubWebhookDelivery = (url: string, headerEvent: string, payload: GithubWebhook, headers: Record<string, string>) => Promise<void> | void;
@@ -53,6 +53,16 @@ function buildPayload(write: GithubWriteEvent): GithubWebhook {
     ...(write.event === 'issues' ? { issue: { number: write.number } } : {}),
     ...(write.event === 'pull_request_review' ? { review: { body: write.body ?? '' }, pull_request: { number: write.number } } : {}),
     ...(write.event === 'issue_comment' ? { comment: { body: write.body ?? '' } } : {}),
+    // push events (git-receive-pack / contents writes): GitHub's ref/before/after triple
+    // plus the created/deleted flags consumers branch on (derived exactly as GitHub derives
+    // them: created ⇔ before is the zero sha, deleted ⇔ after is). `forced` would need
+    // ancestry knowledge the event does not carry — omitted rather than fabricated.
+    ...(write.event === 'push' && write.ref !== undefined
+      ? {
+          ref: write.ref, before: write.before ?? '', after: write.after ?? '',
+          created: write.before === '0'.repeat(40), deleted: write.after === '0'.repeat(40),
+        }
+      : {}),
   };
 }
 

package/src/github-git-http.ts

@@ -0,0 +1,248 @@
+// GitHub twin git smart-HTTP — serves the REAL git wire protocol over the pack's REAL bare
+// repos (github-git-plane.ts), so an UNMODIFIED `git` CLI can clone from and push to the twin:
+//
+//   GET  /:owner/:repo[.git]/info/refs?service=git-upload-pack|git-receive-pack
+//   POST /:owner/:repo[.git]/git-upload-pack
+//   POST /:owner/:repo[.git]/git-receive-pack
+//
+// Implementation choice — `git upload-pack|receive-pack --stateless-rpc` SPAWNED DIRECTLY,
+// not `git http-backend` (CGI). Both are first-party; direct spawn is the simpler one to
+// GATE: http-backend adds a CGI translation layer (GIT_PROJECT_ROOT/PATH_INFO/QUERY_STRING/
+// REMOTE_USER env plumbing + CGI response-header parsing) whose plumbing would live in the
+// twin and need its own tests, while contributing no protocol behavior of its own —
+// http-backend itself execs exactly these two commands with exactly these flags
+// (gitprotocol-http(5), "Smart Service git-upload-pack"). Direct spawn leaves ONE seam
+// (this module) a mutation saboteur can kill and the fidelity oracle (a real `git` client)
+// can prove end-to-end. The only protocol framing the twin adds itself is the documented
+// service-advertisement prefix — one pkt-line (`# service=$servicename` LF) plus a
+// flush-pkt, per gitprotocol-http(5) "smart_reply" — everything else on the wire is
+// produced by real git.
+//
+// Reconciliation (the heart of the upgrade): after a receive-pack POST, ref changes in the
+// bare repo are FOLDED into the kernel event log (git_ref.* + branch.* actions — the same
+// operations the Git Data REST writes append), so a pushed branch is immediately visible to
+// the REST plane: GET git/refs, GET branches, PR head/base resolution. Objects are NOT
+// copied into kernel rows — the bare repo IS the object store (one store, not two); the Git
+// Data REST reads fall back to it (github-twin.ts).
+//
+// Each branch-ref change also yields a `push` webhook event (ref/before/after), which the
+// server emits through the pack's EXISTING emitGithubEvent pipeline — a git push fires the
+// same webhook machinery a REST contents write does.
+//
+// Offline + deterministic: everything here is local files + local `git` subprocesses (no
+// network, no rate budget). Failure to spawn git throws loudly (github-git-plane.ts).
+import { gunzipSync } from 'node:zlib';
+import { applyTwinWrite } from '@volter/twin';
+import {
+  bareRepoDir, ensureBareRepo, hasBareRepo, listGitPlaneRefs, runGit, type PlaneRef,
+} from './github-git-plane.ts';
+import { closePrsForDeletedBranch, githubState, syncPrHeadsToBranchTip, type GithubWriteEvent } from './github-twin.ts';
+
+const SERVICE = 'github';
+
+export type GitSmartHttpRoute =
+  | { kind: 'info-refs'; repo: string }
+  | { kind: 'upload-pack'; repo: string }
+  | { kind: 'receive-pack'; repo: string };
+
+/** Parse a smart-HTTP pathname; null when the path is not a git-protocol route. */
+export function parseGitSmartHttpPath(method: string, pathname: string): GitSmartHttpRoute | null {
+  const m = /^\/([^/]+)\/([^/]+?)(?:\.git)?\/(info\/refs|git-upload-pack|git-receive-pack)$/.exec(pathname);
+  if (!m) return null;
+  const owner = decodeURIComponent(m[1]!);
+  const name = decodeURIComponent(m[2]!);
+  // A name the plane's path validation would reject can never be a twin repo — fall through
+  // to the REST handler's vendor-shaped 404 instead of throwing a 500 out of bareRepoDir.
+  const SEG = /^[A-Za-z0-9_.-]+$/;
+  if (!SEG.test(owner) || !SEG.test(name) || owner === '.' || owner === '..' || name === '.' || name === '..') return null;
+  const repo = `${owner}/${name}`;
+  if (m[3] === 'info/refs') return method === 'GET' ? { kind: 'info-refs', repo } : null;
+  if (method !== 'POST') return null;
+  return m[3] === 'git-upload-pack' ? { kind: 'upload-pack', repo } : { kind: 'receive-pack', repo };
+}
+
+export type GitSmartHttpResponse = {
+  status: number;
+  contentType: string;
+  body: Uint8Array;
+  /** push webhook events (receive-pack only) — the caller emits them via emitGithubEvent. */
+  webhooks: GithubWriteEvent[];
+};
+
+// One pkt-line: 4-byte hex length (including the length itself) + payload (gitprotocol-common(5)).
+function pktLine(payload: string): Buffer {
+  const data = Buffer.from(payload, 'utf8');
+  return Buffer.concat([Buffer.from((data.length + 4).toString(16).padStart(4, '0'), 'utf8'), data]);
+}
+const FLUSH_PKT = Buffer.from('0000', 'utf8');
+
+function plain(status: number, message: string): GitSmartHttpResponse {
+  return { status, contentType: 'text/plain; charset=utf-8', body: Buffer.from(`${message}\n`, 'utf8'), webhooks: [] };
+}
+
+/** The vendor-shaped miss: git clients render a 404 here as "repository not found". */
+function repoNotFound(): GitSmartHttpResponse {
+  return plain(404, 'Repository not found.');
+}
+
+// The bare repo must exist to be served. A repo the CONTROL plane knows (created via REST
+// before the git plane existed, or pulled from real GitHub) is materialized on first
+// protocol contact — creating a repo via REST initializes its bare repo either way.
+function resolveRepoDir(repo: string, root?: string): string | null {
+  if (hasBareRepo(repo, root)) return bareRepoDir(repo, root);
+  const known = githubState(root).repos.find((r) => r.full_name === repo);
+  if (!known) return null;
+  return ensureBareRepo(repo, root, known.default_branch ?? 'main');
+}
+
+function serviceEnv(gitProtocol?: string): Record<string, string> | undefined {
+  // Protocol v2 negotiation rides the Git-Protocol header end-to-end (gitprotocol-http(5)).
+  return gitProtocol ? { GIT_PROTOCOL: gitProtocol } : undefined;
+}
+
+/**
+ * Handle one git smart-HTTP request. Transport-agnostic (the Bun server bridges Request →
+ * this) so tests and saboteurs hit the same seam the wire does. Returns null for non-git
+ * routes (the caller falls through to the REST handler).
+ */
+export async function handleGithubGitSmartHttp(req: {
+  method: string;
+  pathname: string;
+  query?: URLSearchParams;
+  body?: Uint8Array;
+  root?: string;
+  readOnly?: boolean;
+  /** request Content-Encoding (git clients gzip large POST bodies) */
+  contentEncoding?: string;
+  /** request Git-Protocol header (protocol v2 negotiation) */
+  gitProtocol?: string;
+  occurredAt?: string;
+}): Promise<GitSmartHttpResponse | null> {
+  const route = parseGitSmartHttpPath(req.method, req.pathname);
+  if (!route) return null;
+
+  // ── GET info/refs — the smart service advertisement ─────────────────────────────────────
+  if (route.kind === 'info-refs') {
+    const service = req.query?.get('service') ?? '';
+    if (service !== 'git-upload-pack' && service !== 'git-receive-pack') {
+      // Only the smart protocol is served. 403 is the FIRST-PARTY refusal status: git's own
+      // http-backend answers "403 Forbidden — Dumb HTTP protocol not supported" when dumb
+      // HTTP is disabled (http-backend.c), and GitHub refuses dumb clients the same way.
+      return plain(403, 'Dumb HTTP protocol is not supported: pass ?service=git-upload-pack or ?service=git-receive-pack.');
+    }
+    if (service === 'git-receive-pack' && req.readOnly) return plain(403, 'twin is read-only (mirror mode); pushes are rejected');
+    const dir = resolveRepoDir(route.repo, req.root);
+    if (!dir) return repoNotFound();
+    const cmd = service === 'git-upload-pack' ? 'upload-pack' : 'receive-pack';
+    const res = runGit(dir, [cmd, '--stateless-rpc', '--advertise-refs', '.'], { env: serviceEnv(req.gitProtocol) });
+    if (res.code !== 0) throw new Error(`github twin git plane: \`git ${cmd} --advertise-refs\` failed (exit ${res.code}): ${res.stderr.trim()}`);
+    return {
+      status: 200,
+      contentType: `application/x-${service}-advertisement`,
+      body: Buffer.concat([pktLine(`# service=${service}\n`), FLUSH_PKT, res.stdout]),
+      webhooks: [],
+    };
+  }
+
+  // ── POST git-upload-pack / git-receive-pack — the stateless RPC ─────────────────────────
+  // Read-only refusal comes FIRST on both routes (same ordering as the advertisement): a
+  // mirror answers 403 to a push whether or not the repo exists.
+  if (route.kind === 'receive-pack' && req.readOnly) return plain(403, 'twin is read-only (mirror mode); pushes are rejected');
+  const dir = resolveRepoDir(route.repo, req.root);
+  if (!dir) return repoNotFound();
+  let input: Uint8Array = req.body ?? new Uint8Array();
+  if ((req.contentEncoding ?? '').includes('gzip')) {
+    // Bounded + non-throwing: a malformed or bomb-sized body is the CLIENT's protocol error
+    // (400), never an unhandled 500. 256 MiB comfortably covers any local twin push.
+    try { input = gunzipSync(input, { maxOutputLength: 256 * 1024 * 1024 }); }
+    catch { return plain(400, 'Invalid or oversized gzip request body.'); }
+  }
+  const cmd = route.kind === 'upload-pack' ? 'upload-pack' : 'receive-pack';
+  const before = route.kind === 'receive-pack' ? listGitPlaneRefs(route.repo, req.root) : [];
+  const res = runGit(dir, [cmd, '--stateless-rpc', '.'], { stdin: input, env: serviceEnv(req.gitProtocol) });
+  if (res.code !== 0) {
+    // A garbage/aborted request makes the service exit non-zero. Whatever it managed to say
+    // rides back IN-BAND (that is how the wire reports protocol errors — the client renders
+    // it); with nothing on stdout, answer a 400 naming the failure. Never an unhandled 500.
+    if (res.stdout.length === 0) return plain(400, `git ${cmd} rejected the request: ${res.stderr.trim() || 'protocol error'}`);
+  }
+  const webhooks = route.kind === 'receive-pack'
+    ? await reconcileGitPlaneRefs(route.repo, before, { ...(req.root !== undefined ? { root: req.root } : {}), ...(req.occurredAt !== undefined ? { occurredAt: req.occurredAt } : {}) })
+    : [];
+  return { status: 200, contentType: `application/x-git-${cmd}-result`, body: res.stdout, webhooks };
+}
+
+const ZERO_SHA = '0'.repeat(40);
+
+// Per-write ordinal folded into every reconcile write's fields: the kernel dedupes actions
+// by content + occurredAt millisecond, so a ref REVISITING a value under a pinned clock
+// (force-push A→B→A replayed in one ms) would silently collide with its own earlier action
+// and leave the projection at B while the bare repo says A (docs/ADDING_A_TWIN.md §5 — the
+// upstashredis `rev` pattern). Strictly increasing within the process; harmless extra field.
+let reconcileSeq = 0;
+
+/**
+ * Fold the bare repo's ref changes since `before` into the kernel event log — the SAME
+ * git_ref.* / branch.* operations the Git Data REST writes append, so the control plane and
+ * the git plane converge on one ref record. Returns the `push` webhook events (one per
+ * changed branch/tag ref, GitHub-style ref/before/after).
+ */
+export async function reconcileGitPlaneRefs(
+  repo: string,
+  before: PlaneRef[],
+  opts: { root?: string; occurredAt?: string } = {},
+): Promise<GithubWriteEvent[]> {
+  const root = opts.root;
+  const occurredAt = opts.occurredAt ?? new Date().toISOString();
+  const after = listGitPlaneRefs(repo, root);
+  const beforeBy = new Map(before.map((r) => [r.ref, r]));
+  const afterBy = new Map(after.map((r) => [r.ref, r]));
+  const events: GithubWriteEvent[] = [];
+
+  const branchName = (ref: string): string | null => (ref.startsWith('refs/heads/') ? ref.slice('refs/heads/'.length) : null);
+
+  for (const r of after) {
+    const prev = beforeBy.get(r.ref);
+    if (prev && prev.object_sha === r.object_sha) continue;
+    await applyTwinWrite(SERVICE, {
+      operation: prev ? 'git_ref.update' : 'git_ref.create', subjectType: 'git_ref', subjectId: `gitref:${repo}#${r.ref}`,
+      fields: { repository: repo, ref: r.ref, object_sha: r.object_sha, object_type: r.object_type === 'tag' ? 'tag' : 'commit', rev: ++reconcileSeq },
+      occurredAt, actor: { kind: 'agent' },
+    }, root);
+    const name = branchName(r.ref);
+    if (name) {
+      await applyTwinWrite(SERVICE, {
+        operation: 'branch.create', subjectType: 'branch', subjectId: `branch:${repo}#${name}`,
+        fields: { repository: repo, name, commit_sha: r.object_sha, rev: ++reconcileSeq },
+        occurredAt, actor: { kind: 'agent' },
+      }, root);
+      // GitHub's `synchronize`: a push to a PR's head branch moves the PR head — the old
+      // head's statuses/reviews stop matching (exact-head re-earn).
+      for (const n of await syncPrHeadsToBranchTip(repo, name, r.object_sha, root, occurredAt)) {
+        events.push({ event: 'pull_request', action: 'synchronize', repository: repo, number: n });
+      }
+    }
+    events.push({ event: 'push', action: '', repository: repo, number: 0, ref: r.ref, before: prev?.object_sha ?? ZERO_SHA, after: r.object_sha });
+  }
+  for (const r of before) {
+    if (afterBy.has(r.ref)) continue;
+    await applyTwinWrite(SERVICE, {
+      operation: 'git_ref.delete', subjectType: 'git_ref', subjectId: `gitref:${repo}#${r.ref}`,
+      fields: { repository: repo, ref: r.ref, rev: ++reconcileSeq }, occurredAt, actor: { kind: 'agent' },
+    }, root);
+    const name = branchName(r.ref);
+    if (name) {
+      await applyTwinWrite(SERVICE, {
+        operation: 'branch.delete', subjectType: 'branch', subjectId: `branch:${repo}#${name}`,
+        fields: { repository: repo, name, rev: ++reconcileSeq }, occurredAt, actor: { kind: 'agent' },
+      }, root);
+      // Real GitHub CLOSES an open PR whose head branch is deleted (shared with the REST
+      // DELETE .../git/refs path — both converge on the same helper).
+      for (const n of await closePrsForDeletedBranch(repo, name, root, occurredAt)) {
+        events.push({ event: 'pull_request', action: 'closed', repository: repo, number: n });
+      }
+    }
+    events.push({ event: 'push', action: '', repository: repo, number: 0, ref: r.ref, before: r.object_sha, after: ZERO_SHA });
+  }
+  return events;
+}