node

package
v0.3.0-beta Latest Latest
Warning

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

 Go to latest Published: Oct 15, 2022 License: GPL-3.0 Imports: 25 Imported by: 0

Documentation

Index

Constants

View Source 
const RootNodeID = "-"

RootNodeID is the ID used for the root node in node.Do.

Variables

This section is empty.

Functions

func Do 

func Do(rn *Run, src ExeSource, ctrl Control, data chan interface{})

Do runs a Run tree in an in-process "root" node, and sends data items back on the given channel. The item types that may be sent include StreamInfo, StreamIO, PacketInfo, PacketIO, FileData, LogEntry and Error.

Do is used by the antler package and executable.

func PipeConn 

func PipeConn() (conn1, conn2 io.ReadWriteCloser)

PipeConn returns a pair of ReadWriteClosers connected by two Pipes, one each direction.

func Serve 

func Serve(nodeID string, ctrl Control, conn io.ReadWriteCloser) error

Serve runs a node whose parent is connected using the given conn. This is used by the standalone node executable.

An error is returned if there was a failure when serving the connection, or the node was explicitly canceled. Serve closes the conn when complete.

func StdioConn 

func StdioConn() io.ReadWriteCloser

StdioConn is a ReadWriteCloser used for stdio. On Close, only stdout is closed.

Types

type Child 

type Child struct {
	// Run is the Run to execute on Node.
	Run

	// Node is the node to execute Run on. It must be a valid, nonzero value.
	Node Node
}

Child is a Run to execute on a child Node.

type Control 

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

Control is used to send control signals to nodes.

func NewControl 

func NewControl() Control

NewControl returns a new Control.

func (Control) Cancel 

func (c Control) Cancel(reason string)

Cancel sends a cancellation request to all attached nodes.

func (Control) Stop 

func (c Control) Stop()

Stop releases any resources. Cancel must not be called after Stop.

type Direction 

type Direction string

Direction is the client to server sense for a Stream. 

const (
	Up   Direction = "up"   // client to server
	Down Direction = "down" // server to client
)

type Download 

type Download struct {
	Transfer
}

Download is a stream transfer from server to client.

func (Download) String 

func (d Download) String() string

type Error 

type Error struct {
	Time    time.Time // the node time that the error occurred
	NodeID  string    // the node ID
	Tag     string    // a string for error categorization
	Message string    // the error text
}

Error represents an unrecoverable error that occurred on a node.

func (Error) Error 

func (e Error) Error() string

func (Error) String 

func (e Error) String() string

type ErrorFactory 

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

ErrorFactory provides methods to create and return Errors.

func (ErrorFactory) NewError 

func (f ErrorFactory) NewError(message string) Error

NewError returns a new Error with the given message.

func (ErrorFactory) NewErrore 

func (f ErrorFactory) NewErrore(err error) Error

NewErrore returns an Error from the given error. If the given error is already an Error, the existing error is returned.

func (ErrorFactory) NewErrorf 

func (f ErrorFactory) NewErrorf(format string, a ...interface{}) Error

NewErrorf returns an Error with its Message formatted with prinf style args.

type ExeName 

type ExeName string

ExeName represents an antler node executable name.

func PlatformExeName 

func PlatformExeName(platform string) ExeName

PlatformExeName returns an ExeName for the given platform (e.g. linux-amd64).

func (ExeName) Platform 

func (n ExeName) Platform() string

Platform returns the platform for the name (e.g. linux-amd64).

func (ExeName) String 

func (n ExeName) String() string

func (ExeName) Valid 

func (n ExeName) Valid() bool

Valid returns true if this is an executable name for a standalone node.

type ExeSource 

type ExeSource interface {
	// Reader returns a ReadCloser for the given platform's node executable.
	Reader(platform string) (io.ReadCloser, error)

	// Size returns the size of the given platform's node executable.
	Size(platform string) (int64, error)

	// Platforms returns the platforms for which executables are available.
	Platforms() ([]string, error)
}

