more documentation for any-of and basic-integrity plugins (ref. #51)

plugins/any-of/README.md

@@ -6,3 +6,20 @@
 The `any-of` composing plugin runs all plugins configured in its `uses:` configuration field simultaneously (using [`Promise.any()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise/any)), and returns the firs successful response it receives.
 
 In other words, it makes it possible to *simultaneously* try several different transport plugins, and return the response as soon as the first one succeeds.
+
+## Configuration
+
+
+The `any-of` plugin supports the following configuration options:
+
+ - `uses` (required)  
+   Array of objects, each object being in turn a configuration of a plugin. All configured plugins are used simultaneously to handle any `fetch()` requests, returning the first successful response received.
+
+
+## Performance and usability considerations
+
+It is important to understand that using this plugin in conjunction with resource-intensive transport plugins might lead to a degraded performance in visitors' browsers, as all plugins configured for use by `any-of` will be processing the requests *at the same time*.
+
+On the other hand, some transport plugins are slower than others while being more resilient to network issues. So using `any-of` and mixing slow-but-resilient transport plugins with fast-but-less-resilient ones might actually *improve* user experience: content is retrieved by the faster plugin when possible, otherwise it is retrieved by a slower plugin without waiting for the faster plugin to time out and only then starting the request using the slower one.
+
+In the end, as is often the case, this is a balancing act.

plugins/basic-integrity/README.md

@@ -2,3 +2,25 @@
 
 - **status**: beta
 - **type**: [wrapping plugin](https://gitlab.com/rysiekpl/libresilient/-/blob/master/docs/ARCHITECTURE.md#wrapping-plugins)
+
+This plugin sets statically configured [Subresource Integrity (SRI)](https://developer.mozilla.org/en-US/docs/Web/Security/Subresource_Integrity) hashes on requests performed by configured wrapped transport plugins.
+
+This allows plugins that know how to handle it (or that use underlying browser APIs that automatically handle SRI, like [`fetch()`](https://developer.mozilla.org/en-US/docs/Web/API/fetch)) to verify integrity of retrieved content before returning it as a response.
+
+**IMPORTANT NOTE:** this plugin, by itself, does *not* verify the integrity of fetched resources; it merely sets the integrity data on the requests. It's up to the wrapped plugin to actually use that data to verify integrity (or rely on browser APIs like `fetch()` to handle this automatically.
+
+## Configuration
+
+The `basic-integrity` plugin supports the following configuration options:
+
+ - `uses` (required)  
+   Array containing exactly one object which is in turn a configuration of a wrapped plugin. This plugin will be used to actually handle any requests.
+   
+ - `integrity` (default: empty)
+   An object mapping absolute URLs (e.g. "`https://example.com/img/test.png`") to integrity hashes (e.g. "`sha384-kn5dhxz4RpBmx7xC7Dmq2N43PclV9U/niyh+4Km7oz5W0FaWdz3Op+3K0Qxz8y3z`"). Supported integrity hash algorithms [as per SRI specification](https://w3c.github.io/webappsec-subresource-integrity/#terms): `sha256`, `sha384`, `sha512`.  
+   The integrity string can contain multiple hashes, space-separated, [as per the standard](https://w3c.github.io/webappsec-subresource-integrity/#agility).
+   
+ - `requireIntegrity` (default: `true`)
+   Boolean value specifying if integrity data is required for a request to handled. That is: if a request is being handled for a URL that does not have integrity data associated with it, should the request be processed, or errored out?  
+   By default, `basic-integrity` plays it safe and assumes you want integrity data to be present for all resources being fetched; if you only want certain resources to have integrity verified, set this to `false`.  
+   Importantly, integrity data does not need to be explicitly configured in this plugin's config — if integrity data is available in the request already, that also counts, even if no specific data is configured for this URL in this plugin's config.