libresilient/docs/FAQ.md

82 wiersze
8.1 KiB
Markdown
Czysty Zwykły widok Historia

2022-06-16 02:34:20 +00:00
# Frequently Asked Questions
## General questions
### Can LibResilient handle dynamic content?
Yes, but that depends on what alternative transports are used and how. For example, if the particular website uses the [`alt-fetch` plugin](../plugins/alt-fetch/), and all the alternative endpoints configured for it are just reverse proxies that hit the original back-end server, dynamic content would be served perfectly fine.
That approach has a downside, however: if the original backend is completely down (for example, due to hardware failure), LibResilient would not be able to fetch the content. Depending on what is the purpose of LibResilient deployment on a given site, this might or might not be acceptable.
2022-06-16 02:34:20 +00:00
For best resilience it is recommended to either use static sites (that is, websites whose content is served as static files, often generated with the help of static site generators) or at least to build the website in a way such that it lends itself to caching or serving out as static files.
2022-06-16 02:34:20 +00:00
### Can LibResilient handle comments, forms, or other types of visitor interactivity?
2022-06-16 02:34:20 +00:00
Assuming a pretty standard LibResilient set-up, where the [`fetch` plugin](../plugins/fetch/) is configured as the first plugin in the config file, website functionality will not differ from how it would have worked without LibResilient deployed — as long as the original domain remains accessible. When it goes down, and other plugins kick-in, interactivity that requires the original back-end to be available will not work as expected.
2022-06-16 02:34:20 +00:00
LibResilient *only* handles `GET` requests. `POST` requests, websocket connections, and the like are left for the browser to handle. This is done by design, to avoid interfering with website functionality that cannot be handled well by LibResilient.
2022-06-16 02:34:20 +00:00
Of course, any third-party dynamic content (a comment section hanlded by a third party comment interface provider, a "chat with agent" provided by a third party, website analytics solution using third-party servers, etc) will work fine. LibResilient only handles requests that go to the original domain.
2022-06-16 02:34:20 +00:00
LibResilient focuses on making sure that content stays online. For this it needs to make certain assumptions. One of those assumtpions is that the content is not interactive in a way that requires live contact with the back-end of a LibResilient-enabled website. You can find a more in-depth explanation of the reasons behind this [here](./PHILOSOPHY.md).
### Will LibResilient interfere with the admin panel of my website?
No, it should not. As mentioned above, LibResilient does not handle `POST` requests nor websocket connections, leaving them to be handled by the browser, and these are the most common ways admin panels and other such tools provide interactivity.
This also means that LibResilient will not help keep your admin panel functional in case of any kind of downtime. LibResilient focuses on keeping content available in case of website availability problems, not on keeping functionality unchanged.
A good strategy, therefore, is to deploy LibResilient for the public part of a website, and use some other solution (like Tor or a VPN) to harden the admin panel separately.
### Will LibResilient's alternative transports leak cookies to third parties?
No. Currently alternative transport plugins have no access to any headers of the original [Request object](https://developer.mozilla.org/en-US/docs/Web/API/Request) passed on to LibResilient when handling a `fetch` event. Therefore they cannot leak any cookies or any other headers to any third parties they might rely on for content retrieval (like the alternative endpoints when using the [`alt-fetch` plugin](../plugins/alt-fetch/)).
This is another reason why, as discussed above, LibResilient cannot help keep available any interactive functionality of a website that relies on availability of the original back-end (self-hosted comment sections, admin panel, etc).
2022-06-16 02:34:20 +00:00
## Service workers
### What is a service worker?
Service worker is a piece of JavaScript code that is served by the website and registered with the browser, and runs whenever the user tries to visit a website. Service workers can do many things, but most importantly they can manage caches and they can handle `fetch` events. The latter means that the service worker for a given website can be made to handle *all* requests originating from that website, which would otherwise be handled by the browser's built-in `fetch` handler.
More information on the Service Worker API [is available in MDN](https://developer.mozilla.org/en-US/docs/Web/API/Service_Worker_API).
### Can the service worker be updated when the original domain is not accessible?
No, it cannot. This is clearly specified in the API. Until the website on the original domain becomes available again, the code associated with the service worker cannot be updated or modified.
In the context of LibResilient, this means that even when LibResilient is deployed on a website, and works as expected (pulling content from alternative endpoints or through alternative transports), as long as the original domain is down it is *impossible* to update the service worker or load new plugins.
It is, however, possible to change LibResilient's configuration (including configuration of already loaded plugins), as `config.json` is not a JavaScript file and therefore it is *not* treated as code by browsers. You can read more on updating LibResilient's configuration during disruption [here](./UPDATING_DURING_DISRUPTION.md).
### Can a buggy service worker be removed from clients?
Yes, as long as the website on the original domain is up. The Service Worker API only allows installing, updating, and removing service workers for a given website from that website directly.
### If the original domain is down and the service worker is buggy, how long until it gets automatically removed by the browser?
Eventually the browser will remove a service worker. It is unlcear after how long, exactly, but probably a few weeks.
### Can the service worker be deployed only for a specific subdirectory of a website?
Yes, in two ways:
- Implicitly by simply placing the `libresilient.js` loader file and the `service-worker.js` service worker in a subdirectory of the website;
- By using the `scope` init parameter when registering the service worker; see the [`libresilient.js` loader script](../libresilient.js) for example how that parameter is used.
Important note: the Service Worker API does not allow a service worker to handle any requests that originate higher in the directory structure than where the service worker script is hosted itself. In other words, a service worker script under `/some-place/service-worker.js` will *not* be allowed to handle requests for `/some-file.png`, nor `/other-place/index.html`.
By using the `scope` parameter you can further limit the scope of Libresilient's service worker. For example, with the service worker script at `/some-place/service-worker.js` and scope set to `/some-place/go-deeper/`, LibResilient will *only* handle requests for `/some-place/go-deeper/` and below.
### What if the original domain is irrevocably lost/made inaccessible, but the service worker makes the website still work for visitors who had visited before?
The correct way to deal with that is by redirecting them to the new domain using the [`redirect` plugin](../plugins/redirect/).
Crucially, that plugin needs to have been loaded by the service worker when the original website was still up. This means that if you expect that at some point the website might become permanently inaccessible, make sure to add the `redirect` plugin to your LibResilient `config.json` file, but set `enabled` configuration field for that plugin to `false`. That way the plugin code gets loaded into the service worker, but plugin is not actually used to handle any requests.
This gives you the chance to update the `config.json` file when the website is down (using any of the alternative transport plugins that were configured and enabled) to enable the `redirect` plugin and configuring where the redirect should lead.
A deeper dive into updating LibResilient during disruption is available [here](./UPDATING_DURING_DISRUPTION.md).