Merge pull request #14 from Conjur-Enterprise/apiv2-documentation

CNJR-0000: Update documentation for streaming secret values feature

README.md

@@ -240,6 +240,14 @@ fixed locations, e.g. `/etc/ssl/cert.pem` for an SSL certificate. This can be
 accomplished by using symbolic links as described in the
 [symbolic link example](examples/symlinks/README.md).
 
+## Provider interactive mode
+
+When available, Summon uses the provider's stream mode to retrieve secrets. Whereas the legacy mode required
+a new process to be created for each secret retrieval, the stream mode can fetch multiple secrets in a single
+process and allows providers to implement token caching.
+
+If the provider does not support stream mode, Summon uses the legacy mode.
+
 ## Contributing
 
 For more info on contributing, please see [CONTRIBUTING.md](CONTRIBUTING.md).

docs/_includes/content.md

@@ -100,6 +100,14 @@ This is their contract:
 * If retrieval is successful, they return the value on stdout with exit code 0.
 * If an error occurs, they return an error message on stderr and a non-0 exit code.
 
+When providers support stream mode and a call is made without arguments, Summon continuously sends
+secret identifiers to the provider's standard input, and the provider sends the secret values to its
+standard output until all secrets are retrieved. The returned values are Base64 encoded to avoid issues with
+special characters.
+
+Summon always tries to use stream mode. However, when this mode is not supported Summon falls back
+to the legacy mode where each secret is retrieved using its own process.
+
 The default path for providers is `/usr/local/lib/summon/`. If one provider is in that path,
 summon will use it. If multiple providers are in the path, you can specify which one to use
 with the `--provider` flag or the environment variable `SUMMON_PROVIDER`. If your providers are