server

Expresso Server Configuration System Overview

This document explains how the configuration system works for the Expresso server. It follows a flexible pattern that allows easy extension when adding new features.

Core Configuration Structure

The core configuration lives in internal/server/config.go as a struct:

type Config struct {
    host, port          string
    developmentMode     bool
    siweStatement       string
    siweMaxValidity     time.Duration
    // more ...
}

Configuration System Components

1. Factory Pattern with ConfigOptions

NewConfig() creates a config instance using:

• Base host/port parameters
• A list of ConfigOption functions that modify the config

Example:

config, err := NewConfig("localhost", 8080,
    WithDevelopmentMode(),
    WithSignInWithEthereum("statement", 15*time.Minute))

2. CLI Integration

internal/server/cli.go defines command-line flags that map to config options:

// Flags
HostFlag             // -> NewConfig host parameter
PortFlag             // -> NewConfig port parameter
DevelopmentModeFlag  // -> WithDevelopmentMode()
SignInWithEthereum...// -> WithSignInWithEthereum()

3. Configuration Usage

Config is passed to components that need it:

• server.Run() uses config for server settings
• auth.Register() uses config via the AuthConfig interface
• Features access config values through getters

Adding New Configuration Options

To add a new configuration option (e.g., key):

Step 1: Update Config Struct

// internal/server/config.go
type Config struct {
    ...
    key string
}

Step 2: Create ConfigOption Function and Getter

// internal/server/config.go
func WithKey(key string) ConfigOption {
    return func(c *Config) error {
        c.key = key
        return nil
    }
}

func (c Config) GetKey() string {
    return c.key
}

Step 3: Add CLI Flag Support

// internal/server/cli.go
KeyFlag = &cli.StringFlag{
    Name:  "key",
    Usage: "set custom key value for feature X",
}

Step 4: Use in Command Handling

Note: Validation of value should be done inside of the ConfigOption not when processing the CLI values. CLI processing should be used for making sure mutual exclusion occurs, or other CLI related features.

// internal/server/cli.go
options = append(options, WithKey(cmd.String("key")))

Step 5: Use the Config Value

In your feature code:

// internal/myNewFeature/feature.go
package feature

type MyNewFeatureConfig interface {
    GetKey() string
}

func MyFunction(config *MyNewFeatureConfig) {
    // example in a middleware or handler
    configKey := config.GetKey()
}

// internal/server/server.go

import "github.com/edablez/go-expresso/internal/myNewFeature"

func Run(config *Config) error {
    // code above...

    // your code here
    // the config struct will adhere since you added the Getter required in config.go
    myNewFeature.MyFunction(config)

    // code below...
}

## Configuration Flow

1. CLI flags are parsed into command-line values
2. Values are converted to ConfigOption functions
3. `NewConfig()` builds the config struct
4. Config is passed to components that need it
5. Features access config values through getters

## Best Practices

- Use `ConfigOption` functions for validation
- Keep config struct fields lowercase (private)
- Add getters for external access
- Document all options in the CLI help text

The system is designed to be extensible while maintaining strong validation and clear separation between configuration creation, command-line parsing, and feature implementation.