@intentius/chant-lexicon-terraform 0.124.52 → 0.124.55

package/src/registry/targets/fake-hcp.ts

@@ -0,0 +1,233 @@
+/**
+ * An in-memory stand-in for HCP Terraform's private module registry
+ * (chant#4604), for the HCP module target's tests. It is a fetch function:
+ * nothing listens on a port and nothing leaves the process, and no HCP
+ * account or call is involved.
+ *
+ * It answers the calls the API docs give
+ * (developer.hashicorp.com/terraform/cloud-docs/api-docs/private-registry/modules):
+ *
+ *   GET  /api/v2/organizations/:org/registry-modules/private/:org/:name/:provider   attributes.version-statuses
+ *   POST /api/v2/organizations/:org/registry-modules                                 201, 422 when it exists
+ *   POST /api/v2/organizations/:org/registry-modules/private/:org/:name/:provider/versions   201 with links.upload, 422 when it exists
+ *   PUT  https://archivist.terraform.io/v1/object/<id>                               the gzip tarball
+ *
+ * and the registry protocol Terraform installs through:
+ *
+ *   GET  /.well-known/terraform.json            {"modules.v1": "/api/registry/v1/modules/"}
+ *   GET  /api/registry/v1/modules/:org/:name/:provider/:version/download   204, X-Terraform-Get
+ *   GET  https://archivist.terraform.io/v1/object/<id>                     the tarball
+ *
+ * A token the fake does not know gets 401. A known token without Manage
+ * modules, or any token when the organization has no entitlement, gets 404
+ * from the registry calls, as HCP answers. A version is `pending` once
+ * created, and turns `ok` after its tarball is uploaded and the module has
+ * been read `parseAfterReads` more times. `throttle(n)` answers the next n
+ * requests with 429. Every request is kept, headers and body included.
+ */
+import { gunzipSync } from "node:zlib";
+
+export interface FakeHcpRequest {
+  method: string;
+  url: string;
+  /** Header names lower-cased. */
+  headers: Record<string, string>;
+  body?: Uint8Array;
+}
+
+export interface FakeHcpOptions {
+  /** Default app.terraform.io. */
+  host?: string;
+  organization: string;
+  /** Tokens the fake knows, and whether each one's team has Manage modules. */
+  tokens: Record<string, { manageModules: boolean }>;
+  /** Whether the organization has the private registry. Default true. */
+  entitled?: boolean;
+  /** Module reads after an upload before the version is `ok`. Default 0; Infinity keeps it pending. */
+  parseAfterReads?: number;
+}
+
+interface FakeVersion {
+  status: string;
+  commitSha: string | null;
+  archive?: Uint8Array;
+  object: string;
+  readsLeft: number;
+}
+
+export type FakeHcpFetch = (url: string, init?: { method?: string; headers?: unknown; body?: unknown }) => Promise<Response>;
+
+export interface FakeHcp {
+  fetch: FakeHcpFetch;
+  requests: FakeHcpRequest[];
+  /** Modules by `<name>/<provider>`, each with its versions. */
+  modules: Map<string, Map<string, FakeVersion>>;
+  /** Put a module, and a version with its archive, in directly. Status `ok` unless given. */
+  seed(name: string, provider: string, version?: { version: string; archive: Uint8Array; status?: string }): void;
+  /** Answer the next `n` requests with 429, carrying `Retry-After` when it is given. */
+  throttle(n: number, retryAfter?: string): void;
+}
+
+export const ARCHIVIST = "archivist.terraform.io";
+
+function headersOf(h: unknown): Record<string, string> {
+  const out: Record<string, string> = {};
+  if (!h) return out;
+  if (typeof (h as Headers).forEach === "function" && typeof (h as Headers).get === "function") {
+    (h as Headers).forEach((v, k) => (out[k.toLowerCase()] = v));
+    return out;
+  }
+  for (const [k, v] of Object.entries(h as Record<string, string>)) out[k.toLowerCase()] = String(v);
+  return out;
+}
+
+function bodyOf(b: unknown): Uint8Array | undefined {
+  if (b === undefined || b === null) return undefined;
+  if (typeof b === "string") return new TextEncoder().encode(b);
+  if (b instanceof Uint8Array) return b;
+  if (b instanceof ArrayBuffer) return new Uint8Array(b);
+  throw new Error("the fake takes a string or bytes as a body");
+}
+
+const doc = (status: number, body: unknown) => new Response(JSON.stringify(body), { status, headers: { "content-type": "application/vnd.api+json" } });
+const errors = (status: number, title: string) => doc(status, { errors: [{ status: String(status), title }] });
+
+export function createFakeHcp(o: FakeHcpOptions): FakeHcp {
+  const host = o.host ?? "app.terraform.io";
+  const org = o.organization;
+  const requests: FakeHcpRequest[] = [];
+  const modules = new Map<string, Map<string, FakeVersion>>();
+  const objects = new Map<string, { module: string; version: string }>();
+  let throttled = 0;
+  let throttleAfter: string | undefined;
+  let next = 0;
+
+  const newVersion = (module: string, version: string, status: string, commitSha: string | null, archive?: Uint8Array): FakeVersion => {
+    const object = `obj${++next}`;
+    objects.set(object, { module, version });
+    return { status, commitSha, object, readsLeft: o.parseAfterReads ?? 0, ...(archive ? { archive } : {}) };
+  };
+  const seed: FakeHcp["seed"] = (name, provider, version) => {
+    const key = `${name}/${provider}`;
+    const vs = modules.get(key) ?? new Map<string, FakeVersion>();
+    modules.set(key, vs);
+    if (version) vs.set(version.version, newVersion(key, version.version, version.status ?? "ok", null, version.archive));
+  };
+
+  const moduleDoc = (name: string, provider: string, vs: Map<string, FakeVersion>) =>
+    doc(200, {
+      data: {
+        id: `mod-${name}-${provider}`,
+        type: "registry-modules",
+        attributes: {
+          name,
+          provider,
+          namespace: org,
+          "registry-name": "private",
+          status: vs.size ? "setup_complete" : "pending",
+          "version-statuses": [...vs.entries()].map(([version, v]) => ({ version, status: v.status })),
+        },
+      },
+    });
+
+  const fetch: FakeHcpFetch = async (url, init = {}) => {
+    const method = (init.method ?? "GET").toUpperCase();
+    const headers = headersOf(init.headers);
+    const body = bodyOf(init.body);
+    requests.push({ method, url, headers, ...(body ? { body } : {}) });
+    if (throttled > 0) {
+      throttled--;
+      return new Response(JSON.stringify({ errors: [{ status: "429", title: "Too Many Requests" }] }), { status: 429, headers: throttleAfter !== undefined ? { "retry-after": throttleAfter } : {} });
+    }
+    const u = new URL(url);
+
+    if (u.host === ARCHIVIST) {
+      const id = /^\/v1\/object\/([^/]+)$/.exec(u.pathname)?.[1];
+      const ref = id ? objects.get(id) : undefined;
+      if (!ref) return errors(404, "not found");
+      const v = modules.get(ref.module)!.get(ref.version)!;
+      if (method === "PUT") {
+        if (headers["content-type"] !== "application/octet-stream") return errors(400, "content type");
+        if (!body) return errors(400, "no body");
+        try {
+          gunzipSync(body);
+        } catch {
+          v.status = "reg_ingress_failed";
+          return new Response(null, { status: 200 });
+        }
+        v.archive = body;
+        if (v.readsLeft <= 0) v.status = "ok";
+        return new Response(null, { status: 200 });
+      }
+      if (method === "GET") return v.archive ? new Response(new Uint8Array(v.archive), { status: 200 }) : errors(404, "not found");
+      return errors(405, "method");
+    }
+    if (u.host !== host) throw new TypeError(`fetch failed: the fake answers only ${host} and ${ARCHIVIST}, not ${u.host}`);
+
+    if (method === "GET" && u.pathname === "/.well-known/terraform.json") return new Response(JSON.stringify({ "modules.v1": "/api/registry/v1/modules/" }), { status: 200 });
+
+    const bearer = /^Bearer (.+)$/i.exec(headers.authorization ?? "")?.[1];
+    if (!bearer || !o.tokens[bearer]) return errors(401, "unauthorized");
+    const allowed = o.tokens[bearer]!.manageModules && o.entitled !== false;
+
+    const proto = /^\/api\/registry\/v1\/modules\/([^/]+)\/([^/]+)\/([^/]+)\/([^/]+)\/download$/.exec(u.pathname);
+    if (proto && method === "GET") {
+      if (proto[1] !== org || o.entitled === false) return errors(404, "not found");
+      const v = modules.get(`${proto[2]}/${proto[3]}`)?.get(proto[4]!);
+      if (!v || v.status !== "ok") return errors(404, "not found");
+      return new Response(null, { status: 204, headers: { "X-Terraform-Get": `https://${ARCHIVIST}/v1/object/${v.object}` } });
+    }
+
+    const base = `/api/v2/organizations/${org}/registry-modules`;
+    if (!u.pathname.startsWith(base)) return errors(404, "not found");
+    if (!allowed) return errors(404, "not found");
+
+    if (method === "POST" && u.pathname === base) {
+      const d = JSON.parse(new TextDecoder().decode(body ?? new Uint8Array())) as { data?: { type?: string; attributes?: Record<string, unknown> } };
+      const a = d.data?.attributes ?? {};
+      if (d.data?.type !== "registry-modules" || typeof a.name !== "string" || typeof a.provider !== "string" || a["registry-name"] !== "private") return errors(422, "malformed");
+      const key = `${a.name}/${a.provider}`;
+      if (modules.has(key)) return errors(422, "Name has already been taken");
+      modules.set(key, new Map());
+      return doc(201, { data: { type: "registry-modules", attributes: { name: a.name, provider: a.provider } } });
+    }
+
+    const m = /^\/private\/([^/]+)\/([^/]+)\/([^/]+)(\/versions)?$/.exec(u.pathname.slice(base.length));
+    if (!m || m[1] !== org) return errors(404, "not found");
+    const key = `${m[2]}/${m[3]}`;
+    const vs = modules.get(key);
+    if (!vs) return errors(404, "not found");
+
+    if (!m[4] && method === "GET") {
+      for (const v of vs.values()) {
+        if (v.status === "pending" && v.archive) {
+          if (v.readsLeft <= 0) v.status = "ok";
+          else v.readsLeft--;
+        }
+      }
+      return moduleDoc(m[2]!, m[3]!, vs);
+    }
+    if (m[4] && method === "POST") {
+      const d = JSON.parse(new TextDecoder().decode(body ?? new Uint8Array())) as { data?: { type?: string; attributes?: { version?: unknown; "commit-sha"?: unknown } } };
+      const version = d.data?.attributes?.version;
+      if (d.data?.type !== "registry-module-versions" || typeof version !== "string") return errors(422, "malformed");
+      if (vs.has(version)) return errors(422, "Version has already been taken");
+      const sha = d.data.attributes?.["commit-sha"];
+      const v = newVersion(key, version, "pending", typeof sha === "string" ? sha : null);
+      vs.set(version, v);
+      return doc(201, { data: { type: "registry-module-versions", attributes: { version, status: "pending", source: "tfe-api", "commit-sha": v.commitSha }, links: { upload: `https://${ARCHIVIST}/v1/object/${v.object}` } } });
+    }
+    return errors(405, "method");
+  };
+
+  return {
+    fetch,
+    requests,
+    modules,
+    seed,
+    throttle(n, retryAfter) {
+      throttled = n;
+      throttleAfter = retryAfter;
+    },
+  };
+}

