server

README

go-server

This repository implements a "monolithic generic task server", which can serve requests over HTTP and FastCGI. There is a "plugin architecture" which can be embedded within the server at compile time, or dynamically loaded as plugins at runtime.

Standard plugins provided include:

• httpserver which provides a simple HTTP server and routing of requests to plugins;
• router to route requests to different handlers;
• nginx to manage a running nginx reverse proxy instance;
• static to serve static files;
• auth to manage authentication and authorisation;
• tokenjar to manage persistence of authorisation tokens on disk;
• certmanager to manage trust and certificates.

The motivation for this module is to provide a generic server which can be developed and scaled over time. Ultimately the running process is a large "monolith" server which can be composed of many smaller "plugins", which can be connected together loosely.

Running the server

The easiest way to run an nginx reverse proxy server, with an API to manage nginx configuration, is through docker:

docker run -p 8080:80 -v /var/lib/go-server:/data ghcr.io/mutablelogic/go-server

This will start a server on port 8080 and use /var/lib/go-server for persistent data. Use API commands to manage the nginx configuration. Ultimately you'll want to develop your own plugins and can use this image as the base image for your own server.

When you first run the server, a "root" API token is created which is used to authenticate API requests. You can find this token in the log output or by running the following command:

docker exec <container-id> cat /data/tokenauth.json

Requirements and Building

Any modern go compiler should be able to build the server command, 1.21 and above. It has been tested on MacOS and Linux. To build the server and plugins, run:

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

This places all the binaries in the build directory. There are several other make targets:

• make clean to remove all build artifacts;
• make test to run all tests;
• ARCH=<arm64|amd64> OS=<linux|darwin> make to cross-compile the binary;
• DOCKER_REPOSITORY=docker.io/user make docker to build a docker image.
• DOCKER_REPOSITORY=docker.io/user make docker-push to push a docker image.

Project Status

This module is currently in development and is not yet ready for any production environment.

Community & License

File an issue or question on github.

Licensed under Apache 2.0, please read that license about using and forking. The main conditions require preservation of copyright and license notices. Contributors provide an express grant of patent rights. Licensed works, modifications, and larger works may be distributed under different terms and without source code.

Documentation

Index

• type Logger
• type Middleware
• type Plugin
• type Provider
• type Route
• type Router
• type ServiceEndpoints
• type Task

Types

type Logger

type Logger interface {
	// Print logging message
	Print(context.Context, ...any)

	// Print formatted logging message
	Printf(context.Context, string, ...any)
}

Logger interface

type Middleware

type Middleware interface {
	Task

	// Wrap a handler function
	Wrap(context.Context, http.HandlerFunc) http.HandlerFunc
}

Middleware represents an interceptor for HTTP requests

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() (Task, error)
}

Plugin represents a plugin that can create a task

type Provider

type Provider interface {
	Task
	Logger
}

Provider interface

type Route

type Route interface {
	// Label
	Label() string

	// Matched host
	Host() string

	// Matched prefix
	Prefix() string

	// Matching Path
	Path() string

	// Matched parameters
	Parameters() []string

	// Matched methods
	Methods() []string

	// Scopes for authorization
	Scopes() []string
}

Route maps a request to a route handler, with associated host, prefix and path

type Router

type Router interface {
	Task

	// Add a handler to the router, with the given path
	// and methods. The context is used to pass additional
	// parameters to the handler. If no methods are provided, then
	// all methods are allowed.
	AddHandler(context.Context, string, http.Handler, ...string) Route

	// Add a handler function to the router, with the given path
	// and methods. The context is used to pass additional
	// parameters to the handler. If no methods are provided, then
	// all methods are allowed.
	AddHandlerFunc(context.Context, string, http.HandlerFunc, ...string) Route

	// Add a handler to the router, with the given regular expression
	// path and methods. The context is used to pass additional
	// parameters to the handler. If no methods are provided, then
	// all methods are allowed.
	AddHandlerRe(context.Context, *regexp.Regexp, http.Handler, ...string) Route

	// Add a handler function to the router, with the given regular expression
	// path and methods. The context is used to pass additional
	// parameters to the handler. If no methods are provided, then
	// all methods are allowed.
	AddHandlerFuncRe(context.Context, *regexp.Regexp, http.HandlerFunc, ...string) Route
}

Router represents a router to which you can add requests

type ServiceEndpoints

type ServiceEndpoints interface {
	Task

	// Add the endpoints to the router, with the given middleware
	AddEndpoints(context.Context, Router)
}

ServiceEndpoints represents a set of http service endpoints to route requests to

type Task

type Task interface {
	// Return the label for the task
	Label() string

	// Run the task until the context is cancelled and return any errors
	Run(context.Context) error
}

Task represents a task that can be run