@intentius/chant-lexicon-terraform 0.124.54 → 0.124.56

package/dist/registry/mirror.js

@@ -0,0 +1,319 @@
+/**
+ * A provider network mirror served from the module registry's bucket
+ * (chant#4564), and the lock-file grouping terragucci's image recipe uses for
+ * its `filesystem_mirror` (moved from terragucci `image-recipe.ts:225-232`,
+ * 18f6431595), so both build from one implementation.
+ *
+ * The network mirror protocol is the layout `providers mirror` writes, served
+ * over HTTPS (https://developer.hashicorp.com/terraform/internals/provider-network-mirror-protocol):
+ *
+ *   <host>/<namespace>/<type>/index.json        {"versions": {"<v>": {}}}
+ *   <host>/<namespace>/<type>/<v>.json          {"archives": {"<os>_<arch>": {"url": ..., "hashes": ["h1:...", "zh:..."]}}}
+ *   <host>/<namespace>/<type>/terraform-provider-<type>_<v>_<os>_<arch>.zip
+ *
+ * `buildMirror` writes one module per distinct lock file, each holding its
+ * providers at exactly the locked version beside that lock file, and runs
+ * `providers mirror` on each for the platforms asked for, so the lock file's
+ * hashes check every download. `uploadMirror` puts the result under the
+ * registry's prefix at `providers/`, archives first and `index.json` last, and
+ * merges each `index.json` with the one already in the bucket.
+ *
+ * Lock files keep the host the provider came from. A hostless source resolves
+ * to registry.terraform.io under Terraform and to registry.opentofu.org under
+ * OpenTofu and choudoufu, so by default each provider locked on one of those
+ * two hosts is mirrored under the other as well.
+ */
+import { spawnSync } from "node:child_process";
+import { existsSync, mkdirSync, mkdtempSync, readdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join, posix, relative } from "node:path";
+import { keyFor } from "./address.js";
+import { PROVIDER_MIRROR_PREFIX } from "./mirror-paths.js";
+export { PROVIDER_MIRROR_PREFIX, isMirrorVersionPath } from "./mirror-paths.js";
+export const LOCK_FILE = ".terraform.lock.hcl";
+/** The two hosts a hostless provider source resolves to. */
+export const TERRAFORM_REGISTRY = "registry.terraform.io";
+export const OPENTOFU_REGISTRY = "registry.opentofu.org";
+/** Directories a lock file is never looked for in: caches and what init or a package manager writes. */
+const SKIP = new Set([".git", ".terraform", ".terragrunt-cache", "node_modules", "cdktf.out", ".terragucci"]);
+/** Every provider in a lock file, by its full address, with its version. */
+export function readLock(text) {
+    const out = new Map();
+    for (const m of text.matchAll(/provider\s+"([^"]+)"\s*\{([^}]*)\}/g)) {
+        const v = /\bversion\s*=\s*"([^"]+)"/.exec(m[2]);
+        if (v)
+            out.set(m[1], v[1]);
+    }
+    return out;
+}
+/** The repo's lock files, as `/`-separated paths relative to the repo, sorted. */
+export function lockFiles(repo) {
+    const out = [];
+    const walk = (dir) => {
+        let names;
+        try {
+            names = readdirSync(dir);
+        }
+        catch {
+            return;
+        }
+        for (const n of names) {
+            const p = join(dir, n);
+            if (n === LOCK_FILE) {
+                out.push(posix.normalize(relative(repo, p).split("\\").join("/")));
+                continue;
+            }
+            if (SKIP.has(n))
+                continue;
+            let dirLike = false;
+            try {
+                dirLike = statSync(p).isDirectory();
+            }
+            catch {
+                dirLike = false;
+            }
+            if (dirLike)
+                walk(p);
+        }
+    };
+    walk(repo);
+    return out.sort();
+}
+/** Every provider every lock file pins. */
+export function lockEntries(repo, files = lockFiles(repo)) {
+    return files.flatMap((lock) => [...readLock(readFileSync(join(repo, lock), "utf-8"))].map(([address, version]) => ({ lock, address, version })));
+}
+const byKey = ([a], [b]) => (a < b ? -1 : a > b ? 1 : 0);
+/** The repo's lock files grouped by what they pin; a lock file that pins nothing is left out. */
+export function mirrorGroups(repo, locks = lockFiles(repo)) {
+    const groups = new Map();
+    for (const lock of locks) {
+        const text = readFileSync(join(repo, lock), "utf-8");
+        const providers = readLock(text);
+        if (providers.size === 0)
+            continue;
+        const key = [...providers].sort(byKey).map(([a, v]) => `${a}=${v}`).join("\n");
+        const g = groups.get(key);
+        if (g)
+            g.locks.push(lock);
+        else
+            groups.set(key, { locks: [lock], text, providers });
+    }
+    return [...groups.values()];
+}
+/** The other default host's address for a provider locked on one of them, or undefined. */
+export function otherHostAddress(address) {
+    const [host, ...rest] = address.split("/");
+    if (rest.length !== 2)
+        return undefined;
+    const h = host.toLowerCase();
+    if (h === TERRAFORM_REGISTRY)
+        return [OPENTOFU_REGISTRY, ...rest].join("/");
+    if (h === OPENTOFU_REGISTRY)
+        return [TERRAFORM_REGISTRY, ...rest].join("/");
+    return undefined;
+}
+/**
+ * One module per group: `versions.tf` holding each provider at exactly its
+ * locked version, and the lock file beside it so `providers mirror` checks the
+ * hashes. With `bothHosts`, the other default host's address is required too;
+ * the lock file does not name it, so its download is checked by that
+ * registry's signature alone.
+ */
+export function mirrorModules(groups, options = {}) {
+    const base = options.dir ?? "mirror";
+    const files = [];
+    groups.forEach((g, i) => {
+        const dir = `${base}/${String(i + 1).padStart(2, "0")}`;
+        const wanted = new Map(g.providers);
+        if (options.bothHosts) {
+            for (const [address, version] of g.providers) {
+                const other = otherHostAddress(address);
+                if (other && ![...wanted.keys()].some((a) => a.toLowerCase() === other.toLowerCase()))
+                    wanted.set(other, version);
+            }
+        }
+        const required = [...wanted].sort(byKey).map(([address, version], n) => `    p${n} = { source = "${address}", version = "= ${version}" }`);
+        files.push({
+            path: `${dir}/versions.tf`,
+            content: [`# The providers ${g.locks.join(", ")} lock${g.locks.length === 1 ? "s" : ""}, each at exactly its locked version.`, "terraform {", "  required_providers {", ...required, "  }", "}", ""].join("\n"),
+        });
+        files.push({ path: `${dir}/${LOCK_FILE}`, content: g.text });
+    });
+    return files;
+}
+/** A platform as the binaries name it, `linux_amd64`, from that form or Docker's `linux/amd64`. */
+export function binaryPlatform(platform) {
+    const p = platform.trim().toLowerCase().replace("/", "_");
+    if (!/^[a-z0-9]+_[a-z0-9]+$/.test(p))
+        throw new Error(`${platform}: name a platform as os_arch or os/arch, such as linux_amd64`);
+    return p;
+}
+/** The platform this process runs on, as the binaries name it. */
+export function hostPlatform(platform = process.platform, arch = process.arch) {
+    const a = arch === "x64" ? "amd64" : arch === "ia32" ? "386" : arch;
+    return `${platform}_${a}`;
+}
+/**
+ * Whether a mirror directory holds the provider at the version for the
+ * platform, in either layout a `filesystem_mirror` reads: packed (what
+ * `providers mirror` writes, a zip per platform) or unpacked (a directory per
+ * platform).
+ */
+export function mirrorHas(mirror, address, version, platform) {
+    const parts = address.split("/");
+    const type = parts[parts.length - 1];
+    const dir = join(mirror, ...parts);
+    return existsSync(join(dir, `terraform-provider-${type}_${version}_${platform}.zip`)) || existsSync(join(dir, version, platform));
+}
+const defaultRun = (bin, args, cwd) => {
+    const r = spawnSync(bin, args, { cwd, encoding: "utf-8", env: { ...process.env, TF_IN_AUTOMATION: "1", TF_INPUT: "0", CHECKPOINT_DISABLE: "1" } });
+    return { status: r.status, output: `${r.stdout ?? ""}${r.stderr ?? ""}${r.error ? r.error.message : ""}` };
+};
+export class MirrorBuildError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "MirrorBuildError";
+    }
+}
+/** The versions every `<version>.json` beside an `index.json` names, as the index lists them. */
+const indexFor = (dir) => {
+    const versions = readdirSync(dir)
+        .filter((f) => f.endsWith(".json") && f !== "index.json")
+        .map((f) => f.slice(0, -".json".length))
+        .sort();
+    return `${JSON.stringify({ versions: Object.fromEntries(versions.map((v) => [v, {}])) }, null, 2)}\n`;
+};
+/** Every provider directory (`<host>/<ns>/<type>`) under a mirror. */
+const providerDirs = (out) => {
+    const dirs = [];
+    const list = (d) => (existsSync(d) ? readdirSync(d).filter((n) => statSync(join(d, n)).isDirectory()) : []);
+    for (const host of list(out))
+        for (const ns of list(join(out, host)))
+            for (const type of list(join(out, host, ns)))
+                dirs.push(join(out, host, ns, type));
+    return dirs;
+};
+/**
+ * Runs `providers mirror` over every lock file's group into `out`, then
+ * rewrites each `index.json` from the version files present, so groups that
+ * mirror different versions of one provider all show.
+ */
+export function buildMirror(repo, out, options = {}) {
+    const binary = options.binary ?? "tofu";
+    const platforms = [...new Set((options.platforms?.length ? options.platforms : ["linux_amd64"]).map(binaryPlatform))];
+    const bothHosts = options.bothHosts ?? true;
+    const groups = mirrorGroups(repo, options.locks ?? lockFiles(repo));
+    const work = options.workDir ?? mkdtempSync(join(tmpdir(), "chant-provider-mirror-"));
+    const run = options.run ?? defaultRun;
+    const modules = mirrorModules(groups, { dir: "mirror", bothHosts });
+    for (const f of modules) {
+        mkdirSync(join(work, posix.dirname(f.path)), { recursive: true });
+        writeFileSync(join(work, f.path), f.content);
+    }
+    mkdirSync(out, { recursive: true });
+    const dirs = [...new Set(modules.map((f) => posix.dirname(f.path)))];
+    for (const d of dirs) {
+        const r = run(binary, [`-chdir=${join(work, d)}`, "providers", "mirror", ...platforms.map((p) => `-platform=${p}`), out], repo);
+        if (r.status !== 0)
+            throw new MirrorBuildError(`${binary} providers mirror for ${d} failed (exit ${r.status}):\n${r.output.trim()}`);
+    }
+    for (const d of providerDirs(out))
+        writeFileSync(join(d, "index.json"), indexFor(d));
+    const providers = new Set();
+    for (const g of groups) {
+        for (const [address, version] of g.providers) {
+            providers.add(`${address} ${version}`);
+            const other = bothHosts ? otherHostAddress(address) : undefined;
+            if (other)
+                providers.add(`${other} ${version}`);
+        }
+    }
+    return { out, locks: groups.flatMap((g) => g.locks).sort(), providers: [...providers].sort(), platforms };
+}
+const contentTypeOf = (name) => (name.endsWith(".json") ? "application/json" : name.endsWith(".zip") ? "application/zip" : "application/octet-stream");
+/** Every file under a directory, relative to it, `/`-separated. */
+const walkFiles = (root) => {
+    const out = [];
+    const walk = (d) => {
+        for (const n of readdirSync(d)) {
+            const p = join(d, n);
+            if (statSync(p).isDirectory())
+                walk(p);
+            else
+                out.push(relative(root, p).split("\\").join("/"));
+        }
+    };
+    if (existsSync(root))
+        walk(root);
+    return out.sort();
+};
+/** The key a mirror file goes to. */
+export const mirrorKey = (prefix, path) => keyFor(prefix, `${PROVIDER_MIRROR_PREFIX}/${path}`);
+/** The versions an `index.json` lists. */
+const indexVersions = (text) => {
+    if (!text)
+        return [];
+    try {
+        return Object.keys(JSON.parse(text).versions ?? {});
+    }
+    catch {
+        return [];
+    }
+};
+/**
+ * Uploads a built mirror: archives, then each `<version>.json`, then each
+ * `index.json` merged with the versions the store's copy already lists, so a
+ * reader never sees an index naming a version whose files are not there yet.
+ */
+export async function uploadMirror(store, dir, options = {}) {
+    const files = walkFiles(dir);
+    const rank = (f) => (f.endsWith("/index.json") ? 2 : f.endsWith(".json") ? 1 : 0);
+    const ordered = [...files].sort((a, b) => rank(a) - rank(b) || (a < b ? -1 : a > b ? 1 : 0));
+    const put = [];
+    const kept = [];
+    for (const f of ordered) {
+        const key = mirrorKey(options.prefix, f);
+        if (rank(f) === 0 && store.has && (await store.has(key))) {
+            kept.push(key);
+            continue;
+        }
+        let body = readFileSync(join(dir, f));
+        if (rank(f) === 2) {
+            const versions = [...new Set([...indexVersions((await store.read(key)).body), ...indexVersions(body.toString("utf-8"))])].sort();
+            body = `${JSON.stringify({ versions: Object.fromEntries(versions.map((v) => [v, {}])) }, null, 2)}\n`;
+        }
+        await store.put(key, body, contentTypeOf(f));
+        put.push(key);
+    }
+    return { put, kept };
+}
+/** The mirror's URL under a registry's base URL, ending in `/`. */
+export const mirrorUrl = (registryUrl, prefix) => `${registryUrl.replace(/\/+$/, "")}/${mirrorKey(prefix, "")}`;
+/**
+ * The CLI config block users add: the mirrored providers come only from the
+ * mirror, and everything else directly from its registry. `include` keeps
+ * the mirror from being asked for a provider it lacks, and `exclude` keeps a
+ * mirrored provider from going direct.
+ */
+export function mirrorCliConfig(url, addresses) {
+    // Takes addresses, or BuiltMirror.providers' `address version` lines.
+    const list = [...new Set(addresses.map((a) => a.trim().split(/\s+/)[0]))].sort();
+    const quoted = list.map((a) => `      "${a}",`);
+    return [
+        "provider_installation {",
+        "  network_mirror {",
+        `    url = "${url.endsWith("/") ? url : `${url}/`}"`,
+        "    include = [",
+        ...quoted,
+        "    ]",
+        "  }",
+        "  direct {",
+        "    exclude = [",
+        ...quoted,
+        "    ]",
+        "  }",
+        "}",
+        "",
+    ].join("\n");
+}