package/src/registry/targets/fake-http.ts

@@ -0,0 +1,97 @@
+/**
+ * Pieces the in-memory host fakes share (chant#4605): reading a request's
+ * headers and body as a fetch caller passes them, JSON answers, basic and
+ * bearer header parsing, and a module tarball builder, so a test (in chant
+ * or in terragucci#1302) can make a real attested archive to publish.
+ */
+import { gzipSync } from "node:zlib";
+
+/** One request a fake was sent. */
+export interface FakeRequest {
+  method: string;
+  url: string;
+  /** Header names lower-cased. */
+  headers: Record<string, string>;
+  body?: Uint8Array;
+}
+
+/** The fetch a fake answers: both the target's `fetch` and the reader's `registryFetch`. */
+export type FakeFetch = (url: string, init?: { method?: string; headers?: unknown; body?: unknown }) => Promise<Response>;
+
+export function headersOf(h: unknown): Record<string, string> {
+  const out: Record<string, string> = {};
+  if (!h) return out;
+  if (typeof (h as Headers).forEach === "function" && typeof (h as Headers).get === "function") {
+    (h as Headers).forEach((v, k) => (out[k.toLowerCase()] = v));
+    return out;
+  }
+  for (const [k, v] of Object.entries(h as Record<string, string>)) out[k.toLowerCase()] = String(v);
+  return out;
+}
+
+export function bodyOf(b: unknown): Uint8Array | undefined {
+  if (b === undefined || b === null) return undefined;
+  if (typeof b === "string") return new TextEncoder().encode(b);
+  if (b instanceof Uint8Array) return b;
+  if (b instanceof ArrayBuffer) return new Uint8Array(b);
+  throw new Error("the fake takes a string or bytes as a body");
+}
+
+export const jsonAnswer = (status: number, doc: unknown): Response => new Response(JSON.stringify(doc), { status, headers: { "content-type": "application/json" } });
+
+/** The user and password of a `Basic` header, or undefined. */
+export function basicOf(authorization: string | undefined): { user: string; password: string } | undefined {
+  const m = /^Basic (.+)$/i.exec(authorization ?? "");
+  if (!m) return undefined;
+  const text = Buffer.from(m[1]!, "base64").toString("utf-8");
+  const at = text.indexOf(":");
+  return at < 0 ? undefined : { user: text.slice(0, at), password: text.slice(at + 1) };
+}
+
+/** The token of a `Bearer` header, or undefined. */
+export const bearerOf = (authorization: string | undefined): string | undefined => /^Bearer (.+)$/i.exec(authorization ?? "")?.[1];
+
+/** A ustar header block for one entry. */
+function tarHeader(path: string, size: number, type: "0" | "5", mode: number, mtime: number): Buffer {
+  const h = Buffer.alloc(512);
+  const put = (text: string, at: number, len: number) => h.write(text.slice(0, len), at, len, "utf-8");
+  const oct = (n: number, len: number) => n.toString(8).padStart(len - 1, "0") + "\0";
+  put(path, 0, 100);
+  put(oct(mode, 8), 100, 8);
+  put(oct(0, 8), 108, 8);
+  put(oct(0, 8), 116, 8);
+  put(oct(size, 12), 124, 12);
+  put(oct(mtime, 12), 136, 12);
+  h.fill(0x20, 148, 156);
+  h.write(type, 156, 1, "latin1");
+  put("ustar\0", 257, 6);
+  put("00", 263, 2);
+  let sum = 0;
+  for (const b of h) sum += b;
+  put(sum.toString(8).padStart(6, "0") + "\0 ", 148, 8);
+  return h;
+}
+
+/**
+ * A module tarball as the bucket registry serves one: a gzip of a ustar
+ * archive with the given files at its root (paths under 100 bytes), each
+ * directory written before its files.
+ */
+export function moduleTarball(files: Record<string, string | Uint8Array>, mtime = 1_700_000_000): Buffer {
+  const blocks: Buffer[] = [];
+  const dirs = new Set<string>();
+  for (const path of Object.keys(files).sort()) {
+    const parts = path.split("/");
+    for (let i = 1; i < parts.length; i++) {
+      const dir = parts.slice(0, i).join("/");
+      if (dirs.has(dir)) continue;
+      dirs.add(dir);
+      blocks.push(tarHeader(`${dir}/`, 0, "5", 0o755, mtime));
+    }
+    const raw = files[path]!;
+    const data = typeof raw === "string" ? Buffer.from(raw, "utf-8") : Buffer.from(raw);
+    blocks.push(tarHeader(path, data.length, "0", 0o644, mtime), data, Buffer.alloc((512 - (data.length % 512)) % 512));
+  }
+  blocks.push(Buffer.alloc(1024));
+  return gzipSync(Buffer.concat(blocks));
+}

