contract

Documentation

Overview

Package contract defines a set of common interfaces for all packages in this repository.

Note the purpose of this packages is to document what contract the libraries for package core should agree upon.

In general, use a centralized package for contracts is an anti-pattern in go as it prevents progressive upgrade. It is recommended to redeclare them in each individual package, unless there is a reason not to, eg. import cycle.

Package contract should be considered a closed set. Adding new interfaces to this package is strongly discouraged.

Index

• type AppName
• type Codec
• type ConfigAccessor
• type ConfigRouter
• type ConfigUnmarshaler
• type ConfigWatcher
• type Container
• type DIPopulator
• type Env
• type HttpDoer
• type Keyer
• type LevelLogger
• type Logger
• type Printer

Types

type AppName

type AppName interface {
	String() string
}

AppName is the name of the application.

type Codec

type Codec interface {
	Unmarshal(data []byte, value any) error
	Marshal(value any) ([]byte, error)
}

Codec is an interface for serialization and deserialization.

type ConfigAccessor

type ConfigAccessor interface {
	ConfigUnmarshaler
	String(string) string
	Int(string) int
	Strings(string) []string
	Bool(string) bool
	Get(string) any
	Float64(string) float64
	Duration(string) time.Duration
}

ConfigAccessor builds upon the ConfigUnmarshaler and provides a richer set of API. Note: it is recommended to inject ConfigUnmarshaler as the dependency and call config.Upgrade to get the ConfigAccessor. The interface area of ConfigUnmarshaler is much smaller and thus much easier to customize.

type ConfigRouter

type ConfigRouter interface {
	Route(path string) ConfigUnmarshaler
}

ConfigRouter enables modular configuration by giving every piece of configuration a path.

type ConfigUnmarshaler

type ConfigUnmarshaler interface {
	Unmarshal(path string, o any) error
}

ConfigUnmarshaler is a minimum config interface that can be used to retrieve configuration from external system. If the configuration is hot reloaded, ConfigUnmarshaler should fetch the latest info.

type ConfigWatcher

type ConfigWatcher interface {
	Watch(ctx context.Context, reload func() error) error
}

ConfigWatcher is an interface for hot-reload provider.

type Container

type Container interface {
	Modules() []any
}

Container holds modules.

type DIPopulator

type DIPopulator interface {
	// Populate is just another way of fetching dependencies from container. It
	// accepts a ptr to target, and populates the target from the container.
	Populate(target any) error
}

DIPopulator is an interface that models a container to which users can fetch dependencies. It is a syntax sugar to dig.Container. See dig.Container for the implementation requirement.

type Env

type Env interface {
	IsLocal() bool
	IsDevelopment() bool
	IsTesting() bool
	IsStaging() bool
	IsProduction() bool
	String() string
}

Env is the interface for environment of the application.

type HttpDoer

type HttpDoer interface {
	Do(req *http.Request) (*http.Response, error)
}

HttpDoer is the interface for a http client.

type Keyer

type Keyer interface {
	Key(delimiter string, args ...string) string
	Spread() []string
}

Keyer is an interface for key passing.

type LevelLogger

type LevelLogger interface {
	Logger
	Debug(args ...any)
	Info(args ...any)
	Warn(args ...any)
	Err(args ...any)
	Debugf(template string, args ...any)
	Infof(template string, args ...any)
	Warnf(template string, args ...any)
	Errf(template string, args ...any)
	Debugw(msg string, fields ...any)
	Infow(msg string, fields ...any)
	Warnw(msg string, fields ...any)
	Errw(msg string, fields ...any)
}

LevelLogger is plaintext logger with level.

type Logger

type Logger = log.Logger

Logger is an alias of go kit logger

type Printer

type Printer interface {
	Sprintf(msg string, val ...interface{}) string
}

A Printer models a i18n translator.