ozone

README

Version2 of ozone

Cache has been removed in order to remove dependencies for CGO and now the caching is up to the client otherwise the interface is the same.

ozone

Golang HTTP daemon engine.

Ozone is not a web framework. It's a daemon engine which will serve your http.Handler's and take care of the boilerplate to make a nice configurable well behaving daemon.

The use case for using Ozone is HTTP based micro services and infrastructure glue daemons where you know what your http.Handler should do. You just want it served with graceful zero-downtime reloads/upgrades, logging and ready made configuration integrating nicely with Linux systemd. Ozone comes with a ready made configurable and modular reverse HTTP proxy handler.

Ozone reads a JSON config file which defines HTTP servers, their listeners (any TLS configuration) and their http.Handler. Configuration is fully modular, letting you provide your own dedicated handler configuration.

Ozone can be asked to listen on a UNIX socket for commands, allowing you to control the running daemon. New commands can be implemented and registered by the application.

Ozone doesn't per default do access-logging. It can be configured to do that, but you can also just issue the "alog" command on the control socket to get access log for a specific HTTP server.

Feature list

• Modular plugable JSON configuration
• Plugable and configurable HTTP handlers
• Plugable reverse HTTP proxy
• Plugable TLS configuration
• Plugable UNIX socket control interface.
• Graceful restarts and zero-downtime upgrades
• Dump entire config, as parsed, to stdout in "dry run" mode.
• Tunable logging and statsd metrics.
• Client side failover for reverse proxy backends using "virtual upstream" pools of backend servers.

Ozone is build on the github.com/One-com/gone set of libraries which provide much of the functionality.

Example

A simple

//...declarations left out

type handlerConfig struct {
	Response string
}

func createHandler(name string, js jconf.SubConfig, handlerByName func(string) (http.Handler, error)) (h http.Handler, cleanup func() error, err error) {
	h = http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
		var cfg *handlerConfig
		err = js.ParseInto(&cfg)
		if err != nil {
			return
		}
		w.Write([]byte(cfg.Response + "\n"))
	})
	return
}

func init() {
	flag.StringVar(&configFile, "c", "options.json", "Configuration file")

	flag.BoolVar(&dryrun, "n", false, "Dryrun - Dump full config")
	flag.StringVar(&controlSocket, "s", "", "Path to control socket")
	flag.DurationVar(&shutdownTimeout, "g", time.Duration(0), "Default timeout (seconds) to do graceful shutdown")

	flag.Parse()
	
	ozone.Init(ozone.DumpConfig(dryrun), ozone.ControlSocket(controlSocket), ozone.ShutdownTimeout(shutdownTimeout))
}

func main() {

    ozone.RegisterHTTPHandlerType("MyConfigurableHandler", createHandler)

	err := ozone.Main(configFile)
	if err != nil {
		os.Exit(1)
	}
}

The configuration file is structured as:

{
      "HTTP" : {  // defining HTTP servers
          "servername" : {
              "Handler" :  "handlername"  // top level HTTP handler
              "Listeners" : { ... }  // specification of server listeners.
          }
      },
      "Handlers" : {
         "handlername" : {
              "Type" : "MyConfurableHandler",
               "Config" : { ... }
          }
      }
}

Documentation

Overview

Package ozone provide a generic HTTP server engine as a library well suited for creating HTTP serving daemons running under Linux systemd.

The standard library provides the http.Handler and http.Server.

Ozone provides all the rest: Modularized JSON configuration, graceful and zero-downtime restarts using several restart schemes, plugable handlers, plugable TLS configuration and plugable modules to control reverse proxy request and responses, leveled logging, statsd metrics and a UNIX socket interface for controlling the process without stopping it.

With minimal "main" code you can launch your http.Handler with all the standard daemon behavior in place.

Running Ozone requires a JSON configuration file. (the file allows "//" comments). The primary structure of the file is:

{
   "HTTP" : {  // defining HTTP servers
       "servername" : {
           "Handler" :  "handlername"  // top level HTTP handler
           "Listeners" : { ... }  // specification of server listeners.
       }
   },
   "Handlers" : {
      "handlername" : {
           "Type" : "handlertype",
            "Config" : { ... }
       }
   }
}

Handler types are made available either by being built in, registered from code or loaded from plugins.

Index

• Variables
• func DisableInit()
• func Init(opts ...Option)
• func Main(filename string, opts ...Option) error
• func RegisterHTTPHandlerType(typename string, f HandlerConfigureFunc)
• func RegisterStaticHTTPHandler(name string, h http.Handler)
• func RegisterTLSPluginType(typename string, f TLSPluginConfigureFunc)
• func ReopenAccessLogFiles()
• type HandlerConfigureFunc
• type Option
  • func ControlSocket(socketfile string) Option
  • func DumpConfig(dryrun bool) Option
  • func SdNotifyReadyMessage(msg string) Option
  • func ShutdownTimeout(to time.Duration) Option
• type TLSPluginConfigureFunc

Variables

