aws-cdk/lib/api/plugin/plugin.d.ts

CDK Toolkit, the command line tool for CDK apps

import { ContextProviderPlugin } from './context-provider-plugin';
import { CredentialProviderSource } from './credential-provider-source';
/**
 * The basic contract for plug-ins to adhere to::
 *
 *   import { Plugin, PluginHost } from 'aws-cdk';
 *   import { CustomCredentialProviderSource } from './custom-credential-provider-source';
 *
 *   export default class FooCDKPlugIn implements PluginHost {
 *     public readonly version = '1';
 *
 *     public init(host: PluginHost) {
 *     host.registerCredentialProviderSource(new CustomCredentialProviderSource());
 *     }
 *   }
 *
 */
export interface Plugin {
    /**
     * The version of the plug-in interface used by the plug-in. This will be used by
     * the plug-in host to handle version changes.
     */
    version: '1';
    /**
     * When defined, this function is invoked right after the plug-in has been loaded,
     * so that the plug-in is able to initialize itself. It may call methods of the
     * ``PluginHost`` instance it receives to register new ``CredentialProviderSource``
     * instances.
     */
    init?: (host: PluginHost) => void;
}
/**
 * A utility to manage plug-ins.
 *
 */
export declare class PluginHost {
    static instance: PluginHost;
    /**
     * Access the currently registered CredentialProviderSources. New sources can
     * be registered using the +registerCredentialProviderSource+ method.
     */
    readonly credentialProviderSources: CredentialProviderSource[];
    readonly contextProviderPlugins: Record<string, ContextProviderPlugin>;
    constructor();
    /**
     * Loads a plug-in into this PluginHost.
     *
     * @param moduleSpec the specification (path or name) of the plug-in module to be loaded.
     */
    load(moduleSpec: string): void;
    /**
     * Allows plug-ins to register new CredentialProviderSources.
     *
     * @param source a new CredentialProviderSource to register.
     */
    registerCredentialProviderSource(source: CredentialProviderSource): void;
    /**
     * (EXPERIMENTAL) Allow plugins to register context providers
     *
     * Context providers are objects with the following method:
     *
     * ```ts
     *   getValue(args: {[key: string]: any}): Promise<any>;
     * ```
     *
     * Currently, they cannot reuse the CDK's authentication mechanisms, so they
     * must be prepared to either not make AWS calls or use their own source of
     * AWS credentials.
     *
     * This feature is experimental, and only intended to be used internally at Amazon
     * as a trial.
     *
     * After registering with 'my-plugin-name', the provider must be addressed as follows:
     *
     * ```ts
     * const value = ContextProvider.getValue(this, {
     *   providerName: 'plugin',
     *   props: {
     *     pluginName: 'my-plugin-name',
     *     myParameter1: 'xyz',
     *   },
     *   includeEnvironment: true | false,
     *   dummyValue: 'what-to-return-on-the-first-pass',
     * })
     * ```
     *
     * @experimental
     */
    registerContextProviderAlpha(pluginProviderName: string, provider: ContextProviderPlugin): void;
}