An ExeSource provides contents and metadata for node executables.

type Feedback 

type Feedback map[string]interface{}

Feedback contains key/value pairs, which are returned by runners for use by subsequent runners, and are stored in the result Data. Values must be supported by gob.

type FileData 

type FileData struct {
	Name string // the name of the file
	Data []byte // the data
}

FileData contains a chunk of binary data to be saved in a file.

func (FileData) String 

func (f FileData) String() string

type Flow 

type Flow string

Flow is a string name identifying a flow.

type Flower 

type Flower interface {
	Flow() Flow
}

A Flower wraps the Flow method, to return a Flow associated with the implementation.

type Local 

type Local struct {
}

Local is a launcher used to start a node as a locally executed process.

type LogEntry 

type LogEntry struct {
	Time   time.Time // the time of the LogEntry, per the node's clock
	NodeID string    // the ID of the node that created the LogEntry
	Tag    string    // tags the LogEntry for categorization
	Text   string    // the text message for the LogEntry
}

LogEntry represents one log entry.

func (LogEntry) String 

func (e LogEntry) String() string

String returns the entry for display.

type MessageFilter 

type MessageFilter struct {
	// File is a valid glob pattern of FileData names to accept.
	File []string

	// Log indicates whether to accept (true) or reject (false) LogEntry's.
	Log bool

	// Flows to accept.
	Flow []Flow
}

MessageFilter selects messages based on some simple type and field criteria.

type Netns 

type Netns struct {
	// Name is the name of the namespace. If set, this namespace will either be
	// created or used, depending on the value of the Create field.
	Name string

	// Create indicates whether to create a namespace (true) or use an existing
	// one (false). If Create is true with no Name set, the Node ID will be used
	// as the network namespace name.
	Create bool
}

Netns represents the Linux network namespace configuration to use when launching a Node (man ip-netns(8)).

type Node 

type Node struct {
	ID       string    // identifies the Node
	Platform string    // the Node's platform (e.g. linux-amd64)
	Launcher launchers // union of available launchers
	Netns    Netns     // parameters for Linux network namespaces
}

Node represents the information needed to launch a node. It must stay a value object with no pointer fields, so Nodes may be compared and used as map keys.

The zero value for Node is used for the parent Node.

func (Node) String 

func (n Node) String() string

String returns the Node ID, or "parent" for the parent node.

type Packet 

type Packet struct {
	PacketHeader

	// Len is the total length of the packet, in bytes, including the header.
	Len int
	// contains filtered or unexported fields
}

Packet represents a Packet sent in either direction between a PacketClient and PacketServer. Only the header is included in the body of the Packet. Padding is added to reach the Packet Length.

type PacketClient 

type PacketClient struct {
	// Addr is the dial address, as specified to the address parameter in
	// net.Dial (e.g. "addr:port").
	Addr string

	// Protocol is the protocol to use (udp, udp4 or udp6).
	Protocol string

	// Flow is the flow identifier for traffic between the client and server.
	Flow Flow

	// MaxPacketSize is the maximum size of a received packet.
	MaxPacketSize int

	Sender []PacketSenders
}

PacketClient is the client used for packet oriented protocols.

func (*PacketClient) Run 

func (c *PacketClient) Run(ctx context.Context, arg runArg) (ofb Feedback,
	err error)

Run implements runner

type PacketFlag 

type PacketFlag byte

PacketFlag represents the flag bits on a packet. 

const (
	// FlagEcho indicates that the packet requests an echo.
	FlagEcho PacketFlag = 1 << iota

	// FlagReply indicates that the packet is a reply to an echo request.
	FlagReply
)

type PacketHeader 

type PacketHeader struct {
	// Flag contains the packet flags.
	Flag PacketFlag

	// Seq is the sequence number assigned by the client.
	Seq Seq

	// Flow is the flow identifier, and corresponds to a client and server pair.
	Flow Flow
}

PacketHeader represents the header of the packet.

