Document Server and Instance

README.md

@@ -250,7 +250,7 @@ Download from the [Releases page](https://github.com/infogulch/xtemplate/release
 <details><summary><strong>🎏 CLI flags listing and examples</strong></summary>
 
 ```shell
-$ ./xtemplate --help
+$ ./xtemplate -help
 xtemplate is a hypertext preprocessor and html templating http server
 
 Usage: ./xtemplate [options]

TODO.md

@@ -1,9 +1,10 @@
 # TODO
 
-- [ ] Create system for optional modules. DB/FS/NATS
-    - Inject?
-- Support SSE
-    - [ ] Integrate nats subscription
+- [ ] Create system for optional modules. DB/FS/NATS. Inject?
+- [ ] Integrate nats:
+    - [ ] Subscribe to subject, loop on receive to send via open SSE connection
+    - [ ] Publish message to subject
+    - [ ] Request-Reply
 
 ### Automation
 
@@ -28,7 +29,9 @@
     - Potentially useful for invoking a template file with a relative path. (Add DIR constant too?)
     - Parse().Tree.Root.(*ListNode).[].(recurse) where NodeType()==NodeIdentifier replace with StringNode
     - Should be fine?
-- [ ] Add command to pre-compress all static files
+- [ ] Add command that pre-compresses static files
+- [ ] Pass Config.Ctx down to http.Server/net.Listener to allow caller to cancel
+  .Serve() and all associated instances.
 
 # DONE
 

cmd/README.md

@@ -22,7 +22,7 @@ GOFLAGS='-tags="sqlite_json"' CGO_ENABLED=1 go build -o xtemplate ./cmd
 ### Usage
 
 ```shell
-$ ./xtemplate --help
+$ ./xtemplate -help
 xtemplate is a hypertext preprocessor and html templating http server
 
 Usage: ./xtemplate [options]

instance.go

@@ -32,6 +32,41 @@ import (
 // Pubic Definitions //
 ///////////////////////
 
+// Instance is a configured, immutable, xtemplate request handler ready to
+// execute templates and serve static files in response to http requests.
+//
+// Create a new Instance:
+//
+// 1. Create a [Config], directly or with [New]
+// 2. Configure as desired
+// 3. Call [Config.Instance]
+//
+// Configuration of an Instance is intended to be immutable. Instead of mutating
+// a running Instance, build a new Instance from a modified Config and swap
+// them. (See also [Server].)
+type Instance interface {
+	http.Handler
+
+	// Id returns the id of this instance which is unique in the current
+	// process. This differentiates multiple instances, as the instance id
+	// is attached to all logs generated by the instance with the attribute name
+	// `xtemplate.instance`.
+	Id() int64
+
+	// Stats returns summary stats of what was loaded into this instance, which
+	// can be useful as a first pass check that xtemplate discovered and
+	// processed templates and static files as expected. These counts are also
+	// logged on instance start. Detailed information about template files,
+	// routes, and static files is logged at Debug level while the instance is
+	// being configured.
+	Stats() InstanceStats
+
+	// Routes returns the list of ServeMux patterns and matching configured
+	// `http.Handler`s that Instance uses to handle http requests. These can be
+	// used to build your own mux, or to just inspect the route patterns.
+	Routes() []InstanceRoute
+}
+
 type InstanceStats struct {
 	Routes                        int
 	TemplateFiles                 int
@@ -46,13 +81,6 @@ type InstanceRoute struct {
 	Handler http.Handler
 }
 
-type Instance interface {
-	http.Handler
-	Id() int64
-	Stats() InstanceStats
-	Routes() []InstanceRoute
-}
-
 /////////////
 // Builder //
 /////////////

server.go

@@ -14,11 +14,35 @@ import (
 // Pubic Definitions //
 ///////////////////////
 
+// Server is a configured, *reloadable*, xtemplate request handler ready to
+// execute templates and serve static files in response to http requests. It
+// manages an [Instance] and allows you to reload template files with the same
+// config by calling `server.Reload()`. If successful, Reload atomically swaps
+// the old Instance with the new Instance so subsequent requests are handled by
+// the new instance, and any outstanding requests still being served by the old
+// Instance can continue to completion. The old instance's Config.Ctx is also
+// cancelled.
+//
+// Create a new Server:
+//
+// 1. Create a [Config], directly or with [New]
+// 2. Configure as desired
+// 3. Call [Config.Server]
 type Server interface {
-	Instance() Instance
-	Serve(listen_addr string) error
+	// Handler returns a `http.Handler` that always routes new requests to the
+	// current Instance.
 	Handler() http.Handler
+
+	// Instance returns the current [Instance]. After calling Reload, this may
+	// return a different Instance.
+	Instance() Instance
+
+	// Reload creates a new Instance from the config and swaps it with the
+	// current instance if successful.
 	Reload() error
+
+	// Serve opens a net listener on `listen_addr` and serves requests from it.
+	Serve(listen_addr string) error
 }
 
 /////////////