wip: 🔕 temporary commit

README.md

@@ -15,6 +15,40 @@ Global flags:
 | `--log-level="…"`  | logging level (debug/info/warn/error/fatal) |    `info`     |      `LOG_LEVEL`      |
 | `--log-format="…"` | logging format (console/json)               |   `console`   |     `LOG_FORMAT`      |
 
+### `serve` command (aliases: `s`, `server`, `http`)
+
+Start HTTP server.
+
+Usage:
+
+```bash
+$ error-pages [GLOBAL FLAGS] serve [COMMAND FLAGS] [ARGUMENTS...]
+```
+
+The following flags are supported:
+
+| Name                  | Description                                                                                                                                                      | Default value | Environment variables |
+|-----------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------|:-------------:|:---------------------:|
+| `--port="…"` (`-p`)   | TCP port number                                                                                                                                                  |    `8080`     |     `LISTEN_PORT`     |
+| `--listen="…"` (`-l`) | IP (v4 or v6) address to listen on                                                                                                                               |   `0.0.0.0`   |     `LISTEN_ADDR`     |
+| `--add-template="…"`  | to add a new template, provide the path to the file here (may be specified multiple times; the filename without the extension will be used as the template name) |     `[]`      |        *none*         |
+
+### `healthcheck` command (aliases: `chk`, `health`, `check`)
+
+Health checker for the HTTP server. The use case - docker health check.
+
+Usage:
+
+```bash
+$ error-pages [GLOBAL FLAGS] healthcheck [COMMAND FLAGS] [ARGUMENTS...]
+```
+
+The following flags are supported:
+
+| Name                | Description     | Default value | Environment variables |
+|---------------------|-----------------|:-------------:|:---------------------:|
+| `--port="…"` (`-p`) | TCP port number |    `8080`     |     `LISTEN_PORT`     |
+
 <!--/GENERATED:CLI_DOCS-->
 
 

internal/cli/app.go

@@ -11,6 +11,8 @@ import (
 
 	"gh.tarampamp.am/error-pages/internal-old/env"
 	"gh.tarampamp.am/error-pages/internal/appmeta"
+	"gh.tarampamp.am/error-pages/internal/cli/healthcheck"
+	"gh.tarampamp.am/error-pages/internal/cli/serve"
 	"gh.tarampamp.am/error-pages/internal/logger"
 )
 
@@ -75,6 +77,10 @@ func NewApp(appName string) *cli.Command { //nolint:funlen
 
 			return nil
 		},
