server

README

go-server

This module provides a generic server, which serves requests over HTTP and FastCGI and can also run tasks in the background. Unlike many other servers, this one is composed of many "plugins" which can be added to the server.

Standard plugins provided include:

• httpserver which provides a simple HTTP server and routing of requests to plugins;
• log which provides logging for requests and any other tasks;
• env which allows retrieval of environment variables and use in configuration files;
• basicauth provides basic authentication for requests;
• ldapauth provides LDAP authentication for requests;
• static provides static file serving;
• template provides dynamic file serving through templates.

Many of these modules also provide a REST API for accessing information and control, and there are a number of "front ends" developed for display of plugin information in a web browser.

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).

Maybe this design is a good balance between microservices and large (non-plugin) monoliths?

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;
• npm contains frontend NPM packages which can be built. To build the mdns frontend for example, run make npm/mdns. The compiled code is then in the dist folder of each NPM package. These may eventually be moved to a separate repository;
• pkg contains the main code for the server and plugins;
• plugin contains code for the plugins. To build the httpserver plugin for example run make plugin/httpserver. This places the plugin (with .plugin file extension) in the build folder.

The provider.go file contains the interfaces required if you develop plugins. More information about developing plugins is described below.

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.

It is most likely that in a production environment you would want to install the server and any plugins with some sort of packaging (RPM or DEB) or from a Docker container. More information about packaging can be found in the next section.

The -help argument provides more information on the command line options:

[bash]  /opt/go-server/bin/server -help

server: Monolith server

Usage:
  server <flags> config.yaml
  server -help
  server -help <plugin>

Flags:
  -addr string
    	Override path to unix socket or listening address

Version:
  URL: https://github.com/mutablelogic/go-server
  Version: v1.0.6
  Build Time: 2021-09-31T12:00:00Z
  Go: go1.17 (darwin/amd64)

Configuration and Packaging

Packaging for binaries is available in the pkg-server repository for download.

Whilst you can run the server without a reverse proxy, it is recommended that you use nginx or similar to serve the frontend files and communicate with the server using FastCGI with a unix socket.

Developing Plugins

TODO

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 Document
• type DocumentKey
• type DocumentSection
• type Env
• type Event
• type EventQueue
• type Logger
• type Middleware
• type Plugin
• type Provider
• type Renderer
• type Router
• type Service

Types

type Document

type Document interface {
	Title() string
	Description() string
	Shortform() template.HTML
	Tags() []string
	Meta() map[DocumentKey]interface{}
	HTML() []DocumentSection
}

Document to be rendered or indexed

type DocumentKey

type DocumentKey string

DocumentKey provides additional metadata for a document

const (
	DocumentKeyTitle       DocumentKey = "title"
	DocumentKeyDescription DocumentKey = "description"
	DocumentKeyShortform   DocumentKey = "shortform"
	DocumentKeyAuthor      DocumentKey = "author"
	DocumentKeyArtwork     DocumentKey = "artwork"
	DocumentKeyThumbnail   DocumentKey = "thumbnail"
	DocumentKeyContentType DocumentKey = "mimetype"
	DocumentKeyCharset     DocumentKey = "charset"
)

type DocumentSection

type DocumentSection interface {
	// Title for the section
	Title() string

	// Level of the section, or zero if no level defined
	Level() uint

	// Valid HTML for the section (which allows extraction into text tokens)
	HTML() template.HTML

	// Anchor name for the section, if any
	Anchor() string

	// Class name for the section, if any
	Class() string
}

DocumentSection represents document HTML, split into sections

type Env

type Env interface {
	// GetString returns a string value for key, or ErrNotFound
	GetString(string) (string, error)
}

Env interface returns an environment variable

type Event

type Event interface {
	Name() string
	Value() interface{}
}

type EventQueue

type EventQueue interface {
	Post(context.Context, Event)
	Subscribe(context.Context, chan<- Event) error
}

Queue allows posting events and subscription to events from other plugins

type Logger

type Logger interface {
	Print(context.Context, ...interface{})
	Printf(context.Context, string, ...interface{})
}

Logger providers a logging interface

type Middleware

type Middleware interface {
	// Add a child handler object which intercepts a handler
	AddMiddleware(context.Context, http.Handler) http.Handler

	// Add a child handler function which intercepts a handler function
	AddMiddlewareFunc(context.Context, http.HandlerFunc) http.HandlerFunc
}

Middleware intercepts HTTP requests

type Plugin

type Plugin interface {
	// Run plugin background tasks until cancelled
	Run(context.Context, Provider) error
}

Plugin provides handlers to server

type Provider

type Provider interface {
	Logger
	Router
	Env
	EventQueue

	// Plugins returns a list of registered plugin names
	Plugins() []string

	// GetPlugin returns a named plugin or nil if not available
	GetPlugin(context.Context, string) Plugin

	// GetConfig populates yaml config
	GetConfig(context.Context, interface{}) error
}

Provider provides services to a module

type Renderer

type Renderer interface {
	Plugin

	// Return default mimetypes and file extensions handled by this renderer
	Mimetypes() []string

	// Render a file into a document, with reader and optional file info and metadata
	Read(context.Context, io.Reader, fs.FileInfo, map[DocumentKey]interface{}) (Document, error)

	// Render a directory into a document, with optional file info and metadata
	ReadDir(context.Context, fs.ReadDirFile, fs.FileInfo, map[DocumentKey]interface{}) (Document, error)
}

Renderer translates a data stream into a document

type Router

type Router interface {
	AddHandler(context.Context, http.Handler, ...string) error
	AddHandlerFunc(context.Context, http.HandlerFunc, ...string) error
	AddHandlerFuncEx(context.Context, *regexp.Regexp, http.HandlerFunc, ...string) error
}

Router allows handlers to be added for serving URL paths

type Service

type Service interface {
	Instance() string
	Service() string
	Name() string
	Host() string
	Port() uint16
	Zone() string
	Addrs() []net.IP
	Txt() []string

	// Return TXT keys and value for a key
	Keys() []string
	ValueForKey(string) string
}