func (*PacketHeader) Len 

func (p *PacketHeader) Len() int

Len returns the length of the header, in bytes.

func (*PacketHeader) Read 

func (p *PacketHeader) Read(b []byte) (n int, err error)

Read implements io.Reader to "read" from the packet to bytes.

func (*PacketHeader) Write 

func (p *PacketHeader) Write(b []byte) (n int, err error)

Write implements io.Writer to "write" from bytes to the packet.

type PacketIO 

type PacketIO struct {
	// Packet is the packet.
	Packet

	// T is the node-relative time this PacketIO was recorded.
	T metric.RelativeTime

	// Sent is true for a sent packet, and false for received.
	Sent bool
}

PacketIO is a time series data point that records packet send and receive times.

func (PacketIO) String 

func (p PacketIO) String() string

type PacketInfo 

type PacketInfo struct {
	// Tinit is the base time for the flow's RelativeTime values.
	Tinit time.Time

	// Flow is the flow identifier.
	Flow Flow

	// Server indicates if this is from the server (true) or client (false).
	Server bool
}

PacketInfo contains information for a packet flow.

func (PacketInfo) String 

func (p PacketInfo) String() string

func (PacketInfo) Time 

func (p PacketInfo) Time(r metric.RelativeTime) time.Time

Time returns an absolute from a node-relative time.

type PacketSenders 

type PacketSenders struct {
	Unresponsive *Unresponsive
}

PacketSenders is the union of available packetSender implementations.

type PacketServer 

type PacketServer struct {
	// ListenAddr is the listen address, as specified to the address parameter
	// in net.ListenPacket (e.g. ":port" or "addr:port").
	ListenAddr string

	// Protocol is the protocol to use (udp, udp4 or udp6).
	Protocol string

	// MaxPacketSize is the maximum size of a received packet.
	MaxPacketSize int
	// contains filtered or unexported fields
}

PacketServer is the server used for packet oriented protocols.

func (*PacketServer) Cancel 

func (s *PacketServer) Cancel(rec *recorder) error

Cancel implements canceler

func (*PacketServer) Run 

func (s *PacketServer) Run(ctx context.Context, arg runArg) (ofb Feedback,
	err error)

Run implements runner

type Parallel 

type Parallel []Run

Parallel is a list of Runs executed concurrently.

type ResultStream 

type ResultStream struct {
	// Include accepts messages to stream.
	Include *MessageFilter

	// Exclude rejects messages to stream, and buffers them instead.
	Exclude *MessageFilter
}

ResultStream selects messages for either streaming or buffering.

func (*ResultStream) Run 

func (s *ResultStream) Run(ctx context.Context, arg runArg) (ofb Feedback,
	err error)

Run implements runner

type Run 

type Run struct {
	// Serial lists Runs to be executed sequentially
	Serial Serial

	// Parallel lists Runs to be executed concurrently
	Parallel Parallel

	// Schedule lists Runs to be executed on a schedule.
	Schedule *Schedule

	// Child is a Run to be executed on a child Node
	Child *Child

	// Runners is a union of the available runner implementations.
	//
	// NOTE: In the future, this may be an interface field, if CUE can be made
	// to choose a concrete type without using a field for each runner.
	Runners
}

Run represents the information needed to coordinate the execution of runners. Using the Serial, Parallel and Child fields, Runs may be arranged in a tree for sequential, concurrent and child node execution.

Run must be created with valid constraints, i.e. each Run must have exactly one of Serial, Parallel, Child or a Runners field set. Run is not safe for concurrent use, though Parallel Runs execute safely, concurrently.

type Runners 

type Runners struct {
	ResultStream *ResultStream
	Setup        *setup
	Sleep        *Sleep
	System       *System
	StreamClient *StreamClient
	StreamServer *StreamServer
	PacketServer *PacketServer
	PacketClient *PacketClient
}

Runners is a union of the available runner implementations. Only one of the runners may be non-nil.

type SSH 

