Improve README

README.md

@@ -16,6 +16,16 @@ See the specification of the W3C WebSub protocol at
 
   [w3cspec]: https://www.w3.org/TR/pubsub/
 
+## Quick Start
+
+ 1. Install Racket from <http://download.racket-lang.org/>
+ 2. Install RacketMQ by running `raco pkg install --auto racketmq`
+ 3. `racketmq --canonical-host localhost 7827`
+
+To install from git, replace the `raco pkg install ...` step above
+with an invocation of `make link` from the top directory of your git
+checkout.
+
 ## Features
 
  - Offers both *local topics*, topics whose canonical hub is this hub,
@@ -33,16 +43,113 @@ See the specification of the W3C WebSub protocol at
  - Support for `hub.secret` and `hub.lease_seconds` protocol
    parameters
 
-## Conformance
+## Configuration
 
-At the time of writing, no official list of conformance criteria
-exists; however, there is a draft list of Candidate Recommendation
-implementation criteria at <https://github.com/w3c/pubsub/issues/56>.
+RacketMQ has only one required configuration variable: you must tell
+the hub its primary ("canonical") *host name* and *port number*. These
+are used to build URLs for clients of the Hub to use.
 
-## Bug Reports
+When the RacketMQ startup script is given a "`-c` *filename*" option,
+it loads configuration data from the named file. The option can be
+supplied more than once; all named files are imported.
 
-Please report issues using this project's Github issues page,
-<https://github.com/tonyg/racketmq/issues>.
+For a fully-commented example configuration file, see
+[`racketmq/defaults.rktd`](racketmq/defaults.rktd).
+
+Within each file, each configuration entry should be a list (see
+[Racket syntax](https://docs.racket-lang.org/reference/reader.html))
+with a symbol (the "key") as its first item followed by zero or more
+items.
+
+Each configuration file is automatically reread by the server when it
+is changed: if you need to make changes, consider doing so atomically
+by producing an updated configuration file and using
+`rename(2)`/`mv(1)` to activate it.
+
+### Required configuration data
+
+    (canonical-host "localhost" 7827)
+
+Exactly one "canonical-host" key, containing two values, a string
+hostname, and a number TCP port. This causes an HTTP server to be
+spun up on the named port.
+
+Since this is the only mandatory configuration item, RacketMQ can run
+without any configuration file at all if the server is started with
+the `--canonical-host` command-line argument:
+
+    racketmq --canonical-host localhost 7827
+
+### Optional configuration data
+
+    (accepted-host "localhost" 7827)
+    (accepted-host "localhost" 80)
+    (accepted-host "www.example.com" 7827)
+    ;; etc.
+
+If you want your server to appear under several aliases, add them
+here. HTTP servers will be spun up for all mentioned port numbers,
+and within those servers, `Host` headers matching the given host
+names will be accepted.
+
+### Fine tuning
+
+You will seldom want to alter these settings.
+
+    (max-upstream-redirects 5)
+
+When performing discovery / upstream content retrieval, the hub
+will follow this many redirects before deciding it has had enough.
+
+    (default-lease 86400) ;; 86400 seconds = one day
+    (max-lease 604800) ;; 604800 seconds = one week
+
+If a subscription request arrives with no specified
+`hub.lease_seconds`, then `default-lease` is used. If a requested
+lease duration exceeds `max-lease`, then `max-lease` is used
+instead.
+
+    (min-poll-interval 60) ;; seconds
+    (default-poll-interval "none") ;; seconds, or "none"
+
+Upstream topics will be polled from time to time, according to the
+settings of each local subscription to the topic. Subscriptions may
+supply `hub.poll_interval_seconds` as either a number or the string
+"none". If no `hub.poll_interval_seconds` is supplied in a
+subscription, `default-poll-interval` is used. If all subscriptions
+to an upstream topic have "none" as their poll interval, no polling
+will occur; otherwise, polling will occur at the fastest requested
+rate, but never more frequently than every `min-poll-interval`
+seconds.
+
+    (max-dead-letters 10)
+    (max-delivery-retries 10)
+    (initial-retry-delay 5.0) ;; seconds
+    (retry-delay-multiplier 1.618)
+    (max-retry-delay 30) ;; seconds
+
+Subscriptions last until explicitly terminated by an unsubscription
+request, implicitly terminated by lease expiry, or implicitly
+terminated by sustained delivery failure.
+
+When the hub sends a *content distribution request* (see the WebSub
+spec) to a subscription's callback, if a success response is
+returned, the delivery is considered successful.
+
+Otherwise, the hub begins an exponential backoff process, with an
+initial delay of `initial-retry-delay` seconds, increasing by a
+factor of `retry-delay-multiplier` (subject to a cap of
+`max-retry-delay` seconds) with each subsequent attempt until
+`max-delivery-retries` attempts have been made. At that point, if
+all attempts to deliver the particular content distribution request
+have failed, the request is considered a "dead letter" and is
+effectively discarded. Once a request has either succeeded or
+become a dead letter, the hub continues with any further pending
+content distribution requests for the subscription.
+
+If more than `max-dead-letters` dead letters pile up for a
+subscription, the subscription is considered too damaged to
+continue to exist, and is terminated.
 
 ## Hub URL layout
 
@@ -88,6 +195,17 @@ Please report issues using this project's Github issues page,
 
     - method `GET`: retrieve a static resource.
 
+## Conformance
+
+At the time of writing, no official list of conformance criteria
+exists; however, there is a draft list of Candidate Recommendation
+implementation criteria at <https://github.com/w3c/pubsub/issues/56>.
+
+## Bug Reports
+
+Please report issues using this project's Github issues page,
+<https://github.com/tonyg/racketmq/issues>.
+
 ## License
 
 Copyright © 2016 Tony Garnock-Jones <tonyg@leastfixedpoint.com>