Bluesky avatar proxy thing
docs: add README with usage and configuration details
+105
+105
README.md
+105
README.md
···
1
+
# blavatar
2
+
3
+
A caching proxy for Bluesky avatars with real-time cache invalidation.
4
+
5
+
## Overview
6
+
7
+
blavatar is an HTTP service that fetches, caches, and serves user avatars from the Bluesky social network. It maintains cache freshness by subscribing to Bluesky's Jetstream for profile update events, automatically invalidating cached avatars when users change their profiles.
8
+
9
+
## Features
10
+
11
+
- File-based avatar caching with automatic invalidation
12
+
- Real-time updates via Bluesky Jetstream subscription
13
+
- Supports both DIDs and handles as identifiers
14
+
- Generates default placeholder avatars for users without avatars
15
+
- Scales all avatars to 128x128 JPEG format
16
+
- Graceful shutdown handling
17
+
18
+
## Building
19
+
20
+
```bash
21
+
make build # Compile binary
22
+
make install # Build and install
23
+
make clean # Remove build artifacts
24
+
```
25
+
26
+
For Docker:
27
+
28
+
```bash
29
+
make release-dev # Build and push dev image
30
+
make release # Build and push release image
31
+
```
32
+
33
+
## Configuration
34
+
35
+
Configuration is done via CLI flags or environment variables:
36
+
37
+
| Flag | Environment Variable | Default | Description |
38
+
|------|---------------------|---------|-------------|
39
+
| `--jetstream-url` | `BLAVATAR_JETSTREAM_URL` | `wss://jetstream2.us-west.bsky.network/subscribe` | Jetstream WebSocket URL |
40
+
| `--store-path` | `BLAVATAR_STORE_PATH` | `./avatars` | Directory for cached avatars |
41
+
| `--listen` | `BLAVATAR_LISTEN` | `:8080` | HTTP server listen address |
42
+
43
+
## Usage
44
+
45
+
Start the server:
46
+
47
+
```bash
48
+
blavatar
49
+
```
50
+
51
+
Or with custom configuration:
52
+
53
+
```bash
54
+
blavatar --store-path /var/cache/avatars --listen :3000
55
+
```
56
+
57
+
Using environment variables:
58
+
59
+
```bash
60
+
export BLAVATAR_STORE_PATH=/var/cache/avatars
61
+
export BLAVATAR_LISTEN=:3000
62
+
blavatar
63
+
```
64
+
65
+
## API
66
+
67
+
### GET /{identifier}.jpg
68
+
69
+
Retrieve an avatar by DID or handle.
70
+
71
+
**Examples:**
72
+
73
+
```bash
74
+
# By handle
75
+
curl http://localhost:8080/alice.bsky.social.jpg -o avatar.jpg
76
+
77
+
# By DID
78
+
curl http://localhost:8080/did:plc:abcdef123456.jpg -o avatar.jpg
79
+
```
80
+
81
+
**Response Headers:**
82
+
83
+
- `Content-Type: image/jpeg`
84
+
- `Cache-Control: public, max-age=7200` (for real avatars)
85
+
- `Cache-Control: no-cache` (for default placeholder avatars)
86
+
87
+
**Response Codes:**
88
+
89
+
- `200 OK` - Avatar returned (real or default)
90
+
- `400 Bad Request` - Invalid identifier format
91
+
- `500 Internal Server Error` - Fetch or processing failure
92
+
93
+
## How It Works
94
+
95
+
1. **Request**: Client requests an avatar via `/{identifier}.jpg`
96
+
2. **Resolution**: Handle is resolved to DID if needed
97
+
3. **Cache Check**: Local file cache is checked
98
+
4. **Fetch**: On cache miss, avatar is fetched from the user's PDS
99
+
5. **Processing**: Image is scaled to 128x128 and encoded as JPEG
100
+
6. **Caching**: Result is stored in the file cache
101
+
7. **Invalidation**: Jetstream consumer listens for profile updates and removes stale cache entries
102
+
103
+
## License
104
+
105
+
See LICENSE file for details.