type SSH struct {
	Destination string // ssh destination (man ssh(1))
}

SSH is a launcher used to start an Antler node remotely via ssh.

type Schedule 

type Schedule struct {
	// Wait lists the wait Durations to use. If Random is false, the chosen
	// Durations cycle repeatedly through Wait.
	Wait []metric.Duration

	// WaitFirst, if true, indicates to wait before the first Run as well.
	WaitFirst bool

	// Random, if true, indicates to select wait times from Wait randomly.
	// Otherwise, wait times are taken from Wait sequentially.
	Random bool

	// Sequential, if true, indicates to run the Runs in serial.
	Sequential bool

	// Run lists the Runs.
	Run []Run
	// contains filtered or unexported fields
}

Schedule lists Runs to be executed with wait times between each Run.

type Seq 

type Seq uint64

Seq is a packet sequence number.

type Serial 

type Serial []Run

Serial is a list of Runs executed sequentially.

type Sleep 

type Sleep metric.Duration

Sleep is a runner that sleeps for the given Duration, or until canceled.

func (*Sleep) Run 

func (s *Sleep) Run(ctx context.Context, arg runArg) (ofb Feedback, err error)

Run implements runner

func (*Sleep) UnmarshalText 

func (s *Sleep) UnmarshalText(text []byte) (err error)

UnmarshalText implements encoding.TextUnmarshaler.

type Stream 

type Stream struct {
	// Flow is the Stream's flow identifier.
	Flow Flow

	// Direction is the client to server sense.
	Direction Direction

	// CCA is the sender's Congestion Control Algorithm.
	CCA string
}

Stream represents one direction of a stream oriented flow.

func (Stream) Info 

func (s Stream) Info(server bool) StreamInfo

Info returns StreamInfo for this Stream.

func (Stream) String 

func (s Stream) String() string

type StreamClient 

type StreamClient struct {
	// Addr is the dial address, as specified to the address parameter in
	// net.Dial (e.g. "addr:port").
	Addr string

	// AddrKey is a key used to obtain the dial address from the incoming
	// Feedback, if Addr is not specified.
	AddrKey string

	// Protocol is the protocol to use (tcp, tcp4 or tcp6).
	Protocol string

	Streamers
}

StreamClient is the client used for stream oriented protocols.

func (*StreamClient) Run 

func (s *StreamClient) Run(ctx context.Context, arg runArg) (ofb Feedback,
	err error)

Run implements runner

type StreamIO 

type StreamIO struct {
	// Flow is the flow that this StreamIO is for.
	Flow Flow

	// T is the relative time this StreamIO was recorded.
	T metric.RelativeTime

	// Total is the total number of sent or received bytes.
	Total metric.Bytes

	// Sent is true for sent bytes, and false for received.
	Sent bool
}

StreamIO is a time series data point that records the progress of a stream as measured after read or write calls.

func (StreamIO) String 

func (s StreamIO) String() string

type StreamInfo 

type StreamInfo struct {
	// Tinit is the base time for the flow's RelativeTime values.
	Tinit time.Time

	Stream

	// Server indicates if this is from the server (true) or client (false).
	Server bool
}

StreamInfo contains information for a stream flow.

func (StreamInfo) String 

func (s StreamInfo) String() string

func (StreamInfo) Time 

func (s StreamInfo) Time(r metric.RelativeTime) time.Time

Time returns an absolute from a node-relative time.

type StreamServer 

type StreamServer struct {
	// ListenAddr is the listen address, as specified to the address parameter
	// in net.Listen (e.g. ":port" or "addr:port").
	ListenAddr string

	// ListenAddrKey is the key used in the returned Feedback for the listen
	// address, obtained using Listen.Addr.String(). If empty, the listen
	// address will not be included in the Feedback.
	ListenAddrKey string

	// Protocol is the protocol to use (tcp, tcp4 or tcp6).
	Protocol string
	// contains filtered or unexported fields
}

StreamServer is the server used for stream oriented protocols.

