@bitmacro/relay-agent 0.1.5 → 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 +72 -52
  2. package/dist/bin/relay-agent.mjs +455 -209
  3. package/dist/bin/relay-agent.mjs.map +1 -1
  4. package/dist/index.mjs +443 -200
  5. package/dist/index.mjs.map +1 -1
  6. package/package.json +2 -2
package/README.md CHANGED
@@ -41,77 +41,85 @@ docker run -p 7800:7800 \
41
41
 
42
42
  Or build locally: `docker build -t relay-agent .`
43
43
 
44
- **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).
45
45
 
46
- ### Server deployment (complete flow)
46
+ ### Server deployment (v0.2 multi-relay)
47
47
 
48
48
  ```bash
49
- # 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
50
50
  git clone https://github.com/bitmacro/relay-agent.git relay-agent
51
51
 
52
- # 2. Configure .env in the directory containing docker-compose.yml
53
- echo "RELAY_AGENT_TOKEN_PRIVATE=your-secret-token" >> .env
54
- echo "RELAY_AGENT_TOKEN_PUBLIC=your-secret-token" >> .env
55
- echo "RELAY_AGENT_TOKEN_PAID=your-secret-token" >> .env
52
+ # 2. Configure .env (single token for all relays)
53
+ echo "RELAY_AGENT_TOKEN=your-secret-token" >> .env
56
54
 
57
- # 3. Pull images from GHCR (or build locally if testing before merge)
58
- docker compose -f docker-compose.yml -f relay-agent/docker-compose.relay-agents.yml pull
59
-
60
- # 4. Start the services
61
- 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
62
58
  ```
63
59
 
64
- **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/`.
65
61
 
66
- See `docker-compose.relay-agents.yml` for the full setup (1 agent per relay in v0.1).
67
62
 
68
63
  ---
69
64
 
70
65
  ## Operational Commands
71
66
 
72
- For operators using the compose fragment (`docker-compose.yml` + `relay-agent/docker-compose.relay-agents.yml`):
67
+ ### v0.2 multi-relay
73
68
 
74
69
  ```bash
75
- # Rebuild and restart a specific agent
76
- 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
77
72
 
78
- # Rebuild and restart all relay agents
79
- 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
80
75
 
81
- # Pull latest image and restart (when using GHCR)
82
- docker compose -f docker-compose.yml -f relay-agent/docker-compose.relay-agents.yml pull
83
- 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
+ ```
84
79
 
85
- # View logs
86
- 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)
87
81
 
88
- # Stop all relay agents
89
- 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
90
84
  ```
91
85
 
92
86
  ### Smoke Test
93
87
 
94
- Verify the agent can talk to strfry LMDB:
95
-
96
88
  ```bash
97
- docker exec relay-agent-public sh -c 'curl -s -m 60 -H "Authorization: Bearer $RELAY_AGENT_TOKEN" http://localhost:7800/stats'
98
- ```
89
+ # v0.2: health lists relay IDs
90
+ curl http://localhost:7810/health
91
+ # {"status":"ok","relayIds":["public","private","paid"],...}
99
92
 
100
- 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
+ ```
101
96
 
102
97
  ---
103
98
 
104
99
  ## REST API Endpoints
105
100
 
106
- | Method | Path | Description | Example Response |
107
- |--------|------|-------------|------------------|
108
- | `GET` | `/health` | Health check (no auth) | `{"status":"ok","timestamp":"..."}` |
109
- | `GET` | `/events` | List events (NIP-01 filter) | `[{id, pubkey, kind, ...}, ...]` |
110
- | `DELETE` | `/events/:id` | Delete event by id | `{"deleted":"<id>"}` |
111
- | `GET` | `/stats` | Relay statistics | `{total_events, db_size, uptime, version}` |
112
- | `POST` | `/policy/block` | Block pubkey | `{"blocked":"<pubkey>"}` |
113
- | `POST` | `/policy/allow` | Allow pubkey | `{"allowed":"<pubkey>"}` |
114
- | `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 |
115
123
 
116
124
  ### Query parameters for `GET /events`
117
125
 
@@ -135,23 +143,36 @@ Authorization: Bearer <your-token>
135
143
 
136
144
  ## Environment Variables
137
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
+
138
158
  | Variable | Default | Description |
139
159
  |----------|---------|-------------|
140
160
  | `RELAY_AGENT_TOKEN` | — | **Required.** Bearer token for API auth |
141
161
  | `STRFRY_BIN` | `strfry` | Path to strfry binary |
142
162
  | `STRFRY_DB_PATH` | `./strfry-db` | Path to strfry database directory |
143
- | `STRFRY_CONFIG` | — | Path to strfry config file (for explicit db path) |
163
+ | `STRFRY_CONFIG` | — | Path to strfry config file |
144
164
  | `WHITELIST_PATH` | `/etc/strfry/whitelist.txt` | Path to whitelist file |
145
165
  | `PORT` | `7800` | HTTP server port |
146
- | `ALLOWED_ORIGINS` | — | Comma-separated extra CORS origins (defaults include `relay-panel.bitmacro.cloud`, `relay-panel.bitmacro.pro`, `http://localhost:3000`) |
166
+ | `ALLOWED_ORIGINS` | — | Comma-separated extra CORS origins |
147
167
 
148
168
  ---
149
169
 
150
170
  ## Compatibility
151
171
 
152
- | relay-agent | strfry |
153
- |-------------|--------|
154
- | 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 |
155
176
 
156
177
  ---
157
178
 
@@ -180,10 +201,9 @@ The relay-agent is **stateless** — it has no database. State lives in Supabase
180
201
 
181
202
  1. **Capture the error** — run logs in one terminal, then curl in another:
182
203
  ```bash
183
- # Terminal 1
184
- docker compose -f docker-compose.yml -f relay-agent/docker-compose.relay-agents.yml logs -f relay-agent-private
185
- # Terminal 2
186
- 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"
187
207
  ```
188
208
  The strfry stderr will appear in the logs.
189
209
 
@@ -195,14 +215,14 @@ The relay-agent is **stateless** — it has no database. State lives in Supabase
195
215
  ```
196
216
  Then restart the relay: `docker restart relay_private`
197
217
 
198
- 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`:
199
219
  ```bash
200
220
  grep -A5 relay_private docker-compose.yml
201
221
  ```
202
222
 
203
- 4. **Test strfry inside container**:
223
+ 4. **Test strfry inside container** (v0.2):
204
224
  ```bash
205
- 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'
206
226
  ```
207
227
  If `data.mdb` is missing or strfry fails, fix the volume path.
208
228