diff options
author | Matthew Holt <mholt@users.noreply.github.com> | 2019-12-23 12:45:35 -0700 |
---|---|---|
committer | Matthew Holt <mholt@users.noreply.github.com> | 2019-12-23 12:45:35 -0700 |
commit | 95ed603de79c66ff76bfe7e42986a2fc8c7a1fa4 (patch) | |
tree | 1a788b8eba98f0c2e69e5816bac9c7cc09aca96f /modules/caddyhttp/headers | |
parent | cbb405f6aaee046c9de9ffb4f07ca824d9eedeb1 (diff) |
Improve godocs all around
These will be used in the new automated documentation system
Diffstat (limited to 'modules/caddyhttp/headers')
-rw-r--r-- | modules/caddyhttp/headers/headers.go | 54 |
1 files changed, 41 insertions, 13 deletions
diff --git a/modules/caddyhttp/headers/headers.go b/modules/caddyhttp/headers/headers.go index f53e859..ad6c08b 100644 --- a/modules/caddyhttp/headers/headers.go +++ b/modules/caddyhttp/headers/headers.go @@ -28,7 +28,18 @@ func init() { caddy.RegisterModule(Handler{}) } -// Handler is a middleware which can mutate HTTP headers. +// Handler is a middleware which modifies request and response headers. +// +// Changes to headers are applied immediately, except for the response +// headers when Deferred is true or when Required is set. In those cases, +// the changes are applied when the headers are written to the response. +// Note that deferred changes do not take effect if an error occurs later +// in the middleware chain. +// +// Properties in this module accept placeholders. +// +// Response header operations can be conditioned upon response status code +// and/or other header values. type Handler struct { Request *HeaderOps `json:"request,omitempty"` Response *RespHeaderOps `json:"response,omitempty"` @@ -99,12 +110,18 @@ func (h Handler) ServeHTTP(w http.ResponseWriter, r *http.Request, next caddyhtt return next.ServeHTTP(w, r) } -// HeaderOps defines some operations to -// perform on HTTP headers. +// HeaderOps defines manipulations for HTTP headers. type HeaderOps struct { - Add http.Header `json:"add,omitempty"` - Set http.Header `json:"set,omitempty"` - Delete []string `json:"delete,omitempty"` + // Adds HTTP headers; does not replace any existing header fields. + Add http.Header `json:"add,omitempty"` + + // Sets HTTP headers; replaces existing header fields. + Set http.Header `json:"set,omitempty"` + + // Names of HTTP header fields to delete. + Delete []string `json:"delete,omitempty"` + + // Performs substring replacements of HTTP headers in-situ. Replace map[string][]Replacement `json:"replace,omitempty"` } @@ -135,22 +152,33 @@ func (ops HeaderOps) validate() error { } // Replacement describes a string replacement, -// either a simple and fast sugbstring search +// either a simple and fast substring search // or a slower but more powerful regex search. type Replacement struct { - Search string `json:"search,omitempty"` + // The substring to search for. + Search string `json:"search,omitempty"` + + // The regular expression to search with. SearchRegexp string `json:"search_regexp,omitempty"` - Replace string `json:"replace,omitempty"` + + // The string with which to replace matches. + Replace string `json:"replace,omitempty"` re *regexp.Regexp } -// RespHeaderOps is like HeaderOps, but -// optionally deferred until response time. +// RespHeaderOps defines manipulations for response headers. type RespHeaderOps struct { *HeaderOps - Require *caddyhttp.ResponseMatcher `json:"require,omitempty"` - Deferred bool `json:"deferred,omitempty"` + + // If set, header operations will be deferred until + // they are written out and only performed if the + // response matches these criteria. + Require *caddyhttp.ResponseMatcher `json:"require,omitempty"` + + // If true, header operations will be deferred until + // they are written out. Superceded if Require is set. + Deferred bool `json:"deferred,omitempty"` } // ApplyTo applies ops to hdr using repl. |