From bdea298ad878a200c86248b1aa8fe675609cffa0 Mon Sep 17 00:00:00 2001 From: Matt Holt Date: Fri, 15 Nov 2019 16:56:24 -0700 Subject: [PATCH] Add WIP cache docs --- v2:-Documentation.md | 33 ++++++++++++++++++++++++++++++++- 1 file changed, 32 insertions(+), 1 deletion(-) diff --git a/v2:-Documentation.md b/v2:-Documentation.md index e859c52..9b4c154 100644 --- a/v2:-Documentation.md +++ b/v2:-Documentation.md @@ -80,6 +80,7 @@ This page describes how to use Caddy 2, which is a work-in-progress on the [v2 b - [http.matchers.file](#httpmatchersfile) - [http/servers/handle](#httpservershandle) - Middleware (non-terminating handlers): + - [http.handlers.cache](#httphandlerscache) - [http.handlers.headers](#httphandlersheaders) - [http.handlers.rewrite](#httphandlersrewrite) - [http.handlers.markdown](#httphandlersmarkdown) @@ -1202,7 +1203,7 @@ A map of server ID (of your choice) to its configuration object. Each server is - `max_rehandles`: How many rehandles to allow; prevents infinite looping. - `strict_sni_host`: If true, enforce that an HTTP Host header matches the connection's ServerName (SNI) value from the TLS handshake. Important when using TLS client authentication. - `experimental_http3`: If true, IETF-draft-compliant HTTP/3 ("QUIC") will be enabled. It creates a UDP listener. This feature is experimental and is not subject to compatibility promises. -- `logs`: Enables and configures HTTP access and error logging. An empty object uses default settings. Access logs document HTTP requests as they come in; they use the namespace `http.log.access`. Error logs record HTTP handler errors and use the namespace `http.log.error`. +- `logs`: Enables and configures HTTP access logging. An empty object uses default settings. Access logs document HTTP requests as they come in; they use the namespace `http.log.access`. Error logs record HTTP handler errors and use the namespace `http.log.error`. - `logs.logger_names`: Map of request host to custom logger name. For example, if you wanted all requests for `example.com` to be emitted to a logger with a unique name, you can do `"example.com": "example"` and then all access logs related to requests for `example.com` will use a logger named `http.log.access.example` (and same for error logs, but with `.error.` in the name instead). #### http/servers/listen @@ -1554,6 +1555,36 @@ The response flows ⬆️ **UP** (`file_server` -> `templates` -> `encode`): If you think of routes in this way, it will be easy and even fun to solve the puzzle of writing correct routes. +##### http.handlers.cache + +A distributed HTTP cache. + +**NOTE: This module is a work-in-progress. It is not finished and is NOT ready for production use. [We need your help to finish it! Please volunteer in this issue.](https://github.com/caddyserver/caddy/issues/2820)** + +Caches only GET and HEAD requests. Honors the `Cache-Control: no-cache` header. + +Still TODO: + +- Eviction policies and API +- Use single cache per-process +- Preserve cache through config reloads +- More control over what gets cached + +```json +{ + "handler": "cache", + "self": "", + "peers": [], + "max_size": 536870912 +} +``` + +- `self`: The network address of this cache instance; required. +- `peers`: A list of network addresses of cache instances in the group. +- `max_size`: Maximum size of the cache, in bytes. Default is 512 MB. + + + ##### http.handlers.headers Modifies request or response headers.