server

README

go-server

This repository implements a "monolithic generic task server", which can serve requests over HTTP and FastCGI in addition to running "tasks" in the background. Unlike many other servers, this one is composed of many "plugins" 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;
• dnsregister periodically registers the server's IP address with a DNS server;
• log which provides logging for requests and any other tasks;

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 (using a queue in between) or tightly (by calling plugin methods directly).

Requirements and Building

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

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

This places all the binaries in the build directory. The folder structure of the repository is as follows:

• cmd/server contains the command line server tool. In order to build it, run make server. This places the binary in the build folder;
• etc contains files which are used by the server, including a sample configuration file;
• pkg contains the main code for the server and plugins;
• plugin contains plugin bindings. To build the httpserver plugin for example run make plugin/httpserver. This places the plugin (with .plugin file extension) in the build folder.

Running the Server

You can run the server:

1. With a HTTP server over network: You can specify TSL key and certificate to serve requests over a secure connection;
2. With a HTTP server with FastCGI over a unix socket: You would want to do this if the server is behind a reverse proxy such as nginx.
3. In a docker container, and expose the port outside the container. The docker container targets amd64, arm64 and arm architectures on Linux.

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

Overview

The `server` package implements a generic server, which runs multiple tasks until any single task is completed.

Index

• type Event
• type EventSource
• type Plugin
• type Provider
• type Task

Types

type Event

type Event interface {
	Context() context.Context // Returns the context of the emitted event from the source
	Key() any                 // Returns the key (or "type") of the event. Returns nil if an error event
	Value() any               // Returns the value of the event. Returns an error if an error event
	Error() error             // Returns the error or nil if not an error event

	// Emit an event on a channel. If the channel is buffered, returns false if the
	// event could not be sent (buffered channel is full). Blocks if an unbuferred channel.
	// Returns false if an error occured.
	Emit(chan<- Event) bool
}

Event encapsulates a transmitted message with key, value pair. It can also encapsulate an error.

type EventSource

type EventSource interface {
	Sub() <-chan Event
	Unsub(<-chan Event)
}

EventSource is the interface for subscribing and unsubscribing from events

type Plugin

type Plugin interface {
	// Return the name of the task. This should be unique amongst all registered plugins
	Name() string

	// Return the label for the task. This should be unique amongst all plugins with the same name
	Label() string

	// Create a new task with provider of other tasks
	New(context.Context, Provider) (Task, error)
}

Plugin creates a task from a configuration

type Provider

type Provider interface {
	Task
	plugin.Log

	// Create a new task from a plugin and return it. This should only
	// be called during the initialisation phase of the provider, not once
	// the provider is running.
	New(context.Context, Plugin) (Task, error)

	// Return the task labels. Ideally these should be in the order they are created, to
	// satisfy any dependencies.
	Keys() []string

	// Return a task with name and label. Two arguments are required if the first argument is
	// the task name and the second is the task label. Returns nil if there isn't exactly one
	// task to return.
	Get(...string) Task
}

Provider runs many tasks simultaneously. It subscribes to events from the tasks and emits them on its own event channel.

type Task

type Task interface {
	EventSource

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

Task is a long-running task which can be a source of events and errors