package/dist/registry/proxies.d.ts

@@ -0,0 +1,73 @@
+/** The upstream a proxy stands for when an entry names none. */
+export declare const DEFAULT_PROXY_UPSTREAM = "registry.terraform.io";
+/** One registry proxy. */
+export interface RegistryProxy {
+    /** The host sources through the proxy name: Artifactory's host, or the label of a Nexus host block. */
+    host: string;
+    /** Artifactory: the remote or virtual repository's key, joined to the namespace with `__`. Absent for Nexus. */
+    repo?: string;
+    /** The registry host the proxy stands for. Default registry.terraform.io. */
+    upstream?: string;
+    /**
+     * The modules.v1 URL a CLI host block gives the label (a Nexus proxy or
+     * group repository's `<url>/repository/<repo>/v1/modules/`), read in
+     * place of the label's service discovery.
+     */
+    modules?: string;
+    /** The providers.v1 URL of the same host block, when reads of providers go through it. */
+    providers?: string;
+}
+/** The `__` an Artifactory source joins its repository key and namespace with. */
+export declare const ARTIFACTORY_JOINER = "__";
+/** A proxy entry for an Artifactory remote or virtual Terraform repository. */
+export declare const artifactoryProxy: (host: string, repo: string, upstream?: string) => RegistryProxy;
+/**
+ * A proxy entry for a Nexus proxy or group Terraform repository at `url`.
+ * The label defaults to the upstream, as Sonatype's docs write the host
+ * block (`host "registry.terraform.io"`), so plain sources go through it.
+ */
+export declare function nexusProxy(o: {
+    url: string;
+    repo: string;
+    upstream?: string;
+    host?: string;
+}): RegistryProxy;
+/** The bare labels the proxies use as hosts, so a source starting with one parses as a registry source. */
+export declare const proxyLabels: (proxies?: readonly RegistryProxy[]) => string[];
+/**
+ * The upstream registry source a module source written through a proxy
+ * stands for, `<upstream>/<ns>/<name>/<system>` with any `//subdir` kept and
+ * the query dropped, and the proxy it went through. Undefined for a source
+ * through none of them. A Nexus label that is the upstream itself gives the
+ * source back at the upstream.
+ */
+export declare function moduleThroughProxy(source: string, proxies?: readonly RegistryProxy[]): {
+    proxy: RegistryProxy;
+    upstream: string;
+} | undefined;
+/**
+ * The upstream provider address a provider source written through a proxy
+ * stands for, `<upstream>/<ns>/<type>` in lower case. Undefined for a
+ * source through none of them.
+ */
+export declare function providerThroughProxy(source: string, proxies?: readonly RegistryProxy[]): {
+    proxy: RegistryProxy;
+    upstream: string;
+} | undefined;
+/**
+ * Where a read of a module at `host/<ns>/<name>/<system>` goes when a proxy
+ * stands for `host`: the host and namespace the proxy names it by, and the
+ * modules.v1 URL to read in place of discovery (a Nexus host block's).
+ * Undefined when no proxy stands for `host`, or the module already names a
+ * proxy's host.
+ */
+export declare function proxyRoute(s: {
+    host: string;
+    namespace: string;
+}, proxies?: readonly RegistryProxy[]): {
+    proxy: RegistryProxy;
+    host: string;
+    namespace: string;
+    modules?: string;
+} | undefined;
+//# sourceMappingURL=proxies.d.ts.map

