config

Documentation

Index

• Constants
• Variables
• type AccessConfig
• type ClientConfig
  • func (c *ClientConfig) MergeDefaultsFrom(o ClientConfig)
• type Config
  • func DefaultConfig() Config
  • func LoadConfig(config string) (Config, error)
  • func LoadConfigFromFile(filename string) (Config, error)
  • func LoadConfigFromRemote(provider, endpoint, path, format string) (Config, error)
• type EncryptionConfig
• type ErrorConfig
• type ErrorImages
• type ErrorMessages
• type LayerConfig
• type LogConfig
• type MainConfig
• type ServerConfig

Constants

const (
	ModeErrorPlainText   = "text"         //Response will be text/plain with the error message in the body
	ModeErrorNoError     = "none"         //Response will not include any data but wil return status code.
	ModeErrorImage       = "image"        //Response will return an image but not the error itself
	ModeErrorImageHeader = "image+header" //Response will return an image and include the error inside x-error-message
)

Modes for error reporting

const (
	AccessFormatCommon   = "common"
	AccessFormatCombined = "combined"
)

Formats for outputting the access log

const (
	MainFormatPlain = "plain"
	MainFormatJson  = "json"
)

Formats for outputting the main log

const LevelAbsurd slog.Level = slog.LevelDebug - 10

const LevelTrace slog.Level = slog.LevelDebug - 5

Variables

var CustomLogLevel = map[string]slog.Level{
	"trace":  LevelTrace,
	"absurd": LevelAbsurd,
}

Types

type AccessConfig

type AccessConfig struct {
	Console bool   //If true, write access logs to standard out. Defaults to true
	Path    string //The file location to write logs to. Log rotation is not built-in, use an external tool to avoid excessive growth. Defaults to none
	Format  string //The format to output access logs in. Applies to both standard out and file out. Possible values: common, combined. Defaults to common
}

type ClientConfig

type ClientConfig struct {
	UserAgent     string            //The user agent to include in outgoing http requests. Separate from Headers to avoid omitting this.
	MaxLength     int               //The maximum Content-Length to allow incoming responses. Default: 10 Megabytes
	UnknownLength bool              //If true, allow responses that are missing a Content-Length header, this could lead to memory overruns. Default: false
	ContentTypes  []string          //The content-types to allow servers to return. Anything else will be interpreted as an error
	StatusCodes   []int             //The status codes from the remote server to consider successful.  Defaults to just 200
	Headers       map[string]string //Include these headers in requests. Defaults to none
	Timeout       uint              //How long (in seconds) a request can be in flight before we cancel it and return an error
}

func (*ClientConfig) MergeDefaultsFrom

func (c *ClientConfig) MergeDefaultsFrom(o ClientConfig)

TODO: handle this better. Not foolproof in detecting default values and very manual. Probably need to do a mapstructure method for this

type Config

type Config struct {
	Server         ServerConfig
	Client         ClientConfig
	Logging        LogConfig
	Error          ErrorConfig
	Authentication map[string]interface{}
	Cache          map[string]interface{}
	Layers         []LayerConfig
}

func DefaultConfig

func DefaultConfig() Config

func LoadConfig

func LoadConfig(config string) (Config, error)

func LoadConfigFromFile

func LoadConfigFromFile(filename string) (Config, error)

func LoadConfigFromRemote

func LoadConfigFromRemote(provider, endpoint, path, format string) (Config, error)

type EncryptionConfig

type EncryptionConfig struct {
	Domain      string //The domain name you're operating with (the domain end-users use). Required
	Cache       string //The path to a directory to cache certificates in if using let's encrypt. Defaults to ./certs
	Certificate string //The file path to get to the TLS certificate
	KeyFile     string //The file path to get to the keyfile
	HttpPort    int    //The port used for non-encrypted traffic. Required if using Let's Encrypt for ACME challenge and needs to indirectly be 80 (that is, it could be 8080 if something else redirects 80 to 8080). Everything except .well-known will be redirected to the main port when set.
}

Configuration for TLS (HTTPS) operation. If this is configured then TLS is enabled. This can operate either with a static certificate and keyfile via the filesystem or via ACME/Let's Encrypt

type ErrorConfig

type ErrorConfig struct {
	Mode     string        //How errors should be returned.  See the consts above for options
	Messages ErrorMessages //Patterns to use for error messages in logs and responses. Not used for utility commands.
	Images   ErrorImages   //Only used if Mode is image or image+header
	AlwaysOk bool          //If set we always return 200 regardless of what happens
}

type ErrorImages

type ErrorImages struct {
	OutOfBounds    string //A request for a zoom level or tile coordinate that's invalid for the requested layer
	Authentication string //Auth failed
	Provider       string //Provider specific errors
	Other          string //Catch-all for unexpected system errors
}

Selects what image to return when various errors occur. These should either be an embedded:XXX value reflecting an image in `internal/layers/images` or the path to an image in the runtime filesystem

type ErrorMessages

type ErrorMessages struct {
	NotAuthorized           string
	ParamRequired           string
	InvalidParam            string
	RangeError              string
	ServerError             string
	ProviderError           string
	ParamsBothOrNeither     string
	ParamsMutuallyExclusive string
	OneOfRequired           string
	EnumError               string
	ScriptError             string
	Timeout                 string
}

This is a poor-man's i8n solution. It allows replacing the error messages our app generates in the main `serve` mode. It's questionable if anyone will ever want to make use of it, but it at least helps avoid magic strings and can be replaced with fully static constants later if it does turn out nobody ever sees value in it

type LayerConfig

type LayerConfig struct {
	Id        string
	Pattern   string
	Provider  map[string]any
	SkipCache bool
	Client    *ClientConfig //If specified, the default Client is overridden.
}

type LogConfig

type LogConfig struct {
	Access AccessConfig
	Main   MainConfig
}

type MainConfig

type MainConfig struct {
	Console bool     //If true, write access logs to standard out. Defaults to true
	Path    string   //The file location to write logs to. Log rotation is not built-in, use an external tool to avoid excessive growth. Defaults to none
	Format  string   //The format to output access logs in. Applies to both standard out and file out. Possible values: plain, json. Defaults to plain
	Level   string   //logging level. one of: debug, info, warn, error, trace, absurd
	Request string   //Can be "true", "false" or "auto". If false, don't include any extra attributes based on request parameters (excluding the ones requested below). If auto (default) it defaults true if format is json, false otherwise
	Headers []string //Headers to include in the logs. Useful for a transaction/request/trace/correlation ID or user identifiers
}

type ServerConfig

type ServerConfig struct {
	Encrypt    *EncryptionConfig //Whether and how to use TLS. Defaults to none AKA no encryption.
	BindHost   string            //IP address to bind HTTP server to
	Port       int               //Port to bind HTTP server to
	RootPath   string            //Root HTTP Path to apply to all endpoints. Defaults to /
	TilePath   string            //HTTP Path to serve tiles under (in addition to RootPath). Defaults to tiles which means /tiles/{layer}/{z}/{x}/{y}.
	Headers    map[string]string //Include these headers in all response from server
	Production bool              //Controls serving splash page, documentation, x-powered-by header. Defaults to false, set true to harden for prod
	Timeout    uint              //How long (in seconds) a request can be in flight before we cancel it and return an error
	Gzip       bool              //Whether to apply gzip compression. Not super helpful when just serving up raster images
}