anyhttp

README

Create http server listening on unix sockets and systemd socket activated fds

Quick Usage

go get go.balki.me/anyhttp

Just replace http.ListenAndServe with anyhttp.ListenAndServe.

- http.ListenAndServe(addr, h)
+ anyhttp.ListenAndServe(addr, h)

Address Syntax

Unix socket

Syntax

unix?path=<socket_path>&mode=<socket file mode>&remove_existing=<true|false>

Examples

unix?path=relative/path.sock
unix?path=/var/run/app/absolutepath.sock
unix?path=/run/app.sock&mode=600&remove_existing=false

option	description	default
path	path to unix socket	Required
mode	socket file mode	666
remove_existing	Whether to remove existing socket file or fail	true

Systemd Socket activated fd:

Syntax

sysd?idx=<fd index>&name=<fd name>&check_pid=<true|false>&unset_env=<true|false>&idle_timeout=<duration>

Only one of idx or name has to be set

Examples:

# First (or only) socket fd passed to app
sysd?idx=0

# Socket with FileDescriptorName
sysd?name=myapp

# Using default name and auto shutdown if no requests received in last 30 minutes
sysd?name=myapp.socket&idle_timeout=30m

option	description	default
name	Name configured via FileDescriptorName or socket file name	Required
idx	FD Index. Actual fd num will be 3 + idx	Required
idle_timeout	time to wait before shutdown. syntax	no auto shutdown
check_pid	Check process PID matches LISTEN_PID	true
unset_env	Unsets the LISTEN* environment variables, so they don't get passed to any child processes	true

TCP

If the address is not one of above, it is assumed to be tcp and passed to http.ListenAndServe.

Examples:

:http
:8888
127.0.0.1:8080

Documentation

https://pkg.go.dev/go.balki.me/anyhttp

Related links

• https://gist.github.com/teknoraver/5ffacb8757330715bcbcc90e6d46ac74#file-unixhttpd-go
• https://github.com/coreos/go-systemd/tree/main/activation

Documentation

Overview

Package anyhttp has helpers to serve http from unix sockets and systemd socket activated fds

Index

• Constants
• Variables
• func ListenAndServe(addr string, h http.Handler) error
• func ListenAndServeTLS(addr string, certFile string, keyFile string, h http.Handler) error
• func UnsetSystemdListenVars()
• type AddressType
  • func GetListener(addr string) (net.Listener, AddressType, any, error)
• type ServerCtx
  • func Serve(addr string, h http.Handler) (*ServerCtx, error)
  • func ServeTLS(addr string, h http.Handler, certFile string, keyFile string) (*ServerCtx, error)
  • func (s *ServerCtx) Addr() net.Addr
  • func (s *ServerCtx) Shutdown(ctx context.Context) error
  • func (s *ServerCtx) Wait() error
• type SysdConfig
  • func NewSysDConfigWithFDIdx(fdIdx int) SysdConfig
  • func NewSysDConfigWithFDName(fdName string) SysdConfig
  • func (s *SysdConfig) GetListener() (net.Listener, error)
• type UnixSocketConfig
  • func NewUnixSocketConfig(socketPath string) UnixSocketConfig
  • func (u *UnixSocketConfig) GetListener() (net.Listener, error)

Constants

const StartFD = 3

StartFD is the starting file descriptor number

Variables

var DefaultSysdConfig = SysdConfig{
	CheckPID: true,
	UnsetEnv: true,
}

DefaultSysdConfig has the default values for SysdConfig

var DefaultUnixSocketConfig = UnixSocketConfig{
	SocketMode:     0666,
	RemoveExisting: true,
}

DefaultUnixSocketConfig has defaults for UnixSocketConfig

Functions

func ListenAndServe

func ListenAndServe(addr string, h http.Handler) error

ListenAndServe is the drop-in replacement for `http.ListenAndServe`. Supports unix and systemd sockets in addition

func ListenAndServeTLS

func ListenAndServeTLS(addr string, certFile string, keyFile string, h http.Handler) error

func UnsetSystemdListenVars

func UnsetSystemdListenVars()

UnsetSystemdListenVars unsets the LISTEN* environment variables so they are not passed to any child processes

Types

type AddressType

type AddressType string

AddressType of the address passed

var (
	// UnixSocket - address is a unix socket, e.g. unix?path=/run/foo.sock
	UnixSocket AddressType = "UnixSocket"
	// SystemdFD - address is a systemd fd, e.g. sysd?name=myapp.socket
	SystemdFD AddressType = "SystemdFD"
	// TCP - address is a TCP address, e.g. :1234
	TCP AddressType = "TCP"
	// Unknown - address is not recognized
	Unknown AddressType = "Unknown"
)

func GetListener

func GetListener(addr string) (net.Listener, AddressType, any, error)

GetListener is low level function for use with non-http servers. e.g. tcp, smtp Caller should handle idle timeout if needed

type ServerCtx

type ServerCtx struct {
	AddressType      AddressType
	Listener         net.Listener
	Server           *http.Server
	Idler            idle.Idler
	Done             <-chan error
	UnixSocketConfig *UnixSocketConfig
	SysdConfig       *SysdConfig
}

func Serve

func Serve(addr string, h http.Handler) (*ServerCtx, error)

Serve creates and serves a HTTP server.

func ServeTLS

func ServeTLS(addr string, h http.Handler, certFile string, keyFile string) (*ServerCtx, error)

ServeTLS creates and serves a HTTPS server.

func (*ServerCtx) Addr

func (s *ServerCtx) Addr() net.Addr

func (*ServerCtx) Shutdown

func (s *ServerCtx) Shutdown(ctx context.Context) error

func (*ServerCtx) Wait

func (s *ServerCtx) Wait() error

type SysdConfig

type SysdConfig struct {
	// Integer value starting at 0. Either index or name is required
	FDIndex *int
	// Name configured via FileDescriptorName or the default socket file name. Either index or name is required
	FDName *string
	// Check process PID matches LISTEN_PID
	CheckPID bool
	// Unsets the LISTEN* environment variables, so they don't get passed to any child processes
	UnsetEnv bool
	// Shutdown http server if no requests received for below timeout
	IdleTimeout *time.Duration
}

SysdConfig has the configuration for the socket activated fd

func NewSysDConfigWithFDIdx

func NewSysDConfigWithFDIdx(fdIdx int) SysdConfig

NewSysDConfigWithFDIdx creates SysdConfig with defaults and fdIdx

func NewSysDConfigWithFDName

func NewSysDConfigWithFDName(fdName string) SysdConfig

NewSysDConfigWithFDName creates SysdConfig with defaults and fdName

func (*SysdConfig) GetListener

func (s *SysdConfig) GetListener() (net.Listener, error)

GetListener returns the FileListener created with socketed activated fd

type UnixSocketConfig

type UnixSocketConfig struct {

	// Absolute or relative path of socket, e.g. /run/app.sock
	SocketPath string

	// Socket file permission
	SocketMode fs.FileMode

	// Whether to delete existing socket before creating new one
	RemoveExisting bool
}

UnixSocketConfig has the configuration for Unix socket

func NewUnixSocketConfig

func NewUnixSocketConfig(socketPath string) UnixSocketConfig

NewUnixSocketConfig creates a UnixSocketConfig with the default values and the socketPath passed

func (*UnixSocketConfig) GetListener

func (u *UnixSocketConfig) GetListener() (net.Listener, error)

GetListener returns the unix socket listener