package/dist/registry/proxies.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"proxies.d.ts","sourceRoot":"","sources":["../../src/registry/proxies.ts"],"names":[],"mappings":"AAqBA,gEAAgE;AAChE,eAAO,MAAM,sBAAsB,0BAA0B,CAAC;AAE9D,0BAA0B;AAC1B,MAAM,WAAW,aAAa;IAC5B,uGAAuG;IACvG,IAAI,EAAE,MAAM,CAAC;IACb,gHAAgH;IAChH,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,6EAA6E;IAC7E,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;;OAIG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,0FAA0F;IAC1F,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,kFAAkF;AAClF,eAAO,MAAM,kBAAkB,OAAO,CAAC;AAEvC,+EAA+E;AAC/E,eAAO,MAAM,gBAAgB,SAAU,MAAM,QAAQ,MAAM,aAAa,MAAM,KAAG,aAAgH,CAAC;AAElM;;;;GAIG;AACH,wBAAgB,UAAU,CAAC,CAAC,EAAE;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,aAAa,CAK5G;AAKD,2GAA2G;AAC3G,eAAO,MAAM,WAAW,aAAa,SAAS,aAAa,EAAE,KAAQ,MAAM,EAAgC,CAAC;AAS5G;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,GAAE,SAAS,aAAa,EAAO,GAAG;IAAE,KAAK,EAAE,aAAa,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,GAAG,SAAS,CAcjJ;AAED;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,GAAE,SAAS,aAAa,EAAO,GAAG;IAAE,KAAK,EAAE,aAAa,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,GAAG,SAAS,CAWnJ;AAED;;;;;;GAMG;AACH,wBAAgB,UAAU,CACxB,CAAC,EAAE;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CAAE,EACtC,OAAO,GAAE,SAAS,aAAa,EAAO,GACrC;IAAE,KAAK,EAAE,aAAa,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,SAAS,CAOzF"}