func (*StreamServer) Cancel 

func (s *StreamServer) Cancel(rec *recorder) error

Cancel implements canceler

func (*StreamServer) Run 

func (s *StreamServer) Run(ctx context.Context, arg runArg) (ofb Feedback,
	err error)

Run implements runner

type Streamers 

type Streamers struct {
	Upload   *Upload
	Download *Download
}

Streamers is the union of available streamer implementations.

type System 

type System struct {
	// Command is the command to run. The string is split into command name and
	// arguments using space as a delimiter, with no support for escaping. If
	// spaces are needed in arguments, use the Args field instead, or in
	// addition to Command.
	Command string

	// Args is a slice of arguments for the command. If Command is empty, then
	// Args[0] is the command name, otherwise the Args slice is appended to the
	// slice obtained by splitting Command.
	Args []string

	// Background indicates whether to run this command in the background (true)
	// or foreground (false). If true, Run will return as soon as the command is
	// started, and with an error if it could not be started and IgnoreErrors is
	// false. The Context will be cancelled after the rest of the Run tree is
	// complete, at which time the process will be killed, and the node will
	// wait for it to complete.
	Background bool

	// IgnoreErrors indicates whether to discard any errors (true) or not
	// (false).
	IgnoreErrors bool

	// Stdout selects the treatment for stdout. If empty, stdout is gathered and
	// emitted to the log as a single line when the command completes. If
	// "stream", stdout is emitted to the log a line at a time. If "quiet",
	// stdout is discarded. Otherwise, stdout is written to a file of the given
	// name.
	Stdout string

	// Stderr selects the treatment for stderr, with the same semantics as for
	// Stdout.
	Stderr string

	// Kill indicates whether to kill the process on cancellation (true) or
	// signal it with an interrupt (false).
	Kill bool
	// contains filtered or unexported fields
}

System executes a system command.

func (*System) Cancel 

func (s *System) Cancel(rec *recorder) (err error)

Cancel implements canceler

func (*System) Run 

func (s *System) Run(ctx context.Context, arg runArg) (ofb Feedback, err error)

Run implements runner

type Transfer 

type Transfer struct {
	// Duration is the length of time after which the sender stops writing.
	Duration metric.Duration

	// Length is the number of bytes after which the sender stops writing.
	Length metric.Bytes

	// SampleIOInterval is the minimum time between IO samples. Zero means a
	// sample will be recorded for every read and write.
	SampleIOInterval metric.Duration

	// BufLen is the size of the buffer used to read and write from the conn.
	BufLen int

	Stream
}

Transfer contains the parameters for an Upload or Download.

type Unresponsive 

type Unresponsive struct {
	// Wait lists the wait times between packets, which are cycled through
	// either sequentially or randomly (according to RandomWait) until all
	// packets are sent.
	Wait []metric.Duration

	// WaitFirst, if true, indicates to wait before sending the first packet as
	// well.
	WaitFirst bool

	// RandomWait, if true, indicates to use random wait times from the list.
	// Otherwise, the wait times are taken from Wait sequentially.
	RandomWait bool

	// Length lists the lengths of the packets, which are cycled through either
	// sequentially or randomly (according to RandomLength) until all packets
	// are sent.
	Length []int

	// RandomLength, if true, indicates to use random lengths from the list.
	// Otherwise, the lengths are taken from Length sequentially.
	RandomLength bool

	// Duration is how long to send packets.
	Duration metric.Duration

	// Echo, if true, requests mirrored replies from the server.
	Echo bool
	// contains filtered or unexported fields
}

Unresponsive sends packets on a schedule without regard to any congestion signals.

type Upload 

type Upload struct {
	Transfer
}

Upload is a stream transfer from client to server.

func (Upload) String 

func (u Upload) String() string

Source Files

View all Source files

Directories

Path Synopsis
Package metric provides base types for units, measurement and statistics.
 Package metric provides base types for units, measurement and statistics.

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.