From 886a18e0c67624d0882f04c7f6659bcfee6b4d8d Mon Sep 17 00:00:00 2001 From: metamuffin Date: Wed, 29 May 2024 16:37:44 +0200 Subject: refactor filter system --- readme.md | 64 ++++++++++++++++++++++++++++++++++++++++++++------------------- 1 file changed, 45 insertions(+), 19 deletions(-) (limited to 'readme.md') diff --git a/readme.md b/readme.md index 3f30b9c..2ad4faa 100644 --- a/readme.md +++ b/readme.md @@ -6,8 +6,9 @@ a simple stupid reverse proxy - Simple to configure (see below) - Handles connection upgrades correctly by default (websocket, etc.) +- Composable modules - TLS support -- _TODO: h2; match on uris; connection pools_ +- _TODO: h2; match on uris; connection pooling_ ## Quick Start @@ -18,31 +19,36 @@ configuration file is written in YAML and could look like this: # Both the 'http' and 'https' sections are optional http: # the value for 'bind' can either be a string or a list of strings - bind: [ "127.0.0.1:8080", "[::1]:8080" ] + bind: "[::1]:8080" https: - bind: "127.0.0.1:8443" + bind: "[::1]:8443" tls_cert: "ssl/cert.pem" - tls_key: "ssl/key.pem" # only accepts pkcs8 for now - -# this is a lookup table from hostnames to a list of filters -# in this case, requests for `testdomain.local` are forwarded to 127.0.0.1:3000 -hosts: - "testdomain.local": !proxy { backend: "127.0.0.1:8000" } - "192.168.178.39": !proxy { backend: "127.0.0.1:8000" } - "localhost": !files - root: "/home/muffin/videos" + tls_key: "ssl/key.pem" # only accepts pkcs8 + +# !hosts multiplexes requests for different hostnames. +handler: !hosts + # requests for `example.org` are forwarded to 127.0.0.1:8000 + "example.org": !proxy { backend: "127.0.0.1:8000" } + # requests for `mydomain.com` will access files from /srv/http + "mydomain.com": !files + root: "/srv/http" index: true + + "panel.mydomain.com": !access_log + ``` ## Reference - **section `http`** - `bind`: string or list of strings with addresses to listen on. + - **section `https`** - `bind`: string or list of strings with addresses to listen on. - `tls_cert`: path to the SSL certificate. (Sometimes called `fullchain.pem`) - `tls_key`: path to the SSL key. (Often called `key.pem` or `privkey.pem`) + - **section `limits`** - Note: Make sure you do not exceed the maximum file descriptor limit on your platform. @@ -50,21 +56,28 @@ hosts: connections. excess connections are rejected. Default: 512 - `max_outgoing_connections` number of maximum outgoing (upstream) connections. excess connections are rejected. Default: 256 -- **section `hosts`** - - A map from hostname (a string) to a _filter_ or a list of _filters_ + +- **section `handler`** + - A module to handle all requests. Usually an instance of `hosts`. + - `watch_config`: boolean if to watch the configuration file for changes and apply them accordingly. Default: true (Note: This will watch the entire parent directory of the config since most editors first move the file. Currently any change will trigger a reload. TODO) -### Filters +### Modules -- **filter `proxy`** +- **module `hosts`** + - Hands over the requests to different modules depending on the `host` header. + - Takes a map from hostname (string) to handler (module) + +- **module `proxy`** - Forwards the request as-is to some other server. the `x-real-ip` header is injected into the request. Connection upgrades are handled by direct forwarding of network traffic. - `backend`: socket address (string) to the backend server -- **filter `files`** + +- **module `files`** - Provides a simple built-in fileserver. The server handles `accept-ranges`. The `content-type` header is inferred from the file extension and falls back to `application/octet-stream`. If a directory is requested `index.html` will @@ -72,12 +85,25 @@ hosts: prepended to the response. - `root`: root directory to be served (string) - `index`: enables directory indexing (boolean) -- **filter `http_basic_auth`** + +- **module `http_basic_auth`** - Filters requests via HTTP Basic Authentification. Unauthorized clients will be challenged on every request. - - `realm`: string that does essentially nothing + - `realm`: describes what the user is logging into (most modern browsers dont show this anymore -_-) - `valid`: list of valid logins (string) in the format `:` (password in plain text). TODO: hashing + - `next`: a module to handle this request on successfully authentificated. (module) + +- **module `access_log`** + - Logs requests to a file. + - `file`: file path to log (string) + - `reject_on_fail`: rejects requests if log could not be written (boolean) + - `flush`: flushes log on every request (boolean) + - `next`: module for further handling of the request (module) + +- **module `error`** + - Rejects every request with a custom error message. + - Takes an error message (string) ## License -- cgit v1.2.3-70-g09d2