package/dist/registry/proxies.js

@@ -0,0 +1,111 @@
+/**
+ * Registry proxies (chant#4606, terragucci#1290 bundle C): an Artifactory
+ * remote or virtual repository, or a Nexus proxy or group repository,
+ * standing in front of an upstream registry, so a source written through
+ * one and the plain upstream source compare equal, and reads go through the
+ * proxy. The shapes are the ones terragucci#1299's research found:
+ *
+ *   Artifactory   <host>/<repo>__<ns>/<name>/<system>   module, the repository key joined to the namespace by `__`
+ *                 <host>/<repo>__<ns>/<type>            provider, the same joiner
+ *   Nexus         <label>/<ns>/<name>/<system>          behind a CLI `host "<label>"` block whose services
+ *                                                       point at the proxy repository; the label is usually
+ *                                                       the upstream itself (`host "registry.terraform.io"`)
+ *
+ * An entry names the host sources through the proxy write, the Artifactory
+ * repository key when there is one, and the upstream it stands for
+ * (registry.terraform.io unless set). A Nexus entry carries the repository's
+ * modules.v1 URL, which reads use in place of the label's discovery, as the
+ * CLI's host block does. No Node imports, so an edge function can carry it.
+ */
+import { parseRegistrySource } from "./address.js";
+/** The upstream a proxy stands for when an entry names none. */
+export const DEFAULT_PROXY_UPSTREAM = "registry.terraform.io";
+/** The `__` an Artifactory source joins its repository key and namespace with. */
+export const ARTIFACTORY_JOINER = "__";
+/** A proxy entry for an Artifactory remote or virtual Terraform repository. */
+export const artifactoryProxy = (host, repo, upstream) => ({ host: host.toLowerCase(), repo, ...(upstream ? { upstream: upstream.toLowerCase() } : {}) });
+/**
+ * A proxy entry for a Nexus proxy or group Terraform repository at `url`.
+ * The label defaults to the upstream, as Sonatype's docs write the host
+ * block (`host "registry.terraform.io"`), so plain sources go through it.
+ */
+export function nexusProxy(o) {
+    const base = o.url.replace(/\/+$/, "");
+    const upstream = (o.upstream ?? DEFAULT_PROXY_UPSTREAM).toLowerCase();
+    const repo = encodeURIComponent(o.repo);
+    return { host: (o.host ?? upstream).toLowerCase(), upstream, modules: `${base}/repository/${repo}/v1/modules/`, providers: `${base}/repository/${repo}/v1/providers/` };
+}
+const upstreamOf = (p) => (p.upstream ?? DEFAULT_PROXY_UPSTREAM).toLowerCase();
+const sameHost = (a, b) => a.toLowerCase() === b.toLowerCase();
+/** The bare labels the proxies use as hosts, so a source starting with one parses as a registry source. */
+export const proxyLabels = (proxies = []) => proxies.map((p) => p.host);
+/** A namespace through an Artifactory proxy without its `<repo>__`, or undefined when it does not carry that repository. */
+function unjoin(p, namespace) {
+    if (!p.repo)
+        return namespace;
+    const prefix = `${p.repo}${ARTIFACTORY_JOINER}`;
+    return namespace.toLowerCase().startsWith(prefix.toLowerCase()) && namespace.length > prefix.length ? namespace.slice(prefix.length) : undefined;
+}
+/**
+ * The upstream registry source a module source written through a proxy
+ * stands for, `<upstream>/<ns>/<name>/<system>` with any `//subdir` kept and
+ * the query dropped, and the proxy it went through. Undefined for a source
+ * through none of them. A Nexus label that is the upstream itself gives the
+ * source back at the upstream.
+ */
+export function moduleThroughProxy(source, proxies = []) {
+    if (proxies.length === 0)
+        return undefined;
+    const written = source.trim().split("?")[0];
+    const [base, ...sub] = written.split("//");
+    const s = parseRegistrySource(base, proxyLabels(proxies));
+    if (!s)
+        return undefined;
+    for (const p of proxies) {
+        if (!sameHost(p.host, s.host))
+            continue;
+        const ns = unjoin(p, s.namespace);
+        if (ns === undefined)
+            continue;
+        const upstream = [`${upstreamOf(p)}/${ns}/${s.name}/${s.system}`, ...sub].join("//");
+        return { proxy: p, upstream };
+    }
+    return undefined;
+}
+/**
+ * The upstream provider address a provider source written through a proxy
+ * stands for, `<upstream>/<ns>/<type>` in lower case. Undefined for a
+ * source through none of them.
+ */
+export function providerThroughProxy(source, proxies = []) {
+    const parts = source.trim().toLowerCase().split("/");
+    if (parts.length !== 3)
+        return undefined;
+    const [host, namespace, type] = parts;
+    for (const p of proxies) {
+        if (!sameHost(p.host, host))
+            continue;
+        const ns = unjoin(p, namespace);
+        if (ns === undefined || !ns || !type)
+            continue;
+        return { proxy: p, upstream: `${upstreamOf(p)}/${ns}/${type}` };
+    }
+    return undefined;
+}
+/**
+ * Where a read of a module at `host/<ns>/<name>/<system>` goes when a proxy
+ * stands for `host`: the host and namespace the proxy names it by, and the
+ * modules.v1 URL to read in place of discovery (a Nexus host block's).
+ * Undefined when no proxy stands for `host`, or the module already names a
+ * proxy's host.
+ */
+export function proxyRoute(s, proxies = []) {
+    // A source written through a proxy already reads from its host; a Nexus label is resolved by its modules URL.
+    const named = proxies.find((p) => sameHost(p.host, s.host));
+    if (named)
+        return named.modules ? { proxy: named, host: named.host, namespace: s.namespace, modules: named.modules } : undefined;
+    const p = proxies.find((q) => sameHost(upstreamOf(q), s.host));
+    if (!p)
+        return undefined;
+    return { proxy: p, host: p.host, namespace: p.repo ? `${p.repo}${ARTIFACTORY_JOINER}${s.namespace}` : s.namespace, ...(p.modules ? { modules: p.modules } : {}) };
+}

