ranger

Documentation

Overview

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

Ranger

The main entrypoint to package ranger is the Ranger type. A Ranger ought to be constructed with NewRanger and any options required by your application. Calling NewRanger() - without any options - is valid and fully operational.

(*Ranger).Guide begins a trails app's web server. By default, (*Ranger).Guide listens on 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, the signals that method listens for, or, cancel the context.Context passed in with WithContext.

Configuration

A developer configures a trails app with default options and configurable options, of which there are too many to enumerate here. Refer to specific documentation for various functions and methods where necessary.

Some components are directly exposed by configuration functions whereas others are only indirect. This is distinct from the exported and unexported fields on a *Ranger.

Direct exposure often entails a With* function and a Default* function. Take WithLogger and DefaultLogger as examples. DefaultLogger provides a sane logger intended to cover most use cases, whereas WithLogger enables a developer to bring their own implementation of logger.Logger. Notably, though, DefaultLogger can still be configured by providing any logger.LoggerOptFn.

Indirect exposure looks like how the template.Parser only has DefaultParser available. If the template.Parser DefaultParser does not fit a use case, a resp.WithParser() functional option may be passed to resp.NewResponder or this package's DefaultParser.

Environment Variables

Constructing a new *Ranger with NewRanger reads from the OS's environment variables. With that, trails leverages a file called .env to pickup configuration. A file named .env ought to exist in the same directory as the compiled trails' app's executable. Finally, environment variables explicitly set when running the trails app executable have precedence over those read from the .env file.

Router

A Ranger uses a router.Router for serving resources for different HTTP requests. Use WithRouter to first construct a router.Router and then pass that into NewRanger. Or, more conveniently, configure the Ranger's Router after NewRanger and all the way up until calling (*Ranger).Guide. As a last resort, overwriting the Router initially configured is possible up until calling (*Ranger).Guide.

Index

• Constants
• type Config
• type OptFollowup
• type Ranger
  • func New[User RangerUser](cfg Config[U], opts ...RangerOption) (*Ranger, error)
  • func (r *Ranger) EmitDB() postgres.DatabaseService
  • func (r *Ranger) EmitKeyring() keyring.Keyringable
  • func (r *Ranger) EmitSessionStore() session.SessionStorer
  • func (r *Ranger) Guide() error
  • func (r *Ranger) Shutdown() error
• type RangerOption
  • func DefaultContext() RangerOption
  • func DefaultDB(list []postgres.Migration) RangerOption
  • func DefaultKeyring(keys ...keyring.Keyable) RangerOption
  • func DefaultLogger(opts ...logger.LoggerOptFn) RangerOption
  • func DefaultParser(files fs.FS, opts ...template.ParserOptFn) RangerOption
  • func DefaultResponder(opts ...resp.ResponderOptFn) RangerOption
  • func DefaultRouter() RangerOption
  • func DefaultSessionStore(opts ...session.ServiceOpt) RangerOption
  • func WithCancelableContext(ctx context.Context, cancel context.CancelFunc) RangerOption
  • func WithDB(db postgres.DatabaseService) RangerOption
  • func WithKeyring(k keyring.Keyringable) RangerOption
  • func WithLogger(l logger.Logger) RangerOption
  • func WithResponder(r *resp.Responder) RangerOption
  • func WithRouter(r router.Router) RangerOption
  • func WithServer(s *http.Server) RangerOption
  • func WithSessionStore(store session.SessionStorer) RangerOption
  • func WithShutdowns(shutdownFns ...ShutdownFn) RangerOption
• type RangerUser
• type ShutdownFn

Constants

const (

	// Web server defaults
	DefaultHost = "localhost"

	DefaultPort = ":3000"

	DefaultServerReadTimeout = 5 * time.Second

	DefaultServerIdleTimeout = 120 * time.Second

	DefaultServerWriteTimeout = 5 * time.Second
)

Types

type Config

type Config[U RangerUser] struct {
}

type OptFollowup

type OptFollowup func() error

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 New

func New[User RangerUser](cfg Config[U], opts ...RangerOption) (*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) EmitDB

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

func (*Ranger) EmitKeyring

func (r *Ranger) EmitKeyring() keyring.Keyringable

func (*Ranger) EmitSessionStore

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

func (*Ranger) Guide

func (r *Ranger) Guide() error

Guide begins the web server.

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

- os.Interrupt - os.Kill - syscall.SIGHUP - syscall.SIGINT - syscall.SIGQUIT - syscall.SIGTERM

func (*Ranger) Shutdown

