client

package
v0.0.0-...-fd2add7 Latest Latest
Warning

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

 Go to latest Published: Nov 21, 2016 License: Apache-2.0 Imports: 22 Imported by: 2

Documentation

Overview

Package client provides access to the circuit programming environment to user programs.

Index

Constants

View Source 
const (
	Running   = "running"
	Exited    = "exited"
	Stopped   = "stopped"
	Signaled  = "signaled"
	Continued = "continued"
	Unknown   = "unknown"
)

Variables

This section is empty.

Functions

func Split 

func Split(walk string) (r []string)

Split breaks up an anchor path into components.

Types

type Anchor 

type Anchor interface {

	// Addr returns the address of the circuit server hosting this anchor.
	Addr() string

	// ServerID returns the ID of the circuit server hosting this anchor.
	// The returned string will look like "X123..."
	ServerID() string

	// Walk traverses the anchor namespace, starting from this anchor along the path in walk.
	// Errors in communication or a missing circuit server condition are reported via panics.
	Walk(walk []string) Anchor

	// View returns the set of this anchor's sub-anchors.
	View() map[string]Anchor

	// MakeChan creates a new circuit channel element at this anchor with a given capacity n.
	// If the anchor already stores an element, a non-nil error is returned.
	// Panics indicate that the server hosting the anchor is gone.
	MakeChan(n int) (Chan, error)

	// MakeProc issues the execution of an OS process, described by cmd, at the server hosting the anchor
	// and creates a corresponding circuit process element at this anchor.
	// If the anchor already stores an element, a non-nil error is returned.
	// Panics indicate that the server hosting the anchor is gone.
	MakeProc(cmd Cmd) (Proc, error)

	// MakeDocker…
	MakeDocker(run cdocker.Run) (cdocker.Container, error)

	// MakeNameserver…
	MakeNameserver(addr string) (Nameserver, error)

	// MakeOnJoin…
	MakeOnJoin() (Subscription, error)

	// MakeOnLeave…
	MakeOnLeave() (Subscription, error)

	// Get returns a handle for the circuit element (Chan, Proc, Subscription, Server, etc)
	// stored at this anchor, and nil otherwise.
	// Panics indicate that the server hosting the anchor and its element has already died.
	Get() interface{}

	// Scrub aborts and abandons the circuit element stored at this anchor, if one is present.
	// If the hosting server is dead, a panic will be issued.
	Scrub()

	// Path returns the path to this anchor
	Path() string
}

An Anchor represents a location in the global anchor namespace of a circuit cluster. Anchors are named locations where the user can store and operate control primitives, called circuit elements. The anchor namespace hierarchy is represented in paths of the form 

/X8817c114d4941522/hello/dolly

The root anchor "/" represents the cluster abstractly and is the only anchor within which one cannot create elements or freely-named subanchors. The root anchor contains a dynamically changing set of sub-anchors that correspond to the live circuit servers in the cluster.

Every anchor, other than "/", can be used to make, store and operate a circuit element (a process or a channel). Anchors are created on access, if not present, and are garbage-collected when not used or referenced. Therefore the interface allows users to access arbitrary paths without having to create them first.

type Chan 

type Chan interface {

	// Send blocks until the requested transmission is matched to a receiving call to Recv, or
	// until it can be accommodated in the channel's buffer.
	// It returns a WriteCloser representing a byte pipe to the receiver, or a non-nil error
	// if the channel has already been closed.
	Send() (io.WriteCloser, error)

	// Scrub aborts and abandons the channel. Any buffered send operations are lost.
	Scrub()

	// Close closes the channel, reporting an error only if the channel has already been closed.
	Close() error

	// Recv blocks until it can be matched with a sender.
	// It returns a ReadCloser for the byte pipe from the sender, or a non-nil error if the
	// channel has been closed.
	Recv() (io.ReadCloser, error)

	// Cap reports the capacity of the channel.
	Cap() int

	// Stat returns the current state of the channel.
	Stat() ChanStat
}

Chan provides access to a circuit channel element.

A channel element is semantically identical to a Go channel, with the sole exception that the "messages" passed through the channel are pipes that connect the sender and the receiver and allow them, once connected, to exchange an arbitrary stream of byte data which as a whole counts as one channel message.

All methods panic if the server hosting the channel dies.

type ChanStat 

type ChanStat struct {

	// Cap is the channel capacity.
	Cap int

	// Closed is set as soon as Close is called.
	// If Closed is set, the channel might still have messages in its buffer and
	// thus its receive side remains operational.
	Closed bool

	// Aborted is set if the channel has been permanently aborted and is not usable any longer.
	Aborted bool

	// NumSend is the number of completed invocations to Send.
	NumSend int

	// NumRecv is the number of completed invocations to Recv.
	NumRecv int
}

ChanStat describes the state of a channel.

type Client 

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

Client is a live session with a circuit server.

func Dial 

func Dial(addr string, authkey []byte) *Client

Dial establishes a connection to a circuit server specified by a circuit address. Circuit addresses are printed to standard output when a server is started with the "circuit start …" command.

If authkey is non-nil it is used as a private key and all communications are secured by HMAC authentication and RC4 symmetric encryption; otherwise transmissions are in plaintext.

Errors in communication, such as a missing server, or invalid URL format are reported through panics.

func DialDiscover 

func DialDiscover(multicast string, authkey []byte) *Client

func (*Client) Addr 

func (c *Client) Addr() string

Address returns the circuit address of the server that this client is connected to.

func (*Client) Get 

func (c *Client) Get() interface{}

Get is an Anchor interface method, not applicable to the root-level anchor.

func (*Client) MakeChan 

func (c *Client) MakeChan(n int) (Chan, error)

