Documentation

README.md

@@ -6,11 +6,13 @@ It is pretty fast: [docs/PERFORMANCE.md](docs/PERFORMANCE.md).
 
 It can work as your personal relay: [docs/PERSONAL_RELAY.md](docs/PERSONAL_RELAY.md).
 
-It does not have any provisions for charging users.
+To deploy chorus, read [docs/DEPLOYING.md](docs/DEPLOYING.md)
 
-## Deploying chorus
+To configure chorus read [docs/CONFIG.md](docs/CONFIG.md)
 
-Read [contrib/README.md](contrib/README.md)
+To undertand the relay's behavior, read [docs/BEHAVIOR.md](docs/BEHAVIOR.md)
+
+Chorus does not have any provisions for charging users.
 
 ## Status
 

docs/BEHAVIOR.md

@@ -0,0 +1,127 @@
+# Chorus Behavior
+
+## EVENT Write permissions and behavior
+
+If `verify_events` is set in the configuration, chorus rejects invalid events in all cases.
+
+Chorus accepts all events submitted by authorized users.
+
+Chorus accepts relay list metadata (kind 10002) from anybody.
+
+Chorus accepts all ephemeral events from anybody.
+
+Chorus accepts all events authored by an authorized user, irrespective of who submits it. Chorus always verifies such events irrespective of the `verify_events` configuration setting.
+
+Chorus accepts all events that tag one of the authorized users.
+
+If you wish to change these rules, change the source code at `nostr.rs:screen_incoming_event()`
+
+## REQ Read permissions and behavior
+
+Chorus serves all relay list metadata (kind 10002) events queried.
+
+Chorus serves all ephemeral events.
+
+Chorus does not serve any DM (kind 4) or GiftWrap (kind 1059) unless the connection is AUTHed and the user matches either a tagged person or the author of the event.
+
+Chorus serves all events to AUTHed and authorized users.
+
+Chorus serves all events which were authored by an authorized user.
+
+If you wish to change these rules, change the source code at `nostr.rs:screen_outgoing_event()`
+
+## Abuse, Banning, Throttling, and the like
+
+WebSocket frames and messages are limited to 1 MB.
+
+Each connection has a memory buffer used for JSON deserialization that is no larger
+than the WebSocket message. No more than one such buffer exists per connection, and memory
+allocation is generally tightly controlled.
+
+Every connection is IP banned for 4 seconds after disconnection, whether or not the connection
+was well behaved. We don't think clients should ever reconnect immediately. If chorus is
+run directly (not behind an nginx proxy), this IP banning is more efficient because it happens
+prior to SSL setup.
+
+A maximum of 32 subscriptions are allowed by default, although this is configurable with the
+`max_subscriptions` configuration setting.
+
+## NIP Support
+
+### NIP-01 Basic protocol flow description
+
+Chorus fully complies with NIP-01
+
+### NIP-04 Encrypted Direct Message
+
+Chorus fully complies with NIP-04
+
+The chorus relay does not supply kind 4 DMs to anybody except the tagged recipient
+and the author.
+
+REQs for such disallowed events do not generate any error condition, but the events are
+not supplied.
+
+### NIP-09 Event Deletion
+
+Chorus fully compiles with NIP-09.
+
+Chorus both deletes matching events (matched by id and pubkey)
+as well as remembering these (id,pubkey) pairs to reject such events subsequently submitted.
+
+### NIP-11 Relay Information Document
+
+Chorus fully complies with NIP-11.
+
+Chorus returns a brief result without much detail.
+
+### NIP-26 Delegated Event Signing
+
+Chorus does not support NIP-26.
+
+### NIP-28 Public Chat
+
+Chorus does not support NIP-28.
+
+### NIP-40 Expiration Timestamp
+
+Chorus does not support NIP-40.
+
+### NIP-42 Authentication of clients to relays
+
+Chorus fully complies with NIP-42.
+
+Chorus immediately sends an AUTH to every client as soon as the connection is setup.
+
+Chorus continues to serve clients irrespective of whether they have AUTHed or not.
+
+### NIP-45 Counting results
+
+Chorus does not support NIP-45.
+
+### NIP-50 Search Capability
+
+Chorus does not support NIP-50.
+
+### NIP-59 Gift Wrap
+
+The chorus relay does not supply kind 1059 GiftWraps to anybody except the tagged recipient
+and the author.
+
+REQs for such disallowed events do not generate any error condition, but the events are
+not supplied.
+
+### NIP-65 Relay List Metadata
+
+Chorus fully compiles with NIP-65.
+
+Chorus accepts kind 10002 events from anybody, and serves such events to anybody.
+
+### NIP-94 File Metadata
+
+Chorus does not support NIP-94.
+
+### NIP-96 HTTP File Storage Integration
+
+Chorus does not support NIP-96.
+

