pwrap

Documentation

Overview

Package pwrap provides a process wrapper that is suitable to be executed inside a tmux session, allowing to later retriving its stdout, stderr and initial configuration.

Index

• Constants
• func Exec(name string, args ...string) func(*PWrap) error
• func OnCommand(h func(*UnixCommBridge, string) error) func(*UnixCommBridge)
• func OverrideSID(sid string) func(*PWrap) error
• func Register(url string) func(*PWrap) error
• func RootDir(path string) func(*PWrap) error
• type PWrap
  • func New(opts ...func(*PWrap) error) (*PWrap, error)
  • func (p *PWrap) Callback(err error) error
  • func (p *PWrap) KillSession() error
  • func (p *PWrap) Open(rel string, flag int, mode os.FileMode) (*os.File, error)
  • func (p *PWrap) Path(rel string) string
  • func (p *PWrap) Register(port int) error
  • func (p *PWrap) Run(ctx context.Context) error
  • func (p *PWrap) SID() string
  • func (p *PWrap) SockPath() string
  • func (p *PWrap) StartSession() (string, error)
  • func (p *PWrap) Trash() error
  • func (p *PWrap) WorkDir() string
• type UnixCommBridge
  • func NewUnixCommBridge(ctx context.Context, path string, opts ...func(*UnixCommBridge)) (*UnixCommBridge, error)
  • func (b *UnixCommBridge) Close() error
  • func (b *UnixCommBridge) Open(ctx context.Context)
  • func (b *UnixCommBridge) Write(p []byte) (int, error)
  • func (b *UnixCommBridge) WriteProgressUpdate(d string, stage, stages, partial, tot int) error
• type WrapStatus
• type WriteProgressUpdateFunc

Constants

const (
	FileStderr = "stderr"
	FileStdout = "stdout"
	FileConfig = "config"
	FileSID    = "sid"
)

Functions

func Exec

func Exec(name string, args ...string) func(*PWrap) error

Exec sets the executable and first arguments option.

func OnCommand

func OnCommand(h func(*UnixCommBridge, string) error) func(*UnixCommBridge)

OnCommand sets the onCommand function option. When a command is recevied through the socket, this handler will be called.

func OverrideSID

func OverrideSID(sid string) func(*PWrap) error

OverrideSID sets the sid option. This function has to be called before "RootDir" if used in the “New” function in order for it to make effect.

func Register

func Register(url string) func(*PWrap) error

Register sets the register url option.

func RootDir

func RootDir(path string) func(*PWrap) error

RootDir sets the root directory option.

Types

type PWrap

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

PWrap is a process wrapper.

func New

func New(opts ...func(*PWrap) error) (*PWrap, error)

New is used to instantiate new PWrap instances.

func (*PWrap) Callback

func (p *PWrap) Callback(err error) error

func (*PWrap) KillSession

func (p *PWrap) KillSession() error

KillSession kills the associated tmux session, if any is running.

func (*PWrap) Open

func (p *PWrap) Open(rel string, flag int, mode os.FileMode) (*os.File, error)

Open opens a file that must be present in "p"'s root directory. Returns an error otherwise. It is caller's responsibility to close the file.

func (*PWrap) Path

func (p *PWrap) Path(rel string) string

Path returns the full path of the file as if it were inside "p"'s root directory.

func (*PWrap) Register

func (p *PWrap) Register(port int) error

Register performs an HTTP POST request to `regURL`, if present. It registers "port" with the remote handler, and returnes a nil error only if the response's status is 200.

func (*PWrap) Run

func (p *PWrap) Run(ctx context.Context) error

Run executes "p"'s command and waits for it to exit. Its stderr and stdout pipes are connected to their relative files inside process's root directory. The underlying program is executed running `<ename> --config=<configuration file path>`. If an error occurs, is is both returned and written into wrapper's stderr, if possible.

func (*PWrap) SID

func (p *PWrap) SID() string

SID returns the assigned session identifier.

func (*PWrap) SockPath

func (p *PWrap) SockPath() string

SockPath returns a suitable socket address path for this session. It does not use the working directory as in some systems the socket path cannot be longer than "n" chars. Another reason is that this file is not actually a file that should be managed by the wrapper but by the child command itself.

func (*PWrap) StartSession

func (p *PWrap) StartSession() (string, error)

StartSession starts the process wrapper in a tmux session. There is not guarantee that the process will still be running after this function returns. The session identifier returned will be stored indide the relative “FileSID” file. This function is a non blocking function.

func (*PWrap) Trash

func (p *PWrap) Trash() error

Trash removes any traces of the process from the system. It even kills the session if any is running.

func (*PWrap) WorkDir

func (p *PWrap) WorkDir() string

WorkDir returns the current working directory.

type UnixCommBridge

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

UnixCommBridge is a Unix Socket listener that extends the communication channels available by wrapped commands. If a command is capable of providing updates about is progress in completing the task, it can use this socket to write updates to it and receive commands from it. The socket can be used to enable the communication between the child process and the process wrapper, which will expose the socket to the internet through its HTTP API.

func NewUnixCommBridge

func NewUnixCommBridge(ctx context.Context, path string, opts ...func(*UnixCommBridge)) (*UnixCommBridge, error)

NewUnixCommBridge starts a Unix Domain Socket listener on “path”. Is is the caller's responsibility to close the listener when it's done.

func (*UnixCommBridge) Close

func (b *UnixCommBridge) Close() error

Close closes the unix listener and will remove its socket file.

func (*UnixCommBridge) Open

func (b *UnixCommBridge) Open(ctx context.Context)

Open makes the socket accept new connections. Open is expected to run in its own gorountine. Context cancelation will not make the function quit, but it will close any pending connection activity. To make the function exit b.Close() should be used instead, which will close the underlying unix socket.

func (*UnixCommBridge) Write

func (b *UnixCommBridge) Write(p []byte) (int, error)

Write is an “io.Writer” implementation, which delivers the content written to each client listening on the socket.

func (*UnixCommBridge) WriteProgressUpdate

func (b *UnixCommBridge) WriteProgressUpdate(d string, stage, stages, partial, tot int) error

WriteProgressUpdate is an helper function that writes the data in the underlying socket, using csv for encoding. The first call to the function will also print the csv header.

type WrapStatus

type WrapStatus string

const (
	WrapStatusError   WrapStatus = "error"
	WrapStatusSuccess            = "success"
)

type WriteProgressUpdateFunc

type WriteProgressUpdateFunc func(d string, stage, stages, partial, tot int) error

WriteProgressUpdateFunc describes the signature of a progress writer function.