From 8e1a74544c9633841190f6872be990e5e3887cd2 Mon Sep 17 00:00:00 2001 From: infogulch Date: Mon, 11 Mar 2024 00:56:59 -0500 Subject: [PATCH] Document Server and Instance --- README.md | 2 +- TODO.md | 13 ++++++++----- cmd/README.md | 2 +- instance.go | 42 +++++++++++++++++++++++++++++++++++------- server.go | 28 ++++++++++++++++++++++++++-- 5 files changed, 71 insertions(+), 16 deletions(-) diff --git a/README.md b/README.md index 3387aba..ff452ec 100644 --- a/README.md +++ b/README.md @@ -250,7 +250,7 @@ Download from the [Releases page](https://github.com/infogulch/xtemplate/release
🎏 CLI flags listing and examples ```shell -$ ./xtemplate --help +$ ./xtemplate -help xtemplate is a hypertext preprocessor and html templating http server Usage: ./xtemplate [options] diff --git a/TODO.md b/TODO.md index 56d5d46..66c3473 100644 --- a/TODO.md +++ b/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 diff --git a/cmd/README.md b/cmd/README.md index 151f8b3..47a69e8 100644 --- a/cmd/README.md +++ b/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] diff --git a/instance.go b/instance.go index 6962bbe..7fdb3a9 100644 --- a/instance.go +++ b/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 // ///////////// diff --git a/server.go b/server.go index 5b3c76e..5267c13 100644 --- a/server.go +++ b/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 } /////////////