ranger

Documentation

Overview

Package ranger initializes and manages a trails app with sane defaults.

Ranger

The main entrypoint to package ranger is the Ranger type. A Ranger ought to be constructed with New using a Config. A Config must be set with the concrete type for the user of your application. That user must implement RangerUser

*Ranger.Guide begins a trails app's web server. By default, *Ranger.Guide listens on DefaultHost:DefaultPort (localhost:3000), assuming either a reverse proxy proxies requests or only a client application makes direct requests to the trails web server.

Upon calling *Ranger.Guide, all routes configured up to that point are now active. Stop that web server with *Ranger.Shutdown, call the context.CancelFunc returned by [*Ranger.Cancel], or send a signal *Ranger.Guide listens for.

Configuration

A developer configures a trails app through environment variables and by setting fields on Config. For environment variables, required values can be discovered by inspecting the errors New returns.

Environment variables ought to be set in a file called ".env" found at the same directory the application is executed from.

Here are the available environment variables.

• APP_DESCRIPTION: a short description of the application
• APP_TITLE: a short title for the application
• ASSETS_URL: the base URL the application serves client-side assets over
• BASE_URL: the base URL the application runs on; replaces HOST & PORT
• CONTACT_US: the email address end users can contact XYPN at; default: hello@xyplanningnetwork.com
• DATABASE_HOST: the host the database is running on; default: localhost
• DATABASE_NAME: the name of the database
• DATABASE_PORT: the port the database is listening on; default: 5432
• DATABASE_URL: the fully-qualified connection string for connecting to the database; replaces all other DATABASE_* env vars
• DATABASE_USER: the user for authenticating a connection to the database
• DATABSE_PASSWORD: the password for authenticating a connection to the database
• ENVIRONMENT: the environment the application is running in; cf. trails.Environment
• HOST: the host the application is running on; default: localhost
• LOG_LEVEL: the level at which to begin logging; default: INFO; cf. logger.LogLevel
• PORT: the port the application should listen on; default: :3000
• SERVER_IDLE_TIMEOUT: the timeout - as understood by time.ParseDuration - for idiling between requests when using keep-alives; default: 120s
• SERVER_READ_TIMEOUT: the timeout - as understood by time.ParseDuration - for reading HTTP requests; default: 5s
• SERVER_WRITE_TIMEOUT: the timeout - as understood by time.ParseDuration - for writing HTTP responses; default: 5s
• SESSION_AUTH_KEY: a hex-encoded key for authenticating cookies; cf. encoding/hex
• SESSION_ENCRYPTION_KEY: a hex-encoded key for encrypting cookies; cf. encoding/hex
• SESSION_DOMAIN: the host the application is served over for setting as the cookie's domain; default: the hostname of BASE_URL

Index

• Constants
• func MaintModeHandler(p *template.Parser, l logger.Logger, contact string) http.HandlerFunc
• func NewPostgresConfig(env trails.Environment) *postgres.CxnConfig
• type Config
  • func (c *Config[U]) UseDBMock(mockdb *postgres.MockDatabaseService)
  • func (c *Config[U]) UseLogOutput(w io.Writer)
  • func (c Config[U]) Valid() error
• type Metadata
• type Ranger
  • func BuildWorkerCore() (*Ranger, error)
  • func New[U RangerUser](cfg Config[U]) (*Ranger, error)
  • func (r *Ranger) AssetsURL() *url.URL
  • func (r *Ranger) BaseURL() *url.URL
  • func (r *Ranger) Context() (context.Context, context.CancelFunc)
  • func (r *Ranger) DB() postgres.DatabaseService
  • func (r *Ranger) Env() trails.Environment
  • func (r *Ranger) Guide() error
  • func (r *Ranger) Metadata() Metadata
  • func (r *Ranger) SessionStore() session.SessionStorer
  • func (r *Ranger) Shutdown()
• type RangerUser
• type ShutdownFn

Constants

const (
	// URL defaults
	AssetsURLEnvVar = "ASSETS_URL"
	BaseURLEnvVar   = "BASE_URL"

	// App metadata
	AppDescEnvVar   = "APP_DESCRIPTION"
	AppTitleEnvVar  = "APP_TITLE"
	ContactUsEnvVar = "CONTACT_US_EMAIL"

	// Web server defaults
	DefaultHost = "localhost"

	DefaultPort = ":3000"

	DefaultServerReadTimeout = 5 * time.Second

	DefaultServerIdleTimeout = 120 * time.Second

	DefaultServerWriteTimeout = 5 * time.Second

	// Session defaults
	SessionDomainEnvVar     = "SESSION_DOMAIN"
	SessionAuthKeyEnvVar    = "SESSION_AUTH_KEY"
	SessionEncryptKeyEnvVar = "SESSION_ENCRYPTION_KEY"
	SessionMaxAgeEnvVar     = "SESSION_MAX_AGE"
	SessionSameSiteMode     = "SESSION_SAMESITE_MODE"
)