func (r *Ranger) Shutdown() error

Shutdown shutdowns the web server.

If you pass custom ShutdownFns using WithShutdowns, 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 RangerOption

type RangerOption func(rng *Ranger) (OptFollowup, error)

A RangerOption configures a *Ranger either (1) directly, immediately upon being called or (2) in the optFollowup it returns. Some RangerOptions require data in others and thus an optFollowup can be returned in order to be called at a later time when that data is available.

WithKeyring is an example of the first. An unexported field on the passed in *Ranger is updated with the enclosed value.

WithRouter is an example of the second. An unexported field on the passed in *Ranger is updated only when the closure it returns is called.

func DefaultContext

func DefaultContext() RangerOption

DefaultContext constructs a RangerOption initiates a new, base context.Context for the trails app.

func DefaultDB

func DefaultDB(list []postgres.Migration) RangerOption

DefaultDB constructs a RangerOption that connects to a database using default configuration environment variables and runs the list of postgres.Migrations passed in.

func DefaultKeyring

func DefaultKeyring(keys ...keyring.Keyable) RangerOption

DefaultKeyring constructs a RangerOption that applies the default context keys and those keys passed in to the Ranger.

func DefaultLogger

func DefaultLogger(opts ...logger.LoggerOptFn) RangerOption

DefaultLogger constructs a RangerOption that applies the default logger (logger.DefaultLogger) to the Ranger.

func DefaultParser

func DefaultParser(files fs.FS, opts ...template.ParserOptFn) RangerOption

DefaultParser constructs a RangerOption that configures a default HTML template parser to be used when responding to HTTP requests with *resp.Responder.Html.

files can be nil, resulting in the parser using the local directory to find templates.

BASE_URL ought to be set when the default http://localhost:3000 is not wanted.

DefaultParser makes available these functions in an HTML template:

- "env" - "metadata" - "nonce" - "rootUrl" - "packTag" - "isDevelopment" - "isStaging" - "isProduction"

func DefaultResponder

func DefaultResponder(opts ...resp.ResponderOptFn) RangerOption

DefaultResponder constructs a RangerOption that returns a followup option configuring the *Ranger.Responder to be used by http.Handlers.

BASE_URL ought to be set when the default http://localhost:3000 is not wanted.

DefaultResponder delays directly configuring the *Ranger under construction in order to avail itself of data - such as template.Parser - that other RangerOptions configure.

func DefaultRouter

func DefaultRouter() RangerOption

DefaultRouter constructs a RangerOption that returns a followup option configuring the *Ranger.Router to be used by the web server.

func DefaultSessionStore

func DefaultSessionStore(opts ...session.ServiceOpt) RangerOption

DefaultSessionStore constructs a RangerOption that configures the SessionStore to be used for storing session data.

DefaultSessionStore relies on two env vars: - "SESSION_AUTH_KEY" - "SESSION_ENCRYPTION_KEY"

These must be valid hex encoded values.

If these values do not exist, DefaultSessionStore will generate new, random keys and save those to the env var file for later use.

func WithCancelableContext

func WithCancelableContext(ctx context.Context, cancel context.CancelFunc) RangerOption

WithContext exposes the provided context.Context to the trails app.

func WithDB

func WithDB(db postgres.DatabaseService) RangerOption

WithDB exposes the provided postgres.DatabaseService to the trails app.

WithDB assumes a connection has already been established.

func WithKeyring

func WithKeyring(k keyring.Keyringable) RangerOption

WithKeyring exposes the provided keyring.Keyringable to the trails app.

func WithLogger

func WithLogger(l logger.Logger) RangerOption

WithLogger exposes the provided logger.Logger to the trails app.

func WithResponder

func WithResponder(r *resp.Responder) RangerOption

WithResponder constructs a followup option that, when called, exposes the *resp.Responder to the trails app.

func WithRouter

func WithRouter(r router.Router) RangerOption

WithRouter constructs a followup option that, when called, exposes the router.Router to the trails app.

func WithServer

func WithServer(s *http.Server) RangerOption

WithServer exposes the *http.Server to the trails app.

func WithSessionStore

func WithSessionStore(store session.SessionStorer) RangerOption

WithSessionStore exposes the session.SessionStorer to the trails app.

func WithShutdowns

func WithShutdowns(shutdownFns ...ShutdownFn) RangerOption

WithShutdowns allows custom ShutdownFns to be called within Ranger.Shutdown.

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

A ShutdownFn stops running a service or closes a client connection that an application is in control of.