+		Commands: []*cli.Command{
+			serve.NewCommand(log),
+			healthcheck.NewCommand(log, healthcheck.NewHTTPHealthChecker()),
+		},
 		Version: fmt.Sprintf("%s (%s)", appmeta.Version(), runtime.Version()),
 		Flags: []cli.Flag{ // global flags
 			&logLevelFlag,

internal/cli/serve/command.go

@@ -0,0 +1,129 @@
+package serve
+
+import (
+	"context"
+	"fmt"
+	"strings"
+
+	"github.com/urfave/cli/v3"
+	"go.uber.org/zap"
+
+	"gh.tarampamp.am/error-pages/internal/cli/shared"
+	"gh.tarampamp.am/error-pages/internal/config"
+)
+
+type command struct {
+	c *cli.Command
+
+	opt struct{}
+}
+
+// NewCommand creates `serve` command.
+func NewCommand(log *zap.Logger) *cli.Command { //nolint:funlen
+	var cmd command
+
+	var (
+		portFlag    = shared.ListenPortFlag
+		addrFlag    = shared.ListenAddrFlag
+		addTplFlag  = shared.AddTemplateFlag
+		addCodeFlag = shared.AddHTTPCodeFlag
+
+		jsonFormatFlag = cli.StringFlag{
+			Name:     "json-format",
+			Usage:    "override the default error page response in JSON format (Go templates are supported)",
+			Sources:  cli.EnvVars("RESPONSE_JSON_FORMAT"),
+			OnlyOnce: true,
+			Config:   cli.StringConfig{TrimSpace: true},
+		}
+
+		xmlFormatFlag = cli.StringFlag{
+			Name:     "xml-format",
+			Usage:    "override the default error page response in XML format (Go templates are supported)",
+			Sources:  cli.EnvVars("RESPONSE_XML_FORMAT"),
+			OnlyOnce: true,
+			Config:   cli.StringConfig{TrimSpace: true},
+		}
+	)
+
+	cmd.c = &cli.Command{
+		Name:    "serve",
+		Aliases: []string{"s", "server", "http"},
+		Usage:   "Start HTTP server",
+		Suggest: true,
+		Action: func(ctx context.Context, c *cli.Command) error {
+			var cfg = config.New()
+
+			if add := c.StringSlice(addTplFlag.Name); len(add) > 0 { // add templates from files to the config
+				for _, templatePath := range add {
+					if addedName, err := cfg.Templates.AddFromFile(templatePath); err != nil {
+						return fmt.Errorf("cannot add template from file %s: %w", templatePath, err)
+					} else {
+						log.Info("Template added",
+							zap.String("name", addedName),
+							zap.String("path", templatePath),
+						)
+					}
+				}
+			}
+
+			if add := c.StringMap(addCodeFlag.Name); len(add) > 0 { // add custom HTTP codes
+				for code, msgAndDesc := range add {
+					var (
+						parts = strings.SplitN(msgAndDesc, "/", 2) //nolint:mnd
+						desc  config.CodeDescription
+					)
+
+					if len(parts) > 0 {
+						desc.Message = strings.TrimSpace(parts[0])
+					}
+
+					if len(parts) > 1 {
+						desc.Description = strings.TrimSpace(parts[1])
+					}
+
+					cfg.Codes[code] = desc
+
+					log.Info("HTTP code added",
+						zap.String("code", code),
+						zap.String("message", desc.Message),
+						zap.String("description", desc.Description),
+					)
+				}
+			}
+
+			{ // override default JSON and XML formats
+				if c.IsSet(jsonFormatFlag.Name) {
+					cfg.Formats.JSON = c.String(jsonFormatFlag.Name)
+				}
+
+				if c.IsSet(xmlFormatFlag.Name) {
+					cfg.Formats.XML = c.String(xmlFormatFlag.Name)
+				}
+			}
+
+			log.Debug("Configuration",
+				zap.Strings("loaded templates", cfg.Templates.Names()),
+				zap.Strings("described HTTP codes", cfg.Codes.Codes()),
+				zap.String("JSON format", cfg.Formats.JSON),
+				zap.String("XML format", cfg.Formats.XML),
+			)
+
+			return cmd.Run(ctx, log, &cfg)
+		},
+		Flags: []cli.Flag{
+			&portFlag,
+			&addrFlag,
+			&addTplFlag,
+			&addCodeFlag,
+			&jsonFormatFlag,
+			&xmlFormatFlag,
+		},
+	}
+
+	return cmd.c
+}
+
+// Run current command.
+func (cmd *command) Run(ctx context.Context, log *zap.Logger, cfg *config.Config) error {
+	return nil // TODO: implement
+}

internal/cli/shared/flags.go

@@ -3,10 +3,15 @@ package shared
 import (
 	"fmt"
 	"net"
+	"os"
+	"strings"
 
 	"github.com/urfave/cli/v3"
 )
 
+// Note: Don't use pointers for flags, because they have own state which is not thread-safe.
+// https://github.com/urfave/cli/issues/1926
+
 var ListenAddrFlag = cli.StringFlag{
 	Name:     "listen",
 	Aliases:  []string{"l"},
@@ -14,7 +19,6 @@ var ListenAddrFlag = cli.StringFlag{
 	Value:    "0.0.0.0", // bind to all interfaces by default
 	Sources:  cli.EnvVars("LISTEN_ADDR"),
 	OnlyOnce: true,
-	Required: true,
 	Config:   cli.StringConfig{TrimSpace: true},
 	Validator: func(ip string) error {
 		if ip == "" {
@@ -36,7 +40,6 @@ var ListenPortFlag = cli.UintFlag{
 	Value:    8080, // default port number
 	Sources:  cli.EnvVars("LISTEN_PORT"),
 	OnlyOnce: true,
-	Required: true,
 	Validator: func(port uint64) error {
 		if port == 0 || port > 65535 {
 			return fmt.Errorf("wrong TCP port number [%d]", port)
@@ -45,3 +48,48 @@ var ListenPortFlag = cli.UintFlag{
 		return nil
 	},
 }
+
+var AddTemplateFlag = cli.StringSliceFlag{
+	Name: "add-template",
+	Usage: "to add a new template, provide the path to the file using this flag (the filename without the extension " +
+		"will be used as the template name)",
+	Config: cli.StringConfig{TrimSpace: true},
+	Validator: func(paths []string) error {
+		for _, path := range paths {
+			if path == "" {
+				return fmt.Errorf("missing template path")
+			}
+
+			if stat, err := os.Stat(path); err != nil || stat.IsDir() {
+				return fmt.Errorf("wrong template path [%s]", path)
+			}
+		}
+
+		return nil
+	},
+}
+
+var AddHTTPCodeFlag = cli.StringMapFlag{
+	Name: "add-http-code",
+	Usage: "to add a new HTTP status code, provide the code and its message/description using this flag (the format " +
+		"should be '%code%=%message%/%description%'; the code may contain a wildcard '*' to cover multiple codes at once, " +
+		"for example, '4**' will cover all 4xx codes, unless a more specific code was described previously)",
+	Config: cli.StringConfig{TrimSpace: true},
+	Validator: func(codes map[string]string) error {
+		for code, msgAndDesc := range codes {
+			if code == "" {
+				return fmt.Errorf("missing HTTP code")
+			} else if len(code) != 3 {
+				return fmt.Errorf("wrong HTTP code [%s]: it should be 3 characters long", code)
+			}
+
+			if parts := strings.SplitN(msgAndDesc, "/", 3); len(parts) < 1 || len(parts) > 2 {
+				return fmt.Errorf("wrong message/description format for HTTP code [%s]: %s", code, msgAndDesc)
+			} else if parts[0] == "" {
+				return fmt.Errorf("missing message for HTTP code [%s]", code)
+			}
+		}
+
+		return nil
+	},
+}

internal/cli/shared/flags_test.go

@@ -83,3 +83,83 @@ func TestListenPortFlag(t *testing.T) {
 		})
 	}
 }
+
+func TestAddTemplateFlag(t *testing.T) {
+	t.Parallel()
+
+	var flag = shared.AddTemplateFlag
+
+	assert.Equal(t, "add-template", flag.Name)
+
+	for wantErrMsg, giveValue := range map[string][]string{
+		"missing template path":     {""},
+		"wrong template path [.]":   {".", "./"},
+		"wrong template path [..]":  {"..", "../"},
+		"wrong template path [foo]": {"foo"},
+		"":                          {"./flags.go"},
+	} {
+		t.Run(fmt.Sprintf("%s: %s", giveValue, wantErrMsg), func(t *testing.T) {
+			if err := flag.Validator(giveValue); wantErrMsg != "" {
+				assert.ErrorContains(t, err, wantErrMsg)
+			} else {
+				assert.NoError(t, err)
+			}
+		})
+	}
+}
+
+func TestAddHTTPCodeFlag(t *testing.T) {
+	t.Parallel()
+
+	var flag = shared.AddHTTPCodeFlag
+
+	assert.Equal(t, "add-http-code", flag.Name)
+
+	for name, _tt := range map[string]struct {
+		giveValue  map[string]string
+		wantErrMsg string
+	}{
+		"common": {
+			giveValue: map[string]string{
+				"200": "foo/bar",
+				"404": "foo",
+				"2**": "baz",
+			},
+		},
+
+		"missing HTTP code": {
+			giveValue:  map[string]string{"": "foo/bar"},
+			wantErrMsg: "missing HTTP code",
+		},
+		"wrong HTTP code [6]": {
+			giveValue:  map[string]string{"6": "foo"},
+			wantErrMsg: "wrong HTTP code [6]: it should be 3 characters long",
+		},
+		"wrong HTTP code [66]": {
+			giveValue:  map[string]string{"66": "foo"},
+			wantErrMsg: "wrong HTTP code [66]: it should be 3 characters long",
+		},
+		"wrong HTTP code [1000]": {
+			giveValue:  map[string]string{"1000": "foo"},
+			wantErrMsg: "wrong HTTP code [1000]: it should be 3 characters long",
+		},
+		"missing message and description": {
+			giveValue:  map[string]string{"200": "//"},
+			wantErrMsg: "wrong message/description format for HTTP code [200]: //",
+		},
+		"missing message": {
+			giveValue:  map[string]string{"200": "/bar"},
+			wantErrMsg: "missing message for HTTP code [200]",
+		},
+	} {
+		var tt = _tt
+
+		t.Run(name, func(t *testing.T) {
+			if err := flag.Validator(tt.giveValue); tt.wantErrMsg != "" {
+				assert.ErrorContains(t, err, tt.wantErrMsg)
+			} else {
+				assert.NoError(t, err)
+			}
+		})
+	}
+}

internal/config/codes.go

@@ -0,0 +1,124 @@
+package config
+
+import (
+	"slices"
+	"strconv"
+)
+
+type (
+	CodeDescription struct {
+		// Message is a short description of the HTTP error.
+		Message string
+
+		// Description is a longer description of the HTTP error.
+		Description string
+	}
+
+	// Codes is a map of HTTP codes to their descriptions.
+	//
+	// The codes may be written in a non-strict manner. For example, they may be "4xx", "4XX", or "4**".
+	// If the map contains both "404" and "4xx" keys, and we search for "404", the "404" key will be returned.
+	// However, if we search for "405", "400", or any non-existing code that starts with "4" and its length is 3,
+	// the value under the key "4xx" will be retrieved.
+	//
+	// The length of the code (in string format) is matter.
+	Codes map[string]CodeDescription // map[http_code]description
+)
+
+// Find searches the closest match for the given HTTP code, written in a non-strict manner. Read [Codes] for more
+// information.
+func (c Codes) Find(httpCode uint16) (CodeDescription, bool) { //nolint:funlen,gocyclo
+	if len(c) == 0 { // empty map, fast return
+		return CodeDescription{}, false
+	}
+
+	var code = strconv.FormatUint(uint64(httpCode), 10)
+
+	if desc, ok := c[code]; ok { // search for the exact match
+		return desc, true
+	}
+
+	var (
+		keysMap   = make(map[string][]rune, len(c))
+		codeRunes = []rune(code)
+	)
+
+	for key := range c { // take only the keys that are the same length and start with the same character or a wildcard
+		if kr := []rune(key); len(kr) > 0 && len(kr) == len(codeRunes) && isWildcardOr(kr[0], codeRunes[0]) {
+			keysMap[key] = kr
+		}
+	}
+
+	if len(keysMap) == 0 { // no matches found using the first rune comparison
+		return CodeDescription{}, false
+	}
+
+	var matchedMap = make(map[string]uint16, len(keysMap)) // map[mapKey]wildcardMatchedCount
+
+	for mapKey, keyRunes := range keysMap { // search for the closest match
+		var wildcardMatchedCount uint16 = 0
+
+		for i := 0; i < len(codeRunes); i++ { // loop through each httpCode rune
+			var keyRune, codeRune = keyRunes[i], codeRunes[i]
+
+			if wm := isWildcard(keyRune); wm || keyRune == codeRune {
+				if wm {
+					wildcardMatchedCount++
+				}
+
+				if i == len(codeRunes)-1 { // is the last rune?
+					matchedMap[mapKey] = wildcardMatchedCount
+				}
+
+				continue
+			}
+
+			break
+		}
+	}
+
+	if len(matchedMap) == 0 { // no matches found
+		return CodeDescription{}, false
+	} else if len(matchedMap) == 1 { // only one match found
+		for mapKey := range matchedMap {
+			return c[mapKey], true
+		}
+	}
+
+	// multiple matches found, find the most specific one based on the wildcard matched count (pick the one with the
+	// least wildcards)
+	var (
+		minCount uint16
+		key      string
+	)
+
+	for mapKey, count := range matchedMap {
+		if minCount == 0 || count < minCount {
+			minCount, key = count, mapKey
+		}
+	}
+
+	return c[key], true
+}
+
+func isWildcard(r rune) bool       { return r == '*' || r == 'x' || r == 'X' }
+func isWildcardOr(r, or rune) bool { return isWildcard(r) || r == or }
+
+// Codes returns all HTTP codes sorted alphabetically.
+func (c Codes) Codes() []string {
+	var codes = make([]string, 0, len(c))
+
+	for code := range c {
+		codes = append(codes, code)
+	}
+
+	slices.Sort(codes)
+
+	return codes
+}
+
+// Has checks if the HTTP code exists.
+func (c Codes) Has(code string) (found bool) { _, found = c[code]; return } //nolint:nlreturn
+
+// Get returns the HTTP code description by the specified code, if it exists.
+func (c Codes) Get(code string) (data CodeDescription, ok bool) { data, ok = c[code]; return } //nolint:nlreturn

internal/config/codes_test.go

@@ -0,0 +1,133 @@
+package config_test
+
+import (
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+
+	"gh.tarampamp.am/error-pages/internal/config"
+)
+
+func TestCodes_Common(t *testing.T) {
+	t.Parallel()
+
+	var codes = make(config.Codes)
+
+	t.Run("initial state", func(t *testing.T) {
+		require.Empty(t, codes.Codes())
+		require.Empty(t, codes.Has("404"))
+
+		var got, ok = codes.Get("404")
+
+		require.Empty(t, got)
+		require.False(t, ok)
+	})
+
+	t.Run("add a code", func(t *testing.T) {
+		codes["404"] = config.CodeDescription{Message: "Not Found"}
+
+		assert.True(t, codes.Has("404"))
+		assert.Equal(t, []string{"404"}, codes.Codes())
+
+		var got, ok = codes.Get("404")
+
+		assert.Equal(t, got.Message, "Not Found")
+		assert.True(t, ok)
+	})
+}
+
+func TestCodes_Find(t *testing.T) {
+	t.Parallel()
+
+	//nolint:typecheck
+	var common = config.Codes{
+		"101": {Message: "Upgrade"},               // 101
+		"1xx": {Message: "Informational"},         // 102-199
+		"200": {Message: "OK"},                    // 200
+		"20*": {Message: "Success"},               // 201-209
+		"2**": {Message: "Success, but..."},       // 210-299
+		"3**": {Message: "Redirection"},           // 300-399
+		"404": {Message: "Not Found"},             // 404
+		"405": {Message: "Method Not Allowed"},    // 405
+		"500": {Message: "Internal Server Error"}, // 500
+		"501": {Message: "Not Implemented"},       // 501
+		"502": {Message: "Bad Gateway"},           // 502
+		"503": {Message: "Service Unavailable"},   // 503
+		"5XX": {Message: "Server Error"},          // 504-599
+	}
+
+	var ladder = config.Codes{
+		"123": {Message: "Full triple"},
+		"***": {Message: "Triple"},
+		"12":  {Message: "Full double"},
+		"**":  {Message: "Double"},
+		"1":   {Message: "Full single"},
+		"*":   {Message: "Single"},
+	}
+
+	for name, _tt := range map[string]struct {
+		giveCodes config.Codes
+		giveCode  uint16
+
+		wantMessage  string
+		wantNotFound bool
+	}{
+		"101 - exact match":           {giveCodes: common, giveCode: 101, wantMessage: "Upgrade"},
+		"102 - multi-wildcard match":  {giveCodes: common, giveCode: 102, wantMessage: "Informational"},
+		"110 - multi-wildcard match":  {giveCodes: common, giveCode: 110, wantMessage: "Informational"},
+		"111 - multi-wildcard match":  {giveCodes: common, giveCode: 111, wantMessage: "Informational"},
+		"199 - multi-wildcard match":  {giveCodes: common, giveCode: 199, wantMessage: "Informational"},
+		"200 - exact match":           {giveCodes: common, giveCode: 200, wantMessage: "OK"},
+		"201 - single-wildcard match": {giveCodes: common, giveCode: 201, wantMessage: "Success"},
+		"209 - single-wildcard match": {giveCodes: common, giveCode: 209, wantMessage: "Success"},
+		"210 - multi-wildcard match":  {giveCodes: common, giveCode: 210, wantMessage: "Success, but..."},
+		"234 - multi-wildcard match":  {giveCodes: common, giveCode: 234, wantMessage: "Success, but..."},
+		"299 - multi-wildcard match":  {giveCodes: common, giveCode: 299, wantMessage: "Success, but..."},
+		"300 - multi-wildcard match":  {giveCodes: common, giveCode: 300, wantMessage: "Redirection"},
+		"301 - multi-wildcard match":  {giveCodes: common, giveCode: 301, wantMessage: "Redirection"},
+		"311 - multi-wildcard match":  {giveCodes: common, giveCode: 311, wantMessage: "Redirection"},
+		"399 - multi-wildcard match":  {giveCodes: common, giveCode: 399, wantMessage: "Redirection"},
+		"400 - not found":             {giveCodes: common, giveCode: 400, wantNotFound: true},
+		"403 - not found":             {giveCodes: common, giveCode: 403, wantNotFound: true},
+		"404 - exact match":           {giveCodes: common, giveCode: 404, wantMessage: "Not Found"},
+		"405 - exact match":           {giveCodes: common, giveCode: 405, wantMessage: "Method Not Allowed"},
+		"410 - not found":             {giveCodes: common, giveCode: 410, wantNotFound: true},
+		"450 - not found":             {giveCodes: common, giveCode: 450, wantNotFound: true},
+		"499 - not found":             {giveCodes: common, giveCode: 499, wantNotFound: true},
+		"500 - exact match":           {giveCodes: common, giveCode: 500, wantMessage: "Internal Server Error"},
+		"501 - exact match":           {giveCodes: common, giveCode: 501, wantMessage: "Not Implemented"},
+		"502 - exact match":           {giveCodes: common, giveCode: 502, wantMessage: "Bad Gateway"},
+		"503 - exact match":           {giveCodes: common, giveCode: 503, wantMessage: "Service Unavailable"},
+		"504 - multi-wildcard match":  {giveCodes: common, giveCode: 504, wantMessage: "Server Error"},
+		"505 - multi-wildcard match":  {giveCodes: common, giveCode: 505, wantMessage: "Server Error"},
+		"599 - multi-wildcard match":  {giveCodes: common, giveCode: 599, wantMessage: "Server Error"},
+		"600 - not found":             {giveCodes: common, giveCode: 600, wantNotFound: true},
+
+		"ladder - strict triple match": {giveCodes: ladder, giveCode: 123, wantMessage: "Full triple"},
+		"ladder - triple wildcard":     {giveCodes: ladder, giveCode: 321, wantMessage: "Triple"},
+		"ladder - strict double match": {giveCodes: ladder, giveCode: 12, wantMessage: "Full double"},
+		"ladder - double wildcard":     {giveCodes: ladder, giveCode: 21, wantMessage: "Double"},
+		"ladder - strict single match": {giveCodes: ladder, giveCode: 1, wantMessage: "Full single"},
+		"ladder - single wildcard":     {giveCodes: ladder, giveCode: 2, wantMessage: "Single"},
+
+		"empty map": {giveCodes: config.Codes{}, giveCode: 404, wantNotFound: true},
+		"zero code": {giveCodes: common, giveCode: 0, wantNotFound: true},
+	} {
+		var tt = _tt
+
+		t.Run(name, func(t *testing.T) {
+			for i := 0; i < 100; i++ { // repeat the test to ensure the function is idempotent
+				var desc, found = tt.giveCodes.Find(tt.giveCode)
+
+				if !tt.wantNotFound {
+					require.Truef(t, found, "should have found something")
+					require.Equal(t, tt.wantMessage, desc.Message)
+				} else {
+					require.Falsef(t, found, "should not have found anything, but got: %v", desc)
+					require.Empty(t, desc)
+				}
+			}
+		})
+	}
+}

internal/config/config.go

@@ -0,0 +1,101 @@
+package config
+
+import (
+	"maps"
+
+	builtinTemplates "gh.tarampamp.am/error-pages/templates"
+)
+
+type Config struct {
+	// Templates hold all templates, with the key being the template name and the value being the template content
+	// in HTML format (Go templates are supported here).
+	Templates templates
+
+	// Formats contain alternative response formats (e.g., if a client requests a response in one of these formats,
+	// we will render the response using the specified format instead of HTML; Go templates are supported).
+	Formats struct {
+		JSON string
+		XML  string
+	}
+
+	// Codes hold descriptions for HTTP codes (e.g., 404: "Not Found / The server can not find the requested page").
+	Codes Codes
+}
+
+const defaultJSONFormat string = `{
+  "error": true,
+  "Code": {{ Code | json }},
+  "message": {{ message | json }},
+  "description": {{ description | json }}{{ if show_details }},
+  "details": {
+    "host": {{ host | json }},
+    "original_uri": {{ original_uri | json }},
+    "forwarded_for": {{ forwarded_for | json }},
+    "namespace": {{ namespace | json }},
+    "ingress_name": {{ ingress_name | json }},
+    "service_name": {{ service_name | json }},
+    "service_port": {{ service_port | json }},
+    "request_id": {{ request_id | json }},
+    "timestamp": {{ now.Unix }}
+  }{{ end }}
+}`
+
+const defaultXMLFormat string = `<?xml version="1.0" encoding="utf-8"?>
+<error>
+  <Code>{{ Code }}</Code>
+  <message>{{ message }}</message>
+  <description>{{ description }}</description>{{ if show_details }}
+  <details>
+    <host>{{ host }}</host>
+    <originalURI>{{ original_uri }}</originalURI>
+    <forwardedFor>{{ forwarded_for }}</forwardedFor>
+    <namespace>{{ namespace }}</namespace>
+    <ingressName>{{ ingress_name }}</ingressName>
+    <serviceName>{{ service_name }}</serviceName>
+    <servicePort>{{ service_port }}</servicePort>
+    <requestID>{{ request_id }}</requestID>
+    <timestamp>{{ now.Unix }}</timestamp>
+  </details>{{ end }}
+</error>`
+
+//nolint:lll
+var defaultCodes = Codes{ //nolint:gochecknoglobals
+	"400": {"Bad Request", "The server did not understand the request"},
+	"401": {"Unauthorized", "The requested page needs a username and a password"},
+	"403": {"Forbidden", "Access is forbidden to the requested page"},
+	"404": {"Not Found", "The server can not find the requested page"},
+	"405": {"Method Not Allowed", "The method specified in the request is not allowed"},
+	"407": {"Proxy Authentication Required", "You must authenticate with a proxy server before this request can be served"},
+	"408": {"Request Timeout", "The request took longer than the server was prepared to wait"},
+	"409": {"Conflict", "The request could not be completed because of a conflict"},
+	"410": {"Gone", "The requested page is no longer available"},
+	"411": {"Length Required", "The \"Content-Length\" is not defined. The server will not accept the request without it"},
+	"412": {"Precondition Failed", "The pre condition given in the request evaluated to false by the server"},
+	"413": {"Payload Too Large", "The server will not accept the request, because the request entity is too large"},
+	"416": {"Requested Range Not Satisfiable", "The requested byte range is not available and is out of bounds"},
+	"418": {"I'm a teapot", "Attempt to brew coffee with a teapot is not supported"},
+	"429": {"Too Many Requests", "Too many requests in a given amount of time"},
+	"500": {"Internal Server Error", "The server met an unexpected condition"},
+	"502": {"Bad Gateway", "The server received an invalid response from the upstream server"},
+	"503": {"Service Unavailable", "The server is temporarily overloading or down"},
+	"504": {"Gateway Timeout", "The gateway has timed out"},
+	"505": {"HTTP Version Not Supported", "The server does not support the \"http protocol\" version"},
+}
+
+// New creates a new configuration with default values.
+func New() Config {
+	var cfg = Config{
+		Templates: make(templates),          // allocate memory for templates
+		Codes:     maps.Clone(defaultCodes), // copy default codes
+	}
+
+	cfg.Formats.JSON = defaultJSONFormat
+	cfg.Formats.XML = defaultXMLFormat
+
+	// add built-in templates
+	for name, content := range builtinTemplates.BuiltIn() {
+		cfg.Templates[name] = content
+	}
+
+	return cfg
+}

internal/config/config_test.go

@@ -0,0 +1,30 @@
+package config_test
+
+import (
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+
+	"gh.tarampamp.am/error-pages/internal/config"
+)
+
+func TestNew(t *testing.T) {
+	t.Parallel()
+
+	t.Run("default config", func(t *testing.T) {
+		var cfg = config.New()
+
+		assert.NotEmpty(t, cfg.Formats.XML)
+		assert.NotEmpty(t, cfg.Formats.JSON)
+		assert.True(t, len(cfg.Codes) >= 19)
+		assert.True(t, len(cfg.Templates) >= 2)
+	})
+
+	t.Run("changing cfg1 should not affect cfg2", func(t *testing.T) {
+		var cfg1, cfg2 = config.New(), config.New()
+
+		cfg1.Codes["400"] = config.CodeDescription{Message: "foo", Description: "bar"}
+
+		assert.NotEqual(t, cfg1.Codes["400"], cfg2.Codes["400"])
+	})
+}

internal/config/templates.go

@@ -0,0 +1,83 @@
+package config
+
+import (
+	"fmt"
+	"os"
+	"path/filepath"
+	"slices"
+	"strings"
+)
+
+type templates map[string]string // map[name]content
+
+// Add adds a new template.
+func (tpl templates) Add(name, content string) error {
+	if name == "" {
+		return fmt.Errorf("template name cannot be empty")
+	}
+
+	tpl[name] = content
+
+	return nil
+}
+
+// AddFromFile reads the file content and adds it as a new template.
+func (tpl templates) AddFromFile(path string, name ...string) (addedTemplateName string, _ error) {
+	// check if the file exists and is not a directory
+	if stat, err := os.Stat(path); err != nil {
+		if os.IsNotExist(err) {
+			return "", fmt.Errorf("file %s not found", path)
+		}
+
+		return "", err
+	} else if stat.IsDir() {
+		return "", fmt.Errorf("%s is not a file", path)
+	}
+
+	// read the file content
+	var content, err = os.ReadFile(path)
+	if err != nil {
+		return "", fmt.Errorf("cannot read file %s: %w", path, err)
+	}
+
+	var templateName string
+
+	if len(name) > 0 && name[0] != "" { // if the name is provided, use it
+		templateName = name[0]
+	} else { // otherwise, use the file name without the extension
+		var (
+			fileName = filepath.Base(path)
+			ext      = filepath.Ext(fileName)
+		)
+
+		if ext != "" && fileName != ext {
+			templateName = strings.TrimSuffix(fileName, ext)
+		} else {
+			templateName = fileName
+		}
+	}
+
+	// add the template to the config
+	tpl[templateName] = string(content)
+
+	return templateName, nil
+}
+
+// Names returns all template names sorted alphabetically.
+func (tpl templates) Names() []string {
+	var names = make([]string, 0, len(tpl))
+
+	for name := range tpl {
+		names = append(names, name)
+	}
+
+	slices.Sort(names)
+
+	return names
+}
+
+// Has checks if the template with the specified name exists.
+func (tpl templates) Has(name string) (found bool) { _, found = tpl[name]; return } //nolint:nlreturn
+
+// Get returns the template content by the specified name, if it exists.
+func (tpl templates) Get(name string) (data string, ok bool) { data, ok = tpl[name]; return } //nolint:nlreturn

internal/config/templates_test.go

@@ -0,0 +1,136 @@
+package config
+
+import (
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+)
+
+func TestTemplates_Common(t *testing.T) {
+	t.Parallel()
+
+	var tpl = make(templates)
+
+	t.Run("initial state", func(t *testing.T) {
+		assert.Empty(t, tpl.Names())
+		assert.False(t, tpl.Has("test"))
+
+		var got, ok = tpl.Get("test")
+
+		assert.Empty(t, got)
+		assert.False(t, ok)
+	})
+
+	t.Run("add a template from variable", func(t *testing.T) {
+		const testContent = "content"
+
+		assert.NoError(t, tpl.Add("test", testContent))
+		assert.True(t, tpl.Has("test"))
+
+		var got, ok = tpl.Get("test")
+
+		assert.Equal(t, got, testContent)
+		assert.True(t, ok)
+		assert.Equal(t, []string{"test"}, tpl.Names())
+		assert.False(t, tpl.Has("_test99"))
+
+		assert.NoError(t, tpl.Add("_test99", ""))
+		assert.NoError(t, tpl.Add("_test11", ""))
+
+		assert.Equal(t, []string{"_test11", "_test99", "test"}, tpl.Names()) // sorted
+		assert.True(t, tpl.Has("_test99"))
+	})
+
+	t.Run("adding template without a name should fail", func(t *testing.T) {
+		assert.ErrorContains(t, tpl.Add("", "content"), "template name cannot be empty")
+	})
+}
+
+func TestTemplates_AddFromFile(t *testing.T) {
+	t.Parallel()
+
+	for name, _tt := range map[string]struct {
+		givePath string
+		giveName func() []string
+
+		wantError       string
+		wantThisName    string
+		wantThisContent string
+	}{
+		"dotfile": {
+			givePath:     "./testdata/.dotfile",
+			wantThisName: ".dotfile",
+		},
+		"dotfile with extension": {
+			givePath:     "./testdata/.dotfile_with.ext",
+			wantThisName: ".dotfile_with",
+		},
+		"empty file": {
+			givePath:     "./testdata/empty.html",
+			wantThisName: "empty",
+		},
+		"file with multiple dots but without a name": {
+			givePath:     "./testdata/file.with.multiple.dots",
+			wantThisName: "file.with.multiple",
+		},
+		"name with spaces": {
+			givePath:     "./testdata/name with spaces.txt",
+			wantThisName: "name with spaces",
+		},
+		"with content and a name": {
+			givePath:        "./testdata/with-content.htm",
+			giveName:        func() []string { return []string{"test name"} },
+			wantThisName:    "test name",
+			wantThisContent: "<!DOCTYPE html><html lang=\"en\"></html>\n",
+		},
+		"with content but without a name": {
+			givePath:        "./testdata/with-content.htm",
+			wantThisName:    "with-content",
+			wantThisContent: "<!DOCTYPE html><html lang=\"en\"></html>\n",
+		},
+		"filename with no extension": {
+			givePath:     "./testdata/without_extension",
+			wantThisName: "without_extension",
+		},
+
+		"file not found": {
+			givePath:  "./testdata/not-found",
+			wantError: "file ./testdata/not-found not found",
+		},
+		"directory": {
+			givePath:  "./testdata",
+			wantError: "./testdata is not a file",
+		},
+	} {
+		var tt = _tt
+
+		t.Run(name, func(t *testing.T) {
+			t.Parallel()
+
+			var (
+				tpl      = make(templates)
+				giveName []string
+			)
+
+			if tt.giveName != nil {
+				giveName = tt.giveName()
+			}
+
+			var addedName, err = tpl.AddFromFile(tt.givePath, giveName...)
+
+			if tt.wantError == "" {
+				assert.NoError(t, err)
+				assert.True(t, tpl.Has(tt.wantThisName))
+				assert.Equal(t, addedName, tt.wantThisName)
+
+				var content, _ = tpl.Get(tt.wantThisName)
+
+				assert.Equal(t, content, tt.wantThisContent)
+			} else {
+				assert.ErrorContains(t, err, tt.wantError)
+
+				assert.False(t, tpl.Has(tt.wantThisName))
+			}
+		})
+	}
+}

internal/config/testdata/with-content.htm

@@ -0,0 +1 @@
+<!DOCTYPE html><html lang="en"></html>

templates/embed.go

@@ -0,0 +1,38 @@
+package templates
+
+import (
+	"embed"
+	"io/fs"
+	"path/filepath"
+	"strings"
+)
+
+//go:embed *.html
+var content embed.FS
+
+func BuiltIn() map[string]string { // error check is covered by unit tests
+	var (
+		list, _ = fs.ReadDir(content, ".")
+		result  = make(map[string]string, len(list))
+	)
+
+	for _, file := range list {
+		if data, err := fs.ReadFile(content, file.Name()); err == nil {
+			var (
+				fileName     = filepath.Base(file.Name())
+				ext          = filepath.Ext(fileName)
+				templateName string
+			)
+
+			if ext != "" && fileName != ext {
+				templateName = strings.TrimSuffix(fileName, ext)
+			} else {
+				templateName = fileName
+			}
+
+			result[templateName] = string(data)
+		}
+	}
+
+	return result
+}

templates/embed_test.go

@@ -0,0 +1,22 @@
+package templates_test
+
+import (
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+
+	"gh.tarampamp.am/error-pages/templates"
+)
+
+func TestBuiltIn(t *testing.T) {
+	t.Parallel()
+
+	var content = templates.BuiltIn()
+
+	assert.True(t, len(content) > 0)
+
+	for name, data := range content {
+		assert.Regexp(t, `^[a-z0-9_\.-]+$`, name)
+		assert.NotEmpty(t, data)
+	}
+}

templates/template-1.html

@@ -0,0 +1,10 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <title>Template 1</title>
+</head>
+<body>
+
+</body>
+</html>

templates/template-2.html

@@ -0,0 +1,10 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <title>Template 2</title>
+</head>
+<body>
+
+</body>
+</html>