package/dist/registry/reader.d.ts

@@ -0,0 +1,57 @@
+import { type CredentialsOptions } from "@intentius/chant/terraform/credentials";
+import { type RegistryProxy } from "./proxies.js";
+/** The fetch the reader calls: the global fetch's shape. */
+export type RegistryFetch = (url: string, init?: RequestInit) => Promise<Response>;
+export declare class RegistryError extends Error {
+    constructor(message: string);
+}
+/** How a download answer is read. */
+export type DownloadReader = "terraform" | "tofu" | "either";
+export interface RegistryReadOptions {
+    fetch?: RegistryFetch;
+    /** The URL scheme service discovery is fetched over. Default https, as both CLIs use. */
+    scheme?: "https" | "http";
+    /**
+     * The bearer token sent to the registry's host. Default: the one the CLIs
+     * would send (`TF_TOKEN_<host>`, then the credentials files). `false` sends none.
+     */
+    token?: string | false;
+    /** Where the default token lookup reads (a test passes its own env and files). */
+    credentials?: CredentialsOptions;
+    /**
+     * The modules.v1 URL per registry host, read in place of the host's
+     * `/.well-known/terraform.json`, as a CLI's `host "<name>" { services = {...} }`
+     * block does. A host named here is taken as a registry host even without a dot.
+     */
+    services?: Record<string, string>;
+    /**
+     * A whole `Authorization` header value sent on every request to the
+     * registry, in place of the bearer token, such as Nexus's basic
+     * credentials before its bearer form (3.95). Never printed.
+     */
+    authorization?: string;
+    /** Registry proxies in front of upstream hosts; a read of a module at an upstream goes through its proxy. */
+    proxies?: readonly RegistryProxy[];
+}
+/** The token a read sends to a host, by the options. */
+export declare const readToken: (host: string, o: RegistryReadOptions) => string | undefined;
+/** The modules.v1 base a host's service discovery names, ending in `/`. */
+export declare function modulesBase(host: string, options?: RegistryFetch | RegistryReadOptions): Promise<string>;
+/** Every version a registry lists for a module; none when it has no versions file. */
+export declare function registryVersions(source: string, options?: RegistryFetch | RegistryReadOptions): Promise<string[]>;
+export interface RegistryLocationOptions extends RegistryReadOptions {
+    /** Which CLI's reading to follow. Default `either`. */
+    reads?: DownloadReader;
+}
+/** The location a download answer gives, read as `reads` says, or undefined when it gives none that way. */
+export declare function locationFromAnswer(res: Response, reads?: DownloadReader): Promise<string | undefined>;
+/** Where a registry says one version is, resolved against the download URL when it is relative. */
+export declare function registryLocation(source: string, version: string, options?: RegistryFetch | RegistryLocationOptions): Promise<string>;
+/**
+ * The module archive a tarball location holds, uncompressed: the bytes a
+ * release's digest is of. The host's token goes along only when the location
+ * has no query string; a signed URL carries its own grant, and a bucket
+ * refuses a request that has both a signature and an `Authorization` header.
+ */
+export declare function fetchTarball(location: string, options?: RegistryFetch | RegistryReadOptions): Promise<Buffer>;
+//# sourceMappingURL=reader.d.ts.map

