aserver

README

aserver

Golang HTTPS server made easy

Copyright (c) 2024 Tenebris Technologies Inc. Released under the MIT License. Please see the LICENSE file for additional information.

Warning

This is alpha code and should not be used in production.

Overview

This project exists because I hate writing and maintaining the same code more than once and some quirks in the Go standard library don't meet realistic production requirements. Most notably, they don't provide a mechanism to limit the number of concurrent requests. This could result in resource exhaustion and cause the application to crash. In many applications it makes much more sense to limit the number of concurrent requests and

This package implements a production quality HTTP server with the following features:

• Limit the number of concurrent requests
• Log requests
• HTTPS (TLS) support
• Consistent HTTP headers added to every response
• Creating a file with a specific name will cause the health check to fail
• A simple logger that can be replaced with a custom logger if desired

Handlers are also simplified. Instead of using the http.Handler interface, handle functions must accept *http.Request and return an aserver.Response structure.

Contributions

PRs are welcome provided that they are consistent with the MIT License.

Documentation

Overview

Package aserver implements a wrapper around gorilla/mux router and net/http server to create a production grade server and simply the creation of routes and handlers.

Index

• func WithDebug(d bool) func(*AServer) error
• func WithDefaultHeaders(d bool) func(*AServer) error
• func WithDownFile(down string) func(*AServer) error
• func WithHTTPIdleTimeout(t int) func(*AServer) error
• func WithHTTPTimeout(t int) func(*AServer) error
• func WithHealthHandler(h bool) func(*AServer) error
• func WithListen(listen string) func(*AServer) error
• func WithLogFile(logfile string) func(*AServer) error
• func WithLogger(logger Logger) func(*AServer) error
• func WithMaxConcurrent(m int) func(*AServer) error
• func WithSEid(seid uint32) func(*AServer) error
• func WithStrictSlash(s bool) func(*AServer) error
• func WithTLS(t bool) func(*AServer) error
• func WithTLSCertFile(certfile string) func(*AServer) error
• func WithTLSKeyFile(keyfile string) func(*AServer) error
• func WithTLSStrongCiphers(c bool) func(*AServer) error
• func WithTestHandler(t bool) func(*AServer) error
• type AServer
  • func New(options ...func(*AServer) error) (*AServer, error)
  • func (e *AServer) AddHeader(key, value string)
  • func (e *AServer) AddRoute(route Route)
  • func (e *AServer) AddRoutes(routes Routes)
  • func (e *AServer) Handler401(r *http.Request) Response
  • func (e *AServer) Handler404(r *http.Request) Response
  • func (e *AServer) Handler405(r *http.Request) Response
  • func (e *AServer) HandlerHealth(r *http.Request) Response
  • func (e *AServer) HandlerTest(r *http.Request) Response
  • func (e *AServer) Start() error
  • func (e *AServer) Stop() error
  • func (e *AServer) Wrapper(handlerName string, hFunc Handler) http.Handler
• type Handler
• type Header
• type Headers
• type Logger
• type LoggerFields
• type Response
• type Route
• type Routes

Functions

func WithDebug

func WithDebug(d bool) func(*AServer) error

func WithDefaultHeaders

func WithDefaultHeaders(d bool) func(*AServer) error

func WithDownFile

func WithDownFile(down string) func(*AServer) error

func WithHTTPIdleTimeout

func WithHTTPIdleTimeout(t int) func(*AServer) error

func WithHTTPTimeout

func WithHTTPTimeout(t int) func(*AServer) error

func WithHealthHandler

func WithHealthHandler(h bool) func(*AServer) error

func WithListen

func WithListen(listen string) func(*AServer) error

func WithLogFile

func WithLogFile(logfile string) func(*AServer) error

func WithLogger

func WithLogger(logger Logger) func(*AServer) error

func WithMaxConcurrent

func WithMaxConcurrent(m int) func(*AServer) error

func WithSEid

