httpserver

README

httpserver

This package provides a simple HTTP server that can be used to serve HTTP, HTTPS and FCGI requests. For example:

package main

import (
    "github.com/mutablelogic/go-server/pkg/httpserver"
)

func main() {
    // Create the server
    config := httpserver.Config{}
    server, err := config.New(context.Background())

    // Run the server for five seconds
    ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
    defer cancel()
    if err := server.Run(ctx); err != nil {
        log.Fatal(err)
    }
}

Serving HTTP requests

To serve HTTP requests, create a new server with the default configuration. By default, the default router is of type *http.ServeMux. For example, the following creates a server that listens on port 8080:

func main() {
    server, err := httpserver.Config{ Listen: ":8080" }.New(context.Background())
    if err != nil {
        log.Fatal(err)
    }

    // Set the router handers
    server.Router().(*http.ServeMux).HandleFunc("/", func(w http.ResponseWriter, r *http.Request) {
        w.Write([]byte("Hello, World!"))
    })

    // ....
}

You can use a random port by setting the listen parameter to : or :0. You can find out which port the server is listening on by calling server.Addr(). The timeout for serving requests can be set using the Timeout parameter.

Serving HTTPS requests

To serve HTTPS requests, create a new server with the default configuration and set the TLS parameter to the path for the key and certificate files. For example,

func main() {
    server, err := httpserver.Config{
        TLS: httpserver.TLSConfig{
            Key: "server.key",
            Cert: "server.crt",
        },
    }.New(context.Background())
    if err != nil {
        log.Fatal(err)
    }

    // ....
}

Serving FCGI requests

To serve requests over FastCGI using a unix socker, create a new server with the path to the socket:

func main() {
    server, err := httpserver.Config{
        Listen: "socket.fcgi",
        Group: "http",
    }.New(context.Background())
    if err != nil {
        log.Fatal(err)
    }

    // ....
}

Set the Owner and Group configuration parameters to the user and group permissions for the socket file.

Using a custom router

To use a custom router, set the Router parameter to the router you want to use. For example, to use the gorilla/mux router:

package main

import (
    httpserver "github.com/mutablelogic/go-server/pkg/httpserver"
    mux "github.com/gorilla/mux"
)

func main() {
    server, err := httpserver.Config{
        Router: mux.NewRouter(),
    }.New(context.Background())
    if err != nil {
        log.Fatal(err)
    }

    // Set the router handers
    server.Router().(*mux.Router).HandleFunc("/", func(w http.ResponseWriter, r *http.Request) {
        w.Write([]byte("Hello, World!"))
    })

    // ....
}

Documentation

Overview

The `httpserver` task implements a server which can serve requests over HTTP, HTTPS and FCGI

Index

• type Config
  • func (Config) Description() string
  • func (Config) Name() string
  • func (c Config) New() (server.Task, error)
  • func (c Config) String() string
• type Server

Types

type Config

type Config struct {
	Listen string `hcl:"listen" description:"Network address and port to listen on, or path to file socket"`
	TLS    struct {
		Key  string `hcl:"key" description:"Path to private key (if provided, tls.cert is also required)"`
		Cert string `hcl:"cert" description:"Path to certificate (if provided, tls.key is also required)"`
	} `hcl:"tls"`
	Timeout time.Duration `hcl:"timeout" description:"Read request timeout"`
	Owner   string        `hcl:"owner" description:"User ID of the file socket (if listen is a file socket)"`
	Group   string        `hcl:"group" description:"Group ID of the file socket (if listen is a file socket)"`
	Router  http.Handler  `hcl:"router" description:"HTTP router for requests"`
}

Server configuration

func (Config) Description

func (Config) Description() string

Description returns the description of the service

func (Config) Name

func (Config) Name() string

Name returns the name of the service

func (Config) New

func (c Config) New() (server.Task, error)

Create a new http server from the configuration

func (Config) String

func (c Config) String() string

Return the configuration as a string

type Server

type Server interface {
	server.Task

	// Return the type of server (http, https or fcgi)
	Type() string

	// Return the listening address or path
	Addr() string

	// Return the router associated with the server
	Router() http.Handler
}

Server interface