phttp

Documentation

Index

• Constants
• func CheckRedirect(req *http.Request, via []*http.Request) (err error)
• func Get(requestURL string, tlsConfig *tls.Config, ctx context.Context) (resp *http.Response, err error)
• func NewLogCapturer(logF parl.PrintfFunc) (errorLog *log.Logger)
• func NewRequest(requestURL string, ctx context.Context, errp *error) (req *http.Request)
• func NewTransport(tlsConfig *tls.Config) (httpTransport *http.Transport)
• type HandlerFunc
• type HttpClient
  • func NewHttpClient(tlsConfig *tls.Config) (httpClient *HttpClient)
  • func (c *HttpClient) Do(req *http.Request) (resp *http.Response, err error)
• type Https
  • func NewHttps(certDER parl.CertificateDer, signer crypto.Signer, log ...parl.PrintfFunc) (httpsServer *Https)
  • func (s *Https) Errs() (errIterator parl.ErrsIter)
  • func (s *Https) GetServeGoFunction() (serve func(listener net.Listener))
  • func (s *Https) HandleFunc(pattern string, handler HandlerFunc)
  • func (s *Https) Listen(socketAddress pnet.SocketAddress) (nearAddrPort netip.AddrPort, listener net.Listener, err error)
  • func (s *Https) Shutdown(ctx ...context.Context) (err error)
  • func (s *Https) Shutdown2(errp *error, ctx ...context.Context)
  • func (s *Https) ShutdownCh() (ch parl.AwaitableCh)
  • func (s *Https) TLS(socketAddress pnet.SocketAddress) (tlsListener net.Listener, err error)
• type LogCapturer
  • func (c *LogCapturer) Write(p []byte) (n int, err error)

Constants

const (
	ContentType               = "Content-Type"
	ApplicationJson           = "application/json"
	ApplicationJsonCharSet    = ApplicationJson + "; charset=utf-8"
	TextPlain                 = "text/plain"
	TextPlainCharSet          = TextPlain + "; charset=utf-8"
	Authorization             = "Authorization"
	BearerPrefix              = "Bearer"
	GetMethod                 = "GET"
	OptionsMethod             = "OPTIONS"
	UserAgent                 = "User-Agent"
	AcceptEncoding            = "Accept-Encoding"
	Origin                    = "Origin"
	AccessControlAllowOrigin  = "Access-Control-Allow-Origin"
	Star                      = "*"
	AccessControlAllowHeaders = "Access-Control-Allow-Headers"
)

const (
	// default port for https: 443, or address for localhost IPv4 or IPv6 port 443
	HttpsPort uint16 = 443
)

Functions

func CheckRedirect

func CheckRedirect(req *http.Request, via []*http.Request) (err error)

CheckRedirect replaces default policy 10 consecutive requests

func Get

func Get(requestURL string, tlsConfig *tls.Config, ctx context.Context) (resp *http.Response, err error)

Get is a convenience method for pnet.HttpClient.Get

func NewLogCapturer

func NewLogCapturer(logF parl.PrintfFunc) (errorLog *log.Logger)

func NewRequest

func NewRequest(requestURL string, ctx context.Context, errp *error) (req *http.Request)

func NewTransport

func NewTransport(tlsConfig *tls.Config) (httpTransport *http.Transport)

NewTransport returns a transport using tlsConfig

• based on http.DefaultTransport

Types

type HandlerFunc

type HandlerFunc func(http.ResponseWriter, *http.Request)

HandlerFunc is the signature for URL handlers

type HttpClient

type HttpClient struct{ http.Client }

HttpClient implements http GET for specific TLS configuration

• http.DefaultClient uses http.DefaultTransport
• — has no timeouts
• — cannot use client certificate

func NewHttpClient

func NewHttpClient(tlsConfig *tls.Config) (httpClient *HttpClient)

NewHttpClient returns a client based on http.Client and tlsConfig

• HttpClient features custom transport to facilitate TLS setting such as accepting server self-signed certificates or client certificate
• tlsConfig: optional configuration for https. May be obtained from pnet.NewTLSConfig
• phttp.NewRequest obtains a request object that can be modified
• — method, request headers, cookies, body
• HttpClient.Do issues request

func (*HttpClient) Do

func (c *HttpClient) Do(req *http.Request) (resp *http.Response, err error)

type Https

type Https struct {
	// Server holds handler mux and fields like TLSConfig
	http.Server
	// contains filtered or unexported fields
}

