A nostr relay
the code is slowly stablizing but i'm still changing the code in a backwards incompatible way ... this probably isn't ready for prod yet either (until I run it in prod more myself)
- supports many NIPs: 1, 2, 4, 9, 11, 12, 15, 16, 20, 26, 28, 33, 40
- suitable for horizontally scaling websocket layer with a load balancer
- plugin-able: connections, disconnections, subs, sub closes, events, eoses, notices, and errors
- compiles into a single, secure executable
- releases contain executables with different permissions enforced by the
runtime:
- normal - an executable that runs like most things you run on your computer
- secure - a runtime-restricted executable
- booger can only communicate on loopback
- booger can only access relevant environment variables
- booger can only write to
./booger.jsonc - booger can only read from
./booger.jsoncand./plugs/ - read more about booger's runtime restrictions on deno.land
- releases contain executables with different permissions enforced by the
runtime:
- rate limits (very basic ones atm)
- collects stats on connections and subscriptions (for analysis or whatevs)
- elaborate defenses: spam filtering, payments
- these are probably best provided as booger plugs
- use postgres read replicas
- use postgres partitions
simplicity, ease of use, extensibility, scalability, performance, security
- deno serves websockets
- filters are stored in a sqlite in-memory database and mapped to a websocket
- events are persisted in postgres
- when an event is persisted (or an ephemeral event is received) a postgres
NOTIFY event, <event json>is broadcast - all booger processes in the cluster
LISTEN eventand when notified check sqlite for matching filters and send to corresponding websockets
- install postgres and run it (welcome to app programming)
- download the latest booger release and unzip it
- run
./boogerand your nostr relay is listening on127.0.0.1:8006
- install postgres and run it (welcome to app programming)
- insall deno 1.34.2 or later (welcome to deno)
- ways to install deno
- or just run
curl -fsSL https://deno.land/install.sh | sh -s v1.34.2 - 🚨 earlier versions of deno might not play well with booger
- read more about deno on deno.land
- get booger's source
git clone [email protected]:stackernews/booger.git- or
git clone https://github.com/stackernews/booger.git - or download the source archive from the latest booger release
- from booger's dir run
deno task compileto generate an executable booger 🥸- to produce a secure executable run
deno task compile-secureinstead
- to produce a secure executable run
- run
./boogerand your nostr relay is listening on127.0.0.1:8006
The easiest way to configure booger is through the ./booger.jsonc file. Run
./booger --init to generate a ./booger.jsonc containing all of
booger's configuration options and defaults.
The following env vars are used by booger and take precendence over any
corresponding values provided in ./booger.jsonc
| name | booger.jsonc name |
|---|---|
HOSTNAME |
hostname |
PORT |
port |
DB |
db |
DB_STATS |
plugs.builtin.stats.db |
DB_LIMITS |
plugs.builtin.limits.db |
reminder: all of the default values are documented in the ./booger.jsonc file
generated by running ./booger --init.
Configuration values passed via cli take precedence over those in env and
./booger.jsonc.
[keyan booger]🍏 ./booger --help
booger - a nostr relay
Docs: https://github.com/stackernews/booger/blob/main/README.md
Bugs: https://github.com/stackernews/booger/issues
Usage:
booger [options]
Options:
-i, --init
write default config to ./booger.jsonc
-c, --config <path>
path to booger config file (default: ./booger.jsonc)
-b, --hostname <ip or hostname>
interface to listen on (default: 127.0.0.1)
0.0.0.0 for all interfaces
-p, --port <port>
port to listen on (default: 8006)
-d, --db <postgres url>
postgres url for nostr data (default: postgres://127.0.0.1:5432/booger)
-s, --db-stats <postgres url>
postgres url for stats booger data (default: postgres://127.0.0.1:5432/booger_stats)
-l, --db-limits <postgres url>
postgres url for limits booger data (default: postgres://127.0.0.1:5432/booger_limits)
-e, --dotenv <path>
path to .env file (default: none)
--plugs-dir <path>
path to plugs directory (default: ./plugs)
--plugs-builtin-use <plugs>
comma seperated list of builtin plugs to use (default: validate,stats,limits)
-h, --help
print help
-v, --version
print versionbooger's core attempts to provide things that all relays want. Booger plugs are a way for booger operators to define custom behavior like rate limits, special validation rules, logging, and what not via Web Workers.
booger's validation, stat collector, and rate limiting are all implemented as booger plugs.
If you try to access things that a secure booger executable isn't permitted to
access (like a remote postgres or a booger.jsonc not in pwd), deno's runtime
will prompt you to access them. If you'd like to avoid deno's prompts, you'll
need to compile booger with different permissions.
You can view the deno compile command we use to compile booger in
deno.jsonc and modify it to your liking.
Read more about deno's permissions.
- camari's nostream - heavily inspired booger's validation and integration tests
- hoytech's strfry - heavily inspired booger plugs with their write policy
- alex gleason's strfry write policies - awesome set of strfry policy examples
- everyone working on nostr
- everyone working on deno
- the authors of booger's dependencies (all of which are awesome):
- my cat dona, meow
do it. i dare you.