@deployport/api-services-corelib 0.2.0 → 0.3.0

package/configurator/config.d.ts

@@ -0,0 +1,54 @@
+/**
+ * AccountScope selects which account slot of a profile's credentials to use.
+ * - `"auto"`    uses the current account if present, otherwise the global account.
+ * - `"global"`  uses the profile's global account.
+ * - `"current"` uses the profile's current (switched) account.
+ */
+export type AccountScope = "auto" | "global" | "current";
+/**
+ * DeployportConfig holds the DeployPort signing configuration. On Node, unset
+ * fields are resolved from the environment and `~/.deployport` files by
+ * {@link loadDefaultConfig}; in the browser they must be provided explicitly.
+ */
+export type DeployportConfig = {
+    region?: string;
+    accessKeyID?: string;
+    secretAccessKey?: string;
+    /** Profile name; else `DEPLOYPORT_PROFILE`; else `"default"`. */
+    profile?: string;
+    /** Which account slot to read from the profile's credentials. Defaults to `"auto"`. */
+    accountScope?: AccountScope;
+    /** Disables credential auto-loading from env and files. Explicit credentials are still honored. */
+    anonymous?: boolean;
+    /** Overrides the credentials file path. Empty uses {@link DEFAULT_CREDENTIALS_FILE_PATH}. */
+    credentialsFilePath?: string;
+    /** Overrides the settings file path. Empty uses {@link DEFAULT_SETTINGS_FILE_PATH}. */
+    settingsFilePath?: string;
+};
+/** Config is the DeployPort-specific configuration attached to a client config. */
+export type Config = {
+    deployport?: DeployportConfig;
+};
+/**
+ * LoadDefaultConfig resolves a Config using the full default chain. The Node
+ * implementation ({@link loader.node.ts}) fills unset values from the
+ * environment then the default config files; the browser implementation
+ * ({@link loader.browser.ts}) returns the config unchanged (explicit only).
+ */
+export type LoadDefaultConfig = (config?: Config) => Promise<Config>;
+/**
+ * GetEndpointOverride reads a per-service endpoint URL override for a profile.
+ * On Node it reads the settings file; in the browser it always returns "".
+ */
+export type GetEndpointOverride = (service: string, options?: {
+    profile?: string;
+    settingsFilePath?: string;
+}) => Promise<string>;
+export declare const ENV_ACCESS_KEY_ID = "DEPLOYPORT_ACCESS_KEY_ID";
+export declare const ENV_SECRET_ACCESS_KEY = "DEPLOYPORT_SECRET_ACCESS_KEY";
+export declare const ENV_REGION = "DEPLOYPORT_REGION";
+export declare const ENV_PROFILE = "DEPLOYPORT_PROFILE";
+export declare const DEFAULT_PROFILE = "default";
+export declare const DEFAULT_REGION = "us-east-2";
+export declare const DEFAULT_CREDENTIALS_FILE_PATH = "$HOME/.deployport/credentials.yml";
+export declare const DEFAULT_SETTINGS_FILE_PATH = "$HOME/.deployport/settings.yml";

package/configurator/config.js

@@ -0,0 +1,16 @@
+// Universal (browser + Node) configuration types and constants for the
+// DeployPort configurator. This module MUST NOT import any Node builtins
+// (`node:fs`, `node:os`, ...) or Node-only packages so it stays safe to bundle
+// for the browser. The Node-only resolution logic lives in `loader.node.ts`,
+// which is swapped in for `loader.browser.ts` via the package `#config-loader`
+// import condition.
+// Environment variable names used for default configuration loading (Node only).
+export const ENV_ACCESS_KEY_ID = "DEPLOYPORT_ACCESS_KEY_ID";
+export const ENV_SECRET_ACCESS_KEY = "DEPLOYPORT_SECRET_ACCESS_KEY";
+export const ENV_REGION = "DEPLOYPORT_REGION";
+export const ENV_PROFILE = "DEPLOYPORT_PROFILE";
+// Defaults used when resolving configuration from the environment and files.
+export const DEFAULT_PROFILE = "default";
+export const DEFAULT_REGION = "us-east-2";
+export const DEFAULT_CREDENTIALS_FILE_PATH = "$HOME/.deployport/credentials.yml";
+export const DEFAULT_SETTINGS_FILE_PATH = "$HOME/.deployport/settings.yml";

