aws-cdk/lib/cli/proxy-agent.d.ts

AWS CDK Toolkit CLI, the command line tool for CDK apps

import { ProxyAgent } from 'proxy-agent';
/**
 * Validate a proxy address up front.
 *
 * `proxy-agent` only rejects an address with a missing or unsupported protocol
 * lazily, on the first request, so without `-vvv` the CLI appears to hang or
 * fails later with a misleading error (e.g. missing credentials). Fail fast
 * here with an actionable message instead.
 */
export declare function validateProxyAddress(proxyAddress: string): void;
/**
 * Coerce a raw network setting into a value the rest of the CLI can rely on.
 *
 * `Settings.get()` is untyped and surfaces an unset `--proxy` or `--ca-bundle-path` as either
 * `undefined` or an empty array, depending on how it was parsed. An empty STRING is a different
 * thing: `--proxy ''` means "go direct, ignore the proxy environment variables", so it has to survive
 * normalization. Anything that is not a string counts as unconfigured, which is what makes the
 * environment the fallback.
 *
 * Applied at the point these settings enter typed code, for two reasons. An empty array is truthy, so
 * it slips past every `if (value)` guard downstream and then fails somewhere unhelpful --
 * `path.resolve([])` throws a `TypeError` that the CA-bundle resolver swallows, silently discarding
 * the bundle. And both values now cross a process boundary into the detached telemetry sender, which
 * has no access to the settings to re-derive them.
 */
export declare function normalizeNetworkSetting(raw: unknown): string | undefined;
/**
 * Options for proxy-agent SDKs
 */
interface ProxyAgentOptions {
    /**
     * Proxy address to use
     *
     * @default No proxy
     */
    readonly proxyAddress?: string;
    /**
     * A path to a certificate bundle that contains a cert to be trusted.
     *
     * @default No certificate bundle
     */
    readonly caBundlePath?: string;
}
/**
 * The proxy configuration resolved for this invocation.
 */
export interface ResolvedProxyAgent {
    /**
     * The agent to pass to anything making HTTPS requests in this process.
     */
    readonly agent: ProxyAgent;
    /**
     * Absolute path to the resolved CA bundle, if one was configured and exists on disk.
     *
     * Exposed because `agent` cannot cross a process boundary: the detached telemetry sender builds its
     * own and needs to be told which bundle to trust. The path travels rather than the bytes, because a
     * system bundle is routinely ~190KB.
     *
     * @default - no CA bundle was configured, or the configured one does not exist
     */
    readonly caBundlePath?: string;
}
/**
 * The part of `IoHelper` that proxy resolution needs.
 *
 * Structural so the detached telemetry sender, which has no IoHost, can pass a writer that goes to
 * stderr instead. A full `IoHelper` satisfies this as-is.
 */
export interface ProxyAgentDiagnostics {
    readonly defaults: {
        debug(message: string): Promise<void>;
    };
}
export declare class ProxyAgentProvider {
    private readonly ioHelper;
    constructor(ioHelper: ProxyAgentDiagnostics);
    create(options: ProxyAgentOptions): Promise<ResolvedProxyAgent>;
    /**
     * Resolve the configured CA bundle to an absolute path, or undefined if there isn't a usable one.
     *
     * Absolute because the path is handed to the detached sender, which runs from a different cwd.
     */
    private resolveCABundlePath;
    private tryReadCABundle;
    /**
     * Find and return a CA certificate bundle path to be passed into the SDK.
     */
    private caBundlePathFromEnvironment;
}
export {};