chore: Documentation for plugins (#733)

Added basic documentation for the Plugins mechanism and surface it offers
in the `Tools` section of the documentation.

Fixes #717

docs/src/tools.rst

@@ -139,3 +139,238 @@ To out-out, use one of the following methods:
           "versionReporting": false
         }
 
+Plugins
+=======
+
+The |cdk| toolkit provides extension points that enable users to augment the features provided by
+the toolkit. There is currently only one extension point, allowing users to define custom AWS
+credential providers, but other extension points may be added in the future as the needs arise.
+
+Loading Plugins
+---------------
+
+Plugins can be loaded by providing the Node module name (or path) to the CDK toolkit:
+
+1. Using the ``--plugin`` command line option (which can be specified multiple times):
+
+   .. code-block:: console
+
+      $ cdk list --plugin=module
+      $ cdk deploy --plugin=module_1 --plugin=module_2
+
+2. Adding entries to the ``~/.cdk.json`` or ``cdk.json`` file:
+
+   .. code-block:: js
+
+      {
+        // ...
+        "plugin": [
+            "module_1",
+            "module_2"
+        ],
+        // ...
+      }
+
+Authoring Plugins
+-----------------
+
+Plugins must be authored in TypeScript or Javascript, and are defined by implementing a Node module
+that implements the following protocol, and using :js:class:`~aws-cdk.PluginHost` methods:
+
+.. tabs::
+    .. code-tab:: typescript
+
+        import cdk = require('aws-cdk');
+
+        export = {
+            version: '1', // Version of the plugin infrastructure (currently always '1')
+            init(host: cdk.PluginHost): void {
+                // Your plugin initialization hook.
+                // Use methods of ``host`` to register custom code with the CDK toolkit
+            }
+        };
+
+    .. code-tab:: javascript
+
+        export = {
+            version: '1', // Version of the plugin infrastructure (currently always '1')
+            init(host) {
+                // Your plugin initialization hook.
+                // Use methods of ``host`` to register custom code with the CDK toolkit
+            }
+        };
+
+Credential Provider Plugins
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Custom credential providers are classes implementing the
+:js:class:`~aws-cdk.CredentialProviderSource` interface, and registered to the toolkit using
+the :js:func:`~aws-cdk.PluginHost.registerCredentialProviderSource` method.
+
+.. tabs::
+   .. code-tab:: typescript
+
+      import cdk = require('aws-cdk');
+      import aws = require('aws-sdk');
+
+      class CustomCredentialProviderSource implements cdk.CredentialProviderSource {
+        public async isAvailable(): Promise<boolean> {
+          // Return ``false`` if the plugin could determine it cannot be used (for example,
+          // if it depends on files that are not present on this host).
+          return true;
+        }
+
+        public async canProvideCredentials(accountId: string): Promise<boolean> {
+          // Return ``false`` if the plugin is unable to provide credentials for the
+          // requested account (for example if it's not managed by the credentials
+          // system that this plugin adds support for).
+          return true;
+        }
+
+        public async getProvider(accountId: string, mode: cdk.Mode): Promise<aws.Credentials> {
+          let credentials: aws.Credentials;
+          // Somehow obtain credentials in ``credentials``, and return those.
+          return credentials;
+        }
+      }
+
+      export = {
+        version = '1',
+        init(host: cdk.PluginHost): void {
+          // Register the credential provider to the PluginHost.
+          host.registerCredentialProviderSource(new CustomCredentialProviderSource());
+        }
+      };
+
+   .. code-tab:: javascript
+
+      class CustomCredentialProviderSource {
+        async isAvailable() {
+          // Return ``false`` if the plugin could determine it cannot be used (for example,
+          // if it depends on files that are not present on this host).
+          return true;
+        }
+
+        async canProvideCredentials(accountId) {
+          // Return ``false`` if the plugin is unable to provide credentials for the
+          // requested account (for example if it's not managed by the credentials
+          // system that this plugin adds support for).
+          return true;
+        }
+
+        async getProvider(accountId, mode) {
+          let credentials;
+          // Somehow obtain credentials in ``credentials``, and return those.
+          return credentials;
+        }
+      }
+
+      export = {
+        version = '1',
+        init(host) {
+          // Register the credential provider to the PluginHost.
+          host.registerCredentialProviderSource(new CustomCredentialProviderSource());
+        }
+      };
+
+Note that the credentials obtained from the providers for a given account and mode will be cached,
+and as a consequence it is strongly advised that the credentials objects returned are self-refreshing,
+as descibed in the `AWS SDK for Javascript documentation <https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/Credentials.html>`_.
+
+Reference
+---------
+
+.. js:module:: aws-cdk
+
+CredentialProviderSource *(interface)*
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. js:class:: CredentialProviderSource
+
+   .. js:attribute:: name
+
+      A friendly name for the provider, which will be used in error messages, for example.
+
+      :type: ``string``
+
+   .. js:method:: isAvailable()
+
+      Whether the credential provider is even online. Guaranteed to be called before any of the other functions are called.
+
+      :returns: ``Promise<boolean>``
+
+   .. js:method:: canProvideCredentials(accountId)
+
+      Whether the credential provider can provide credentials for the given account.
+
+      :param string accountId: the account ID for which credentials are needed.
+      :returns: ``Promise<boolean>``
+
+   .. js:method:: getProvider(accountId, mode)
+
+      Construct a credential provider for the given account and the given access mode.
+      Guaranteed to be called only if canProvideCredentails() returned true at some point.
+
+      :param string accountId: the account ID for which credentials are needed.
+      :param aws-cdk.Mode mode: the kind of operations the credentials are intended to perform.
+      :returns: ``Promise<aws.Credentials>``
+
+Mode *(enum)*
+^^^^^^^^^^^^^
+
+.. js:class:: Mode
+
+   .. js:data:: ForReading
+
+      Credentials are inteded to be used for read-only scenarios.
+
+   .. js:data:: ForWriting
+
+      Credentials are intended to be used for read-write scenarios.
+
+Plugin *(interface)*
+^^^^^^^^^^^^^^^^^^^^
+
+.. js:class:: Plugin()
+
+   .. js:attribute:: version
+
+      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. Currently, the only valid value for
+      this attribute is ``'1'``.
+
+      :type: ``string``
+
+   .. js:method:: init(host)
+
+      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
+      :js:class:`~aws-cdk.PluginHost` instance it receives to register new
+      :js:class:`~aws-cdk.CredentialProviderSource` instances.
+
+      :param aws-cdk.PluginHost host: The |cdk| plugin host
+      :returns: ``void``
+
+PluginHost
+^^^^^^^^^^
+
+.. js:class:: PluginHost()
+
+   .. js:data:: instance
+
+      :type: :js:class:`~aws-cdk.PluginHost`
+
+   .. js:method:: load(moduleSpec)
+
+      Loads a plug-in into this PluginHost.
+
+      :param string moduleSpec: the specification (path or name) of the plug-in module to be loaded.
+      :throws Error: if the provided ``moduleSpec`` cannot be loaded or is not a valid :js:class:`~aws-cdk.Plugin`.
+      :returns: ``void``
+
+   .. js:method:: registerCredentialProviderSource(source)
+
+      Allows plug-ins to register new :js:class:`~aws-cdk.CredentialProviderSources`.
+
+      :param aws-cdk.CredentialProviderSources source: a new CredentialProviderSource to register.
+      :returns: ``void``