documentation updated (ref. #36)

docs/ARCHITECTURE.md

@@ -219,3 +219,31 @@ The still-loading screen is *only* displayed when *all* of these conditions are
 The reason why a stashing plugin needs to be configured and enabled is to avoid loops. Consider a scenario, where a visitor is navigating to a page, and the request is taking very long. The still-loading screen is displayed (by way of the service worker returning the relevant HTML in response to the request). Eventually, the request completes in the background, but the response is discarded due to lack of a stashing plugin.
 
 In such a case reloading the page will cause a repeat: request, still-loading screen, request completes in the background (and the result is discarded). The visitor would be stuck in a loop. If a stashing plugin (like `cache`) is enabled, this loop can be expected not to emerge, since the second request would quickly return the cached response.
+
+## Error handling
+
+LibResilient's error handling focuses on attempting to "do the right thing". In some cases this means passing a HTTP error response from a plugin directly to the browser to be displayed to the user; in other cases it means ignoring HTTP error response from a plugin so that other plugins can attempt to retrieve a given resource.
+
+In general:
+
+ - **A response with status code value of `499` or lower is passed immediately to the browser**  
+   no other plugins are used to try to retrieve the content; if a stashing plugin is configured, the response might be cached locally.
+
+ - **A response with status code value of `500` or higher is treated as a plugin error**  
+   if other plugins are configured, they will be used to try to retrieve the content; if a stashing plugin is configured it will not stash that response.
+   
+ - **Any exception thrown in a plugin will be caught and treated as a plugin error**  
+   if other plugins are configured, they will be used to try to retrieve the content; there is no response object, so there is nothing to stash.
+   
+ - **If a plugin rejects for whatever reason, it is treated as a plugin error**  
+   if other plugins are configured, they will be used to try to retrieve the content; there is no response object, so there is nothing to stash.
+
+All plugin errors (`5xx` HTTP responses, thrown exceptions, rejections) are logged internally. This data is printed in the console (if `loggedComponents` config field contains `service-worker`), and sent to the client using `Client.postMessage()`, to simplify debugging.
+
+If all plugins fail in case of a navigate request, a Request object is created with a `404 Not Found` HTTP status, containing a simple HTML error page (similar to the still-loading screen mentioned above) to be displayed to the user. If the request is not a navigate request, the rejected promise is returned directly.
+
+Mapping plugin errors onto HTTP errors is not always going to be trivial. For example, an IPFS-based transport plugin could in some circumstances return a `404 Not Found` HTTP error, but the `any-of` plugin necessarily has to ignore any HTTP errors it receives from plugins it is configured to use, while waiting for one to potentially return the resource successfully. If all of the configured plugins fail, with different HTTP errors, which one should the `any-of` plugin return itself?..
+
+At the same time, returning HTTP errors makes sense, as it allows the browser and the user to properly interpret well-understood errors. So, the `fetch` plugin will return any `4xx` HTTP error it receives, for example, and the service worker will in turn treat that as a successfully completed retrieval and return that to the browser to be displayed to the user.
+
+Plugin authors should consider this carefully. If in doubt, it's probably better to throw an exception or reject the promise with a meaningful error message, than to try to fit a potentially complex failure mode into the limited and rigit contraints of HTTP error codes.