web

README

web

Refer to go package documentation for details.

Documentation

Overview

Package web provides structs and functions to support configuration and building of an HTTPS web server via TLS 1.2 or TLS 1.3.

TLS

To encrypt data across network communications, this package supports the use of Transport Layer Security (TLS, formerly SSL). Specifically, versions 1.2 and 1.3 are supported. Using types from crypto/tls and crypto/x509, this package implements functions to configure TLS and mTLS, look up the available cipher suites, and load CA certificates from a given file to construct a CA pool.

Address

Pertaining to network addresses, this package provides helpful types and functions to store information (network and address strings) and manipulate information (transform from text form of address to ServerAddress form and vice versa).

Adapter

An adapter "adapts" an http.Handler, returning a wrapped http.Handler. This package provides the type definition for Adapter and function definition for Wrap() to wrap such an http.Handler given a slice of Adapter objects.

Index

• func LoadCACerts(cacertFile string) (*x509.CertPool, error)
• func MutualTLS12Config(caCertPool *x509.CertPool) *tls.Config
• func MutualTLS13Config(caCertPool *x509.CertPool) *tls.Config
• func TLS12Config() *tls.Config
• func TLS12SecureCipherList() []uint16
• func TLS13Config() *tls.Config
• func TLS13SecureCipherList() []uint16
• func Wrap(handler http.Handler, adapters ...Adapter) http.Handler
• type Adapter
• type Address
  • func NewAddress(address string) *Address
  • func (s *Address) Format() string
  • func (s *Address) Listener() (net.Listener, error)
  • func (s *Address) MarshalText() ([]byte, error)
  • func (s *Address) Network() string
  • func (s *Address) String() string
  • func (s *Address) UnmarshalText(t []byte) error
• type Config
• type Server
  • func NewServer(config *Config, handler http.Handler) *Server
  • func (s *Server) Start(ctx context.Context) error
  • func (s *Server) Stop(ctx context.Context, e error) error
• type TLS
  • func (tc *TLS) Listener(addr *Address) (net.Listener, error)

Examples

• LoadCACerts
• MutualTLS12Config
• MutualTLS13Config
• NewAddress
• TLS12Config
• TLS13Config
• Wrap

Functions

func LoadCACerts

func LoadCACerts(cacertFile string) (*x509.CertPool, error)

LoadCACerts parses cacertFile for cert files and adds them to a CertPool caCertPool, returning caCertPool with nil error if successful. Else, return nil CertPool and the error encountered.

Example

package main

import (
	"gojini.dev/web"
)

func main() {
	_, err := web.LoadCACerts("./unknown_file")
	if err == nil {
		panic(err)
	}

	certs, err := web.LoadCACerts("./test_certs/ca.crt")
	if err != nil || certs == nil {
		panic(err)
	}

}

func MutualTLS12Config

func MutualTLS12Config(caCertPool *x509.CertPool) *tls.Config

MutualTLS12Config returns *tls.Config that supports mTLS 1.2 with verification via the specified certificate authority.

Example

package main

import (
	"fmt"

	"gojini.dev/web"
)

func main() {
	certs, err := web.LoadCACerts("./test_certs/ca.crt")
	if err != nil {
		panic(err)
	}

	tls12Config := web.MutualTLS12Config(certs)
	fmt.Println("tls12 max version:", tls12Config.MaxVersion)
	fmt.Println("tls12 min version:", tls12Config.MinVersion)
	fmt.Println("prefer cipher suites:", tls12Config.PreferServerCipherSuites)
	fmt.Println("client auth:", tls12Config.ClientAuth)

}

Output:

tls12 max version: 772
tls12 min version: 771
prefer cipher suites: true
client auth: RequireAndVerifyClientCert

func MutualTLS13Config

func MutualTLS13Config(caCertPool *x509.CertPool) *tls.Config

MutualTLS13Config returns *tls.Config that supports mTLS 1.3 with verification via the specified certificate authority.

Example

package main

import (
	"fmt"

	"gojini.dev/web"
)

func main() {
	certs, err := web.LoadCACerts("./test_certs/ca.crt")
	if err != nil {
		panic(err)
	}

	tls13Config := web.MutualTLS13Config(certs)
	fmt.Println("tls13 max version:", tls13Config.MaxVersion)
	fmt.Println("tls13 min version:", tls13Config.MinVersion)
	fmt.Println("prefer cipher suites:", tls13Config.PreferServerCipherSuites)
	fmt.Println("client auth:", tls13Config.ClientAuth)

}

Output:

tls13 max version: 772
tls13 min version: 772
prefer cipher suites: true
client auth: RequireAndVerifyClientCert

func TLS12Config

func TLS12Config() *tls.Config

TLS12Config returns *tls.Config with TLS 1.2 settings.

Example

package main

import (
	"fmt"

	"gojini.dev/web"
)

func main() {
	tls12Config := web.TLS12Config()
	fmt.Println("tls12 max version:", tls12Config.MaxVersion)
	fmt.Println("tls12 min version:", tls12Config.MinVersion)
	fmt.Println("prefer cipher suites:", tls12Config.PreferServerCipherSuites)

}

Output:

tls12 max version: 772
tls12 min version: 771
prefer cipher suites: true

func TLS12SecureCipherList

func TLS12SecureCipherList() []uint16

TLS12SecureCipherList returns a slice of TLS 1.2 cipher suites.

func TLS13Config

func TLS13Config() *tls.Config

TLS13Config returns *tls.Config that only supports TLS 1.3 and does not enforce client side authentication.

Example

package main

import (
	"fmt"

	"gojini.dev/web"
)

