go-nacelle / httpbase

Abstract HTTP server process for nacelle.

Nacelle Base HTTP Process

Abstract HTTP server process for nacelle.

---

This library supplies an abstract HTTP server process whose behavior can be configured by implementing a ServerInitializer interface. For a more full-featured HTTP server framework built on nacelle, see chevron.

You can see an additional example of an HTTP process in the example repository, specifically the server initializer.

Process

An HTTP process is created by supplying an initializer, described below, that controls its behavior.

server := httpbase.NewServer(NewServerInitializer(), options...)

Server Initializer

A server initializer is a struct with an Init method that takes a config object and an http.Server as parameters. This method may return an error value, which signals a fatal error to the process that runs it. This method provides an extension point to register handlers to the server instance before the process accepts connections.

The following example registers an HTTP handler function to the server that will handle all incoming requests. Each request atomically increments a request counter on the containing initializer struct and returns its new value. In more complex applications, an HTTP router, such as gorilla/mux should likely be used.

type Initializer struct {
    requests uint
}

func (i *Initializer) Init(config nacelle.Config, server *http.Server) error {
    server.Handler = http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
        value := atomic.AddUint32(&i.requests)
        w.WriteHeader(http.StatusOK)
        w.Write([]byte(fmt.Sprintf("Hello, #%d!\n", value)))
    })

    return nil
}

Initializer Function

A simple server initializer stuct that does not need additional methods, state, or dependency instances injected via a service container can use the server initializer function wrapper instead.

ServerInitializerFunc(func(config nacelle.Config, server *http.Server) error {
    server.Handler = http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
        w.WriteHeader(http.StatusOK)
        w.Write([]byte("Hello, World!\n"))
    })

    return nil
})

Server Process Options

The following options can be supplied to the server constructor to tune its behavior.

WithTagModifiers

WithTagModifiers registers the tag modifiers to be used when loading process configuration (see below). This can be used to change default hosts and ports, or prefix all target environment variables in the case where more than one HTTP server is registered per application (e.g. health server and application server, data plane and control plane server).

Configuration

The default process behavior can be configured by the following environment variables.

Environment Variable	Default	Description
HTTP_HOST	0.0.0.0	The host on which to accept connections.
HTTP_PORT	5000	The port on which to accept connections.
HTTP_CERT_FILE		The path to the TLS cert file.
HTTP_KEY_FILE		The path to the TLS key file.
HTTP_SHUTDOWN_TIMEOUT	5	The time (in seconds) the server can spend in a graceful shutdown.

The one of HTTP_CERT_FILE and HTTP_KEY_FILE are set, then they must both be set. Setting these will start a TLS server.