httpserver

Documentation

Overview

Package httpserver provides API to standard http server with graceful shutdown.

Typical usage:

httpserver.New(
    httpserver.WithName("my-server"),
    httpserver.WithAddress("127.0.0.1:8080"),
    httpserver.WithHandler(myHandler),
).Run(ctx)

Index

• Constants
• type Config
• type ConfigService
• type Option
  • func WithAddress(address string) Option
  • func WithConfig(service ConfigService, key string) Option
  • func WithHandler(handler http.Handler) Option
  • func WithLogger(logger log.Logger) Option
  • func WithName(name string) Option
  • func WithReadHeaderTimeout(readHeaderTimeout int64) Option
  • func WithReadTimeout(readTimeout int64) Option
  • func WithWriteTimeout(writeTimeout int64) Option
• type Server
  • func MustNew(opts ...Option) *Server
  • func New(opts ...Option) (*Server, error)
  • func (server *Server) Address() string
  • func (server *Server) Name() string
  • func (server *Server) ReadHeaderTimeout() time.Duration
  • func (server *Server) ReadTimeout() time.Duration
  • func (server *Server) Run(ctx context.Context)
  • func (server *Server) WriteTimeout() time.Duration

Constants

const (
	// DefAddress is the default server's address that will be listened to.
	DefAddress = "127.0.0.1:8080"
	// DefName is the default server's name.
	DefName = "http-server"
	// DefReadHeaderTimeout is the default maximum time in seconds to read http header.
	DefReadHeaderTimeout = 2
	// DefReadTimeout is the default maximum time in seconds to read request.
	DefReadTimeout = 3
	// DefWriteTimeout is the maximum time in seconds to write request response.
	DefWriteTimeout = 3
)

Types

type Config

type Config struct {
	// contains filtered or unexported fields
}

Config structure with server configuration. Shouldn't be created manually.

type ConfigService

type ConfigService interface {
	GetByKey(string, interface{}) error
	IsNoSuchKeyError(error) bool
}

ConfigService interface used to obtain configuration from somewhere into some specific structure.

type Option

type Option func(*Config) error

Option function that is fed to New and MustNew. Obtain them using 'With' functions down below.

func WithAddress

func WithAddress(address string) Option

WithAddress option applies provided address that will be listened to. Default: "127.0.0.1:8080".

func WithConfig

func WithConfig(service ConfigService, key string) Option

WithConfig option retrieves configuration from provided configuration service.

Example JSON configuration with all possible fields (if some are not present, defaults will be used):

{
    "name": "server-name",
    "address": "127.0.0.1:8080"
}

func WithHandler

func WithHandler(handler http.Handler) Option

WithHandler option applies provided handler. Default: http.NotFoundHandler().

func WithLogger

func WithLogger(logger log.Logger) Option

WithLogger option applies provided logger. Default: standard logger with name equal to server's one.

func WithName

func WithName(name string) Option

WithName option applies provided server name. Default: "http-server".

func WithReadHeaderTimeout

func WithReadHeaderTimeout(readHeaderTimeout int64) Option

WithReadHeaderTimeout option applies provided maximum time in seconds to read http header. Default: 2.

func WithReadTimeout

func WithReadTimeout(readTimeout int64) Option

WithReadTimeout option applies provided maximum time in seconds to read request. Default: 3.

func WithWriteTimeout

func WithWriteTimeout(writeTimeout int64) Option

WithWriteTimeout option applies provided maximum time in seconds to write response. Default: 3.

type Server

type Server struct {
	// contains filtered or unexported fields
}

Server structure that provides http server functionality. Don't create manually, use the functions down below instead.

func MustNew

func MustNew(opts ...Option) *Server

MustNew function creates new server with provided options and panics on any error.

func New

func New(opts ...Option) (*Server, error)

New function creates new server with provided options.

func (*Server) Address

func (server *Server) Address() string

Address method gets server's address that it listens to.

func (*Server) Name

func (server *Server) Name() string

Name method gets server's name.

func (*Server) ReadHeaderTimeout

func (server *Server) ReadHeaderTimeout() time.Duration

ReadHeaderTimeout method gets server's maximum time to read http header.

func (*Server) ReadTimeout

func (server *Server) ReadTimeout() time.Duration

ReadTimeout method gets server's maximum time to read request.

func (*Server) Run

func (server *Server) Run(ctx context.Context)

Run method runs server listen loop. It is blocking so you probably want to run it in a separate goroutine. If you pass cancellable context here, you will be able to gracefully shutdown server that waits for all requests to complete.

Only upgraded connections (such as websocket ones) will not be waited for, you will need to shutdown them manually.

func (*Server) WriteTimeout

func (server *Server) WriteTimeout() time.Duration

WriteTimeout method gets server's maximum time to write response.