MakeChan is an Anchor interface method, not applicable to the root-level anchor.

func (*Client) MakeDocker 

func (c *Client) MakeDocker(run docker.Run) (docker.Container, error)

MakeDocker is an Anchor interface method, not applicable to the root-level anchor.

func (*Client) MakeNameserver 

func (c *Client) MakeNameserver(string) (Nameserver, error)

MakeNameserver…

func (*Client) MakeOnJoin 

func (c *Client) MakeOnJoin() (Subscription, error)

MakeOnJoin is an Anchor interface method, not applicable to the root-level anchor.

func (*Client) MakeOnLeave 

func (c *Client) MakeOnLeave() (Subscription, error)

MakeOnLeave is an Anchor interface method, not applicable to the root-level anchor.

func (*Client) MakeProc 

func (c *Client) MakeProc(cmd Cmd) (Proc, error)

MakeProc is an Anchor interface method, not applicable to the root-level anchor.

func (*Client) Path 

func (c *Client) Path() string

func (*Client) Scrub 

func (c *Client) Scrub()

Scrub is an Anchor interface method, not applicable to the root-level anchor.

func (*Client) ServerID 

func (c *Client) ServerID() string

ServerID returns the server ID of the circuit server that this client is connected to.

func (*Client) View 

func (c *Client) View() map[string]Anchor

View returns a map of all currently-live circuit server anchors. Errors in communication are reported as panics.

func (*Client) Walk 

func (c *Client) Walk(walk []string) Anchor

Walk traverses the global virtual anchor namespace and returns a handle to the desired anchor. The first element of walk should be the ID of a live circuit server. An up to date list of available circuit servers in the cluster can be obtained by calling View. The remainder of the walk slice is up to the user. Errors in communication or missing servers are reported as panics.

type Cmd 

type Cmd struct {

	// Env, if set, is the desired OS execution environment. It corresponds to Cmd.Env from package "os/exec".
	Env []string

	// Dir, if non-empty, is the working directory for the process.
	Dir string

	// Path is the local file-system path, at the respective circuit server, to the process binary.
	Path string

	// Args is a list of command line arguments to be passed on to the process.
	// The first element in the slice corresponds to the first argument to the process (not to its binary path).
	Args []string

	// If Scrub is set, the process element will automatically be removed from its anchor
	// when the process exits.
	Scrub bool
}

Cmd describes the execution parameters for an OS process.

type Nameserver 

type Nameserver interface {
	Set(rr string) error

	Unset(name string)

	// Peek asynchronously returns the current state of the server.
	Peek() NameserverStat

	// Scrub shuts down the nameserver and removes its circuit element.
	Scrub()
}

type NameserverStat 

type NameserverStat struct {

	// IP address of the nameserver
	Address string

	// Resource records resolved by this nameserver
	Records map[string][]string
}

NameserverStat encloses process state information.

type Proc 

type Proc interface {

	// Wait blocks until the underlying OS process exits and returns the final status of the process.
	// An error is returned only if the wait invocation is aborted by a concurring call to Scrub.
	Wait() (ProcStat, error)

	// Signal sends an OS signal to the process. The following are recognized signal names:
	// ABRT, ALRM, BUS, CHLD, CONT, FPE, HUP, ILL, INT, IO, IOT,  KILL, PIPE,
	// PROF, QUIT, SEGV,  STOP, SYS, TERM, TRAP, TSTP, TTIN, TTOU,  URG, USR1,
	// USR2, VTALRM, WINCH, XCPU, XFSZ.
	Signal(sig string) error

	// GetEnv returns the environment at the hosting server OS.
	GetEnv() []string

	// GetCmd returns the command that started this process.
	GetCmd() Cmd

	// Peek asynchronously returns the current state of the process.
	Peek() ProcStat

	// Scrub abandons the circuit process element, without affecting the underlying OS process.
	Scrub()

	// Stdin returns a WriterCloser to the standard input of the underlying OS process.
	// The user is responsible for closing the standard input, even if they do not
	// intend to write to it.
	Stdin() io.WriteCloser

	// Stdout returns the standard output of the underlying OS process.
	Stdout() io.ReadCloser

	// Stderr returns the standard error of the underlying OS process.
	Stderr() io.ReadCloser
}

Proc provides access to a circuit process element. All methods panic if the hosting circuit server dies.

type ProcStat 

type ProcStat struct {

	// Cmd is a copy of the command that started the process.
	Cmd Cmd

	// Error will be non-nil if the process has already exited in error.
	Exit error

	// Phase describes the current state of the process.
	// Its possible values are Running, Exited, Stopped, Signaled, Continued and Unknown.
	Phase string
}

ProcStat encloses process state information.

type Server 

type Server interface {
	Profile(string) (io.ReadCloser, error)
	Peek() ServerStat
	Rejoin(string) error
	Suicide()
}

Server… All methods panic if the hosting circuit server dies.

type ServerStat 

type ServerStat struct {
	Addr   string
	Joined time.Time
}

ServerStat encloses subscription state information.

type Subscription 

type Subscription interface {

	// Consume blocks until the next message is available on the channel.
	Consume() (interface{}, bool)

	// Peek asynchronously returns the current state of the process.
	Peek() SubscriptionStat

	// Scrub abandons the circuit process element, without affecting the underlying OS process.
	Scrub()
}

Subscription provides access to a circuit subscription element. All methods panic if the hosting circuit server dies.

type SubscriptionStat 

type SubscriptionStat struct {

	// Name of event source
	Source string

	// Pending equals the number of messages waiting to be consumed.
	Pending int

	// Closed is true if the publisher stream has marked an end.
	Closed bool
}

SubscriptionStat encloses subscription state information.

Source Files

View all Source files

Directories

Path Synopsis

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.