package/configurator/config.ts

@@ -0,0 +1,69 @@
+// Universal (browser + Node) configuration types and constants for the
+// DeployPort configurator. This module MUST NOT import any Node builtins
+// (`node:fs`, `node:os`, ...) or Node-only packages so it stays safe to bundle
+// for the browser. The Node-only resolution logic lives in `loader.node.ts`,
+// which is swapped in for `loader.browser.ts` via the package `#config-loader`
+// import condition.
+
+/**
+ * AccountScope selects which account slot of a profile's credentials to use.
+ * - `"auto"`    uses the current account if present, otherwise the global account.
+ * - `"global"`  uses the profile's global account.
+ * - `"current"` uses the profile's current (switched) account.
+ */
+export type AccountScope = "auto" | "global" | "current";
+
+/**
+ * DeployportConfig holds the DeployPort signing configuration. On Node, unset
+ * fields are resolved from the environment and `~/.deployport` files by
+ * {@link loadDefaultConfig}; in the browser they must be provided explicitly.
+ */
+export type DeployportConfig = {
+    region?: string;
+    accessKeyID?: string;
+    secretAccessKey?: string;
+    /** Profile name; else `DEPLOYPORT_PROFILE`; else `"default"`. */
+    profile?: string;
+    /** Which account slot to read from the profile's credentials. Defaults to `"auto"`. */
+    accountScope?: AccountScope;
+    /** Disables credential auto-loading from env and files. Explicit credentials are still honored. */
+    anonymous?: boolean;
+    /** Overrides the credentials file path. Empty uses {@link DEFAULT_CREDENTIALS_FILE_PATH}. */
+    credentialsFilePath?: string;
+    /** Overrides the settings file path. Empty uses {@link DEFAULT_SETTINGS_FILE_PATH}. */
+    settingsFilePath?: string;
+};
+
+/** Config is the DeployPort-specific configuration attached to a client config. */
+export type Config = {
+    deployport?: DeployportConfig;
+};
+
+/**
+ * LoadDefaultConfig resolves a Config using the full default chain. The Node
+ * implementation ({@link loader.node.ts}) fills unset values from the
+ * environment then the default config files; the browser implementation
+ * ({@link loader.browser.ts}) returns the config unchanged (explicit only).
+ */
+export type LoadDefaultConfig = (config?: Config) => Promise<Config>;
+
+/**
+ * GetEndpointOverride reads a per-service endpoint URL override for a profile.
+ * On Node it reads the settings file; in the browser it always returns "".
+ */
+export type GetEndpointOverride = (
+    service: string,
+    options?: { profile?: string; settingsFilePath?: string },
+) => Promise<string>;
+
+// Environment variable names used for default configuration loading (Node only).
+export const ENV_ACCESS_KEY_ID = "DEPLOYPORT_ACCESS_KEY_ID";
+export const ENV_SECRET_ACCESS_KEY = "DEPLOYPORT_SECRET_ACCESS_KEY";
+export const ENV_REGION = "DEPLOYPORT_REGION";
+export const ENV_PROFILE = "DEPLOYPORT_PROFILE";
+
+// Defaults used when resolving configuration from the environment and files.
+export const DEFAULT_PROFILE = "default";
+export const DEFAULT_REGION = "us-east-2";
+export const DEFAULT_CREDENTIALS_FILE_PATH = "$HOME/.deployport/credentials.yml";
+export const DEFAULT_SETTINGS_FILE_PATH = "$HOME/.deployport/settings.yml";

package/configurator/index.d.ts

@@ -1,2 +1,12 @@
+import type { Config } from "./config.js";
 import { Runtime } from "@deployport/specular-runtime";