package/src/registry/targets/fake-nexus.ts

@@ -0,0 +1,152 @@
+/**
+ * An in-memory stand-in for a Sonatype Nexus Repository hosted Terraform
+ * repository (chant#4605), for the Nexus module target's tests here and in
+ * terragucci#1302. It is a fetch function: nothing listens on a port and
+ * nothing leaves the process.
+ *
+ * It answers the calls terragucci#1299's research found in Sonatype's docs,
+ * under `/repository/<repo>/`:
+ *
+ *   PUT  v1/modules/<ns>/<name>/<system>/<version>/<file>      basic credentials, the archive as the body
+ *   GET  v1/modules/<ns>/<name>/<system>/<version>/<file>
+ *   GET  v1/modules/<ns>/<name>/<system>/versions
+ *   GET  v1/modules/<ns>/<name>/<system>/<version>/download    204, X-Terraform-Get
+ *   GET  v1/api/token                                            the 3.95 bearer token, for basic credentials
+ *
+ * There is no `/.well-known/terraform.json`: a Nexus repository is reached
+ * through a CLI `host` block. Without credentials every call gets 401.
+ * `bearer: false` drops the token call (Nexus before 3.95), and reads then
+ * take basic credentials only. A body that is not a zip or a gzip holding a
+ * `.tf` file gets 400, and an upload over a version already held gets 400,
+ * as a deployment policy that disallows redeploy does, unless `redeploy` is
+ * set. `cacheNotFound` keeps a new version's versions list answering 404 for
+ * that many reads, as Nexus before 3.95 kept a "not found" in its cache.
+ * Every request is kept, headers and body included.
+ */
+import { gunzipSync } from "node:zlib";
+import { readZip } from "./zip";
+import { basicOf, bearerOf, bodyOf, headersOf, jsonAnswer, type FakeFetch, type FakeRequest } from "./fake-http";
+
+export interface FakeNexusOptions {
+  /** The host, such as `nexus.example.com`. */
+  host: string;
+  /** The hosted Terraform repositories' names. */
+  repos: string[];
+  /** Users (or user token name codes) and their passwords (or pass codes). */
+  users: Record<string, string>;
+  /** Whether the 3.95 token call is there. Default true. */
+  bearer?: boolean;
+  /** Whether an upload over a held version is taken. Default false: 400. */
+  redeploy?: boolean;
+  /** How many versions reads a new version answers 404 for. Default 0. */
+  cacheNotFound?: number;
+}
+
+export interface FakeNexus {
+  fetch: FakeFetch;
+  requests: FakeRequest[];
+  /** Uploaded assets, keyed `<repo>/<ns>/<name>/<system>/<version>/<file>`. */
+  assets: Map<string, Uint8Array>;
+  /** Bearer tokens the token call issued. */
+  issued: Set<string>;
+  /** Put an asset in directly, as an upload by hand would. */
+  seed(repo: string, ns: string, name: string, system: string, version: string, file: string, bytes: Uint8Array): void;
+}
+
+const holdsTf = (body: Uint8Array): boolean => {
+  if (body[0] === 0x50 && body[1] === 0x4b) return readZip(body).entries.some((e) => !e.dir && e.path.endsWith(".tf"));
+  if (body[0] === 0x1f && body[1] === 0x8b) return gunzipSync(body).includes(Buffer.from(".tf"));
+  return false;
+};
+
+export function createFakeNexus(o: FakeNexusOptions): FakeNexus {
+  const requests: FakeRequest[] = [];
+  const assets = new Map<string, Uint8Array>();
+  const issued = new Set<string>();
+  const cached = new Map<string, number>();
+
+  const userOf = (headers: Record<string, string>): string | undefined => {
+    const b = basicOf(headers.authorization);
+    return b && o.users[b.user] === b.password ? b.user : undefined;
+  };
+  const mayRead = (headers: Record<string, string>): boolean => {
+    if (userOf(headers)) return true;
+    const bearer = bearerOf(headers.authorization);
+    return o.bearer !== false && bearer !== undefined && issued.has(bearer);
+  };
+  const versionOf = (key: string) => key.split("/").slice(0, 5).join("/");
+
+  const seed: FakeNexus["seed"] = (repo, ns, name, system, version, file, bytes) => void assets.set(`${repo}/${ns}/${name}/${system}/${version}/${file}`, bytes);
+
+  const fetch: FakeFetch = async (url, init = {}) => {
+    const method = (init.method ?? "GET").toUpperCase();
+    const headers = headersOf(init.headers);
+    const body = bodyOf(init.body);
+    requests.push({ method, url, headers, ...(body ? { body } : {}) });
+    const u = new URL(url);
+    if (u.host !== o.host) throw new TypeError(`fetch failed: the fake answers only ${o.host}, not ${u.host}`);
+    const m = /^\/repository\/([^/]+)\/(.*)$/.exec(u.pathname);
+    if (!m || !o.repos.includes(decodeURIComponent(m[1]!))) return jsonAnswer(404, { message: "Not Found" });
+    const repo = decodeURIComponent(m[1]!);
+    const rest = m[2]!.split("/").map(decodeURIComponent);
+
+    if (rest.join("/") === "v1/api/token") {
+      if (method !== "GET" || o.bearer === false) return jsonAnswer(404, { message: "Not Found" });
+      const user = userOf(headers);
+      if (!user) return jsonAnswer(401, { message: "Unauthorized" });
+      const token = `TerraformBearerToken.fake-${user}-${issued.size + 1}`;
+      issued.add(token);
+      return jsonAnswer(200, { token });
+    }
+    if (rest[0] !== "v1" || rest[1] !== "modules") return jsonAnswer(404, { message: "Not Found" });
+    const [ns, name, system] = rest.slice(2, 5);
+    const prefix = `${repo}/${ns}/${name}/${system}/`;
+    const tail = rest.slice(5);
+
+    if (method === "PUT") {
+      if (tail.length !== 2) return jsonAnswer(404, { message: "Not Found" });
+      if (!userOf(headers)) return jsonAnswer(401, { message: "Unauthorized" });
+      if (!body || body.length === 0) return jsonAnswer(400, { message: "empty body" });
+      let ok = false;
+      try {
+        ok = holdsTf(body);
+      } catch {
+        ok = false;
+      }
+      if (!ok) return jsonAnswer(400, { message: "the archive must be a .zip, .tar.gz or .tgz holding .tf files" });
+      const k = `${prefix}${tail[0]}/${tail[1]}`;
+      const held = [...assets.keys()].some((a) => versionOf(a) === versionOf(k));
+      if (held && !o.redeploy) return jsonAnswer(400, { message: "Repository does not allow updating assets" });
+      assets.set(k, body);
+      if (o.cacheNotFound) cached.set(`${prefix}`, o.cacheNotFound);
+      return new Response(null, { status: 201 });
+    }
+    if (method !== "GET") return jsonAnswer(405, { message: "Method Not Allowed" });
+    if (!mayRead(headers)) return jsonAnswer(401, { message: "Unauthorized" });
+
+    if (tail.length === 1 && tail[0] === "versions") {
+      const left = cached.get(prefix) ?? 0;
+      if (left > 0) {
+        cached.set(prefix, left - 1);
+        return jsonAnswer(404, { message: "Not Found" });
+      }
+      const versions = [...new Set([...assets.keys()].filter((k) => k.startsWith(prefix)).map((k) => k.slice(prefix.length).split("/")[0]!))];
+      if (versions.length === 0) return jsonAnswer(404, { message: "Not Found" });
+      return jsonAnswer(200, { modules: [{ versions: versions.map((version) => ({ version })) }] });
+    }
+    if (tail.length === 2 && tail[1] === "download") {
+      const asset = [...assets.keys()].find((k) => k.startsWith(`${prefix}${tail[0]}/`));
+      if (!asset) return jsonAnswer(404, { message: "Not Found" });
+      const file = asset.slice(`${prefix}${tail[0]}/`.length);
+      return new Response(null, { status: 204, headers: { "X-Terraform-Get": `${u.origin}/repository/${repo}/v1/modules/${ns}/${name}/${system}/${tail[0]}/${file}` } });
+    }
+    if (tail.length === 2) {
+      const stored = assets.get(`${prefix}${tail[0]}/${tail[1]}`);
+      if (!stored) return jsonAnswer(404, { message: "Not Found" });
+      return new Response(new Uint8Array(stored), { status: 200, headers: { "content-type": "application/octet-stream" } });
+    }
+    return jsonAnswer(404, { message: "Not Found" });
+  };
+
+  return { fetch, requests, assets, issued, seed };
+}