Https is an https server instance encapsulating its credentials

• Https is an http.Server that:
• — uses in-memory credentials
• — has route-handler configuration
• — provides awaitable threading for any number of listeners
• — has awaitable first error and shutdown
• — provides streaming or collectable net.Listener.Accept errors

func NewHttps

func NewHttps(certDER parl.CertificateDer, signer crypto.Signer, log ...parl.PrintfFunc) (httpsServer *Https)

NewHttps creates https server with any number of listeners

• Https is an http.Server that:
• — uses in-memory credentials
• — has route-handler configuration
• — provides awaitable threading for any number of listeners
• — has awaitable first error and deferrable shutdown
• — provides streaming or collectable net.Listener.Accept errors
• certDER: certificate in binary DER ASN.1 format. Can be obtained from parl.CertificateAuthority.Sign
• signer: private key material and signing methods. Can be obatined from [parlca.NewPrivateKey]
• log: optional function receiving log output
• — if missing, output may occur on standard error
• Https.HandleFunc configures handle functions
• Https.Listen creates TLS listener
• [Https.Serve] gorouting invoking net.Listener.Accept
• Https.Errs returns error iterator
• Https.ShutdownCh awaits Shutdown complete
• Https.Shutdown graceful shutdown
• Https.Shutdown2 deferrable shutdown
• error sources:
• — returned by Https.Listen: troubles in listener set-up
• — returned by Https.Shutdown Https.Shutdown2 listener shutdown errors
• — Https.Errs real-time streaming iterator erorrs or error collection after shutdown
• awaitable via Https.ShutdownCh that awaits completion of Shutdown invocaion and exit of all Serve threads. Serve threads that do not exit causes wait to be indefinite

Usage:

var s = NewHttps(cert, key)
defer s.Shutdown2(&err)
s.HandleFunc("/", myHandler)
if nearAddrPort, listener, e := s.Listen(socketAddress); e == nil {
  go s.Serve(listener)
  println(nearAddrPort.String())
} else {
  err = e
  return
}
<-s.ShutdownCh()
parl.DeferredErrorSource(s.Errs(), &err)
return

func (*Https) Errs

func (s *Https) Errs() (errIterator parl.ErrsIter)

Errs returns a streaming error iterator or post serve-exit error collection

func (*Https) GetServeGoFunction

func (s *Https) GetServeGoFunction() (serve func(listener net.Listener))

func (*Https) HandleFunc

func (s *Https) HandleFunc(pattern string, handler HandlerFunc)

HandleFunc registers a URL-handler for the server

func (*Https) Listen

func (s *Https) Listen(socketAddress pnet.SocketAddress) (
	nearAddrPort netip.AddrPort,
	listener net.Listener,
	err error,
)

Listen initiates listening and returns the error channel

• can only be invoked once or panic
• errCh closes on server shutdown
• non-blocking, all errors are sent on the error channel
• if nearSocket.Addr is invalid, all interfaces for IPv6 if allowed, IPv4 otherwise is used
• if nearSocket.Port is zero:
• — if network is NetworkDefault: ephemeral port
• — otherwise port 443 “:https” is used
• for NetworkDefault, NetworkTCP is used
• panic for bad Network

func (*Https) Shutdown

func (s *Https) Shutdown(ctx ...context.Context) (err error)

Shutdown shuts down the server gracefully

• ctx: optional context for how long to wait for threads to exit
• — default: 3 s
• err: only the fiurst invocation receive errors

func (*Https) Shutdown2

func (s *Https) Shutdown2(errp *error, ctx ...context.Context)

Shutdown2 is deferrable Shutdown

func (*Https) ShutdownCh

func (s *Https) ShutdownCh() (ch parl.AwaitableCh)

ShutdownCh triggers when the first Shutdown has completes

func (*Https) TLS

func (s *Https) TLS(socketAddress pnet.SocketAddress) (tlsListener net.Listener, err error)

TLS creates a TLS listener

• can only be invoked once or panic
• errCh closes on server shutdown
• non-blocking, all errors are sent on the error channel
• if nearSocket.Addr is invalid, all interfaces for IPv6 if allowed, IPv4 otherwise is used
• if nearSocket.Port is zero:
• — if network is NetworkDefault: ephemeral port
• — otherwise port 443 “:https” is used

type LogCapturer

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

func (*LogCapturer) Write

func (c *LogCapturer) Write(p []byte) (n int, err error)