From 9b83f0f2438d8510b7863bfd7dbeeaef0fc05668 Mon Sep 17 00:00:00 2001
From: Tony Garnock-Jones <tonygarnockjones@gmail.com>
Date: Mon, 21 Nov 2016 09:48:12 +1300
Subject: [PATCH] Comment defaults.rktd

---
 racketmq/defaults.rktd | 98 +++++++++++++++++++++++++++++++++++++-----
 1 file changed, 88 insertions(+), 10 deletions(-)

diff --git a/racketmq/defaults.rktd b/racketmq/defaults.rktd
index 2ded0b5..5fe0a2c 100644
--- a/racketmq/defaults.rktd
+++ b/racketmq/defaults.rktd
@@ -1,22 +1,100 @@
+;;===========================================================================
+;;                       Configuration for RacketMQ
+;;---------------------------------------------------------------------------
+;;
+;; Each configuration entry should be a list with a symbol (the "key")
+;; as its first item followed by zero or more items.
+;;
+;; The configuration file is automatically reread by the server when
+;; it is changed: if you need to make changes to it, consider doing so
+;; atomically by producing an updated configuration file and using
+;; rename(2) / mv(1) to activate it.
+
+;;===========================================================================
 ;; REQUIRED:
-;; (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.
+(canonical-host "localhost" 7827)
+
+;;===========================================================================
 ;; OPTIONAL:
+;;===========================================================================
 
+;;---------------------------------------------------------------------------
+;; 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.
+;;
 ;; (accepted-host "localhost" 7827)
 ;; (accepted-host "localhost" 80)
+;; (accepted-host "www.example.com" 7827)
+;;
 ;; etc.
 
-(max-upstream-redirects 5)
+;;===========================================================================
+;; FINE TUNING:
+;;===========================================================================
 
-(min-poll-interval 60)
+;;---------------------------------------------------------------------------
+;; When performing discovery / upstream content retrieval, the hub
+;; will follow this many redirects before deciding it has had enough.
+;;
+;; (max-upstream-redirects 5)
 
-(default-lease 86400) ;; seconds
+;;---------------------------------------------------------------------------
+;; 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.
+;;
+;; (default-lease 86400) ;; 86400 seconds = one day
+;; (max-lease 604800) ;; 604800 seconds = one week
 
-(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.
+;;
+;; (min-poll-interval 60) ;; seconds
+;; (default-poll-interval "none") ;; seconds, or "none"
 
-(max-dead-letters 10)
-(max-delivery-retries 10)
-(initial-retry-delay 5.0) ;; seconds
-(retry-delay-multiplier 1.618)
-(max-retry-delay 30)
+;;---------------------------------------------------------------------------
+;; 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.
+;;
+;; (max-dead-letters 10)
+;; (max-delivery-retries 10)
+;; (initial-retry-delay 5.0) ;; seconds
+;; (retry-delay-multiplier 1.618)
+;; (max-retry-delay 30) ;; seconds