Update documentation w/dynamic content, config file (#36)

Updates to REAME.md:
- [x] Dynamic content
- [x] Configuration file

Co-authored-by: Nicolas Herry <beastieboy@beastieboy.net>
Reviewed-on: #36
beastieboy 7 months ago
parent 40d607cc16
commit e92e9325e8
  1. 89

@ -46,8 +46,10 @@ As of today, the code lives in a single package, simply called `gopher`. The cod
marmotte accepts a series of options on the command line to customise many aspects. Calling the server with the option `--help` gives the complete list:
$ marmotte --help
Usage of /usr/local/bin/marmotte:
--errors string the directory where the error templates can be found (default "$ROOT/errors")
Usage of ./marmotte:
--configfile string YAML configuration file (default "/usr/local/etc/marmotte/marmotte.yaml")
--debug set logging level to Debug
--errors string the directory where the error templates can be found (default "/errors")
--host string the hostname the server sockets will bind to (default "localhost")
--logfile string the logfile (not rotated) (default "/var/log/marmotte.log")
--port int the port the server will listen on (default 7070)
@ -65,6 +67,52 @@ The table below explains explains each option in detail:
|users_gopherspace|marmotte offers users' gopherspace (refer to the section [Users' gopherspace](#users-gopherspace) for details on what it is and directions to set this up). This option allows to specify the root directory for the users' gopherspace, which will be resolved as a subdirectory of `root`.|`users_gopherspace`<br>`homes`|
|errors|Root directory where the error content templates can be found. For more information on error templates and error handling in general, please refer to the section [Error handling](#error-handling). The directory is resolved as a subdirectory of `root`.|`errors`<br>`custom/error_templates`|
|logfile|The full path to the logfile. If none is given, the logs are printed on `stdout`, which allows to have a logshipper take care of them. It is recommended the logfile lives outside of `root`.|`/var/log/marmotte.log`|
|debug|Flag to toggle debug messages in the logs on and off|`true`<br>`false`|
|configfile|The path to the configuration file for marmotte, relative to `root`. Refer to the section [Configuring marmotte](#configuring-marmotte) for details.|`/usr/local/etc/marmotte/marmotte.yaml`|
## Configuring marmotte
marmotte can be configured via a YAML file, environment variables and the command line. marmotte searches for settings and applies them going through these sources in this order. This allows to override a parameter defined in a configuration file by passing an option on the command line, for example. The environment variables are useful when deploying in a container and in a cloud context, typically.
The preceding section presents all the options available on the command line.
The name of the different environment variables are exactly as the command-line options, with the prefix `MARMOTTE_`. For example, the `--root` option's counterpart in the environment is `MARMOTTE_ROOT`. These environment variables can be defined in a `.env` file placed next to the binary, or can be defined and exported directly in the environment.
The configuration file uses also the exact same names as the command line options. Below is an example of such a configuration file:
# Example configuration file for marmotte
# Copy and edit to suits your needs
# Host the sockets will be bound to
host: localhost
# Port the sockets will be bound to
# Note: On Unix-like systems, to listen to ports below 1024 a process must run as a privileged user
port: 7070
# Network transport protocol the server will create the sockets with
# Today, only tcp makes sense here
transport: tcp
# The directory where gopher resources can be found
# The directory must be readable by the user running the server
root: /usr/local/marmotte
# When not shipping logs to an aggregator, set this to a writable file
# To print on stdout and/or use a logshipper, comment out the following line
logfile: /var/log/marmotte
# The directory alias for users' gopherspaces
# The path is relative to the root directory
users_gopherspace: /users
# The path to the directory containing the error templates (10.gt, 20.gt, 30.gt, etc.)
# The path is relative to the root directory
errors: /errors
# Whether log level should be set to debug
debug: false
## Customising gophermaps and text files
marmotte offers a simple way to customise gophermaps and text files via Headers and Footers. The Context holds Header and Footer data as a slice of strings in a map. By combining `Predicates` and the functions `HeaderTransformerfor` and `FooterTransformerfor`, one can define Headers only applicable to specific situations, and bind specific Headers and Footers to these situations.
@ -83,6 +131,8 @@ The code in `cmd/marmotte/main.go` gives a good example:
In the code above, a simple Header is defined under the key "all\_gophermaps". There are no special keywords here; it can be anything. Then, a `ResponseTransformer` is added to the Context that applies the Headers to a Response (prepends the text to the content) found behind that same key, "all\_gophermaps", and reserve its use to gophermaps by tying it with the `Predicate` `GopherMapPredicate`. That way, text files will not come with this Header, only gophermaps.
Another way to customise gophermaps is to write dynamic gophermaps. See the section [Dynamic content](#dynamic-content) for details.
## Executables
marmotte allows executables to be called and returns the result to the client. The executables can be of any nature: as long as their permissions in the filesystem allow the operating system user or group marmotte runs as to execute them, they represent valid resources.
@ -94,6 +144,40 @@ The executable should be referenced in a gophermap by giving the type of the fil
1Generate a collection of images /image-gen mygopherhole.net 70
## Dynamic content
marmotte is able to generate dynamic content via a templating system. A `ResponseTransformer` handles the processing of the templates, and returns plain text content. The syntax for these templates is detailed in the page that documents the Go module [text/template](https://pkg.go.dev/text/template).
marmotte today passes the following struct to all templates:
type DynamicContext struct {
ServerContext Context
ErrorInfo GopherErrorInfo
RequestInfo Request
ResponseInfo Response
CurrentTime time.Time
Below is an example of a template using this structure:
Hello there! This content has been dynamically generated.
Current Configuration:
- Server Context
- Host: {{- .ServerContext.Host }}
- Port: {{- .ServerContext.Port }}
- TransportProtocol: {{- .ServerContext.TransportProtocol }}
- Root: {{- .ServerContext.Root }}
- ErrorRoot: {{- .ServerContext.ErrorRoot }}
- UsersGopherspace: {{- .ServerContext.UsersGopherspace }}
- Request
- FullPath: {{- .RequestInfo.FullPath }}
- Path: {{- .RequestInfo.Path }}
- Additional parameters
- Current time: {{- .CurrentTime }}
In the future, this structure will offer more data to the templates to play with.
## Error handling
marmotte offers dynamic error handling, similarly to what is found usually in http servers. Depending on the error encountered, a different message is reported to the user, with some information to help understand the error. As the Gopher Protocol leaves all the details of error handling to the server implementation, there are no standard error codes or specific mechanism expected by Gopher clients. marmotte handles error by redirecting a failed request to some content informing the user of the problem. This content is a template found in the `errors` subdirectory of `root`. There is one template per error code. Today, the templates are in plain text. marmotte defines the following error codes and templates:
|Error code|Description|Template|
@ -137,6 +221,7 @@ Below is a list of the features currently implemented. This is by no means a com
- [X] Dynamic content via templates
- [X] Dynamic execution of scripts and programs
- [ ] Image filtering via Transformers
- [ ] Search