phttp

Documentation

Index

• Constants
• func NewLogCapturer(logF parl.PrintfFunc) (errorLog *log.Logger)
• type HandlerFunc
• 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) HandleFunc(pattern string, handler HandlerFunc)
  • func (s *Https) Listen(socketAddress pnet.SocketAddress) (nearAddrPort netip.AddrPort, listener net.Listener, err error)
  • func (s *Https) Serve(listener net.Listener)
  • 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 (
	// default port for https: 443, or address for localhost IPv4 or IPv6 port 443
	HttpsPort uint16 = 443
)

Functions

func NewLogCapturer

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

Types

type HandlerFunc

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

HandlerFunc is the signature for URL handlers

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) 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) Serve

func (s *Https) Serve(listener net.Listener)

Serve is a thread invoking http.Server.Serve providing:

• await via wg
• error collection

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)