ranger

package
v0.10.2 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Apr 11, 2024 License: MIT Imports: 32 Imported by: 4

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
  • 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

Index

Constants

View Source 
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
	SessionAuthKeyEnvVar    = "SESSION_AUTH_KEY"
	SessionEncryptKeyEnvVar = "SESSION_ENCRYPTION_KEY"
	SessionMaxAgeEnvVar     = "SESSION_MAX_AGE"
)

Variables

This section is empty.

Functions

func MaintModeHandler added in v0.8.5 

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

func NewPostgresConfig added in v0.6.1 

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 added in v0.6.0 

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 added in v0.6.1 

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 added in v0.6.1 

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 added in v0.6.1 

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

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

type Metadata added in v0.6.1 

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 added in v0.7.0 

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 added in v0.9.4 

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

func (*Ranger) BaseURL added in v0.6.1 

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

func (*Ranger) Context added in v0.6.1 

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

func (*Ranger) DB added in v0.6.1 

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

func (*Ranger) Env added in v0.6.1 

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 added in v0.6.1 

func (r *Ranger) Metadata() Metadata

func (*Ranger) SessionStore added in v0.6.1 

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 added in v0.6.0 

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

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.