Bluesky avatar proxy thing
angrydutchman.peedee.es
1# blavatar
2
3A caching proxy for Bluesky avatars with real-time cache invalidation.
4
5## Overview
6
7blavatar 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. Currently it observes only the Bluesky profile since there is no single profile lexicon (yet). This may change in the future.
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
21make build # Compile binary
22make install # Build and install
23make clean # Remove build artifacts
24```
25
26For Docker:
27
28```bash
29make release-dev # Build and push dev image
30make release # Build and push release image
31```
32
33## Configuration
34
35Configuration 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
45Start the server:
46
47```bash
48blavatar
49```
50
51Or with custom configuration:
52
53```bash
54blavatar --store-path /var/cache/avatars --listen :3000
55```
56
57Using environment variables:
58
59```bash
60export BLAVATAR_STORE_PATH=/var/cache/avatars
61export BLAVATAR_LISTEN=:3000
62blavatar
63```
64
65## API
66
67### GET /{identifier}.jpg
68
69Retrieve an avatar by DID or handle.
70
71**Examples:**
72
73```bash
74# By handle
75curl http://localhost:8080/alice.bsky.social.jpg -o avatar.jpg
76
77# By DID
78curl 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
951. **Request**: Client requests an avatar via `/{identifier}.jpg`
962. **Resolution**: Handle is resolved to DID if needed
973. **Cache Check**: Local file cache is checked
984. **Fetch**: On cache miss, avatar is fetched from the user's PDS
995. **Processing**: Image is scaled to 128x128 and encoded as JPEG
1006. **Caching**: Result is stored in the file cache
1017. **Invalidation**: Jetstream consumer listens for profile updates and removes stale cache entries
102
103## License
104
105See LICENSE file for details.