@containerbase/base 14.49.0 → 14.51.0

package/README.md

@@ -106,6 +106,21 @@ if (isContainerbase()) {
 }
 ```
 
+Containerbase replaces the urls it downloads from with the `CONTAINERBASE_CDN` and `URL_REPLACE_<n>_FROM` / `URL_REPLACE_<n>_TO` variables, see [custom registries](https://github.com/containerbase/base/blob/main/docs/custom-registries.md).
+A reader can replace its urls the same way, so a mirror configured for containerbase works for it too:
+
+```ts
+import { getUrlReplacements, replaceUrl } from '@containerbase/base';
+
+const { replacements, invalid } = getUrlReplacements(); // reads `process.env`
+// `invalid` lists the `URL_REPLACE_<n>_FROM` variables without a value or `_TO` counterpart
+replaceUrl(
+  'https://containerbase.github.io/tool-versions/v1/node.json',
+  replacements,
+  process.env.CONTAINERBASE_CDN,
+);
+```
+
 The schemas ignore unknown keys and accept any arch name, so additive changes of the format don't break a reader; readers ignore files of an arch they don't know.
 
 ## Contents

package/dist/index.d.ts

@@ -4,6 +4,8 @@ export type { Arch, DistroCode, InstallToolType, ToolMetadata, ToolType, } from
 export type { FileIntegrity, FileReference, FormatIndex, ToolFile, ToolIndex, ToolVersion, ToolVersions, VersionFiles, VersionIntegrity, } from './tool-versions-types.ts';
 export { containerbaseVersionFile, isCompatibleVersion, isContainerbase, packageVersion, toolVersionsPath, validateContainerbaseVersion, } from './containerbase.ts';
 export { isToolVersionsFormat, toolVersionsFormat, toolVersionsFormatPath, } from './tool-versions-format.ts';
+export type { UrlReplacement, UrlReplacements } from './url.ts';
+export { getUrlReplacements, replaceUrl } from './url.ts';
 export { tools };
 /**
  * The Ubuntu release the default containerbase image is built from, the

package/dist/index.js

@@ -1,6 +1,7 @@
 import { tools } from "./data.js";
 export { containerbaseVersionFile, isCompatibleVersion, isContainerbase, packageVersion, toolVersionsPath, validateContainerbaseVersion, } from "./containerbase.js";
 export { isToolVersionsFormat, toolVersionsFormat, toolVersionsFormatPath, } from "./tool-versions-format.js";
+export { getUrlReplacements, replaceUrl } from "./url.js";
 export { tools };
 /**
  * The Ubuntu release the default containerbase image is built from, the

package/dist/url.d.ts

@@ -0,0 +1,31 @@
+/** A url replacement: the text to replace and its replacement. */
+export type UrlReplacement = [from: string, to: string];
+/** The url replacements read from the environment. */
+export interface UrlReplacements {
+    /** The valid replacements, in numerical order. */
+    replacements: UrlReplacement[];
+    /**
+     * The `URL_REPLACE_<n>_FROM` variables which are ignored, because they or
+     * their `URL_REPLACE_<n>_TO` counterpart are empty or missing.
+     */
+    invalid: string[];
+}
+/**
+ * Reads the url replacements from the `URL_REPLACE_<n>_FROM` and
+ * `URL_REPLACE_<n>_TO` variables, in numerical order of `<n>`.
+ *
+ * @param env the environment to read, `process.env` by default
+ */
+export declare function getUrlReplacements(env?: Record<string, string | undefined>): UrlReplacements;
+/**
+ * Replaces a url the way containerbase does for its downloads: with a `cdn`,
+ * `https://` is replaced by it first, eg. `https://example.com/file` becomes
+ * `<cdn>/example.com/file`. Then every replacement is applied in order, each
+ * replacing the first occurrence of its `from` text.
+ *
+ * @param url the url to replace
+ * @param replacements the replacements, see `getUrlReplacements`
+ * @param cdn the cdn url, eg. from `CONTAINERBASE_CDN`, skipped when empty
+ * @returns the replaced url
+ */
+export declare function replaceUrl(url: string, replacements: readonly UrlReplacement[], cdn?: string): string;

package/dist/url.js

@@ -0,0 +1,49 @@
+const fromRe = /^URL_REPLACE_\d+_FROM$/;
+const collator = new Intl.Collator('en', {
+    sensitivity: 'base',
+    numeric: true,
+});
+/**
+ * Reads the url replacements from the `URL_REPLACE_<n>_FROM` and
+ * `URL_REPLACE_<n>_TO` variables, in numerical order of `<n>`.
+ *
+ * @param env the environment to read, `process.env` by default
+ */
+export function getUrlReplacements(env = process.env) {
+    const result = { replacements: [], invalid: [] };
+    for (const from of Object.keys(env)
+        .filter((key) => fromRe.test(key))
+        .sort((a, b) => collator.compare(a, b))) {
+        const to = from.replace(/_FROM$/, '_TO');
+        const fromValue = env[from];
+        const toValue = env[to];
+        if (fromValue && toValue) {
+            result.replacements.push([fromValue, toValue]);
+        }
+        else {
+            result.invalid.push(from);
+        }
+    }
+    return result;
+}
+/**
+ * Replaces a url the way containerbase does for its downloads: with a `cdn`,
+ * `https://` is replaced by it first, eg. `https://example.com/file` becomes
+ * `<cdn>/example.com/file`. Then every replacement is applied in order, each
+ * replacing the first occurrence of its `from` text.
+ *
+ * @param url the url to replace
+ * @param replacements the replacements, see `getUrlReplacements`
+ * @param cdn the cdn url, eg. from `CONTAINERBASE_CDN`, skipped when empty
+ * @returns the replaced url
+ */
+export function replaceUrl(url, replacements, cdn) {
+    let result = url;
+    if (cdn) {
+        result = result.replace(/^https:\//, cdn.replace(/\/$/, ''));
+    }
+    for (const [from, to] of replacements) {
+        result = result.replace(from, to);
+    }
+    return result;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@containerbase/base",
-  "version": "14.49.0",
+  "version": "14.51.0",
   "description": "Metadata about the tools supported by containerbase",
   "keywords": [
     "containerbase",