http

Documentation

Overview

Package http provides opinionated production-ready configured HTTP server.

It includes error recovery, logger integration, h2c and optional telemetry instrument, request timeout with following code sample:

Usage

http.NewServer(
  http.WithTelemetry(),
  http.WithTimeout(15*time.Second),
)(
  func(*mux.Router) {
    // Register your handlers here.
  },
)

Index

• func NewServer(handler func(*mux.Router), opts ...ServerOption) func(context.Context) error
• func RegisterUnixProtocol(transport *http.Transport)
• type ServerOption
  • func WithAddress(address string) ServerOption
  • func WithHTTPServer(server *http.Server) ServerOption
  • func WithStopGate(gate func()) ServerOption
  • func WithTLS(certs ...tls.Certificate) ServerOption
  • func WithTelemetry(opts ...otelhttp.Option) ServerOption
  • func WithTimeout(duration time.Duration) ServerOption

Functions

func NewServer

func NewServer(handler func(*mux.Router), opts ...ServerOption) func(context.Context) error

NewServer returns an HTTP server runner with provided ServerOption. It supports both HTTP/1 and HTTP/2 clear text.

func RegisterUnixProtocol

func RegisterUnixProtocol(transport *http.Transport)

RegisterUnixProtocol adds a protocol handler to the provided transport that can serve requests to Unix domain sockets via the "unix" schemes.

Request URLs should have the following form:

unix:socket_file/request/path?query=val&...

The registered transport is based on a clone of the provided transport, and so uses the same configuration: timeouts, TLS settings, and so on. Connection pooling should also work as normal.

Types

type ServerOption

type ServerOption func(*serverOptions)

ServerOption configures how we run HTTP server.

func WithAddress

func WithAddress(address string) ServerOption

WithAddress specifies the address listened by HTTP server.

It could be either tcp address like :8080 or unix socket like unix:path.

For unix socket, the client request URL should have the following form:

unix:socket_file/request/path?query=val&...

The unix protocol works for http.Client with http.DefaultTransport. It can be created like the following sample:

client = http.Client{}

Or

client = http.Client{
  Transport: http.DefaultTransport,
}

Otherwise it needs to call http.RegisterUnixProtocol to register unix protocol to the transport.

The default address is :8080.

func WithHTTPServer

func WithHTTPServer(server *http.Server) ServerOption

WithHTTPServer provides a customized http.Server so that it would be configured with more options which aren't exposed.

func WithStopGate

func WithStopGate(gate func()) ServerOption

WithStopGate provides gate function blocks the shutdown of the HTTP server until it returns.

func WithTLS

func WithTLS(certs ...tls.Certificate) ServerOption

WithTLS enables TLS on the HTTP server.

By default, it uses self-signed certificate if there is no certificates provided.

func WithTelemetry

func WithTelemetry(opts ...otelhttp.Option) ServerOption

WithTelemetry enables trace and metric instrument on HTTP Server.

func WithTimeout

func WithTimeout(duration time.Duration) ServerOption

WithTimeout specifies the duration that timeout the request.

The default value is 0, which means no timeout. In that case, it depends on the reverse proxy (e.g. API Gateway, Load Balancer) to cancel the request with timeout.