package/dist/registry/reader.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"reader.d.ts","sourceRoot":"","sources":["../../src/registry/reader.ts"],"names":[],"mappings":"AA8BA,OAAO,EAAkD,KAAK,kBAAkB,EAAE,MAAM,wCAAwC,CAAC;AAEjI,OAAO,EAAmD,KAAK,aAAa,EAAE,MAAM,WAAW,CAAC;AAGhG,4DAA4D;AAC5D,MAAM,MAAM,aAAa,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,WAAW,KAAK,OAAO,CAAC,QAAQ,CAAC,CAAC;AAInF,qBAAa,aAAc,SAAQ,KAAK;IACtC,YAAY,OAAO,EAAE,MAAM,EAG1B;CACF;AAED,qCAAqC;AACrC,MAAM,MAAM,cAAc,GAAG,WAAW,GAAG,MAAM,GAAG,QAAQ,CAAC;AAE7D,MAAM,WAAW,mBAAmB;IAClC,KAAK,CAAC,EAAE,aAAa,CAAC;IACtB,yFAAyF;IACzF,MAAM,CAAC,EAAE,OAAO,GAAG,MAAM,CAAC;IAC1B;;;OAGG;IACH,KAAK,CAAC,EAAE,MAAM,GAAG,KAAK,CAAC;IACvB,kFAAkF;IAClF,WAAW,CAAC,EAAE,kBAAkB,CAAC;IACjC;;;;OAIG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAClC;;;;OAIG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,6GAA6G;IAC7G,OAAO,CAAC,EAAE,SAAS,aAAa,EAAE,CAAC;CACpC;AAED,wDAAwD;AACxD,eAAO,MAAM,SAAS,SAAU,MAAM,KAAK,mBAAmB,KAAG,MAAM,GAAG,SAA+F,CAAC;AAqD1K,2EAA2E;AAC3E,wBAAsB,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,aAAa,GAAG,mBAAmB,GAAG,OAAO,CAAC,MAAM,CAAC,CAiB9G;AAED,sFAAsF;AACtF,wBAAsB,gBAAgB,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,aAAa,GAAG,mBAAmB,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAUvH;AAED,MAAM,WAAW,uBAAwB,SAAQ,mBAAmB;IAClE,uDAAuD;IACvD,KAAK,CAAC,EAAE,cAAc,CAAC;CACxB;AAED,4GAA4G;AAC5G,wBAAsB,kBAAkB,CAAC,GAAG,EAAE,QAAQ,EAAE,KAAK,GAAE,cAAyB,GAAG,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAcrH;AAED,mGAAmG;AACnG,wBAAsB,gBAAgB,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,aAAa,GAAG,uBAAuB,GAAG,OAAO,CAAC,MAAM,CAAC,CAiB1I;AAED;;;;;GAKG;AACH,wBAAsB,YAAY,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,aAAa,GAAG,mBAAmB,GAAG,OAAO,CAAC,MAAM,CAAC,CAYnH"}