hop

README

Hop - Experimental

hop is a light-weight web toolkit for Go that emphasizes simplicity and ease of use. It's my personal collection of HTTP helpers and middleware that I've found useful in my projects. It helps me build web applications without the complexity of larger frameworks, while attempting to stay close to the standard library.

Why the name hop? Because it’s a small, light-weight toolkit that helps me "hop" into web development quickly!

Goals

This is primarily a personal toolkit that works well for my needs - it may or may not be your cup of tea. The goals of the project are:

• Stay close to Go's standard library
• Keep dependencies minimal
• Use simple, predictable patterns
• Have just enough structure to get going quickly
• Be flexible and extensible

Sub-packages

• chain - Middleware routines that mostly use the standard library.
• conf - A simple configuration manager that uses the standard library's encoding/json package, env variables, and flags.
• decode - A collection of decoding functions for various data types and formats (e.g. forms, json, etc).
• log - A wrapper to set up a logger using the standard library's slog package.
• render - A simple view manager for rendering HTML templates. It uses the html/template package from the standard library.
• serve - A simple HTTP server with basic routing and middleware support.
• sess - Session management interfaces, helpers, and middleware.
• wrap - A collection of validation functions for various data types.

Brainstorming future sub-packages

• auth - Authentication and authorization middleware.
• cache - Caching/temporary storage middleware, helpers, and persistent key-value storage.
• keep - A collection of helpers for keeping track of state and data across requests.
• mail - Email sending and receiving helpers.
• query - Database operations and helpers.
• save - File upload and storage helpers.

TODO

• Add more useful tests

Documentation

Index

• type App
  • func New(cfg AppConfig) (*App, error)
  • func (a *App) AddChainedRoute(pattern string, handler http.Handler, chain route.Chain)
  • func (a *App) AddChainedRoutes(routes map[string]http.Handler, chain route.Chain)
  • func (a *App) AddRoute(pattern string, handler http.Handler, middleware ...route.Middleware)
  • func (a *App) AddRoutes(routes map[string]http.Handler, middleware ...route.Middleware)
  • func (a *App) Config() *conf.HopConfig
  • func (a *App) Dispatcher() *dispatch.Dispatcher
  • func (a *App) Error() error
  • func (a *App) GetModule(id string) (Module, error)
  • func (a *App) Logger() *slog.Logger
  • func (a *App) NewResponse(r *http.Request) (*render.Response, error)
  • func (a *App) NewTemplateData(r *http.Request) map[string]any
  • func (a *App) OnShutdown(fn func(context.Context) error)
  • func (a *App) OnTemplateData(fn OnTemplateDataFunc)
  • func (a *App) RegisterModule(m Module) *App
  • func (a *App) Router() *route.Mux
  • func (a *App) RunInBackground(r *http.Request, fn func() error)
  • func (a *App) Session() *scs.SessionManager
  • func (a *App) ShutdownServer(ctx context.Context) error
  • func (a *App) Start(ctx context.Context) error
  • func (a *App) StartModules(ctx context.Context) error
  • func (a *App) Stop(ctx context.Context) error
  • func (a *App) TM() *render.TemplateManager
• type AppConfig
• type ConfigurableModule
• type DispatcherModule
• type HTTPModule
• type Module
• type OnTemplateDataFunc
• type ShutdownModule
• type StartupModule
• type TemplateDataModule

Types

type App

type App struct {
	// contains filtered or unexported fields
}

App holds core components that most services need

func New

func New(cfg AppConfig) (*App, error)

New creates a new application with core components

func (*App) AddChainedRoute

func (a *App) AddChainedRoute(pattern string, handler http.Handler, chain route.Chain)

AddChainedRoute adds a new route to the server with a chain of middleware It takes a pattern, an http.Handler, and a route.Chain struct

func (*App) AddChainedRoutes

func (a *App) AddChainedRoutes(routes map[string]http.Handler, chain route.Chain)

AddChainedRoutes adds multiple routes to the server with a chain of middleware

func (*App) AddRoute

func (a *App) AddRoute(pattern string, handler http.Handler, middleware ...route.Middleware)

AddRoute adds a new route to the server, using the newer v1.22 http.Handler interface. It takes a pattern, an http.Handler, and an optional list of middleware.