-export declare function Configure(c?: Runtime.ClientConfig): Runtime.ClientConfig;
+export type { Config, DeployportConfig, AccountScope } from "./config.js";
+/**
+ * Configure installs the DeployPort request signer on a client config.
+ *
+ * On Node, config left unset is resolved from the DEPLOYPORT_* environment
+ * variables and the ~/.deployport files on the first request (the resolution is
+ * async and memoized). In the browser, `loadDefaultConfig` is a no-op, so the
+ * `deployport` config must be provided explicitly.
+ */
+export declare function Configure(config?: Runtime.ClientConfig & Config): Runtime.ClientConfig;

package/configurator/index.js

@@ -1,12 +1,31 @@
-import { ConfigureSignatureV1 } from "./signer.js";
+import { ConfigureSignatureV1, replaceRegionInRequest } from "./signer.js";
+import { loadDefaultConfig } from "#config-loader";
 import { Runtime } from "@deployport/specular-runtime";
-export function Configure(c) {
-    const requestConfigurators = c?.requestConfigurators ?? [];
-    requestConfigurators.push(async (sub) => {
-        console.warn("configuring request from config", sub.request);
-        await ConfigureSignatureV1(sub, c);
+/**
+ * Configure installs the DeployPort request signer on a client config.
+ *
+ * On Node, config left unset is resolved from the DEPLOYPORT_* environment
+ * variables and the ~/.deployport files on the first request (the resolution is
+ * async and memoized). In the browser, `loadDefaultConfig` is a no-op, so the
+ * `deployport` config must be provided explicitly.
+ */
+export function Configure(config) {
+    const requestConfigurators = config?.requestConfigurators ?? [];
+    // Resolve once, lazily, on the first request. Keeps Configure synchronous
+    // and browser-safe while deferring any Node I/O to request time.
+    let resolved;
+    requestConfigurators.push(async (submission) => {
+        resolved ??= loadDefaultConfig(config);
+        const cfg = await resolved;
+        // Substitute the <region> endpoint placeholder for every request that
+        // has a resolved region, whether or not it is signed (mirrors Go).
+        const region = cfg.deployport?.region;
+        if (region) {
+            replaceRegionInRequest(submission.request, region);
+        }
+        await ConfigureSignatureV1(submission, cfg);
     });
-    return Runtime.MergeClientConfig(c, {
+    return Runtime.MergeClientConfig(config, {
         requestConfigurators,
     });
 }

package/configurator/index.ts

@@ -1,13 +1,35 @@
-import { Config, ConfigureSignatureV1 } from "./signer.js";
+import { ConfigureSignatureV1, replaceRegionInRequest } from "./signer.js";
+import type { Config } from "./config.js";
+import { loadDefaultConfig } from "#config-loader";
 import { Runtime } from "@deployport/specular-runtime";
 
-export function Configure(c?: Runtime.ClientConfig): Runtime.ClientConfig {
-    const requestConfigurators = c?.requestConfigurators ?? [];
-    requestConfigurators.push(async (sub) => {
-        console.warn("configuring request from config", sub.request);
-        await ConfigureSignatureV1(sub, c as Config)
+export type { Config, DeployportConfig, AccountScope } from "./config.js";
+
+/**
+ * Configure installs the DeployPort request signer on a client config.
+ *
+ * On Node, config left unset is resolved from the DEPLOYPORT_* environment
+ * variables and the ~/.deployport files on the first request (the resolution is
+ * async and memoized). In the browser, `loadDefaultConfig` is a no-op, so the
+ * `deployport` config must be provided explicitly.
+ */
+export function Configure(config?: Runtime.ClientConfig & Config): Runtime.ClientConfig {
+    const requestConfigurators = config?.requestConfigurators ?? [];
+    // Resolve once, lazily, on the first request. Keeps Configure synchronous
+    // and browser-safe while deferring any Node I/O to request time.
+    let resolved: Promise<Config> | undefined;
+    requestConfigurators.push(async (submission) => {
+        resolved ??= loadDefaultConfig(config);
+        const cfg = await resolved;
+        // Substitute the <region> endpoint placeholder for every request that
+        // has a resolved region, whether or not it is signed (mirrors Go).
+        const region = cfg.deployport?.region;
+        if (region) {
+            replaceRegionInRequest(submission.request, region);
+        }
+        await ConfigureSignatureV1(submission, cfg);
     });
-    return Runtime.MergeClientConfig(c, {
+    return Runtime.MergeClientConfig(config, {
         requestConfigurators,
     });
 }

package/configurator/loader.browser.d.ts

@@ -0,0 +1,14 @@
+import type { Config } from "./config.js";
+/**
+ * loadDefaultConfig is a no-op passthrough in the browser: whatever the
+ * consumer passed is what gets used. There is no env/file resolution.
+ */
+export declare function loadDefaultConfig(config?: Config): Promise<Config>;
+/**
+ * getEndpointOverride always returns "" in the browser: there is no settings
+ * file to read. Consumers set endpoints explicitly on the client config.
+ */
+export declare function getEndpointOverride(_service: string, _options?: {
+    profile?: string;
+    settingsFilePath?: string;
+}): Promise<string>;

package/configurator/loader.browser.js

@@ -0,0 +1,28 @@
+// Browser configuration loader. This module is selected via the
+// `#config-loader` package import for non-Node targets (see package.json
+// `imports`). It contains NO Node builtins, so bundlers never pull `fs`/`os`
+// into a browser build. In the browser there is no environment or filesystem
+// to read, so config must be provided explicitly by the consumer.
+//
+// It intentionally mirrors the public surface of `loader.node.ts` so that
+// `#config-loader` resolves to the same shape in both environments.
+/**
+ * loadDefaultConfig is a no-op passthrough in the browser: whatever the
+ * consumer passed is what gets used. There is no env/file resolution.
+ */
+export async function loadDefaultConfig(config) {
+    return config ?? {};
+}
+/**
+ * getEndpointOverride always returns "" in the browser: there is no settings
+ * file to read. Consumers set endpoints explicitly on the client config.
+ */
+export async function getEndpointOverride(_service, _options) {
+    return "";
+}
+// Compile-time guard: this variant must match the shared loader signatures so
+// `#config-loader` resolves identically in Node and the browser.
+const _loadDefaultConfig = loadDefaultConfig;
+const _getEndpointOverride = getEndpointOverride;
+void _loadDefaultConfig;
+void _getEndpointOverride;

package/configurator/loader.browser.ts

@@ -0,0 +1,36 @@
+// Browser configuration loader. This module is selected via the
+// `#config-loader` package import for non-Node targets (see package.json
+// `imports`). It contains NO Node builtins, so bundlers never pull `fs`/`os`
+// into a browser build. In the browser there is no environment or filesystem
+// to read, so config must be provided explicitly by the consumer.
+//
+// It intentionally mirrors the public surface of `loader.node.ts` so that
+// `#config-loader` resolves to the same shape in both environments.
+
+import type { Config, GetEndpointOverride, LoadDefaultConfig } from "./config.js";
+
+/**
+ * loadDefaultConfig is a no-op passthrough in the browser: whatever the
+ * consumer passed is what gets used. There is no env/file resolution.
+ */
+export async function loadDefaultConfig(config?: Config): Promise<Config> {
+    return config ?? {};
+}
+
+/**
+ * getEndpointOverride always returns "" in the browser: there is no settings
+ * file to read. Consumers set endpoints explicitly on the client config.
+ */
+export async function getEndpointOverride(
+    _service: string,
+    _options?: { profile?: string; settingsFilePath?: string },
+): Promise<string> {
+    return "";
+}
+
+// Compile-time guard: this variant must match the shared loader signatures so
+// `#config-loader` resolves identically in Node and the browser.
+const _loadDefaultConfig: LoadDefaultConfig = loadDefaultConfig;
+const _getEndpointOverride: GetEndpointOverride = getEndpointOverride;
+void _loadDefaultConfig;
+void _getEndpointOverride;

package/configurator/loader.node.d.ts

@@ -0,0 +1,18 @@
+import { type Config } from "./config.js";
+/**
+ * loadDefaultConfig resolves the DeployPort config using the full default
+ * chain, filling only values not already set explicitly: environment variables,
+ * then the default config files for the resolved profile, then DEFAULT_REGION
+ * as a last resort. Explicit values always win. Missing files are ignored;
+ * malformed files throw.
+ */
+export declare function loadDefaultConfig(config?: Config): Promise<Config>;
+/**
+ * getEndpointOverride reads `profiles.<profile>.services.<service>.endpoint.url`
+ * from the settings file, or "" if none is set. Lets a Node consumer (e.g. a
+ * CLI) pick a per-service endpoint while corelib stays service-agnostic.
+ */
+export declare function getEndpointOverride(service: string, options?: {
+    profile?: string;
+    settingsFilePath?: string;
+}): Promise<string>;

package/configurator/loader.node.js

@@ -0,0 +1,166 @@
+// Node-only configuration loader. This module is selected via the
+// `#config-loader` package import when running under Node (see package.json
+// `imports`). It is NEVER bundled for the browser, so it may freely import
+// Node builtins. The browser gets `loader.browser.ts` instead.
+//
+// The resolution chain mirrors the Go corelib (configurator/config_files.go,
+// configurator/configurator.go): explicit config -> DEPLOYPORT_* env ->
+// ~/.deployport files (for the resolved profile) -> DefaultRegion.
+import { readFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { parse as parseYAML } from "yaml";
+import { DEFAULT_CREDENTIALS_FILE_PATH, DEFAULT_PROFILE, DEFAULT_REGION, DEFAULT_SETTINGS_FILE_PATH, ENV_ACCESS_KEY_ID, ENV_PROFILE, ENV_REGION, ENV_SECRET_ACCESS_KEY, } from "./config.js";
+// --- Public API -------------------------------------------------------------
+/**
+ * loadDefaultConfig resolves the DeployPort config using the full default
+ * chain, filling only values not already set explicitly: environment variables,
+ * then the default config files for the resolved profile, then DEFAULT_REGION
+ * as a last resort. Explicit values always win. Missing files are ignored;
+ * malformed files throw.
+ */
+export async function loadDefaultConfig(config) {
+    const dp = { ...(config?.deployport ?? {}) };
+    const anonymous = dp.anonymous ?? false;
+    const scope = dp.accountScope ?? "auto";
+    const profile = resolveProfile(dp.profile);
+    // Credentials are treated as a unit: if the caller set either field
+    // explicitly, we do not auto-load them from env or files (mirrors Go's
+    // `Credentials == nil` gate).
+    const credsExplicit = dp.accessKeyID != null || dp.secretAccessKey != null;
+    if (!anonymous && !credsExplicit) {
+        const envKeyID = process.env[ENV_ACCESS_KEY_ID];
+        const envSecret = process.env[ENV_SECRET_ACCESS_KEY];
+        if (envKeyID || envSecret) {
+            // Env provides the credentials as a unit; files are skipped.
+            dp.accessKeyID = envKeyID ?? "";
+            dp.secretAccessKey = envSecret ?? "";
+        }
+        else {
+            const credsFile = await loadCredentialsFile(credentialsPath(dp));
+            const acc = accountFor(credsFile, profile, scope);
+            if (acc && acc.accessKeyID) {
+                dp.accessKeyID = acc.accessKeyID;
+                dp.secretAccessKey = acc.secretAccessKey ?? "";
+            }
+        }
+    }
+    // Region: explicit -> env -> settings file -> default.
+    if (!dp.region) {
+        const envRegion = process.env[ENV_REGION];
+        if (envRegion) {
+            dp.region = envRegion;
+        }
+    }
+    if (!dp.region) {
+        const settingsFile = await loadSettingsFile(settingsPath(dp));
+        const region = regionFor(settingsFile, profile);
+        if (region) {
+            dp.region = region;
+        }
+    }
+    if (!dp.region) {
+        dp.region = DEFAULT_REGION;
+    }
+    return { ...config, deployport: dp };
+}
+/**
+ * getEndpointOverride reads `profiles.<profile>.services.<service>.endpoint.url`
+ * from the settings file, or "" if none is set. Lets a Node consumer (e.g. a
+ * CLI) pick a per-service endpoint while corelib stays service-agnostic.
+ */
+export async function getEndpointOverride(service, options) {
+    const profile = resolveProfile(options?.profile);
+    const settingsFile = await loadSettingsFile(options?.settingsFilePath ? expandPath(options.settingsFilePath) : defaultSettingsPath());
+    return endpointFor(settingsFile, profile, service);
+}
+// --- Resolution helpers (mirror Go) -----------------------------------------
+function resolveProfile(explicit) {
+    if (explicit) {
+        return explicit;
+    }
+    const fromEnv = process.env[ENV_PROFILE];
+    if (fromEnv) {
+        return fromEnv;
+    }
+    return DEFAULT_PROFILE;
+}
+function accountFor(file, profile, scope) {
+    const p = file.profiles?.[profile];
+    if (!p) {
+        return undefined;
+    }
+    switch (scope) {
+        case "global":
+            return p.global;
+        case "current":
+            return p.current;
+        default: // "auto"
+            return p.current ?? p.global;
+    }
+}
+function regionFor(file, profile) {
+    return file.profiles?.[profile]?.region ?? "";
+}
+function endpointFor(file, profile, service) {
+    return file.profiles?.[profile]?.services?.[service]?.endpoint?.url ?? "";
+}
+// --- File loading ------------------------------------------------------------
+async function loadCredentialsFile(path) {
+    return loadYamlFile(path, "credentials");
+}
+async function loadSettingsFile(path) {
+    return loadYamlFile(path, "settings");
+}
+async function loadYamlFile(path, kind) {
+    let data;
+    try {
+        data = await readFile(path, "utf8");
+    }
+    catch (err) {
+        if (isNotFound(err)) {
+            return { profiles: {} };
+        }
+        throw new Error(`failed to read ${kind} file: ${errMessage(err)}`);
+    }
+    try {
+        return parseYAML(data) ?? { profiles: {} };
+    }
+    catch (err) {
+        throw new Error(`failed to parse ${kind} file: ${errMessage(err)}`);
+    }
+}
+function isNotFound(err) {
+    return err?.code === "ENOENT";
+}
+function errMessage(err) {
+    return err instanceof Error ? err.message : String(err);
+}
+// --- Path resolution ---------------------------------------------------------
+function credentialsPath(dp) {
+    return dp.credentialsFilePath
+        ? expandPath(dp.credentialsFilePath)
+        : defaultCredentialsPath();
+}
+function settingsPath(dp) {
+    return dp.settingsFilePath ? expandPath(dp.settingsFilePath) : defaultSettingsPath();
+}
+function defaultCredentialsPath() {
+    return expandPath(DEFAULT_CREDENTIALS_FILE_PATH);
+}
+function defaultSettingsPath() {
+    return expandPath(DEFAULT_SETTINGS_FILE_PATH);
+}
+/** Expands a leading `~` and `$HOME`/`${HOME}` to the user's home directory. */
+function expandPath(path) {
+    const home = homedir();
+    return path
+        .replace(/^~(?=\/|$)/, home)
+        .replace(/\$\{HOME\}/g, home)
+        .replace(/\$HOME/g, home);
+}
+// Compile-time guard: this variant must match the shared loader signatures so
+// `#config-loader` resolves identically in Node and the browser.
+const _loadDefaultConfig = loadDefaultConfig;
+const _getEndpointOverride = getEndpointOverride;
+void _loadDefaultConfig;
+void _getEndpointOverride;