docs/CONFIG.md

@@ -0,0 +1,131 @@
+# Chorus Configuration
+
+The chorus binary requires one command line parameter which specifies the config file path.
+
+The config file must be in RON format. See the [RON documentation](https://docs.rs/ron/latest/ron/)
+
+## Configuration Variables
+
+### data_directory
+
+This is the directory where chorus stores data.
+
+Default is "/tmp".
+
+If deployed according to [docs/DEPLOYING.md](docs/DEPLOYING.md), is "/opt/chorus/var/chorus".
+
+### ip_address
+
+This is the IP address that chorus listens on. If deployed directly on the Internet, this should
+be an Internet globally accessible IP address. If proxied or if testing locally, this can be
+a localhost address.
+
+Default is "127.0.0.1".
+
+### port
+
+This is the port that chorus listens on. If deployed directly on the Internet, this should
+probably be 443 which is the expected default port for the "wss://" protocol.
+
+Default is 443.
+
+### hostname
+
+This is the DNS hostname of your relay. This is used for verifying AUTH events, which specify
+your relay host name.
+
+### use_tls
+
+If true, chorus will handle TLS, running over HTTPS.  If false, chorus run over HTTP.
+
+If you are proxying via nginx, normally you will set this to false and allow nginx to handle
+TLS.
+
+### certchain_pem_path
+
+This is the path to your TLS certificate chain file.
+
+If `use_tls` is false, this value is irrelevant.
+
+Default is "./tls/fullchain.pem".
+
+If deployed according to [docs/DEPLOYING.md](docs/DEPLOYING.md) using the direct method,
+this is set to "/opt/chorus/etc/tls/fullchain.pem" and the systemd service copies letsencrypt
+TLS certificates into this position on start.
+
+### key_pem_path
+
+This is the path to yoru TLS private key file.
+
+If `use_tls` is false, this value is irrelevant.
+
+Default is "./tls/privkey.pem".
+
+If deployed according to [docs/DEPLOYING.md](docs/DEPLOYING.md) using the direct method,
+this is set to "/opt/chorus/etc/tls/privkey.pem" and the systemd service copies letsencrypt
+TLS certificates into this position on start.
+
+### name
+
+This is an optional name for your relay, displayed in the NIP-11 response.
+
+Default is None.
+
+### description
+
+This is an optional description for your relay, displayed in the NIP-11 response.
+
+Default is None.
+
+### contact
+
+This is an optional contact for your relay, displayed in the NIP-11 response.
+
+Default is None.
+
+### public_key_hex
+
+This is an optional public key (hex format) for your relay, displayed in the NIP-11 response.
+
+Default is None.
+
+### user_hex_keys
+
+These are the public keys (hex format) of your relay's authorized users. See [BEHAVIOR.md](BEHAVIOR.md) to understand how chorus uses these.
+
+Default is `[]`
+
+### verify_events
+
+This is a boolean indicating whether or not chorus verifies incoming events.
+
+This setting only skips verification of events that are submitted by AUTHed and authorized users. Chorus always verifies incoming AUTH events, and any event that is not submitted by an AUTHed and authorized relay user.
+
+Default is true.
+
+### allow_scraping
+
+This is a boolean indicating whether or not scraping is allowed. Scraping is any filter that does not match one of the following conditions:
+
+- A non-empty `id` list is set
+- A non-empty `authors` list is set and a non-empty `kinds` list is set
+- A non-empty `authors` list is set and at least one tag is set.
+- A non-empty `kinds` list is set and at least one tag is set.
+
+Filter that fail to match these conditions will be rejected if `allow_scraping` is false.
+
+If `allow_scraping` is true, be aware that filters that don't match any of these conditions have no indexes to speed up their query, so they scan through every single event on the relay.
+
+The purpose of this setting is as a temporary setting that allows you to dump every single event on your relay.
+
+Default is false.
+
+### max_subscriptions
+
+This is a usize indicating the maximum number of subscriptions a connection can have open at a given time.
+
+If you set this too low, clients will be incentivised to resubmit updated subscriptions which will pull down the same events over again, instead of submitting a new subscription that only gets the additional events that the client wants. It may seem intuitive that setting this to a low value like 10 will decrease server load, but it will probably increase server load.
+
+It is strongly recommended to not go below 16.
+
+Default is 32.