phttp

Documentation

Index

• Constants
• type HandlerFunc
• type Http
  • func NewHttp(nearSocket netip.AddrPort, network pnet.Network) (hp *Http)
  • func (s *Http) HandleFunc(pattern string, handler HandlerFunc)
  • func (s *Http) Listen() (errCh <-chan error)
  • func (s *Http) SendErr(err error)
  • func (s *Http) Shutdown()
• type Https
  • func NewHttps(nearSocket netip.AddrPort, network pnet.Network, certDER parl.CertificateDer, ...) (hp *Https)
  • func (s *Https) Listen() (errCh <-chan error)
  • func (s *Https) TLS() (tlsListener net.Listener, err error)

Constants

const (
	// default port for http: 80, or address for localhost IPv4 or IPv6 port 80
	HttpAddr = ":http"
)

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

Types

type HandlerFunc

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

HandlerFunc is the signature for URL handlers

type Http

type Http struct {
	// used for [http.Server.Listen] invocation
	//	- "tcp", "tcp4", "tcp6", "unix" or "unixpacket"
	Network pnet.Network
	// Close() ListenAndServe() ListenAndServeTLS() RegisterOnShutdown()
	// Serve() ServeTLS() SetKeepAlivesEnabled() Shutdown()
	http.Server
	// real-time server error stream, unbound non-blocking
	//	- [Http.SendErr] invocations
	//   - shutdown error
	ErrCh parl.NBChan[error]
	// near socket address, protocol is tcp
	Near netip.AddrPort
	// allows to wait for listen
	//	- when triggered, [Http.Near] is present
	ListenAwaitable parl.Awaitable
	// allows to wait for end of listen
	//	- end of thread launched by [Http.Listen]
	EndListenAwaitable parl.Awaitable

	// whether Listen invocation is allowed
	NoListen atomic.Bool
	// Cancel of listening set-up
	Cancel atomic.Pointer[context.CancelFunc]
	// contains filtered or unexported fields
}

Http is an http server instance

• based on http.Server
• has listener thread
• all errors sent on channel
• idempotent deferrable panic-free shutdown
• awaitable, observable

func NewHttp

func NewHttp(nearSocket netip.AddrPort, network pnet.Network) (hp *Http)

NewHttp creates http server for default “localhost:80”

• 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 80 “:http” is used
• for NetworkDefault, NetworkTCP is used
• panic for bad Network

Usage:

var s = NewHttp(netip.AdddrPort{}, pnet.NetworkTCP)
s.HandleFunc("/", myHandler)
defer s.Shutdown()
for err := range s.Listen() {

func (*Http) HandleFunc

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

HandleFunc registers a URL-handler for the server

func (*Http) Listen

func (s *Http) Listen() (errCh <-chan 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

func (*Http) SendErr

func (s *Http) SendErr(err error)

SendErr sends errors on the server’s error channel

func (*Http) Shutdown

func (s *Http) Shutdown()

idempotent panic-free shutdown that does not return prior to server shut down

type Https

type Https struct {
	Http
	Cert    parl.CertificateDer
	Private crypto.Signer
}

Http is an http server instance

• based on http.Server
• has listener thread
• all errors sent on channel
• idempotent deferrable panic-free shutdown
• awaitable, observable

func NewHttps

func NewHttps(nearSocket netip.AddrPort, network pnet.Network, certDER parl.CertificateDer, signer crypto.Signer) (hp *Https)

NewHttp creates http server for default “localhost:443”

• 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

Usage:

var s = NewHttps(netip.AdddrPort{}, pnet.NetworkTCP)
s.HandleFunc("/", myHandler)
defer s.Shutdown()
for err := range s.Listen() {

func (*Https) Listen

func (s *Https) Listen() (errCh <-chan 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

func (*Https) TLS

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