Commit 5cb4aa22 authored by Michał "rysiek" Woźniak's avatar Michał "rysiek" Woźniak 🔒

Merge branch 'wip-documentation' into 'master'

Documentation

See merge request !26
parents 8b3dd7e5 5ceeb319
Pipeline #46294 failed with stage
in 60 minutes
This diff is collapsed.
......@@ -6,14 +6,14 @@ Eventually this will document the architecture of Samizdat.
There are two kinds of plugins:
- **Live plugins**
Plugins that *fetch* live content, e.g. 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).
- **Transport plugins**
Plugins that *retrieve* website content, e.g. 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 *live plugin* works, or before content is received via one of them.
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.
Methods these plugins implement:
- `fetch` - fetch the locally stored content (e.g., from cache)
- `stash` - stash the content locally (e.g., in cache)
......@@ -31,9 +31,9 @@ self.SamizdatPlugins.push({
})
```
### Live plugins
### Transport plugins
Live plugins *must* add `X-Samizdat-Method` and `X-Samizdat-ETag` headers to the response they return, so as to facilitate informing the user about new content after content was displayed using a stashing plugin.
Transport plugins *must* add `X-Samizdat-Method` and `X-Samizdat-ETag` headers to the response they return, so as to facilitate informing the user about new content after content was displayed using a stashing plugin.
- **`X-Samizdat-Method`**:
contains the name of the plugin used to fetch the content.
......@@ -57,9 +57,9 @@ If a background plugin `fetch()` succeeds, the result is added to the cache and
## Stashed versions invalidation
Invalidation heuristic is rather naïve, and boils down to checking if either of `X-Samizdat-Method` or `X-Samizdat-ETag` differs between the response from a live plugin and whatever has already been stashed by a stashing plugin. If either differs, the live plugin response is considered "*fresher*".
Invalidation heuristic is rather naïve, and boils down to checking if either of `X-Samizdat-Method` or `X-Samizdat-ETag` differs between the response from a transport plugin and whatever has already been stashed by a stashing plugin. If either differs, the transport plugin response is considered "*fresher*".
This is far from ideal and will need improvements in the long-term. The difficulty is that different live plugins can provide different ways of determining the "*freshness*" of fetched content -- HTTPS-based requests offer `ETag`, `Date`, `Last-Modified`, and other headers that can help with that; whereas IPFS can't really offer much apart from the address which itself is a hash of the content, so at least we know the content is *different* (but is it *fresher* though?).
This is far from ideal and will need improvements in the long-term. The difficulty is that different transport plugins can provide different ways of determining the "*freshness*" of fetched content -- HTTPS-based requests offer `ETag`, `Date`, `Last-Modified`, and other headers that can help with that; whereas IPFS can't really offer much apart from the address which itself is a hash of the content, so at least we know the content is *different* (but is it *fresher* though?).
## Messaging
......@@ -69,4 +69,4 @@ When the browser window context wants to message the service worker, it uses the
### Messages
TBD.
This section is a work in progress.
This diff is collapsed.
# Project's Philosophy
Samizdat's philosophy can be boiled down to a single sentence:
**Information must remain easily accessible.**
The choice of words here is very deliberate.
## Information vs. communication
Samizdat purposely focuses on ***making information accessible***, as opposed to facilitating *live two-way communication flow*.
There is plenty of misinformation to go around, and plenty of communication that is meant solely to muddy the waters and create a toxic information environment. Those who organize such disingenuous communication and participate in it often rely on it being two-way, fast-paced, and emotional, intentionally leaving as little space for calm rational thought as possible.
There is a meaningful difference between a debate of ideas, and a shouting match or a lynch mob. Samizdat is not interested in supporting the latter. While discriminatory content does also come in the form of articles on websites, it becomes truly toxic when live mass communication can be employed in an aggressive manner.
This is where Samizdat draws a line by making specific architectural decisions. We cannot stop bigots from using Samizdat on their websites, but we can make Samizdat less useful for specific strategies often employed by them.
## Centralization as a dis-service
Samizdat grew out of the experience of managing websites that are blocked in some places, and the frustration regarding options available to website admins in who find their websites made unavailable, entirely or only to certain groups of visitors, be it via direct malicious actions (like exploiting CMS vulnerabilities), or DDoS, or state-level web censorship.
These options tend to be limited to a few massive gatekeepers like CloudFlare, and a few smaller ethical providers like [Deflect](https://deflect.ca/).
In practice, website owners are incentivised to use the massive gatekeepers' services, which [gradually centralizes the Internet](https://iscloudflaresafeyet.com/). Such centralization then becomes a problem itself, when these gatekeepers [find themselves under pressure to drop protection for specific sites](https://www.techrepublic.com/article/as-google-and-aws-kill-domain-fronting-users-must-find-a-new-way-to-fight-censorship/), leaving website owners with nowhere to go.
Samizdat is explicitly focusing on decentralized tools like [IPFS](https://ipfs.io); in some cases and for certain very specific threats using the biggest gatekeepers might still make sense, and Samizdat might facilitate that. But whenever that is the case, care will be taken to do it in a way that is not tied to particular service or company.
......@@ -21,7 +21,7 @@
</div>
<div id="description">
<p><em>Samizdat</em> is a browser-based Web censorship circumvention library, easily deployable on any website.</p>
<p>Implemented in JavaScript, it uses <a href="https://developer.mozilla.org/en-US/docs/Web/API/Service_Worker_API/Using_Service_Workers">ServiceWorkers</a> and a set of non-standard in-browser content delivery mechanisms (with a strong focus on decentralized ones like <a href="https://gun.eco/">Gun</a> and <a href="https://github.com/ipfs/js-ipfs">JS-IPFS</a>).</p>
<p>Implemented in JavaScript, it uses <a href="https://developer.mozilla.org/en-US/docs/Web/API/Service_Worker_API/Using_Service_Workers">ServiceWorkers</a> and a set of non-standard in-browser content delivery mechanisms (with a strong focus on decentralized ones like <a href="https://github.com/ipfs/js-ipfs">JS-IPFS</a>).</p>
<p>Ideally, as soon as users are able to access a blocked <em>Samizdat</em>-enabled site <em>once</em>, they would not need to install any special software nor change any settings in order to continue to access that site.</p>
<p><em>Samizdat</em> is currently considered <code>alpha</code> software. We would love to hear if you'd like to test it &ndash; you can contact us at <code>rysiek+samizdat[at]hackerspace.pl</code>.<p>
</div>
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment