appext

Documentation

Overview

Package appext contains functionality to work with flags.

Index

• func Listen(ctx context.Context, container NameContainer, defaultPort uint16) (net.Listener, error)
• func ReadConfig(container NameContainer, value interface{}) error
• func ReadSecret(container NameContainer, name string) (string, error)
• func WriteConfig(container NameContainer, value interface{}) error
• type Builder
  • func NewBuilder(appName string, options ...BuilderOption) Builder
• type BuilderOption
  • func BuilderWithInterceptor(interceptor Interceptor) BuilderOption
  • func BuilderWithLoggerProvider(loggerProvider LoggerProvider) BuilderOption
  • func BuilderWithTimeout(defaultTimeout time.Duration) BuilderOption
• type Container
  • func NewContainer(nameContainer NameContainer, logger *slog.Logger) Container
• type Interceptor
• type LogFormat
  • func ParseLogFormat(logFormatString string) (LogFormat, error)
  • func (l LogFormat) String() string
• type LogLevel
  • func ParseLogLevel(logLevelString string) (LogLevel, error)
  • func (l LogLevel) SlogLevel() slog.Level
  • func (l LogLevel) String() string
• type LoggerContainer
  • func NewLoggerContainer(logger *slog.Logger) LoggerContainer
• type LoggerProvider
• type NameContainer
  • func NewNameContainer(baseContainer app.Container, appName string) (NameContainer, error)
• type SubCommandBuilder

Functions

func Listen

func Listen(ctx context.Context, container NameContainer, defaultPort uint16) (net.Listener, error)

Listen listens on the container's port, falling back to defaultPort.

func ReadConfig

func ReadConfig(container NameContainer, value interface{}) error

ReadConfig reads the configuration from the YAML configuration file config.yaml in the configuration directory.

If the file does not exist, this is a no-op. The value should be a pointer to unmarshal into.

func ReadSecret

func ReadSecret(container NameContainer, name string) (string, error)

ReadSecret returns the contents of the file at path filepath.Join(container.ConfigDirPath(), secretRelDirPath, name).

func WriteConfig

func WriteConfig(container NameContainer, value interface{}) error

WriteConfig writes the configuration to the YAML configuration file config.yaml in the configuration directory.

The directory is created if it does not exist. The value should be a pointer to marshal.

Types

type Builder

type Builder interface {
	BindRoot(flagSet *pflag.FlagSet)
	SubCommandBuilder
}

Builder builds run functions for both top-level commands and sub-commands.

func NewBuilder

func NewBuilder(appName string, options ...BuilderOption) Builder

NewBuilder returns a new Builder.

type BuilderOption

type BuilderOption func(*builder)

BuilderOption is an option for a new Builder

func BuilderWithInterceptor

func BuilderWithInterceptor(interceptor Interceptor) BuilderOption

BuilderWithInterceptor adds the given interceptor for all run functions.

func BuilderWithLoggerProvider

func BuilderWithLoggerProvider(loggerProvider LoggerProvider) BuilderOption

BuilderWithLoggerProvider overrides the default LoggerProvider.

The default is to use slogbuild.

func BuilderWithTimeout

func BuilderWithTimeout(defaultTimeout time.Duration) BuilderOption

BuilderWithTimeout returns a new BuilderOption that adds a timeout flag and the default timeout.

type Container

type Container interface {
	NameContainer
	LoggerContainer
}

Container contains not just the base app container, but all extended containers.

func NewContainer

func NewContainer(
	nameContainer NameContainer,
	logger *slog.Logger,
) Container

NewContainer returns a new Container.

type Interceptor

type Interceptor func(func(context.Context, Container) error) func(context.Context, Container) error

Interceptor intercepts and adapts the request or response of run functions.

type LogFormat

type LogFormat int

LogFormat is a format to print logs in.

const (
	// LogFormatText is the text log format.
	LogFormatText LogFormat = iota + 1
	// LogFormatColor is the colored text log format.
	//
	// This is the default value when parsing LogFormats. However, unless BuilderWithLoggerProvider
	// is used, there is no difference between LogFormatText and LogFormatColor.
	LogFormatColor
	// LogFormatJSON is the JSON log format.
	LogFormatJSON
)

func ParseLogFormat

func ParseLogFormat(logFormatString string) (LogFormat, error)

ParseLogFormat parses the log format for the string.

If logFormatString is empty, this returns LogFormatColor.

func (LogFormat) String

func (l LogFormat) String() string

String implements fmt.Stringer

type LogLevel

type LogLevel int

LogLevel is a level to print logs in.

const (
	// LogLevelDebug is the debug log level.
	LogLevelDebug LogLevel = iota + 1
	// LogLevelInfo is the infolog level.
	LogLevelInfo
	// LogLevelWarn is the warn log level.
	LogLevelWarn
	// LogLevelError is the error log level.
	LogLevelError
)

func ParseLogLevel

func ParseLogLevel(logLevelString string) (LogLevel, error)

ParseLogLevel parses the log level for the string.

If logLevelString is empty, this returns LogLevelInfo.

func (LogLevel) SlogLevel

func (l LogLevel) SlogLevel() slog.Level

SlogLevel returns the corresponding slog.Level.

If l is known, this return the corresponding value. If l < LogLevelDebug, this returns slog.LevelDebug. If l > LogLevelError, this returns slog.LevelError. Otherwise, this returns slog.LevelInfo.

func (LogLevel) String

func (l LogLevel) String() string

String implements fmt.Stringer

type LoggerContainer

type LoggerContainer interface {
	Logger() *slog.Logger
}

LoggerContainer provides a *slog.Logger.

func NewLoggerContainer

func NewLoggerContainer(logger *slog.Logger) LoggerContainer

NewLoggerContainer returns a new LoggerContainer.

type LoggerProvider

type LoggerProvider func(NameContainer, LogLevel, LogFormat) (*slog.Logger, error)

LoggerProvider provides new Loggers.

type NameContainer

type NameContainer interface {
	app.Container

	// AppName is the application name.
	//
	// The name must be in [a-zA-Z0-9-_].
	AppName() string
	// ConfigDirPath is the config directory path for the named application.
	//
	// First checks for $APP_NAME_CONFIG_DIR.
	// If this is not set, uses app.ConfigDirPath()/app-name.
	// Unnormalized.
	ConfigDirPath() string
	// CacheDirPath is the cache directory path for the named application.
	//
	// First checks for $APP_NAME_CACHE_DIR.
	// If this is not set, uses app.CacheDirPath()/app-name.
	// Unnormalized.
	CacheDirPath() string
	// DataDirPath is the data directory path for the named application.
	//
	// First checks for $APP_NAME_DATA_DIR.
	// If this is not set, uses app.DataDirPath()/app-name.
	// Unnormalized.
	DataDirPath() string
	// Port is the port to use for serving.
	//
	// First checks for $APP_NAME_PORT.
	// If this is not set, checks for $PORT.
	// If this is not set, returns 0, which means no port is known.
	// Returns error on parse.
	Port() (uint16, error)
}

NameContainer is a container for named applications.

Application name foo-bar translates to environment variable prefix FOO_BAR_, which is used for the various functions that NameContainer provides.

func NewNameContainer

func NewNameContainer(baseContainer app.Container, appName string) (NameContainer, error)

NewNameContainer returns a new NameContainer.

The name must be in [a-zA-Z0-9-_].

type SubCommandBuilder

type SubCommandBuilder interface {
	NewRunFunc(func(context.Context, Container) error) func(context.Context, app.Container) error
}

SubCommandBuilder builds run functions for sub-commands.