luci

README

luci

Go module to create web services quickly and painlessly.

Using luci

Installing

go get github.com/larzconwell/luci

Example

See the example project for a simple example using all of the functionality luci provides.

Developing luci

Prerequisites

• Go 1.21
• golangci-lint 1.55

Setting up hooks

ln -s $(pwd)/.hooks/pre-commit .git/hooks/pre-commit

Testing and linting

Make targets exist for testing and linting

• make test
• make testrace
• make lint

Documentation

Index

• Variables
• func Duration(req *http.Request) time.Duration
• func ID(req *http.Request) string
• func Logger(req *http.Request) *slog.Logger
• func Var(req *http.Request, key string) string
• func Vars(req *http.Request) map[string]string
• type Application
• type Config
• type ErrorHandlerFunc
• type Middleware
  • func WithValue(key, value any) Middleware
• type Middlewares
  • func (middlewares Middlewares) Handler(next http.Handler) http.Handler
  • func (middlewares Middlewares) HandlerFunc(next http.HandlerFunc) http.Handler
• type Route
  • func RequestRoute(req *http.Request) Route
  • func (route Route) Path(vals ...string) (string, error)
  • func (route Route) String() string
• type Server
  • func NewServer(config Config, app Application) *Server
  • func (server *Server) Address() string
  • func (server *Server) ListenAndServe(ctx context.Context) error
  • func (server *Server) Route(name string) (Route, bool)

Variables

var (
	// ErrMethodNotAllowed is used for requests with a method that's not allowed by a route.
	ErrMethodNotAllowed = errors.New("luci: method not allowed")
	// ErrNotFound is used for requests with a path that doesn't match any routes.
	ErrNotFound = errors.New("luci: not found")
	// ErrForcedShutdown is used when server shutdown takes longer than the configured timeout.
	ErrForcedShutdown = errors.New("luci: forced server shutdown")
)

var (
	// DefaultConfig is the base configuration that's used when creating a server.
	DefaultConfig = Config{
		Address:           ":http",
		RouteTimeout:      time.Second,
		ReadHeaderTimeout: time.Second,
		ShutdownTimeout:   5 * time.Second,
		Logger:            slog.Default(),
	}
)

Functions

func Duration

func Duration(req *http.Request) time.Duration

Duration returns the duration of the request from the time it was started to the time Duration was called.

func ID

func ID(req *http.Request) string

ID returns the unique identifier associated with the request.

func Logger

func Logger(req *http.Request) *slog.Logger

Logger returns the logger associated with the request.

func Var

func Var(req *http.Request, key string) string

Var returns the request variable with the given key that is defined by the associated routes pattern.

func Vars

func Vars(req *http.Request) map[string]string

Vars returns the request variables that are defined by the associated routes pattern.

Types

type Application

type Application interface {
	// Routes defines the routes an application supports.
	Routes() []Route
	// Middlewares defines the middlewares to run before any route specific middlewares.
	Middlewares() Middlewares
	// Error defines how the application responds to errors when handling a request.
	Error(http.ResponseWriter, *http.Request, int, error)
	// Respond defines how the application reponds to requests that are successful.
	Respond(http.ResponseWriter, *http.Request, any)
}

Application is used to define a server application and it's request/response behavior.

type Config

type Config struct {
	// Address defines the address to listen on.
	Address string
	// RouteTimeout defines the default timeout duration for defined routes.
	RouteTimeout time.Duration
	// ReadHeaderTimeout defines the timeout to read request headers.
	// See net/http.Server.ReadHeaderTimeout for details.
	ReadHeaderTimeout time.Duration
	// ShutdownTimeout defines the timeout for the server to gracefully
	// shutdown on context cancellation.
	ShutdownTimeout time.Duration
	// Logger defines the logger the server uses when logging startup/shutdown/requests.
	Logger *slog.Logger
}

Config defines how a server should behave when it's running. See DefaultConfig for configuration defaults.

type ErrorHandlerFunc

type ErrorHandlerFunc func(http.ResponseWriter, *http.Request, int, error)

ErrorHandlerFunc is used to define functions that handle error specific responses.

type Middleware

type Middleware func(http.Handler) http.Handler

Middleware defines functionality that runs before an endpoint handler.

func WithValue

func WithValue(key, value any) Middleware

WithValue is a middleware that adds the key/value to the request context.

type Middlewares

type Middlewares []Middleware

Middlewares defines a list of ordered middleware to run before an endpoint handler.

func (Middlewares) Handler

func (middlewares Middlewares) Handler(next http.Handler) http.Handler

Handler creates a handler that runs the middlewares in the defined order and then calls the given handler.

func (Middlewares) HandlerFunc

func (middlewares Middlewares) HandlerFunc(next http.HandlerFunc) http.Handler

Handler creates a handler that runs the middlewares in the defined order and then calls the given handler function.

type Route

type Route struct {
	// Name is used to uniquely identify a route by name.
	Name string
	// Timeout defines the timeout for a request to a route.
	// Once the timeout has been reached a timeout response is
	// sent and the request context is cancelled. If Timeout is
	// not set the default RouteTimeout will be used instead.
	Timeout time.Duration
	// Method may be optionally used to specify the method a route supports.
	// If not set the route will be used for all methods.
	Method string
	// Defines the pattern that the route should match on.
	// Refer to github.com/go-chi/chi/v5 for details on defining patterns.
	Pattern string
	// Middlewares define the route specific middlewares to run after the application middlewares.
	Middlewares Middlewares
	// HandlerFunc defines the handler function to call to handle the request.
	HandlerFunc http.HandlerFunc
}

Route defines an endpoint an application supports.

func RequestRoute

func RequestRoute(req *http.Request) Route

RequestRoute retrieves the route that's associated with the given request.

func (Route) Path

func (route Route) Path(vals ...string) (string, error)

Path builds an absolute path from the routes pattern using the given variable values. Variable values must be in the order defined by the routes pattern, and are validated against the associated regex matcher if one exists.

func (Route) String

func (route Route) String() string

String returns the routes name, method, and pattern.

type Server

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

Server maintains the running state of an application.

func NewServer

func NewServer(config Config, app Application) *Server

NewServer creates a server for the given application using the given configuration. NewServer panics if any route does not have a name, the name is not unique, or if the route doesn't have a handler defined.

func (*Server) Address

func (server *Server) Address() string

Address can be used to retrieve the address the server is listening on. Address blocks until the server has begun listening on the address.

func (*Server) ListenAndServe

func (server *Server) ListenAndServe(ctx context.Context) error

ListenAndServe listens on the configured address and serves requests until the given context has been cancelled. ListenAndServe will gracefully shutdown on context cancellation up until the configured shutdown timeout has been reached, if the shutdown timeout is reached ErrForcedShutdown is returned.

func (*Server) Route

func (server *Server) Route(name string) (Route, bool)

Route retrieves a defined route by name, and whether a route was found with the given name.