mirror of
https://github.com/jmcorgan/fips.git
synced 2026-08-09 00:04:54 +00:00
docs: reviewer feedback pass on Nostr-discovery surface
Walk through reviewer feedback on the Nostr-discovery docs and land 18 items. Bulk patterns: - `external_addr` / `public: true` semantics consistently misdescribed. The advert path is gated on `cfg.is_public()`; inside that branch the daemon picks an address by precedence (`external_addr`, non-wildcard `bind_addr`, STUN). The docs treated `public: true` and `external_addr` as alternatives when they are stacked: `public: true` is the master switch and `external_addr` populates the address inside it. Reconciled across `enable-nostr-discovery.md` and `advertise-your-node.md`: add `public: true` to the `external_addr` examples; replace "STUN as a logging cross-check" with "STUN is skipped entirely"; fix "neither flag is needed" for direct public bind (both flags still required); make the publish-tutorial Step 3 conditional on the chosen Step 2 path (STUN runs only on the `public: true` path); rewrite the troubleshooting "wrong public IP advertised" bullet with two coherent fixes. - `udp:nat` overpromised as a symmetric-NAT solution. Symmetric NAT on either side typically defeats the punch. Reframe `udp:nat` as best-effort hole-punching for nodes without a directly reachable UDP endpoint in the how-to, the publish tutorial (intro, callout, section heading rewrite from "If you're behind symmetric NAT" to "If your direct UDP advert isn't reachable"), the consume tutorial's "What's next" pointer, and `tutorials/README.md`. Promote reachability over named NAT classes: STUN can confirm the public IP but not that the listener-port mapping is open. - YAML "silently ignores unknown keys" is wrong. Config parser rejects unknown fields via `serde(deny_unknown_fields)` on the per-section structs; misspelled fields refuse the daemon's start with a parse-error line in the journal. Fixed in the publish tutorial's troubleshooting and the open-discovery tutorial's `policy` typo bullet. Mechanical fixes: - Repoint stale anchors. `getting-started.md` and `configuration.md` linked to `#installation` / `#inspect` on the README; the README has no such headings. Repoint to `#quick-start` and `cli-fipsctl.md`. Two stale anchors in the publish tutorial pointing at non-existent sub-scenarios in the how-to (`#sub-scenario-2c-...`, `#sub-scenario-2b-tor-onion-node`) repointed to the correct anchors. - Drop the `fipsctl show status` claim from the open-discovery troubleshooting bullet (`show_status` doesn't include `discovery.nostr.policy`). Replace with daemon startup logs. - Fix the `advertise: false` parenthetical in the consume-only tutorial (`default_advertise()` returns `true`; we set `false` explicitly for the consume-only path). - Drop the "supplies a relay list" overstatement in two activation paragraphs (the how-to and the design doc). Default relay / STUN-server lists ship in the config; both are optional overrides. - Add the missing `transports.udp.public` entry to the open-discovery tutorial's prerequisites checklist. Tutorial users coming out of advertise-your-node could be on either the direct-UDP (`public: true`) or `udp:nat` (`public: false`) path; list both. Files: docs/getting-started.md, docs/reference/configuration.md, docs/how-to/enable-nostr-discovery.md, docs/tutorials/README.md, docs/tutorials/advertise-your-node.md, docs/tutorials/resolve-peers-via-nostr.md, docs/tutorials/open-discovery.md, docs/design/fips-nostr-discovery.md.
This commit is contained in:
@@ -110,8 +110,12 @@ You should be coming out of
|
||||
[advertise-your-node](advertise-your-node.md) with:
|
||||
|
||||
- Persistent identity, advertising enabled
|
||||
(`discovery.nostr.advertise: true`), UDP advertising on
|
||||
Nostr (`transports.udp.advertise_on_nostr: true`).
|
||||
(`discovery.nostr.advertise: true`), and either the
|
||||
direct-UDP path
|
||||
(`transports.udp.advertise_on_nostr: true`,
|
||||
`transports.udp.public: true`) or the `udp:nat` path
|
||||
(`transports.udp.advertise_on_nostr: true`,
|
||||
`transports.udp.public: false`) from the previous tutorial.
|
||||
- A static `test-us01` peer entry that the daemon dials
|
||||
outbound; possibly an inbound `test-us03` peer (the
|
||||
open-discovery test mesh node that dialed in after seeing
|
||||
@@ -288,11 +292,12 @@ the previous tutorial:
|
||||
WebSocket connection to the relays is failing repeatedly,
|
||||
no adverts arrive. Look for relay-connection errors in
|
||||
`sudo journalctl -u fips -n 200`.
|
||||
- **`policy: open` typo.** YAML accepts and ignores unknown
|
||||
values silently. If `fipsctl show status` (or the daemon's
|
||||
startup log) shows `policy: configured_only`, the YAML
|
||||
didn't parse the new value — re-check spelling and
|
||||
indentation.
|
||||
- **`policy: open` typo.** YAML is case-sensitive, and the
|
||||
`policy` field is a serde enum that rejects unknown values —
|
||||
a misspelled value produces a config-parse error at startup
|
||||
rather than a silent fall-back. If the daemon refuses to
|
||||
start, check `sudo journalctl -u fips -n 200` for the
|
||||
parse-error line naming the field and value.
|
||||
|
||||
If too many peers are appearing and you want to dial down:
|
||||
|
||||
|
||||
Reference in New Issue
Block a user