var HandledSignals = signals.Mappings{
	syscall.SIGINT:  onSignalExit,
	syscall.SIGTERM: onSignalExitGraceful,
	syscall.SIGHUP:  onSignalReload,
	syscall.SIGUSR2: onSignalRespawn,
	syscall.SIGTTIN: onSignalIncLogLevel,
	syscall.SIGTTOU: onSignalDecLogLevel,
	syscall.SIGUSR1: onSignalReopenAccessLogFiles,
}

HandledSignals is a map (syscall.Signal->func()) defining default OS signals to handle and how. Change this by assigning to HandledSignals before calling Init() if you need. Default signals:

SIGINT: Exit immediately
SIGTERM: Wait for shutdown timeout before closing and exiting.
SIGHUP: Retain open file descriptors, but configure new servers from config reusing any open sockets.
SIGUSR2: Respawn the process with the same arguments inheriting file descriptors. The new process will send SIGTERM to the parent once it's configured.
SIGTTIN: Increase log level
SIGTTOU: Decrease log level
SIGUSR1: Reopen all access log files.

var TLSPLUGINPATH string

TLSPLUGINPATH is the default directory containing TLS .so plugins. It default to "" (to not be used) but can be set by the linker (by using -ldflags " -X ozone.TLSPLUGINPATH=..."). Otherwise "TLSPluginDir" in the config is used.

Functions

func DisableInit

func DisableInit()

DisableInit disables Ozones default initialization of Logging, and OS signals using gone/log, gone/daemon and gone/signals. You are on your own now to handle signal and configure logging.

func Init

func Init(opts ...Option)

Init initializes Ozone. If you don't call it, it is called for you by Main(). You can force initialization from your init() function by calling it here. Init will: 1) Set the github.com/One-com/gone/daemon logger function. 2) Register a daemon controlling control socket command. 3) Start the signal handler processing HandledSignals. If you don't want this and control daemon and logging your self, call DisableInit early.

func Main

func Main(filename string, opts ...Option) error

Main starts Ozone serving, by parsing the provided config file and serving everything defined in it by calling github.com/One-com/gone/daemon.Run(). Main can be provided options which will overwrite any options given to Init()

func RegisterHTTPHandlerType

func RegisterHTTPHandlerType(typename string, f HandlerConfigureFunc)

RegisterHTTPHandlerType defines a handler type, so it can be used in the config file by "Type" and be used to configure http.Handler's from the associated config. Referencing a handler of type "name" in the config file, will use the provided function to configure the handler.

func RegisterStaticHTTPHandler

func RegisterStaticHTTPHandler(name string, h http.Handler)

RegisterStaticHTTPHandler makes it possible to directly reference an stdlib HTTP handler in the config file and from other handlers generated dynamically from config. Such handlers are not configurable. If you want to be able to configure your handler from the config file, you probably want to call RegisterHTTPHandlerType.

func RegisterTLSPluginType

func RegisterTLSPluginType(typename string, f TLSPluginConfigureFunc)

RegisterTLSPluginType makes a named type of TLS plugin available via config. Not go-routine safe.

func ReopenAccessLogFiles

func ReopenAccessLogFiles()

ReopenAccessLogFiles opens the configured accesslog files and atomically replaces the old filehandles with the new ones - and closes the old file handles.

Types

type HandlerConfigureFunc

type HandlerConfigureFunc func(name string, cfg jconf.SubConfig, lookupHandler func(string) (http.Handler, error)) (handler http.Handler, cleanup func() error, err error)

HandlerConfigureFunc is called to create a http.Handler from a JSON config stanza. Each registered handler type must define such a function. The function is passed a way to lookup other handlers by name of it needs to wrap around them.

type Option

type Option func(*runcfg)

Option to pass to Init()

func ControlSocket

func ControlSocket(socketfile string) Option

ControlSocket specifies an alternative path for the daemon control socket. If "", the socket is disabled. The socket defaults to "ozone-control.sock" in the current working directory.

func DumpConfig

func DumpConfig(dryrun bool) Option

DumpConfig makes Ozone dry-run and exit after dumping the parsed configuration to os.Stdout

func SdNotifyReadyMessage

func SdNotifyReadyMessage(msg string) Option

SdNotifyReadyMessage changes the default message to send to systemd via the notify socket.

func ShutdownTimeout

func ShutdownTimeout(to time.Duration) Option

ShutdownTimeout changes how long to wait for Servers to do graceful Shutdown before forcefully closing them. You can use the control socket to shutdown with any timeout later, but this is the default which is used by SIGTERM.

type TLSPluginConfigureFunc

type TLSPluginConfigureFunc func(name string, cfg jconf.SubConfig) (func(*tls.Config) error, []daemon.Server, []daemon.CleanupFunc, error)

TLSPluginConfigureFunc is the function called to configure a TLS plugin. It should return a function to modify the *tls.Config already configured from static config. This function can in principle do anything, but most useful is to add callbacks like GetCertificate() for SNI. Additionally it can return servers and cleanup functions to be run in parallel with the other services.