mirror of https://github.com/vitorpamplona/amethyst.git synced 2026-10-06 19:53:08 +00:00

Files

T

Claude bb92054f65 refactor: NIP-FE frames in, frames out, on the relay URL

Follows the NIP revision: the body is one REQ, COUNT or EVENT frame as
the websocket carries it, POSTed to the relay's own URL, and the answer
is the session's frames verbatim, the client's subscription id
included.

quartz:
- HttpRelayHandler parses the body to refuse what HTTP does not carry
  and to know how the answer ends, then feeds the text to the session
  as socket text. The body splicing and the subscription-id stripping
  are gone; refusals are the command's own CLOSED / OK false, and
  pre-run refusals (400/413/503) a NOTICE.
- NIP-98: the token is checked once, against the address its `u` names
  (any of the relay's, trailing slash or not), within 60 seconds, and
  may repeat for the same body.
- HttpRelayCommand is the three kinds, their end frames and refusals;
  HttpRelayAnswerReader parses lines with the socket parser;
  HttpRelayClient sends ReqCmd/CountCmd/EventCmd frames.

geode:
- One POST on the relay path: application/nostr+json+rpc goes to
  NIP-86, anything else is a command. One CORS preflight. With [http]
  off, every POST goes to NIP-86 as before.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01RbNrTdV2e7kW5S9tkMoPgh

2026-09-27 16:51:41 +00:00

5.5 KiB

Raw Blame History

geode

A standalone Nostr relay for the JVM, built on Quartz's relay-server code (Ktor CIO). It speaks the core relay protocol plus NIP-11 (info doc), NIP-42 (AUTH), NIP-45 (COUNT), NIP-50 (full-text search), NIP-77 (Negentropy sync), NIP-86 (relay management) and NIP-FE (REQ/COUNT/EVENT over plain HTTP), stores events in SQLite (or a filesystem backend), and can mirror upstream relays strfry-router style.

geode depends only on :quartz — no Android, no Compose. amy serve (the Amethyst CLI) embeds the same engine in-process.

Install

Pick the channel that matches how you deploy. For a real relay, the Docker image or the .deb/.rpm + systemd are the two production paths; Homebrew and the portable tarball are handy for local testing.

Docker (recommended for servers)

Images are published to GHCR on every release:

# Ephemeral — in-memory store, events vanish on restart:
docker run --rm -p 7447:7447 ghcr.io/vitorpamplona/geode:latest

# Persistent + configured:
docker run -d --name geode -p 7447:7447 \
  -v $PWD/geode.toml:/etc/geode/geode.toml:ro \
  -v geode-data:/var/lib/geode \
  ghcr.io/vitorpamplona/geode:latest --config /etc/geode/geode.toml

with in_memory = false and file = "/var/lib/geode/events.db" in your geode.toml. Pin a version (:1.16.0) instead of :latest for reproducible deploys. To build the image yourself, from the repo root:

docker build -f geode/Dockerfile -t geode:local .

Debian/Ubuntu (`.deb`) and Fedora/RHEL (`.rpm`)

Download geode-<version>-linux-x64.deb (or .rpm) from the release page and install it — a minimal JRE is bundled, so no system Java is required. It installs to /opt/geode/ with the launcher at /opt/geode/bin/geode.

sudo dpkg -i geode-1.16.0-linux-x64.deb    # or: sudo rpm -i geode-1.16.0-linux-x64.rpm

To run it as a managed service, wire up the shipped systemd unit (/opt/geode/share/geode/geode.service) — the unit file's header comment has the copy-paste steps (create the geode user, drop your config in /etc/geode/geode.toml, systemctl enable --now geode).

Homebrew

brew install vitorpamplona/tap/geode-relay    # from the tap, once published

The formula depends on openjdk and installs the no-JRE jar bundle. Reference formula: packaging/homebrew/geode-relay.rb.

Portable tarball (any Linux/macOS, no system Java)

Download geode-<version>-<os>-<arch>.tar.gz, unpack, and run:

tar xzf geode-1.16.0-linux-x64.tar.gz
./geode/bin/geode --config geode/share/geode/config.example.toml

The tarball bundles a jlink'd JRE plus share/geode/config.example.toml and share/geode/geode.service.

From source

./gradlew :geode:run --args="--config /etc/geode.toml"

Configure

geode runs with zero config (binds 0.0.0.0:7447, in-memory SQLite). For anything real, copy config.example.toml and edit it — the sections mirror nostr-rs-relay's config.toml so existing configs port almost verbatim. Precedence is CLI flags > TOML > built-in defaults.

geode --config /etc/geode/geode.toml
geode --help          # full flag list
geode --version

Key sections: [info] (NIP-11 doc), [network] (bind + thread pools), [database] (SQLite path/tuning), [options] (AUTH / verify / search), [authorization] (allow/deny lists), [[mirror]] (upstream mirroring), [http] (NIP-FE limits) and [admin] (NIP-86 management). See the example file for every knob.

Commands over HTTP (NIP-FE)

Besides the websocket, geode answers one command per HTTP POST to the relay URL: the body is the frame you would send on the socket, and the answer is the socket's frames as NDJSON, streamed — no socket, no subscription left open:

curl -N -d '["REQ","q",{"kinds":[1],"limit":2}]' http://localhost:7447/
# ["EVENT","q",{"id":"…","kind":1,…}]
# ["EVENT","q",{"id":"…","kind":1,…}]
# ["EOSE","q"]
curl -d '["COUNT","c",{"kinds":[1]}]' http://localhost:7447/   # ["COUNT","c",{"count":2}]
curl -d "[\"EVENT\",$(cat signed-event.json)]" http://localhost:7447/   # ["OK","<id>",true,""]

A body that does not end on EOSE/CLOSED (REQ), COUNT/CLOSED (COUNT) or OK (EVENT) was cut off. On an AUTH-gated relay the answer is 401 until the request carries a NIP-98 Authorization: Nostr … header whose u is the relay's http URL and whose payload is the body's sha256. NIP-86 admin calls share the URL, told apart by Content-Type: application/nostr+json+rpc. Quartz's HttpRelayClient does all of this for JVM/Android clients.

Verbs

geode [relay] [flags]        serve the relay (default)
geode import [flags] [FILE…] bulk-load NDJSON events into the store
geode export [flags]         dump the store as NDJSON to stdout

import/export are geode's strfry import / strfry export — one JSON event per line, for seeding, migrating, or backing up a relay. Both stream, so a multi-million-event corpus round-trips in roughly constant memory.

Release process

geode ships on the same tag-driven pipeline as the rest of Amethyst: pushing a v* tag runs .github/workflows/create-release.yml, whose build-geode job produces the tarball + .deb/.rpm + Homebrew jvm bundle, docker-geode builds and pushes the GHCR image, and bump-homebrew-geode-formula.yml syncs the reference formula. Design notes: plans/2026-07-24-geode-release.md.

5.5 KiB Raw Blame History