Functions

func MaintModeHandler

func MaintModeHandler(p *template.Parser, l logger.Logger, contact string) http.HandlerFunc

func NewPostgresConfig

func NewPostgresConfig(env trails.Environment) *postgres.CxnConfig

NewPostgresConfig constructs a *postgres.CxnConfig appropriate to the given environment. Confer the DATABASE env vars for usage.

Types

type Config

type Config[U RangerUser] struct {

	// FS is the filesystem to find templates in for rendering them.
	FS fs.FS

	// MaintMode determines how to configure ranger on ranger.New.
	// If true, it skips setting up a database connection and routes to a maintenance page.
	MaintMode bool

	// Migrations are a list of DB migrations to run upon DB successful connection.
	Migrations []postgres.Migration
	// contains filtered or unexported fields
}

func (*Config[U]) UseDBMock

func (c *Config[U]) UseDBMock(mockdb *postgres.MockDatabaseService)

UseDBMock overrides a real database connection with a mocked database hooked up to ctrl.

func (*Config[U]) UseLogOutput

func (c *Config[U]) UseLogOutput(w io.Writer)

UseLogOutput overrides the writing logs to os.Stdout; use a bytes.Buffer in unit tests so log outputs can be inspected.

func (Config[U]) Valid

func (c Config[U]) Valid() error

Valid asserts the Config has all required data, returning trails.ErrBadConfig if not.

type Metadata

type Metadata struct {
	Contact string
	Desc    string
	Title   string
}

Metadata captures values set by different env vars used to customize identifying the application to end users.

Metadata provides its data through the "metadata" template function.

type Ranger

type Ranger struct {
	logger.Logger
	*resp.Responder
	router.Router
	// contains filtered or unexported fields
}

A Ranger manages and exposes all components of a trails app to one another.

func BuildWorkerCore

func BuildWorkerCore() (*Ranger, error)

BuildWorkerCore constructs a *Ranger but skips those components relating to the HTTP router.

func New

func New[U RangerUser](cfg Config[U]) (*Ranger, error)

New constructs a Ranger from the provided options. Default options are applied first followed by the options passed into New. Options supplied to New overwrite default configurations.

func (*Ranger) AssetsURL

func (r *Ranger) AssetsURL() *url.URL

func (*Ranger) BaseURL

func (r *Ranger) BaseURL() *url.URL

func (*Ranger) Context

func (r *Ranger) Context() (context.Context, context.CancelFunc)

func (*Ranger) DB

func (r *Ranger) DB() postgres.DatabaseService

func (*Ranger) Env

func (r *Ranger) Env() trails.Environment

func (*Ranger) Guide

func (r *Ranger) Guide() error

Guide begins the web server.

These, and (*Ranger).Shutdown, stop Guide:

• os.Interrupt
• syscall.SIGHUP
• syscall.SIGINT
• syscall.SIGQUIT
• syscall.SIGTERM

func (*Ranger) Metadata

func (r *Ranger) Metadata() Metadata

func (*Ranger) SessionStore

func (r *Ranger) SessionStore() session.SessionStorer

func (*Ranger) Shutdown

func (r *Ranger) Shutdown()

Shutdown shutdowns the web server and cancels the context.Context exposed by *Ranger.Context.

If you pass custom ShutdownFns using Config.Shutdowns, Shutdown calls these before closing the web server.

You may want to provide custom ShutdownFns if other services ought to be stopped before the web server stops accepts requests.

In such a case, Ranger continues to accept HTTP requests until these custom ShutdownFns finish. This state of affairs ought to be gracefully handled in your web handlers.

type RangerUser

type RangerUser interface {
	middleware.User
}

A RangerUser is the kind of functionality an application's User must fulfill in order to take advantage of trails.

NOTE(dlk): refer to this example as to why we have all the theatrics around generics: https://go.dev/play/p/IfXLlgaJUM_N

type ShutdownFn

type ShutdownFn func(context.Context) error