documentation updated for per-plugin subdirectories (ref. #50)

docs/ARCHITECTURE.md

@@ -7,20 +7,20 @@ Eventually this will document the architecture of LibResilient.
 There are three kinds of plugins:
 
 - **Transport plugins**  
-  Plugins that *retrieve* website content, for example by using regular HTTPS [`fetch()`](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API), or by going through [IPFS](https://js.ipfs.io/). They *should* also offer a way to *publish* content by website admins (if relevant credentials or encryption keys are provided, depending on the method).  
+  Plugins that *retrieve* remote content by any means, for example by using regular HTTPS [`fetch()`](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API), or by going through [IPFS](https://js.ipfs.io/). They *should* also offer a way to *publish* content by website admins (if relevant credentials or encryption keys are provided, depending on the method).  
 Methods these plugins implement:
   - `fetch` - fetch content from an external source (e.g., from IPFS)
   - `publish` - publish the content to the external source (e.g., to IPFS)
 
 - **Stashing plugins**  
-  Plugins that *stash* content locally (e.g., in the [browser cache](https://developer.mozilla.org/en-US/docs/Web/API/Cache)) for displaying when no *transport plugin* works, or before content is received via one of them.  
+  Plugins that *stash* content locally (for example, in the [browser cache](https://developer.mozilla.org/en-US/docs/Web/API/Cache)). This is useful when no *transport plugin* works, or before remote content is received.  
 Methods these plugins implement:
   - `fetch` - fetch the locally stored content (e.g., from cache)
   - `stash` - stash the content locally (e.g., in cache)
   - `unstash` - clear the content from the local store (e.g., clear the cache)
 
-- **Composing plugins**  
-  Plugins that *compose* other plugins, for example by running them simultaneously to retrieve content from whichever succeeds first.  
+- **Composing plugins** and **Wrapping plugins**  
+  Plugins that *compose* multiple other plugins (for example, by running them simultaneously to retrieve content from whichever succeeds first); or that *wrap* other plugins, applying some action to the results returned by the wrapped plugin (for instance, checking known resource integrity hashes on returned content).  
 Methods these plugins implement depend on which plugins they compose. Additionally, plugins being composed the `uses` key, providing the configuration for them the same way configuration is provided for plugins in the `plugins` key of `LibResilientConfig` (which is configurable via `config.json`).
 
 Every plugin needs to be implemented as a constructor function that is added to the `LibResilientPluginConstructors` [Map()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map) object for later instantiation.
@@ -68,7 +68,26 @@ uses: [{
 }]
 ```
 
-If these mappings are to be configured via the global configuration file, the `uses` key should instead point to `config.uses`:
+If these mappings are to be configured via the global configuration file (which is most often the case), the `uses` key should instead point to `config.uses`:
+
+```javascript
+uses: config.uses
+```
+
+### Wrapping plugins
+
+Wrapping plugins wrap other plugins, in order to performing some actions on request data sent to them, or on response data received from them.
+A wrapping plugin needs to set the `uses` key in the object returned by it's constructor. The key should contain a mapping from wrapped plugin name to configuration:
+
+```javascript
+uses: [{
+          name: "composed-plugin-1",
+          configKey1: "whatever-data-here"
+      }
+}]
+```
+
+If this mapping is to be configured via the global configuration file (which is most often the case), the `uses` key should instead point to `config.uses`:
 
 ```javascript
 uses: config.uses

docs/QUICKSTART.md

@@ -15,11 +15,11 @@ We are going to assume a simple website, consisting of:
 
  - `index.html`
  - `favicon.ico`
- - an `/assets/` directory, containing:
+ - an `assets/` directory, containing:
    - `style.css`
    - `logo.png`
    - `font.woff`
- - a `/blog/` directory, containing two blog posts:
+ - a `blog/` directory, containing two blog posts:
    - `01-first.html`
    - `02-second.html`
 
@@ -38,9 +38,9 @@ To start, we need:
  - [`service-worker.js`](https://gitlab.com/rysiekpl/libresilient/-/blob/master/service-worker.js)\
    This is the heart of LibResilient. Once loaded, it will use the supplied configuration (in `config.json`) to load and configure plugins. Plugins in turn will perform actual requests and other tasks.
    
- - the [`fetch` plugin](https://gitlab.com/rysiekpl/libresilient/-/blob/master/plugins/fetch.js)\
+ - the [`fetch` plugin](https://gitlab.com/rysiekpl/libresilient/-/blob/master/plugins/fetch/)\
    This LibResilient plugin uses the basic [Fetch API](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API) to retrieve content.\
-   LibResilient expects plugins in the `plugins/` subdirectory of the directory where the `service-worker.js` script is located, so this file should be saved as `/plugins/fetch.js` for our hypothetical website.
+   LibResilient expects plugins to be in the `plugins/` subdirectory of the directory where the `service-worker.js` script is located; each plugin is a directory with at least the file `index.js` in it (containing plugin code). In our case this means `/plugins/fetch/index.js` should exist for our hypothetical website.
    
  - `config.json`\
    That's the config file, and should also reside in the same directory as `service-worker.js`.\
@@ -60,7 +60,7 @@ Our `config.json` has to be a [valid JSON file](https://jsonlint.com/); for now
 Let's unpack this:
 
  - The `plugins` key contains an array of objects.\
-   Each object defines configuration for a plugin. For simplest plugins, the minimal configuration is just the name of the plugin. Based on the name `service-worker.js` establishes which file to load for a given plugin — in this case, it will be `./plugins/fetch.js` (relative to where `service-worker.js` is).
+   Each object defines configuration for a plugin. For simplest plugins, the minimal configuration is just the name of the plugin. Based on the name `service-worker.js` establishes which file to load for a given plugin — in this case, it will be `./plugins/fetch/index.js` (relative to where `service-worker.js` script is located).
    
  - The `loggedComponents` key is a narray of strings.\
    It lists the components whose logs should be visible in the deveoper console in the browser. The `service-worker.js` script logs messages as the "service-worker" component, the `fetch` plugin as (you guessed it!) "fetch".\
@@ -70,26 +70,27 @@ With all this, our website structure now looks like this:
 
  - `index.html`
  - `favicon.ico`
- - `/assets/`
+ - `assets/`
    - `style.css`
    - `logo.png`
    - `font.woff`
- - `/blog/`
+ - `blog/`
    - `01-first.html`
    - `02-second.html`
  - **`config.json`**
  - **`libresilient.js`**
  - **`service-worker.js`**
- - **`/plugins/`**
-   - **`fetch.js`**
+ - **`plugins/`**
+   - **`fetch/`**
+     - **`index.js`**
 
-We also need to add this to the `<head>` section of our `index.html`, and HTML files in the `/blog/` directory:
+We also need to add this to the `<head>` section of our `index.html`, and HTML files in the `blog/` directory:
 
 ```html
 <script defer src="/libresilient.js"></script>
 ```
 
-Once we deploy these changes, our HTML files will load `libresilient.js` for each visitor, which in turn will register `service-worker.js`. That code in turn will load `config.json`, and based on it, will load `/plugins/fetch.js`.
+Once we deploy these changes, our HTML files will load `libresilient.js` for each visitor, which in turn will register `service-worker.js`. That code in turn will load `config.json`, and based on it, will load `/plugins/fetch/index.js`.
 
 Each user of our website, after visiting any of the HTML pages, will now have their browser load and register the Libresilient service worker, as configured. From that point on all initiated in the context of our website will always be handled by LibResilient, and in this particular configuration — the `fetch` plugin.
 
@@ -101,9 +102,9 @@ Bare minimum would be to add offline cache to our website. This would at least a
 
 This is now easy to do. We need just two things:
 
- - the [`cache` plugin](https://gitlab.com/rysiekpl/libresilient/-/blob/master/plugins/cache.js)\
+ - the [`cache` plugin](https://gitlab.com/rysiekpl/libresilient/-/blob/master/plugins/cache/)\
    This LibResilient plugin makes use of the [Cache API](https://developer.mozilla.org/en-US/docs/Web/API/Cache) to store and retrieve content offline.\
-   As with `fetch` plugin before, we need it in the `/plugins/` subdirectory of our website.
+   As with `fetch` plugin before, we need it in the `plugins/` subdirectory of our website.
    
  - a small modification of our `config.json` to enable the `cache` plugin.
 
@@ -111,19 +112,21 @@ Our website structure is now:
 
  - `index.html`
  - `favicon.ico`
- - `/assets/`
+ - `assets/`
    - `style.css`
    - `logo.png`
    - `font.woff`
- - `/blog/`
+ - `blog/`
    - `01-first.html`
    - `02-second.html`
  - `config.json`
  - `libresilient.js`
  - `service-worker.js`
- - `/plugins/`
-   - `fetch.js`
-   - **`cache.js`**
+ - `plugins/`
+   - `fetch/`
+     - `index.js`
+   - **`cache/`**
+     - **`index.js`**
  
 Our `config.json` should now look like this:
 
@@ -156,8 +159,8 @@ What this gives us is that any content successfully retrieved by `fetch` will no
 > - **"transport"** plugins\
 >   These are the plugins that are able to access content remotely, by whatever means; `fetch` plugin is an example of a transport plugin. There are others, and we will use them later on.
 >   
-> - **"wrapper"** plugins\
->   These are plugins that wrap other plugins to add functionality. To function, wrapping plugins need other plugins to "wrap". We will cover this later.
+> - **"composing"** and **"wrapping"** plugins\
+>   These are plugins that wrap other plugins to add functionality. To function, composing/wrapping plugins need other plugins to "compose"/"wrap". We will cover this later.
 
 ### Cache-first?
 
@@ -184,7 +187,7 @@ But it does not let them get new content in such a case. For that we need an alt
 
 The simplest available is the `alt-fetch` transport plugin. It still uses the Fetch API, but instead of fetching content from the original website address, it uses other, configured endpoints. We will need:
 
- - the [`alt-fetch` plugin](https://gitlab.com/rysiekpl/libresilient/-/blob/master/plugins/alt-fetch.js)\
+ - the [`alt-fetch` plugin](https://gitlab.com/rysiekpl/libresilient/-/blob/master/plugins/alt-fetch/)\
    This LibResilient plugin performs [`fetch()`](https://developer.mozilla.org/en-US/docs/Web/API/fetch) to configured alternative endpoints in order to retrieve content.
    
  - some actual alternative endpoint where our website content can be made available\
@@ -197,20 +200,23 @@ Updated website structure looks like this now:
 
  - `index.html`
  - `favicon.ico`
- - `/assets/`
+ - `assets/`
    - `style.css`
    - `logo.png`
    - `font.woff`
- - `/blog/`
+ - `blog/`
    - `01-first.html`
    - `02-second.html`
  - `config.json`
  - `libresilient.js`
  - `service-worker.js`
- - `/plugins/`
-   - `fetch.js`
-   - `cache.js`
-   - **`alt-fetch.js`**
+ - `plugins/`
+    - `fetch/`
+     - `index.js`
+   - `cache/`
+     - `index.js`
+   - **`alt-fetch/`**
+     - **`index.js`**
  
 And the `config.json` file contains: