fdstore

package module
v1.2.3 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: May 24, 2024 License: MIT Imports: 15 Imported by: 8

README

fdstore

Go Reference Test

A helper package to communicate with systemd through the sd_notify api, implements an abstraction layer on top of the file descriptor store of systemd.

Documentation

Index

Constants

This section is empty.

Variables

View Source 
var (
	ErrShortWrite     = errors.New("short write")
	ErrNoFile         = errors.New("File method missing")
	ErrNoSocket       = errors.New("NOTIFY_SOCKET is empty")
	ErrNotOurName     = errors.New("FDNAME was not the correct format")
	ErrWrongType      = errors.New("fd is of the wrong type")
	ErrDataRead       = errors.New("failed to read data from memfd")
	ErrUnexpectedRead = errors.New("did not expect to read anything")
)
View Source 
var (
	NOTIFY_SOCKET  = "NOTIFY_SOCKET"
	LISTEN_PID     = "LISTEN_PID"
	LISTEN_FDS     = "LISTEN_FDS"
	LISTEN_FDNAMES = "LISTEN_FDNAMES"
)

Functions

func AsConn 

func AsConn(file *os.File) (net.Conn, error)

AsConn is a helper function that tries to convert the file given to a net.Conn, the passed in file is closed on success

func AsListener 

func AsListener(file *os.File) (net.Listener, error)

AsListener is a helper function that tries to convert the file given to a net.Listener, the passed in file is closed on success

func IsValidFDName 

func IsValidFDName(name string) bool

func Notify 

func Notify(state ...State) error

Notify is like sd_notify (https://www.freedesktop.org/software/systemd/man/latest/sd_notify.html#Description)

func NotifyConn 

func NotifyConn(conn *net.UnixConn, state ...State) error

NotifyConn is like sd_notify (https://www.freedesktop.org/software/systemd/man/latest/sd_notify.html#Description), but lets you pass in your own connection to use to write to

func NotifySocket 

func NotifySocket() (*net.UnixConn, error)

NotifySocket returns a connected UnixConn to the path in env NOTIFY_SOCKET

func NotifySocketNamed added in v1.2.0 

func NotifySocketNamed(name string) (*net.UnixConn, error)

NotifySocketNamed is like NotifySocket but lets you pick the name of the socket

func NotifyWithFDs 

func NotifyWithFDs(name string, files []*os.File, state ...State) error

NotifyWithFDs is like sd_notify_with_fds We add FDSTORE=1 and FDNAME={name} for you with the name given, the rest of state is prepended before the other two

func NotifyWithFDsConn 

func NotifyWithFDsConn(conn *net.UnixConn, name string, files []*os.File, state ...State) error

NotifyWithFDsConn is NotifyWithFDs but lets you pass your own connection

func WaitBarrier 

func WaitBarrier(timeout time.Duration) error

WaitBarrier is like sd_notify_barrier

func WaitBarrierConn 

func WaitBarrierConn(conn *net.UnixConn, timeout time.Duration) error

WaitBarrierConn is WaitBarrier but lets you pass your own connection

Types

type ConnEntry 

type ConnEntry struct {
	Conn net.Conn
	// contains filtered or unexported fields
}

ConnEntry is the type returned by the RemoveConn helper

type Entry 

type Entry struct {

	// File is the file associated with this entry
	File *os.File
	// contains filtered or unexported fields
}

type Filer 

type Filer interface {
	File() (*os.File, error)
}

type ListenerEntry 

type ListenerEntry struct {
	Listener net.Listener
	// contains filtered or unexported fields
}

ListenerEntry is the type returned by the RemoveListener helper

type LogFn added in v1.2.0 

type LogFn func(string)

type NotifyAccessOption 

type NotifyAccessOption string
const (
	NotifyAccessNone NotifyAccessOption = "none"
	NotifyAccessAll  NotifyAccessOption = "all"
	NotifyAccessMain NotifyAccessOption = "main"
	NotifyAccessExec NotifyAccessOption = "exec"
)

type Option added in v1.2.0 

type Option func(*storeOptions)

func ListenFDNamesOpt added in v1.2.0 

func ListenFDNamesOpt(name string) Option

ListenFDNamesOpt changes what environment variable to use instead of LISTEN_FDNAMES

func ListenFDStartOpt added in v1.2.0 

func ListenFDStartOpt(n int) Option

ListenFDStartOpt changes at what fd number to start, the default is 3 since 0, 1, 2 are stdin, stdout, stderr respectively.

func ListenFDsOpt added in v1.2.0 

func ListenFDsOpt(name string) Option

ListenFDsOpt changes what environment variable to use instead of LISTEN_FDS

func ListenPIDOpt added in v1.2.0 

func ListenPIDOpt(name string) Option

ListenPIDOpt changes what environment variable to use instead of LISTEN_PID

func LoggerOpt added in v1.2.0 

func LoggerOpt(fn LogFn) Option

LoggerOpt changes where log lines go to, the default uses the log pkg

func NotifySocketOpt added in v1.2.0 

func NotifySocketOpt(name string) Option

NotifySocketOpt changes what environment variable to use instead of NOTIFY_SOCKET

type State 

type State string
const (
	Ready           State = "READY=1"
	Reloading       State = "RELOADING=1"
	Stopping        State = "STOPPING=1"
	Watchdog        State = "WATCHDOG=1"
	WatchdogTrigger State = "WATCHDOG=trigger"
	FDStore         State = "FDSTORE=1"
	FDPoll          State = "FDPOLL=0"
	Barrier         State = "BARRIER=1"
)

func Combine 

func Combine(state ...State) State

func Errno 

func Errno(errno syscall.Errno) State

func FDName 

func FDName(name string) State

func FDStoreRemove 

func FDStoreRemove(name string) State

func MainPID 

func MainPID(pid uint) State

func MonotonicUsec 

func MonotonicUsec() State

MonotonicUsec is not implemented, since there is no clear way to get the value of CLOCK_MONOTONIC right now

func NotifyAccess 

func NotifyAccess(na NotifyAccessOption) State

func Status 

func Status(status string) State

type Store 

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

Store is an abstraction on top of the file descriptor store of systemd, it lets you collect files, connections and listeners before sending them over to systemd for storage during restarts

func NewStore 

func NewStore(opts ...Option) *Store

NewStore creates a new Store instance with the options given. Store is an abstraction on top of the systemd file descriptor store interface that lets you pass fds to systemd between service restarts. The defaults are configured to use what systemd uses.

func NewStoreListenFDs 

func NewStoreListenFDs() *Store

NewStoreListenFDs is a helper function to use the systemd default configuration and read and process the files stored in the fdstore. Equal to NewStore() followed by a call to Restore()

func (*Store) AddConn 

func (s *Store) AddConn(conn net.Conn, name string, data []byte) error

AddConn is like AddFile but takes a net.Conn, it is expected that the net.Conn given implements Filer. AddConn duplicates the connection fd

Returns error matching ErrNoFile if no File method was found or whatever the call to File() itself returns if it errors

func (*Store) AddFile 

func (s *Store) AddFile(file *os.File, name string, data []byte) error

AddFile adds a file to the store with the name given and associated data. The data is stored in an memfd when passed through the socket and can be any kind of data. The file given is duplicated before storing it

func (*Store) AddFiler 

func (s *Store) AddFiler(filer Filer, name string, data []byte) error

AddFiler is like AddFile but takes any type with a File() (*os.File, error) method

Returns error from File() if any.

func (*Store) AddListener 

func (s *Store) AddListener(ln net.Listener, name string, state []byte) error

AddListener is like AddFile but takes a net.Listener, is is expected that the net.Listener given implements Filer. AddListener duplicates the listener fd

Returns error matching ErrNoFile if no File method was found or whatever the call to File() itself returns if it errors

func (*Store) Close 

func (s *Store) Close()

Close calls close on all files contained in the store and empties its internal map

func (*Store) RemoveConn 

func (s *Store) RemoveConn(name string) (res []ConnEntry, err error)

RemoveConn finds and removes the entries associated with the name given and tries to return them as net.Conn, entries are not removed or returned if an error occurs.

Returns error matching ErrWrongType if an entry could not be converted

func (*Store) RemoveFile 

func (s *Store) RemoveFile(name string) []Entry

RemoveFile finds and removes the entries associated with the name given and returns them.

func (*Store) RemoveListener 

func (s *Store) RemoveListener(name string) (res []ListenerEntry, err error)

RemoveConn finds and removes the entries associated with the name given and tries to return them as net.Listener, entries are not removed or returned if an error occurs.

Returns error matching ErrWrongType if an entry could not be converted

func (*Store) Restore added in v1.2.0 

func (s *Store) Restore()

Restore tries to restore the files from the fdstore, files that don't match what we expect are closed and removed from the fdstore through FDSTOREREMOVE, the environment variables configured to be used are unset after a call to Restore

func (*Store) RestoreFilelist added in v1.2.0 

func (s *Store) RestoreFilelist(filelist map[string][]*os.File)

RestoreFilelist takes a list of files with names, typically retrieved from another process and tries to parse the names as if they were send by Store.Send

func (*Store) Send 

func (s *Store) Send() error

Send sends the contents of the store over the configured NOTIFY_SOCKET with the systemd sd_pid_notify_with_fds api

func (*Store) SendConn 

func (s *Store) SendConn(conn *net.UnixConn) error

SendConn is like Send but lets you pass in your own conn

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.