@bitmacro/relay-agent 0.1.4 → 0.2.0-beta.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (6) hide show
  1. package/README.md +85 -56
  2. package/dist/bin/relay-agent.mjs +482 -203
  3. package/dist/bin/relay-agent.mjs.map +1 -1
  4. package/dist/index.mjs +470 -194
  5. package/dist/index.mjs.map +1 -1
  6. package/package.json +2 -2
package/README.md CHANGED
@@ -8,6 +8,12 @@
8
8
 
9
9
  `relay-agent` is a REST API agent that runs on your relay server and translates HTTP requests into strfry CLI commands. It is part of the [BitMacro Relay Manager](https://bitmacro.io) ecosystem.
10
10
 
11
+ | Project | Description | License |
12
+ |---------|-------------|---------|
13
+ | **relay-agent** | This repo — REST API for strfry | MIT |
14
+ | [relay-api](https://github.com/bitmacro/relay-api) | Central hub (Supabase, proxy) | Private |
15
+ | [relay-panel](https://github.com/bitmacro/relay-panel) | Frontend | BSL 1.1 |
16
+
11
17
  ---
12
18
 
13
19
  ## Quick Start
@@ -35,77 +41,85 @@ docker run -p 7800:7800 \
35
41
 
36
42
  Or build locally: `docker build -t relay-agent .`
37
43
 
38
- **Multiple relays:** Use the compose fragment. Place relay-agent next to your docker-compose.yml.
44
+ **Multiple relays (v0.2):** One agent, N relays via `RELAY_INSTANCES`. Use `docker-compose.relay-agent.yml` (fragment) or `docker-compose.yml` (standalone).
39
45
 
40
- ### Server deployment (complete flow)
46
+ ### Server deployment (v0.2 multi-relay)
41
47
 
42
48
  ```bash
43
- # 1. Clone (or pull) relay-agent into a subdir next to your docker-compose.yml
49
+ # 1. Clone relay-agent into a subdir next to your docker-compose.yml
44
50
  git clone https://github.com/bitmacro/relay-agent.git relay-agent
45
51
 
46
- # 2. Configure .env in the directory containing docker-compose.yml
47
- echo "RELAY_AGENT_TOKEN_PRIVATE=your-secret-token" >> .env
48
- echo "RELAY_AGENT_TOKEN_PUBLIC=your-secret-token" >> .env
49
- echo "RELAY_AGENT_TOKEN_PAID=your-secret-token" >> .env
50
-
51
- # 3. Pull images from GHCR (or build locally if testing before merge)
52
- docker compose -f docker-compose.yml -f relay-agent/docker-compose.relay-agents.yml pull
52
+ # 2. Configure .env (single token for all relays)
53
+ echo "RELAY_AGENT_TOKEN=your-secret-token" >> .env
53
54
 
54
- # 4. Start the services
55
- docker compose -f docker-compose.yml -f relay-agent/docker-compose.relay-agents.yml up -d relay-agent-private relay-agent-public relay-agent-paid
55
+ # 3. Build and start (requires relay_private, relay_public, relay_paid, network bitmacro in parent compose)
56
+ docker compose -f docker-compose.yml -f relay-agent/docker-compose.relay-agent.yml build relay-agent
57
+ docker compose -f docker-compose.yml -f relay-agent/docker-compose.relay-agent.yml up -d relay-agent
56
58
  ```
57
59
 
58
- **Before GHCR has the image:** Use `build` instead of `pull` — the compose includes a build fallback. Run `docker compose ... build` then `up -d`.
60
+ Prerequisites: `nostr/{public,private,paid}/` must have `strfry.conf`, `whitelist.txt`, `data/`.
59
61
 
60
- See `docker-compose.relay-agents.yml` for the full setup (1 agent per relay in v0.1).
61
62
 
62
63
  ---
63
64
 
64
65
  ## Operational Commands
65
66
 
66
- For operators using the compose fragment (`docker-compose.yml` + `relay-agent/docker-compose.relay-agents.yml`):
67
+ ### v0.2 multi-relay
67
68
 
68
69
  ```bash
69
- # Rebuild and restart a specific agent
70
- docker compose -f docker-compose.yml -f relay-agent/docker-compose.relay-agents.yml up -d --build relay-agent-public
70
+ # Build and start
71
+ docker compose -f docker-compose.yml -f relay-agent/docker-compose.relay-agent.yml up -d --build relay-agent
71
72
 
72
- # Rebuild and restart all relay agents
73
- docker compose -f docker-compose.yml -f relay-agent/docker-compose.relay-agents.yml up -d --build relay-agent-private relay-agent-public relay-agent-paid
73
+ # View logs
74
+ docker compose -f docker-compose.yml -f relay-agent/docker-compose.relay-agent.yml logs -f relay-agent
74
75
 
75
- # Pull latest image and restart (when using GHCR)
76
- docker compose -f docker-compose.yml -f relay-agent/docker-compose.relay-agents.yml pull
77
- docker compose -f docker-compose.yml -f relay-agent/docker-compose.relay-agents.yml up -d relay-agent-private relay-agent-public relay-agent-paid
76
+ # Stop
77
+ docker compose -f docker-compose.yml -f relay-agent/docker-compose.relay-agent.yml stop relay-agent
78
+ ```
78
79
 
79
- # View logs
80
- docker compose -f docker-compose.yml -f relay-agent/docker-compose.relay-agents.yml logs -f relay-agent-public
80
+ ### Standalone (from relay-agent dir)
81
81
 
82
- # Stop all relay agents
83
- docker compose -f docker-compose.yml -f relay-agent/docker-compose.relay-agents.yml stop relay-agent-private relay-agent-public relay-agent-paid
82
+ ```bash
83
+ cd relay-agent && docker compose up -d
84
84
  ```
85
85
 
86
86
  ### Smoke Test
87
87
 
88
- Verify the agent can talk to strfry LMDB:
89
-
90
88
  ```bash
91
- docker exec relay-agent-public sh -c 'curl -s -m 60 -H "Authorization: Bearer $RELAY_AGENT_TOKEN" http://localhost:7800/stats'
92
- ```
89
+ # v0.2: health lists relay IDs
90
+ curl http://localhost:7810/health
91
+ # {"status":"ok","relayIds":["public","private","paid"],...}
93
92
 
94
- Expected response: `{"total_events":...,"db_size":"...","uptime":...,"version":"..."}`
93
+ # v0.2: stats for a specific relay (replace TOKEN and relay id)
94
+ curl -H "Authorization: Bearer TOKEN" http://localhost:7810/private/stats
95
+ ```
95
96
 
96
97
  ---
97
98
 
98
99
  ## REST API Endpoints
99
100
 
100
- | Method | Path | Description | Example Response |
101
- |--------|------|-------------|------------------|
102
- | `GET` | `/health` | Health check (no auth) | `{"status":"ok","timestamp":"..."}` |
103
- | `GET` | `/events` | List events (NIP-01 filter) | `[{id, pubkey, kind, ...}, ...]` |
104
- | `DELETE` | `/events/:id` | Delete event by id | `{"deleted":"<id>"}` |
105
- | `GET` | `/stats` | Relay statistics | `{total_events, db_size, uptime, version}` |
106
- | `POST` | `/policy/block` | Block pubkey | `{"blocked":"<pubkey>"}` |
107
- | `POST` | `/policy/allow` | Allow pubkey | `{"allowed":"<pubkey>"}` |
108
- | `GET` | `/users` | List unique pubkeys | `{"users":["<pubkey>", ...]}` |
101
+ ### v0.2 multi-relay (RELAY_INSTANCES set)
102
+
103
+ | Method | Path | Description | Auth |
104
+ |--------|------|-------------|------|
105
+ | `GET` | `/health` | List active relay IDs | no |
106
+ | `GET` | `/:relayId/health` | Health for relay | no |
107
+ | `GET` | `/:relayId/stats` | Relay statistics | Bearer |
108
+ | `GET` | `/:relayId/events` | List events | Bearer |
109
+ | `DELETE` | `/:relayId/events/:id` | Delete event | Bearer |
110
+ | `GET` | `/:relayId/policy` | Policy entries | Bearer |
111
+ | `POST` | `/:relayId/policy/block` | Block pubkey | Bearer |
112
+ | `POST` | `/:relayId/policy/allow` | Allow pubkey | Bearer |
113
+ | `GET` | `/:relayId/users` | List pubkeys | Bearer |
114
+
115
+ `relayId` = logical ID from RELAY_INSTANCES (e.g. `public`, `private`, `paid`). Must match `agent_relay_id` in relay_configs.
116
+
117
+ ### v0.1 single-relay (no RELAY_INSTANCES)
118
+
119
+ | Method | Path | Description |
120
+ |--------|------|-------------|
121
+ | `GET` | `/health` | Health check |
122
+ | `GET` | `/stats`, `/events`, `/policy`, `/users` | Same as above, no prefix |
109
123
 
110
124
  ### Query parameters for `GET /events`
111
125
 
@@ -129,39 +143,55 @@ Authorization: Bearer <your-token>
129
143
 
130
144
  ## Environment Variables
131
145
 
146
+ ### v0.2 multi-relay
147
+
148
+ | Variable | Default | Description |
149
+ |----------|---------|-------------|
150
+ | `RELAY_INSTANCES` | — | JSON array of `{id, token, strfryConfig, strfryDb, whitelistPath?}` |
151
+ | `RELAY_AGENT_TOKEN` | — | Not used when RELAY_INSTANCES is set |
152
+ | `STRFRY_BIN` | `strfry` | Path to strfry binary |
153
+ | `PORT` | `7800` | HTTP server port |
154
+ | `ALLOWED_ORIGINS` | — | Comma-separated extra CORS origins |
155
+
156
+ ### v0.1 single-relay
157
+
132
158
  | Variable | Default | Description |
133
159
  |----------|---------|-------------|
134
160
  | `RELAY_AGENT_TOKEN` | — | **Required.** Bearer token for API auth |
135
161
  | `STRFRY_BIN` | `strfry` | Path to strfry binary |
136
162
  | `STRFRY_DB_PATH` | `./strfry-db` | Path to strfry database directory |
137
- | `STRFRY_CONFIG` | — | Path to strfry config file (for explicit db path) |
163
+ | `STRFRY_CONFIG` | — | Path to strfry config file |
138
164
  | `WHITELIST_PATH` | `/etc/strfry/whitelist.txt` | Path to whitelist file |
139
165
  | `PORT` | `7800` | HTTP server port |
140
- | `ALLOWED_ORIGINS` | — | Comma-separated extra CORS origins (defaults include `https://admin.bitmacro.io`, `http://localhost:3000`) |
166
+ | `ALLOWED_ORIGINS` | — | Comma-separated extra CORS origins |
141
167
 
142
168
  ---
143
169
 
144
170
  ## Compatibility
145
171
 
146
- | relay-agent | strfry |
147
- |-------------|--------|
148
- | 0.1.x | 1.0.x |
172
+ | relay-agent | strfry | Mode |
173
+ |-------------|--------|------|
174
+ | 0.1.x | 1.0.x | Single-relay |
175
+ | 0.2.0-beta.1 | 1.0.x | Multi-relay (RELAY_INSTANCES) — beta |
149
176
 
150
177
  ---
151
178
 
152
179
  ## Architecture
153
180
 
154
181
  ```
155
- bitmacro-api (Vercel)
182
+ relay-panel
183
+ │ HTTP + JWT
184
+ ▼
185
+ relay-api (Vercel)
156
186
  │ HTTP REST + Bearer JWT
157
187
  ▼
158
- relay-agent ← this package
188
+ relay-agent (this repo)
159
189
  │ child_process spawn()
160
190
  ▼
161
191
  strfry (local C++ process / LMDB)
162
192
  ```
163
193
 
164
- The relay-agent is **stateless** — it has no database. State lives in Supabase, managed by bitmacro-api. The relay-agent only translates HTTP calls into strfry CLI commands.
194
+ The relay-agent is **stateless** — it has no database. State lives in Supabase, managed by relay-api. The relay-agent only translates HTTP calls into strfry CLI commands.
165
195
 
166
196
  ---
167
197
 
@@ -171,10 +201,9 @@ The relay-agent is **stateless** — it has no database. State lives in Supabase
171
201
 
172
202
  1. **Capture the error** — run logs in one terminal, then curl in another:
173
203
  ```bash
174
- # Terminal 1
175
- docker compose -f docker-compose.yml -f relay-agent/docker-compose.relay-agents.yml logs -f relay-agent-private
176
- # Terminal 2
177
- curl -H "Authorization: Bearer TOKEN" "http://localhost:7811/events?limit=3"
204
+ # v0.2
205
+ docker compose -f docker-compose.yml -f relay-agent/docker-compose.relay-agent.yml logs -f relay-agent
206
+ curl -H "Authorization: Bearer TOKEN" "http://localhost:7810/private/events?limit=3"
178
207
  ```
179
208
  The strfry stderr will appear in the logs.
180
209
 
@@ -186,14 +215,14 @@ The relay-agent is **stateless** — it has no database. State lives in Supabase
186
215
  ```
187
216
  Then restart the relay: `docker restart relay_private`
188
217
 
189
- 3. **Verify db path** — relay-agent mounts `./nostr/private/data:/app/strfry-db`. Your relay (`relay_private`) must use the **same** host path for its strfry db. Check your main `docker-compose.yml`:
218
+ 3. **Verify db path** — relay-agent mounts `./nostr/private/data:/app/nostr/private/data`. Your relay (`relay_private`) must use the **same** host path for its strfry db. Check your main `docker-compose.yml`:
190
219
  ```bash
191
220
  grep -A5 relay_private docker-compose.yml
192
221
  ```
193
222
 
194
- 4. **Test strfry inside container**:
223
+ 4. **Test strfry inside container** (v0.2):
195
224
  ```bash
196
- docker compose -f docker-compose.yml -f relay-agent/docker-compose.relay-agents.yml run --rm relay-agent-private sh -c 'ls -la /app/strfry-db && /app/strfry --config /app/strfry.conf scan "{}" | head -3'
225
+ docker compose -f docker-compose.yml -f relay-agent/docker-compose.relay-agent.yml run --rm relay-agent sh -c 'ls -la /app/nostr/private/data && /app/strfry --config /app/nostr/private/strfry.conf scan "{}" | head -3'
197
226
  ```
198
227
  If `data.mdb` is missing or strfry fails, fix the volume path.
199
228
 
@@ -202,7 +231,7 @@ The relay-agent is **stateless** — it has no database. State lives in Supabase
202
231
  ## Security
203
232
 
204
233
  - **Run on a private network.** The relay-agent should run on the operator's server and **never be exposed directly to the internet**.
205
- - Access is controlled by the bitmacro-api, which proxies requests with a shared Bearer token.
234
+ - Access is controlled by the relay-api, which proxies requests with a shared Bearer token.
206
235
  - Use a strong, random token in production. Rotate it if compromised.
207
236
 
208
237
  ---