From 175cfa92e986536b503e47469ede499f1e647add Mon Sep 17 00:00:00 2001 From: Balakrishnan Balasubramanian Date: Thu, 20 Apr 2023 17:56:44 -0400 Subject: [PATCH] Add documentation --- README.md | 8 ++++---- anyhttp.go | 34 ++++++++++++++++++++++++++++------ 2 files changed, 32 insertions(+), 10 deletions(-) diff --git a/README.md b/README.md index 2eae9dd..95b0866 100644 --- a/README.md +++ b/README.md @@ -9,9 +9,9 @@ Just replace `http.ListenAndServe` with `anyhttp.ListenAndServe`. + anyhttp.ListenAndServe(addr, h) ``` -### Address Syntax +## Address Syntax -#### Unix socket +### Unix socket Syntax @@ -22,7 +22,7 @@ Examples unix/relative/path.sock unix//var/run/app/absolutepath.sock -#### Systemd Socket activated fd: +### Systemd Socket activated fd: Syntax @@ -40,7 +40,7 @@ Examples: # Using default name sysd/fdname/myapp.socket -#### TCP port +### TCP port If the address is a number less than 65536, it is assumed as a port and passed as `http.ListenAndServe(":",...)` diff --git a/anyhttp.go b/anyhttp.go index 12150cc..0943aea 100644 --- a/anyhttp.go +++ b/anyhttp.go @@ -13,47 +13,65 @@ import ( "syscall" ) +// UnixSocketConfig has the configuration for Unix socket type UnixSocketConfig struct { - SocketPath string - SocketMode fs.FileMode + + // 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 } +// DefaultUnixSocketConfig has defaults for UnixSocketConfig var DefaultUnixSocketConfig = UnixSocketConfig{ SocketMode: 0666, RemoveExisting: true, } +// NewUnixSocketConfig creates a UnixSocketConfig with the default values and the socketPath passed func NewUnixSocketConfig(socketPath string) UnixSocketConfig { usc := DefaultUnixSocketConfig usc.SocketPath = socketPath return usc } +// SysdConfig has the configuration for the socket activated fd type SysdConfig struct { - FDIndex *int - FDName *string + // 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 } +// DefaultSysdConfig has the default values for SysdConfig var DefaultSysdConfig = SysdConfig{ CheckPID: true, UnsetEnv: false, } +// NewSysDConfigWithFDIdx creates SysdConfig with defaults and fdIdx func NewSysDConfigWithFDIdx(fdIdx int) SysdConfig { sysc := DefaultSysdConfig sysc.FDIndex = &fdIdx return sysc } +// NewSysDConfigWithFDName creates SysdConfig with defaults and fdName func NewSysDConfigWithFDName(fdName string) SysdConfig { sysc := DefaultSysdConfig sysc.FDName = &fdName return sysc } +// GetListener returns the unix socket listener func (u *UnixSocketConfig) GetListener() (net.Listener, error) { if u.RemoveExisting { @@ -74,6 +92,7 @@ func (u *UnixSocketConfig) GetListener() (net.Listener, error) { return l, nil } +// StartFD is the starting file descriptor number const StartFD = 3 func makeFdListener(fd int, name string) (net.Listener, error) { @@ -86,6 +105,7 @@ func makeFdListener(fd int, name string) (net.Listener, error) { return l, nil } +// GetListener returns the FileListener created with socketed activated fd func (s *SysdConfig) GetListener() (net.Listener, error) { if s.UnsetEnv { @@ -117,9 +137,8 @@ func (s *SysdConfig) GetListener() (net.Listener, error) { fd := StartFD + idx if idx < len(fdNames) { return makeFdListener(fd, fdNames[idx]) - } else { - return makeFdListener(fd, fmt.Sprintf("sysdfd_%d", fd)) } + return makeFdListener(fd, fmt.Sprintf("sysdfd_%d", fd)) } if s.FDName != nil { @@ -159,6 +178,8 @@ func GetListener(addr string) (net.Listener, error) { return nil, nil } +// ListenAndServe is the drop-in replacement for `http.ListenAndServe`. +// Supports unix and systemd sockets in addition func ListenAndServe(addr string, h http.Handler) error { listener, err := GetListener(addr) @@ -181,6 +202,7 @@ func ListenAndServe(addr string, h http.Handler) error { return http.ListenAndServe(addr, h) } +// UnsetSystemdListenVars unsets the LISTEN* environment variables so they are not passed to any child processes func UnsetSystemdListenVars() { os.Unsetenv("LISTEN_PID") os.Unsetenv("LISTEN_FDS")