func WithSEid(seid uint32) func(*AServer) error

func WithStrictSlash

func WithStrictSlash(s bool) func(*AServer) error

func WithTLS

func WithTLS(t bool) func(*AServer) error

func WithTLSCertFile

func WithTLSCertFile(certfile string) func(*AServer) error

func WithTLSKeyFile

func WithTLSKeyFile(keyfile string) func(*AServer) error

func WithTLSStrongCiphers

func WithTLSStrongCiphers(c bool) func(*AServer) error

func WithTestHandler

func WithTestHandler(t bool) func(*AServer) error

Types

type AServer

type AServer struct {
	Headers          Headers
	Routes           Routes
	Listen           string
	HTTPTimeout      int
	HTTPIdleTimeout  int
	MaxConcurrent    int
	LogFile          string // Optional, defaults to stdout
	DownFile         string
	HealthHandler    bool
	TestHandler      bool
	StrictSlash      bool
	DefaultHeaders   bool
	TLS              bool
	TLSCertFile      string
	TLSKeyFile       string
	TLSStrongCiphers bool
	Debug            bool

	Logger Logger // Our logger interface for compatibility
	SEid   uint32 // Event ID for logging
	// contains filtered or unexported fields
}

func New

func New(options ...func(*AServer) error) (*AServer, error)

New returns a AServer struct with default values and options applied

func (*AServer) AddHeader

func (e *AServer) AddHeader(key, value string)

AddHeader adds a header to the list

func (*AServer) AddRoute

func (e *AServer) AddRoute(route Route)

AddRoute adds a route to the router

func (*AServer) AddRoutes

func (e *AServer) AddRoutes(routes Routes)

AddRoutes adds routes to the router

func (*AServer) Handler401

func (e *AServer) Handler401(r *http.Request) Response

func (*AServer) Handler404

func (e *AServer) Handler404(r *http.Request) Response

func (*AServer) Handler405

func (e *AServer) Handler405(r *http.Request) Response

func (*AServer) HandlerHealth

func (e *AServer) HandlerHealth(r *http.Request) Response

HandlerHealth implements a health check for load balancers, etc.

func (*AServer) HandlerTest

func (e *AServer) HandlerTest(r *http.Request) Response

HandlerTest accepts an optional 'id' variable and echos it back This is an example of a handler that can receive a variable in the URL or not Note that two routes are defined in routes.go, one with the variable and one without

func (*AServer) Start

func (e *AServer) Start() error

Start starts the API

func (*AServer) Stop

func (e *AServer) Stop() error

func (*AServer) Wrapper

func (e *AServer) Wrapper(handlerName string, hFunc Handler) http.Handler

Wrapper returns a standard http.HandlerFunc This wrapper provides consistent logging and HTTP headers

type Handler

type Handler func(request *http.Request) Response

type Header

type Header struct {
	Key   string
	Value string
}

type Headers

type Headers []Header

type Logger

type Logger interface {
	Debug(eid uint32, msg string, fields map[string]interface{})
	Info(eid uint32, msg string, fields map[string]interface{})
	Warning(eid uint32, msg string, fields map[string]interface{})
	Error(eid uint32, msg string, fields map[string]interface{})
	Fatal(eid uint32, msg string, fields map[string]interface{})
}

Logger is an interface that defines the logging methods and is compatible with log.Logger

type LoggerFields

type LoggerFields map[string]interface{}

LoggerFields is a map of key/value pairs for logging

type Response

type Response struct {
	Status  string `json:"status"`            // Text Status
	Code    int    `json:"code"`              // HTTP status code
	Details string `json:"details,omitempty"` // optional response details
	Data    any    `json:"data,omitempty"`    // any is the new interface{}
}

Response provides a consistent format for API responses Data is used to hold an appropriate structure

type Route

type Route struct {
	Name    string
	Method  string
	Pattern string
	Handler Handler
}

type Routes

type Routes []Route