func main() {
	tls13Config := web.TLS13Config()
	fmt.Println("tls13 max version:", tls13Config.MaxVersion)
	fmt.Println("tls13 min version:", tls13Config.MinVersion)
	fmt.Println("prefer cipher suites:", tls13Config.PreferServerCipherSuites)

}

Output:

tls13 max version: 772
tls13 min version: 772
prefer cipher suites: true

func TLS13SecureCipherList

func TLS13SecureCipherList() []uint16

TLS13SecureCipherList returns a slice of TLS 1.3 cipher suites.

func Wrap

func Wrap(handler http.Handler, adapters ...Adapter) http.Handler

Wrap wraps the actual http.Handler that handles the request with a list of adapters. The adapters provided are called in sequence and if all adapters forward the call to the next one the handler will be called.

Example

package main

import (
	"fmt"
	"net/http"

	"gojini.dev/web"
)

func main() {
	god := http.HandlerFunc(func(http.ResponseWriter, *http.Request) {
		fmt.Println("You reached God!")
	})

	charity := func(h http.Handler) http.Handler {
		return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
			// Before
			fmt.Println("Donate and volunteer blood and sweat!")

			h.ServeHTTP(w, r)

			// After
			fmt.Println("Donate more and volunteer more!")
		})
	}

	prayer := func(h http.Handler) http.Handler {
		return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
			// Before
			fmt.Println("Pray in the morning!")

			h.ServeHTTP(w, r)

			// After
			fmt.Println("Pray in the evening!")
		})
	}

	faith := func(h http.Handler) http.Handler {
		return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
			// Before
			fmt.Println("Believe when things are good!")

			h.ServeHTTP(w, r)

			// After
			fmt.Println("Believe more when things are bad!")
		})
	}

	web.Wrap(god, charity, prayer, faith).ServeHTTP(nil, nil)

}

Output:

Donate and volunteer blood and sweat!
Pray in the morning!
Believe when things are good!
You reached God!
Believe more when things are bad!
Pray in the evening!
Donate more and volunteer more!

Types

type Adapter

type Adapter func(http.Handler) http.Handler

Adapter wraps a http.Handler and returns a http.Handler. For a detailed discussion please checkout: https://medium.com/@matryer/writing-middleware-in-golang-and-how-go-makes-it-so-much-fun-4375c1246e81

type Address

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

Address encapsulates listening address of the http server. This structure implements the net.Addr interface.

func NewAddress

func NewAddress(address string) *Address

NewAddress returns a server address by parsing the address in string form. The address string can be of following forms: * unix://var/run/server.sock * tcp://127.0.0.1:6666 * 127.0.0.1:7777 If the network is not specified in the string, it defaults to tcp and uses the rest of the string as the tcp address.

Example

package main

import (
	"fmt"

	"gojini.dev/web"
)

func main() {
	addr := web.NewAddress("tcp://127.0.0.1:8888")

	fmt.Println("address format:", addr.Format())
	fmt.Println("address string:", addr.String())
	fmt.Println("network:", addr.Network())

	text, err := addr.MarshalText()
	if err != nil {
		panic(err)
	}

	if err = addr.UnmarshalText(text); err != nil {
		panic(err)
	}

	addr = web.NewAddress("127.0.0.1:8888")

	fmt.Println("address format:", addr.Format())
	fmt.Println("address string:", addr.String())
	fmt.Println("network:", addr.Network())

	text, err = addr.MarshalText()
	if err != nil {
		panic(err)
	}

	if err = addr.UnmarshalText(text); err != nil {
		panic(err)
	}

	addr = web.NewAddress("unix://var/run/server.sock")

	fmt.Println("address format:", addr.Format())
	fmt.Println("address string:", addr.String())
	fmt.Println("network:", addr.Network())

	text, err = addr.MarshalText()
	if err != nil {
		panic(err)
	}

	if err = addr.UnmarshalText(text); err != nil {
		panic(err)
	}

}

Output:

address format: tcp://127.0.0.1:8888
address string: 127.0.0.1:8888
network: tcp
address format: tcp://127.0.0.1:8888
address string: 127.0.0.1:8888
network: tcp
address format: unix://var/run/server.sock
address string: var/run/server.sock
network: unix

func (*Address) Format

func (s *Address) Format() string

Format returns a fully qualified address string as described in the NewAddress.

func (*Address) Listener

func (s *Address) Listener() (net.Listener, error)

func (*Address) MarshalText

func (s *Address) MarshalText() ([]byte, error)

MarshalText returns the address in text form.

func (*Address) Network

func (s *Address) Network() string

Network returns the network of this server address. For example: tcp, unix.

func (*Address) String

func (s *Address) String() string

String returns address specific to the network. For example: 127.0.0.1:6666 or /var/run/server.sock.

func (*Address) UnmarshalText

func (s *Address) UnmarshalText(t []byte) error

UnmarshalText parses the address in text form into an address.

type Config

type Config struct {
	Address *Address `json:"address"`
	TLS     *TLS     `json:"tls,omitempty"`
}

type Server

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

func NewServer

func NewServer(config *Config, handler http.Handler) *Server

func (*Server) Start

func (s *Server) Start(ctx context.Context) error

func (*Server) Stop

func (s *Server) Stop(ctx context.Context, e error) error

type TLS

type TLS struct {
	CACertFile  string `json:"caCertFile,omitempty"`
	CertFile    string `json:"certFile"`
	KeyFile     string `json:"keyFile"`
	EnableTLS12 bool   `json:"tls12,omitempty"`
}

func (*TLS) Listener

func (tc *TLS) Listener(addr *Address) (net.Listener, error)