mirror
/
libresilient
kopia lustrzana https://gitlab.com/rysiekpl/libresilient
1
0
Forkuj 0
Kod Zgłoszenia Projekty Wydania Wiki Aktywność

updating the documentation wrt. JSON config (ref. #31)

merge-requests/11/head
Michał 'rysiek' Woźniak 2022-01-25 00:47:24 +00:00
rodzic 629b2eef33
commit 6d6af2b13e
2 zmienionych plików z 55 dodań i 57 usunięć
Pokaż statystyki Ściągnij plik aktualizacji Ściągnij plik porównania Expand all files Collapse all files

28
docs/ARCHITECTURE.md
Wyświetl plik

@ -21,7 +21,7 @@ Methods these plugins implement:
- **Composing plugins**
Plugins that *compose* other plugins, for example by running them simultaneously to retrieve content from whichever succeeds first.
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`.
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.
@ -76,7 +76,7 @@ uses: config.uses
## Fetching a resource via LibResilient
Whenever a resource is being fetched on a LibResilient-enabled site, the `service-worker.js` script dispatches plugins in the set order. This order is configured via the `plugins` key of the `LibResilientConfig` variable, usually set in `config.json` config file.
Whenever a resource is being fetched on a LibResilient-enabled site, the `service-worker.js` script dispatches plugins in the set order. This order is configured via the `plugins` key of the `LibResilientConfig` variable, usually set via the `config.json` config file.
A minimal default configuration is hard-coded in case no site-specific configuration is provided. This default configuration runs these plugins:
@ -85,17 +85,19 @@ A minimal default configuration is hard-coded in case no site-specific configura
A more robust configuration could look like this:
```javascript
self.LibResilientConfig.plugins = [{
name: 'fetch'
},{
name: 'cache'
},{
name: 'alt-fetch',
endpoints: [
'https://fallback-endpoint.example.com'
]}
}]
```json
{
"plugins": [{
"name": "fetch"
},{
"name": "cache"
},{
"name": "alt-fetch",
"endpoints": [
"https://fallback-endpoint.example.com"
]}
}]
}
```
For each resource, such a config would:

84
docs/CONTENT_INTEGRITY.md
Wyświetl plik

@ -42,30 +42,29 @@ If using `alt-fetch` as the transport pluging, we can rely on the Fetch API impl
The minimal config could in such a case look something like this:
```javascript
self.LibResilientConfig.plugins = [{
name: 'basic-integrity',
// integrity data for certain resources
integrity: {
'/some/image.png': 'sha256-<integrity-data>',
'/index.html': 'sha384-<integrity-data>',
'/css/style.css': 'sha512-<integrity-data>',
'/documents/example.pdf': 'sha384-<integrity-data> sha256-<integrity-data>'
},
// wrapped transport plugin, in this case alt-fetch
uses: [{
name: 'alt-fetch',
// configuring the alternate endpoints plugin to use IPNS gateways
endpoints: [
'https://<CIDv1>.ipns.dweb.link/', // USA
'https://ipfs.kxv.io/ipns/<CIDv0-or-CIDv1>/', // Hong Kong
'https://jorropo.net/ipns/<CIDv0-or-CIDv1>/', // France
'https://gateway.pinata.cloud/ipns/<CIDv0-or-CIDv1>/', // Germany
'https://<CIDv1>.ipns.bluelight.link/' // Singapore
```json
{
"plugins": [{
"name": "basic-integrity",
"integrity": {
"/some/image.png": "sha256-<integrity-data>",
"/index.html": "sha384-<integrity-data>",
"/css/style.css": "sha512-<integrity-data>",
"/documents/example.pdf": "sha384-<integrity-data> sha256-<integrity-data>"
},
"uses": [{
"name": "alt-fetch",
"endpoints": [
"https://<CIDv1>.ipns.dweb.link/",
"https://ipfs.kxv.io/ipns/<CIDv0-or-CIDv1>/",
"https://jorropo.net/ipns/<CIDv0-or-CIDv1>/",
"https://gateway.pinata.cloud/ipns/<CIDv0-or-CIDv1>/",
"https://<CIDv1>.ipns.bluelight.link/"
]
}]
}]
]
}]
}]
}
```
### Scenario 2. `non-fetch`, a hypothetical plugin not based on Fetch API
@ -74,27 +73,24 @@ When *not* using a Fetch API based plugin as the transport pluging, we must expl
Example minimal config:
```javascript
self.LibResilientConfig.plugins = [{
name: 'basic-integrity',
// integrity data for certain resources
integrity: {
'/some/image.png': 'sha256-<integrity-data>',
'/index.html': 'sha384-<integrity-data>',
'/css/style.css': 'sha512-<integrity-data>',
'/documents/example.pdf': 'sha384-<integrity-data> sha256-<integrity-data>'
},
// wrapped integrity-check plugin, ensuring integrity of content
// returned by the transport plugin will be verified
uses: [{
name: 'integrity-check',
uses: [{
// finally, the wrapped transport plugin, in this case not-fetch
name: 'not-fetch',
// any not-fetch related config here
}]
}]
}]
```json
{
"plugins": [{
"name": "basic-integrity",
"integrity": {
"/some/image.png": "sha256-<integrity-data>",
"/index.html": "sha384-<integrity-data>",
"/css/style.css": "sha512-<integrity-data>",
"/documents/example.pdf": "sha384-<integrity-data> sha256-<integrity-data>"
},
"uses": [{
"name": "integrity-check",
"uses": [{
"name": "not-fetch"
}]
}]
}]
}
```
## Integrity data for dynamic resources