func (*App) AddRoutes

func (a *App) AddRoutes(routes map[string]http.Handler, middleware ...route.Middleware)

AddRoutes adds multiple routes to the server. It takes a map of patterns to http.Handlers and an optional list of middleware.

func (*App) Config

func (a *App) Config() *conf.HopConfig

Config returns the configuration for the app

func (*App) Dispatcher

func (a *App) Dispatcher() *dispatch.Dispatcher

Dispatcher returns the event bus for the app

func (*App) Error

func (a *App) Error() error

Error returns the first error that occurred during initialization

func (*App) GetModule

func (a *App) GetModule(id string) (Module, error)

GetModule returns a module by ID

func (*App) Logger

func (a *App) Logger() *slog.Logger

Logger returns the logger instance for the app

func (*App) NewResponse

func (a *App) NewResponse(r *http.Request) (*render.Response, error)

NewResponse creates a new Response instance with the TemplateManager.

func (*App) NewTemplateData

func (a *App) NewTemplateData(r *http.Request) map[string]any

NewTemplateData returns a map of data that can be used in a Go template, API response, etc. It includes the current user, environment, version, and other useful information.

func (*App) OnShutdown

func (a *App) OnShutdown(fn func(context.Context) error)

OnShutdown registers a function to be called when the app is shutting down

func (*App) OnTemplateData

func (a *App) OnTemplateData(fn OnTemplateDataFunc)

OnTemplateData registers a function that populates template data each time a template is rendered.

func (*App) RegisterModule

func (a *App) RegisterModule(m Module) *App

RegisterModule adds a module to the app

func (*App) Router

func (a *App) Router() *route.Mux

Router returns the router instance for the app

func (*App) RunInBackground

func (a *App) RunInBackground(r *http.Request, fn func() error)

RunInBackground runs a function in the background via the server

func (*App) Session

func (a *App) Session() *scs.SessionManager

Session returns the session manager instance for the app

func (*App) ShutdownServer

func (a *App) ShutdownServer(ctx context.Context) error

ShutdownServer gracefully shuts down the server

func (*App) Start

func (a *App) Start(ctx context.Context) error

Start initializes the app and starts all modules and the server

func (*App) StartModules

func (a *App) StartModules(ctx context.Context) error

StartModules initializes and starts all modules without starting the server

func (*App) Stop

func (a *App) Stop(ctx context.Context) error

Stop gracefully shuts down the app and all modules. This is only called when the server is shutting down.

func (*App) TM

func (a *App) TM() *render.TemplateManager

TM returns the template manager instance for the app

type AppConfig

type AppConfig struct {
	Config          *conf.HopConfig
	Logger          *slog.Logger
	TemplateSources render.Sources
	TemplateFuncs   template.FuncMap
	TemplateExt     string
	SessionStore    scs.Store
	Stdout          io.Writer
	Stderr          io.Writer
}

AppConfig is a configuration for the app

type ConfigurableModule

type ConfigurableModule interface {
	Module
	Configure(ctx context.Context, config any) error
}

ConfigurableModule represents a module that can be configured

type DispatcherModule

type DispatcherModule interface {
	Module
	RegisterEvents(events *dispatch.Dispatcher)
}

DispatcherModule represents a module that can handle events

type HTTPModule

type HTTPModule interface {
	Module
	RegisterRoutes(router *route.Mux)
}

HTTPModule represents a module that can add routes to the router

type Module

type Module interface {
	ID() string
	Init() error
}

Module represents a pluggable component that can be registered with the app

type OnTemplateDataFunc

type OnTemplateDataFunc func(r *http.Request, data *map[string]any)

OnTemplateDataFunc is a function type that takes an HTTP request and a pointer to a map of data. It represents a callback function that can be used to populate data for templates.

type ShutdownModule

type ShutdownModule interface {
	Module
	Stop(ctx context.Context) error
}

ShutdownModule represents a module that has a shutdown process

type StartupModule

type StartupModule interface {
	Module
	Start(ctx context.Context) error
}

StartupModule represents a module that has a startup process

type TemplateDataModule

type TemplateDataModule interface {
	Module
	OnTemplateData(r *http.Request, data *map[string]any)
}

TemplateDataModule represents a module that can add data to the template context