server

README

go-server

This is an opinionated HTTP server which is designed to be used as a base for building API and web applications. It is designed to be extensible and modular, allowing you to add new features and functionality as needed. By default the server includes the following features:

• Authentication of users using JWT tokens and API keys
• Connection to PostgreSQL databases
• Task queues for running background jobs
• Ability to manage the PostgreSQL database roles, databases, schemas and connections
• Prometheus metrics support

The idea is that you can use this server as a base for your own applications, and add your own features and functionality as needed. More documentation soon on how to do that.

Running

The binary includes both the server-side application and the client-side command-line tools. Both can be run as docker containers.

To run the latest released version as a docker container:

docker run ghcr.io/mutablelogic/go-server:latest

This will print out the help message and provide insight into running both the server application and interacting with the server through commands. To run the server, you'll need a PostgreSQL database, and you can set the environment variables PG_HOST, PG_DATABASE, PG_USER and PG_PASS.

Bootstrapping the database server and roles

More information about setting up the databses TODO

Creating a new database

Information about setting up a new database

Building

Download and build

git clone github.com/mutablelogic/go-server
cd go-server
make

The plugins and the server binary will be built in the build directory.

Build requirements

You need the following three tools installed to build the server:

• Go (1.23 or later, not required for docker builds)
• Make
• Docker
• NPM

Makefile targets

Binaries are placed in the build directory.

Target	Description
make all	Build all plugins and the server
make cmd/server	Build the server binary
make plugins	Build the server binary
make docker	Build the docker container
make docker-push	Push the docker container to remote repository, assuming logged in
make docker-version	Prints out the docker container tag
make test	Runs unit amd coverage tests
make unit-test	Runs unit tests
VERBOSE=1 make unit-test	Runs unit tests with verbose output
make coverage-test	Reports code coverage
make tidy	Runs go mod tidy
make clean	Removes binaries and distribution files

You can also affect the build by setting the following environment variables. For example,

OS=linux ARCH=amd64 make

Variable	Description
OS	The target operating system for the build
ARCH	The target architecture for the build
BUILD_DIR	The target architecture for the build
VERBOSE	Setting this flag will provide verbose output for unit tests
VERSION	Explicitly set the version
DOCKER_REPO	The docker repository to push to. Defaults to ghcr.io/mutablelogic/go-server

Documentation

Index

• type Auth
• type Cmd
• type DebugLevel
• type HTTPMiddleware
• type HTTPRouter
• type Logger
• type PG
• type PGCallback
• type PGQueue
• type Plugin
• type PluginResolverFunc
• type Provider
• type Task

Types

type Auth

type Auth interface {
	// Authenticate attempts to identify and return the user associated with
	// an incoming HTTP request, typically by inspecting headers or tokens.
	Authenticate(*http.Request) (*authschema.User, error)

	// Authorize checks if a given user has the necessary permissions (scopes)
	// to perform an action.
	Authorize(context.Context, *authschema.User, ...string) error
}

Auth defines methods for authenticating users based on HTTP requests and authorizing them based on required scopes.

type Cmd

type Cmd interface {
	// Run the command
	Run() error

	// Return the context
	Context() context.Context

	// Return the debug mode
	GetDebug() DebugLevel

	// Return the endpoint
	GetEndpoint(paths ...string) *url.URL

	// Return the HTTP client options
	GetClientOpts() []client.ClientOpt
}

Cmd represents the command line interface context

type DebugLevel

type DebugLevel uint

const (
	None DebugLevel = iota
	Debug
	Trace
)

type HTTPMiddleware

type HTTPMiddleware interface {
	// Return a http handler with middleware as the parent handler
	HandleFunc(http.HandlerFunc) http.HandlerFunc
}

type HTTPRouter

type HTTPRouter interface {
	// Return the CORS origin
	Origin() string

	// Register a function to handle a URL path
	HandleFunc(context.Context, string, http.HandlerFunc)

	// Register serving of static files from a filesystem
	HandleFS(context.Context, string, fs.FS)
}

type Logger

type Logger interface {
	HTTPMiddleware

	// Debug logs a debugging message.
	Debug(context.Context, ...any)

	// Debugf logs a formatted debugging message.
	Debugf(context.Context, string, ...any)

	// Print logs an informational message.
	Print(context.Context, ...any)

	// Printf logs a formatted informational message.
	Printf(context.Context, string, ...any)

	// With returns a new Logger that includes the given key-value pairs
	// in its structured log output.
	With(...any) Logger
}

Logger defines methods for logging messages and structured data. It can also act as HTTP middleware for request logging.

type PG

type PG interface {
	// Conn returns the underlying connection pool object.
	Conn() pg.PoolConn
}

PG provides access to a PostgreSQL connection pool.

type PGCallback

type PGCallback func(context.Context, any) error

PGCallback defines the function signature for handling tasks dequeued from a PostgreSQL-backed queue.

type PGQueue

type PGQueue interface {
	// Conn returns the underlying connection pool object.
	Conn() pg.PoolConn

	// RegisterTicker registers a periodic task (ticker) with a callback function.
	// It returns the metadata of the registered ticker.
	RegisterTicker(context.Context, pgschema.TickerMeta, PGCallback) (*pgschema.Ticker, error)

	// RegisterQueue registers a task queue with a callback function.
	// It returns the metadata of the registered queue.
	RegisterQueue(context.Context, pgschema.QueueMeta, PGCallback) (*pgschema.Queue, error)

	// CreateTask adds a new task to a specified queue with a payload and optional delay.
	// It returns the metadata of the created task.
	CreateTask(context.Context, string, any, time.Duration) (*pgschema.Task, error)

	// UnmarshalPayload unmarshals a payload into a destination object.
	UnmarshalPayload(dest any, payload any) error
}

PGQueue defines methods for interacting with a PostgreSQL-backed task queue.

type Plugin

type Plugin interface {
	// Return the unique name for the plugin
	Name() string

	// Return a description of the plugin
	Description() string

	// Create a task from a plugin
	New(context.Context) (Task, error)
}

Plugin represents a service

type PluginResolverFunc

type PluginResolverFunc func(context.Context, string, Plugin) error

Define a function for resolving plugin configuration

type Provider

type Provider interface {
	Task

	// Write out the plugin configuration to a writer
	WriteConfig(io.Writer) error

	// Load a plugin by name and label, and provide a resolver function
	Load(string, string, PluginResolverFunc) error

	// Return a task given a plugin label
	Task(context.Context, string) Task
}

Provider represents a service provider

type Task

type Task interface {
	// Run a task
	Run(context.Context) error
}

Task represents a service task