[MIRROR ONLY] A correct and efficient ATProto blob proxy for secure content delivery.
codeberg.org/Blooym/porxie
docs: cleanup documentation
+20
-19
+17
-16
README.md
+17
-16
README.md
···
4
4
5
5
# Porxie
6
6
7
-
A correct and efficient ATProto blob proxy for secure content delivery.
7
+
A correct and efficient ATProtocol blob proxy for secure content delivery.
8
8
9
9
</div>
10
10
···
14
14
- Secure serving: blobs are always served with secure headers to help improve end-user security.
15
15
- MIME filtering: detects blob content MIME-types and enforces an optional allowlist of permitted types.
16
16
- Policy enforcement: optionally integrate with an external policy service (like an AppView) to control which blobs can be served.
17
-
- In-memory cache: configurable in-memory caching for fast repeat access with support for manual cache purging via authenticated HTTP DELETE.
17
+
- In-memory cache: configurable in-memory caching for fast repeat access with support for manual cache purging.
18
18
19
19
## Usage
20
20
···
30
30
31
31
### Run: Binary
32
32
33
-
To run Porxie directly, install [Rust and Cargo](https://rust-lang.org/tools/install/) and then:
33
+
To run Porxie as a binary, you'll first need to install it locally.
34
34
35
-
1. Install the binary:
35
+
As Porxie is not packaged or pre-built in many places yet, the easiest way to do this is building it via Cargo directly. Ensure you have a relatively up to date version of [Rust and Cargo](https://rust-lang.org/tools/install/) installed before following these steps:
36
+
37
+
1. Install the binary, replacing v0.0.0 with the version you want to install:
36
38
37
39
```sh
38
-
cargo install --git https://codeberg.org/Blooym/porxie.git
40
+
cargo install --git https://codeberg.org/Blooym/porxie.git#v0.0.0 porxie
39
41
```
40
42
41
43
2. Run the server with your chosen [configuration](#configuration) options:
···
44
46
porxie
45
47
```
46
48
47
-
### Run: Docker Compose
49
+
### Run: Docker / Containers
50
+
51
+
Porxie is available as a pre-built container image on [DockerHub](https://hub.docker.com/r/blooym/porxie) and can be used with whatever container setup you use. The published image runs a statically linked binary in a `scratch` environment as a non-root user by default.
48
52
49
-
To run Porxie with Docker Compose, you can start with the following `compose.yml` template:
53
+
You can use the following `compose.yml` template as a starting point, adding any [configuration](#configuration) options as environment variables:
50
54
51
55
```yaml
52
56
services:
···
62
66
- no-new-privileges
63
67
```
64
68
65
-
### Run: Nix
69
+
### Run: Nix / NixOS Service
66
70
67
-
To run Porxie with Nix, you can use the [package](https://search.nixos.org/packages?channel=unstable&query=porxie) or [NixOS module](https://search.nixos.org/options?channel=unstable&query=porxie) provided directly in nixpkgs.
71
+
To run Porxie with Nix, you can either use the [package](https://search.nixos.org/packages?channel=unstable&query=porxie) directly or the [NixOS module](https://search.nixos.org/options?channel=unstable&query=porxie), both of which are provided directly in nixpkgs. Please refer to the Nix search page for NixOS service options.
68
72
69
73
## Routes
70
74
71
75
- [GET] `/{did}/{cid}`: Fetch a blob either from cache or origin.
72
-
- [GET] `/xrpc/dev.blooym.porxie.getBlob?did=<did>&cid=<cid>`: XRPC Compatibility alias for the fetch blob endpoint.
76
+
- [GET] `/xrpc/dev.blooym.porxie.getBlob?did=<did>&cid=<cid>`: XRPC Compatibility shim for the fetch blob endpoint.
73
77
- [POST] `/xrpc/dev.blooym.porxie.cache.purgeActor?did=<did>`: Purge all cached items relating to an actor DID.
74
78
- [POST] `/xrpc/dev.blooym.porxie.cache.purgeBlob?cid=<cid>`: Purge all cache items relating to a blob CID.
75
-
76
79
77
80
## Policy Service
78
81
79
-
Porxie can optionally check with an external HTTP service before serving any blob. You build and run this service yourself - Porxie just calls it and acts on the response. This is useful for things like content takedowns or blob allow lists.
80
-
81
-
For every incoming request, Porxie sends `GET <policy-service-url>/xrpc/dev.blooym.porxie.getBlobPolicy` and expects a response that conforms to the (`lexicon xrpc output`)[lexicons/dev/blooym/porxie/getBlobPolicy.json].
82
+
Porxie can check with an external HTTP "policy" service before serving blobs, which is useful for moderating content or only serving specific content. You build and run this service yourself - Porxie just sends requests to an XRPC endpoint at [`/xrpc/dev.blooym.porxie.getBlobPolicy`](lexicons/dev/blooym/porxie/getBlobPolicy.json) and acts on the response accordingly.
82
83
83
-
Policy decisions are cached per DID+CID pair, so your service won't be hit on every request. The policy cache can be cleared for a blob or actor via the cache clearing xrpc endpoints.
84
+
Policy decisions will be cached using the request DID+CID by default to reduce load on the policy service. The duration items are cached can be configured, and the cache can be cleared manually for a blob or actor via the relevant endpoint.
84
85
85
-
By default, Porxie will fail-closed: if the policy service errors, the blob request fails too. This can be changed to fail-open if preferred.
86
+
By default, Porxie will fail-closed: if the policy service returns an error is otherwise unavailable, the blob request will fail too. This behaviour can be configured to fail-open if availability is more important than applying policies.
86
87
87
88
See the [Configuration](#configuration) section for all available policy options.
88
89
+1
-1
crates/porxie/Cargo.toml
+1
-1
crates/porxie/Cargo.toml
···
1
1
[package]
2
2
name = "porxie"
3
-
description = "A correct and efficient ATProto blob proxy for secure content delivery."
3
+
description = "A correct and efficient ATProtocol blob proxy for secure content delivery."
4
4
authors = ["Blooym"]
5
5
repository = "https://codeberg.org/Blooym/porxie"
6
6
homepage = "https://codeberg.org/Blooym/porxie/src/branch/main/README.md"
+1
-1
crates/porxie/src/types/blob_cid.rs
+1
-1
crates/porxie/src/types/blob_cid.rs