testing/github.mjs

Functions

Imports

It imports testing/network.mjs. No module of this repo imports it.

Source

1// A fake of the GitHub API for code that reads and commits files through it. Stubbed at the outbound fetch, not the
2// module, because the module calling GitHub is the subject. The owner, repository and branch are parameters.
3//
4// An unknown host or path THROWS, so nothing can fall through to the live repository. Blob shas are REAL git blob
5// shas, or a provenance check that compares them could not fail. A tree applies only when the ref moves, so a refused
6// save leaves the repository unchanged.
7
8import { installFetch, urlOf } from "./network.mjs";
9
10const API = "https://api.github.com";
11const STUB_HEAD_SHA = "a".repeat(40);
12const encoder = new TextEncoder();
13
14/**
15 * The sha git gives `content` as a blob: SHA-1 over `blob <byte length>\0` and the bytes. The header counts UTF-8
16 * BYTES, not string length.
17 *
18 * @param {string} content
19 * @returns {Promise<string>} lowercase hex
20 */
21export async function gitBlobSha(content) {
22  const body = encoder.encode(content);
23  const header = encoder.encode(`blob ${body.byteLength}\0`);
24  const framed = new Uint8Array(header.byteLength + body.byteLength);
25  framed.set(header, 0);
26  framed.set(body, header.byteLength);
27  const digest = new Uint8Array(await crypto.subtle.digest("SHA-1", framed));
28  return Array.from(digest, (byte) => byte.toString(16).padStart(2, "0")).join("");
29}
30
31/**
32 * @typedef {{ method: string, path: string, body: unknown }} RecordedCall
33 * @typedef {{ sha: string, message: string, author: string, date: string }} HistoryEntry
34 */
35
36/**
37 * Stands up the fake for one repository. By default it is installed as the global fetch; `install: false` leaves the
38 * global alone and the caller passes `fetch` to the code under test.
39 *
40 * @param {{ owner: string, repo: string, branch?: string, files?: Record<string, string>, install?: boolean }} options
41 */
42export function stubGitHub({ owner, repo, branch = "main", files: seed = {}, install = true }) {
43  if (!owner || !repo) throw new Error("stubGitHub needs the owner and repo it stands in for.");
44  const prefix = `/repos/${owner}/${repo}`;
45
46  /** @type {Map<string, string>} */
47  const files = new Map(Object.entries(seed));
48  /** @type {RecordedCall[]} */
49  const calls = [];
50  /** @type {HistoryEntry[]} */
51  const history = [];
52  const head = { commitSha: STUB_HEAD_SHA, treeSha: "tree-initial" };
53  /** @type {Map<string, number>} */
54  const failures = new Map();
55  /** @type {Map<string, string>} */
56  const blobBodies = new Map();
57  /** @type {Array<{ path: string, content: string | null }>} */
58  let pendingTree = [];
59  let commitCounter = 0;
60
61  const json = (/** @type {unknown} */ body, status = 200) =>
62    new Response(JSON.stringify(body), { status, headers: { "content-type": "application/json" } });
63
64  /**
65   * Each recorded endpoint: `path` is matched exactly, or as a prefix when `prefix` is set.
66   *
67   * @type {Array<{ method: string, path: string, prefix?: boolean, handle: (path: string, body: unknown) => Response | Promise<Response> }>}
68   */
69  const routes = [
70    { method: "GET", path: `${prefix}/git/ref/heads/${branch}`, handle: () => json({ object: { sha: head.commitSha } }) },
71    { method: "GET", path: `${prefix}/git/commits/`, prefix: true, handle: () => json({ tree: { sha: head.treeSha } }) },
72    { method: "GET", path: `${prefix}/contents/`, prefix: true, handle: getContents },
73    {
74      method: "GET",
75      path: `${prefix}/commits?`,
76      prefix: true,
77      // With no history planted the listing fails, so a case that reads history has to say what it is.
78      handle: () =>
79        history.length === 0
80          ? json({ message: "no history planted" }, 500)
81          : json(history.map((c) => ({ sha: c.sha, commit: { message: c.message, author: { name: c.author, date: c.date } } }))),
82    },
83    { method: "POST", path: `${prefix}/git/blobs`, handle: postBlob },
84    { method: "POST", path: `${prefix}/git/trees`, handle: postTree },
85    {
86      method: "POST",
87      path: `${prefix}/git/commits`,
88      handle: () => json({ sha: `commit${String(commitCounter).padStart(34, "0")}` }),
89    },
90    { method: "PATCH", path: `${prefix}/git/refs/heads/${branch}`, handle: patchRef },
91  ];
92
93  /** @param {string} path */
94  async function getContents(path) {
95    const target = decodeURI(path.slice(`${prefix}/contents/`.length).split("?")[0] ?? "");
96
97    // A directory answers with an ARRAY of its immediate children and a file with an OBJECT, as GitHub does: a nested
98    // file shows as its folder, `type: "dir"`.
99    const children = [...files.keys()].filter((p) => p.startsWith(`${target}/`));
100    if (!files.has(target) && children.length > 0) {
101      const names = [...new Set(children.map((p) => p.slice(target.length + 1).split("/")[0] ?? ""))];
102      return json(
103        await Promise.all(
104          names.map(async (name) => {
105            const path = `${target}/${name}`;
106            const content = files.get(path);
107            if (content === undefined) return { name, path, sha: await gitBlobSha(""), type: "dir", size: 0 };
108            return { name, path, sha: await gitBlobSha(content), type: "file", size: content.length };
109          }),
110        ),
111      );
112    }
113
114    const content = files.get(target);
115    if (content === undefined) return json({ message: "Not Found" }, 404);
116    const bytes = encoder.encode(content);
117    let binary = "";
118    for (const byte of bytes) binary += String.fromCharCode(byte);
119    return json({ content: btoa(binary), encoding: "base64", sha: await gitBlobSha(content), size: bytes.byteLength });
120  }
121
122  /** @param {string} _path @param {unknown} body */
123  async function postBlob(_path, body) {
124    const { content } = /** @type {{ content: string }} */ (body);
125    const sha = await gitBlobSha(content);
126    blobBodies.set(sha, content);
127    return json({ sha });
128  }
129
130  /** @param {string} _path @param {unknown} body */
131  function postTree(_path, body) {
132    const { tree } = /** @type {{ tree: Array<{ path: string, sha: string | null }> }} */ (body);
133    pendingTree = tree.map((entry) => {
134      if (entry.sha === null) return { path: entry.path, content: null };
135      const content = blobBodies.get(entry.sha);
136      if (content === undefined) {
137        throw new Error(`the tree names blob ${entry.sha}, which no recorded blob POST created.`);
138      }
139      return { path: entry.path, content };
140    });
141    commitCounter += 1;
142    return json({ sha: `tree-${commitCounter}` });
143  }
144
145  /** @param {string} _path @param {unknown} body */
146  function patchRef(_path, body) {
147    const { sha } = /** @type {{ sha: string }} */ (body);
148    for (const entry of pendingTree) {
149      if (entry.content === null) files.delete(entry.path);
150      else files.set(entry.path, entry.content);
151    }
152    pendingTree = [];
153    head.commitSha = sha;
154    head.treeSha = `tree-after-${sha}`;
155    return json({ object: { sha } });
156  }
157
158  /** @type {typeof fetch} */
159  const stub = async (input, init) => {
160    const url = urlOf(input);
161    if (!url.startsWith(API)) {
162      throw new Error(
163        `the GitHub stub refuses ${url}: this layer never reaches the network. ` +
164          `If a new outbound call is legitimate, record its shape in the stub.`,
165      );
166    }
167
168    const method = (init?.method ?? "GET").toUpperCase();
169    const path = url.slice(API.length);
170    const rawBody = typeof init?.body === "string" ? init.body : null;
171    const body = rawBody ? JSON.parse(rawBody) : null;
172    calls.push({ method, path, body });
173
174    for (const [fragment, remaining] of failures) {
175      if (remaining > 0 && path.includes(fragment)) {
176        failures.set(fragment, remaining - 1);
177        return json({ message: `planted failure on ${fragment}` }, 500);
178      }
179    }
180
181    const route = routes.find((r) => r.method === method && (r.prefix ? path.startsWith(r.path) : path === r.path));
182    if (route) return route.handle(path, body);
183
184    throw new Error(
185      `the GitHub stub has no recorded shape for ${method} ${path}. Record it rather than letting the call through.`,
186    );
187  };
188
189  const restore = install ? installFetch(stub) : () => {};
190
191  return {
192    calls,
193    files,
194    history,
195    /** Fail the next `times` requests whose path contains `fragment`, with a 500. */
196    failNext: (/** @type {string} */ fragment, /** @type {number} */ times) => void failures.set(fragment, times),
197    fetch: stub,
198    restore,
199  };
200}
201
202/**
203 * The blob sha of a file as the stub holds it now: what a caller that versions files by blob sha would send back.
204 *
205 * @param {{ files: Map<string, string> }} stub
206 * @param {string} path
207 */
208export const versionOf = async (stub, path) => {
209  const content = stub.files.get(path);
210  if (content === undefined) throw new Error(`versionOf: ${path} is not in the stub`);
211  return gitBlobSha(content);
212};