booster

Documentation

Overview

Package booster provides the higher interface for dealing with booster instances that follow the booster protocol. It wraps together node, proxy, network.

Index

• Constants
• Variables
• type Booster
  • func New(pport, bport int) (*Booster, error)
  • func (b *Booster) Close() error
  • func (b *Booster) Connect(ctx context.Context, network, laddr, raddr string) (string, error)
  • func (b *Booster) Ctrl(ctx context.Context, network, addr string, op protocol.Operation) error
  • func (b *Booster) DialContext(ctx context.Context, netwrk, addr string) (*Conn, error)
  • func (b *Booster) Disconnect(ctx context.Context, network, addr, id string) error
  • func (b *Booster) Handle(ctx context.Context, conn SendConsumeCloser)
  • func (b *Booster) HandleConnect(ctx context.Context, conn SendCloser, p *packet.Packet)
  • func (b *Booster) HandleCtrl(ctx context.Context, conn SendCloser, p *packet.Packet)
  • func (b *Booster) HandleDisconnect(ctx context.Context, conn SendCloser, p *packet.Packet)
  • func (b *Booster) HandleHeartbeat(ctx context.Context, conn SendCloser, p *packet.Packet)
  • func (b *Booster) HandleTunnel(ctx context.Context, conn *Conn, p *packet.Packet)
  • func (b *Booster) ListenAndServe(ctx context.Context, port int) error
  • func (b *Booster) Monitor(ctx context.Context, network, addr string, cmd Inspection) error
  • func (b *Booster) Net() *Network
  • func (b *Booster) RecvHello(ctx context.Context, conn *network.Conn) (*Conn, error)
  • func (b *Booster) Restart() error
  • func (b *Booster) Run() error
  • func (b *Booster) SendHello(ctx context.Context, conn SendCloser) error
  • func (b *Booster) ServeMonitor(ctx context.Context, conn SendCloser, p *packet.Packet)
  • func (b *Booster) ServeStatus(ctx context.Context, conn SendCloser)
  • func (b *Booster) UpdateNode(n *node.Node, p protocol.PayloadProxyUpdate, acknoledged bool) error
  • func (b *Booster) UpdateRoot(ctx context.Context) error
  • func (b *Booster) Wire(ctx context.Context, network, target string) (*Conn, error)
• type Conn
  • func (c *Conn) Close() error
  • func (c *Conn) Consume() (<-chan *packet.Packet, error)
  • func (c *Conn) Recv() (*packet.Packet, error)
  • func (c *Conn) Send(p *packet.Packet) error
• type Inspection
• type Network
  • func NewNet(n *node.Node, boosterID string) *Network
  • func (n *Network) AddConn(c *Conn) error
  • func (n *Network) AddTunnel(node *node.Node, t *node.Tunnel)
  • func (n *Network) Decode(p *packet.Packet, m protocol.Module, v interface{}) error
  • func (n *Network) Encode(v interface{}, msg protocol.Message, meta packet.Metadata) (*packet.Packet, error)
  • func (n *Network) EncodeDefault(v interface{}, msg protocol.Message) (*packet.Packet, error)
  • func (n *Network) NewConn(conn *network.Conn, node *node.Node, id string) *Conn
  • func (n *Network) Nodes() (*node.Node, []*node.Node)
  • func (n *Network) RemoveTunnel(node *node.Node, target string, acknoledged bool) error
  • func (n *Network) TraceNodes(ctx context.Context, b *Booster) error
  • func (n *Network) ValidatePacket(p *packet.Packet, h *protocol.Header) error
• type Networks
  • func (n Networks) Close(id string)
  • func (n Networks) Get(id string) *Network
  • func (n Networks) Set(id string, net *Network)
• type Proxy
• type PubSub
• type SendCloser
• type SendConsumeCloser

Constants

const TopicNetworkUpdate = "topic_network_update"

TopicNetworkUpdate is the topic where the network updates, such as connection creation, are published.

Variables

var DefaultNetConfig = network.Config{
	TagSet: packet.TagSet{
		PacketOpeningTag: protocol.PacketOpeningTag,
		PacketClosingTag: protocol.PacketClosingTag,
		ModuleOpeningTag: protocol.ModuleOpeningTag,
		ModuleClosingTag: protocol.ModuleClosingTag,
		Separator:        protocol.Separator,
	},
}

var Nets = &Networks{}

Nets will be populated with the networks of every booster node started.

Types

type Booster

type Booster struct {
	ID string

	Proxy Proxy
	PubSub

	Netconfig network.Config
	// contains filtered or unexported fields
}

Booster wraps the parts that compose a booster node together.

func New

func New(pport, bport int) (*Booster, error)

New creates a new configured booster node. Creates a network configuration based in the information contained in the protocol package.

The internal proxy is configured to use the node dispatcher as network dialer.

func (*Booster) Close

func (b *Booster) Close() error

Close stops the Run routine. It drops the whole booster network, preparing for the node to reset or stop.

func (*Booster) Connect

func (b *Booster) Connect(ctx context.Context, network, laddr, raddr string) (string, error)

Connect dials with laddr, creates a connect packet using raddr and tells laddr to connect with raddr. Both laddr and raddr are expected to point to a booster node.

Closes the connection when done.

func (*Booster) Ctrl

func (b *Booster) Ctrl(ctx context.Context, network, addr string, op protocol.Operation) error

Ctrl commands addr to perform operation op.

func (*Booster) DialContext

func (b *Booster) DialContext(ctx context.Context, netwrk, addr string) (*Conn, error)

DialContext dials a new connection to addr and wraps the connection around a booster connection. Consumes the first hello message received.

func (*Booster) Disconnect

func (b *Booster) Disconnect(ctx context.Context, network, addr, id string) error

Disconnect dials a booster connection with addr, expecting it to be a booster node. It then creates a disconnect packet, telling the node to disconnect from id.

Closes the connection when done.

func (*Booster) Handle

func (b *Booster) Handle(ctx context.Context, conn SendConsumeCloser)

Handle takes care of consuming the connection, handling each incoming packet. Blocks until conn gets closed.

func (*Booster) HandleConnect

func (b *Booster) HandleConnect(ctx context.Context, conn SendCloser, p *packet.Packet)

HandleConnect handles a connect packet. It validates the packet and retrives the target node from its payload. It then wires with the target node, handling the new connection in a different goroutine.

If the connection with the remote node is successful, sends a node packet with the information regarding the added node back. The node identifier contained in the packet is used as connection identifier in the network.

Should run in its own gorountine. Closes the connection used to perform the request when done.

func (*Booster) HandleCtrl

func (b *Booster) HandleCtrl(ctx context.Context, conn SendCloser, p *packet.Packet)

HandleCtrl handels control (ctrl) packets.

func (*Booster) HandleDisconnect

func (b *Booster) HandleDisconnect(ctx context.Context, conn SendCloser, p *packet.Packet)

HandleDisconnect takes a disconnect packet, unwraps its information and removes the target node in this node's network, closing the connection between the two.

Disconnect also closes the connection used to perform this operation upon error or when done.

func (*Booster) HandleHeartbeat

func (b *Booster) HandleHeartbeat(ctx context.Context, conn SendCloser, p *packet.Packet)

HandleHeartbeat validates the packet and checks the validity and expiration of its payload. If the TTL is not yet expired, it waits for it to finish before composing a new heartbeat message, in order to avoid a flood.

Closes the connection in case of any kind of failure.

func (*Booster) HandleTunnel

func (b *Booster) HandleTunnel(ctx context.Context, conn *Conn, p *packet.Packet)

func (*Booster) ListenAndServe

func (b *Booster) ListenAndServe(ctx context.Context, port int) error

ListenAndServe shows to the network, listening for incoming tcp connections an turning them into booster connections.

func (*Booster) Monitor

func (b *Booster) Monitor(ctx context.Context, network, addr string, cmd Inspection) error

func (*Booster) Net

func (b *Booster) Net() *Network

func (*Booster) RecvHello

func (b *Booster) RecvHello(ctx context.Context, conn *network.Conn) (*Conn, error)

RecvHello takes a raw network connection and reads the next message coming. It is expected to be an hello message, introducing a new remote booster instance.

With the informations contained in the packet, it creates a new booster connection and returns it.

func (*Booster) Restart

func (b *Booster) Restart() error

restart restarts the Run routine.

func (*Booster) Run

func (b *Booster) Run() error

Run starts the proxy and booster node.

This is a blocking routine that can be stopped using the Close() method. Traps INTERRUPT signals.

func (*Booster) SendHello

func (b *Booster) SendHello(ctx context.Context, conn SendCloser) error

SendHello composes and sends an hello packet trough conn.

func (*Booster) ServeMonitor

func (b *Booster) ServeMonitor(ctx context.Context, conn SendCloser, p *packet.Packet)

ServeMonitor is a blocking function that serves information responding to an monitor package. The package should contain a list of supported features that should be delivered.

func (*Booster) ServeStatus

func (b *Booster) ServeStatus(ctx context.Context, conn SendCloser)

ServeStatus listens on the local proxy for tunnel events, sending then them though the connection. In case of error closes the connection.

func (*Booster) UpdateNode

func (b *Booster) UpdateNode(n *node.Node, p protocol.PayloadProxyUpdate, acknoledged bool) error

UpdateNode acknoledges or removes a tunnel of node, depending on p's content.

func (*Booster) UpdateRoot

func (b *Booster) UpdateRoot(ctx context.Context) error

UpdateRoot subscribes to the local proxy updating the root node information with the updated data.

func (*Booster) Wire

func (b *Booster) Wire(ctx context.Context, network, target string) (*Conn, error)

Wire connects the target and the local node together, adding the remote booster instance as a new connection of the network.

type Conn

type Conn struct {
	*network.Conn

	ID string // ID is usually the remoteNode identifier.

	RemoteNode     *node.Node
	IOTimeout      time.Duration
	HeartbeatTimer *time.Timer
	// contains filtered or unexported fields
}

Conn adds an identifier and a convenient RemoteNode field to a bare network.Conn.

func (*Conn) Close

func (c *Conn) Close() error

Close takes care of closing the network connection that wires together the root node with its connected remote node.

func (*Conn) Consume

func (c *Conn) Consume() (<-chan *packet.Packet, error)

TODO: what if consume accepted a function to be used for each packet? (see pubsub refactoring of Sub function)

func (*Conn) Recv

func (c *Conn) Recv() (*packet.Packet, error)

func (*Conn) Send

func (c *Conn) Send(p *packet.Packet) error

Send tries to send p though the connection. If the operation is not performed bofore IOTimeout, returns an error.

type Inspection

type Inspection struct {
	Feature protocol.MonitorFeature
	Run     func(m packet.Module) error
	PostRun func(err error)
}

type Network

type Network struct {
	PubSub
	*tracer.Tracer

	IOTimeout    time.Duration
	HeartbeatTTL time.Duration
	DialTimeout  time.Duration

	LocalNode *node.Node
	Outgoing  map[string]*Conn
	// contains filtered or unexported fields
}

Network describes a booster network: a local node, connected to other booster nodes using network.Conn as connector.

func NewNet

func NewNet(n *node.Node, boosterID string) *Network

NewNet returns a new network instance, configured with default parameters.

func (*Network) AddConn

func (n *Network) AddConn(c *Conn) error

AddConn adds c to network. Returns an error if the connection is already present.

func (*Network) AddTunnel

func (n *Network) AddTunnel(node *node.Node, t *node.Tunnel)

AddTunnel finds the node in the network, creates a new tunnel using target and adds the tunnel to the node. If node is not a local node, it also adds the tunnel to the local node, but settings its ProxiedBy value to the remote node's proxy address. Publishes the update in TopicNode.

func (*Network) Decode

func (n *Network) Decode(p *packet.Packet, m protocol.Module, v interface{}) error

Decode tries to decode the payload content of the module m contained in p into v, which has to be a pointer to a struct. f is the function that will be used for the decoding. It is important to choose the right combo between f and v, meaning that we cannot decode an "Hello" message using a "Node" decoder.

Check package protocol for the decoding functions available.

func (*Network) Encode

func (n *Network) Encode(v interface{}, msg protocol.Message, meta packet.Metadata) (*packet.Packet, error)

func (*Network) EncodeDefault

func (n *Network) EncodeDefault(v interface{}, msg protocol.Message) (*packet.Packet, error)

EncodeDefault calls Encode using protobuf for encoding, no compression nor encryption.

func (*Network) NewConn

func (n *Network) NewConn(conn *network.Conn, node *node.Node, id string) *Conn

NewConn creates a new connection and associates it with the network.

func (*Network) Nodes

func (n *Network) Nodes() (*node.Node, []*node.Node)

Nodes returns the root node of the network, together with all the remote nodes connected to it.

func (*Network) RemoveTunnel

func (n *Network) RemoveTunnel(node *node.Node, target string, acknoledged bool) error

RemoveTunnel finds the node in the network and removes the tunnel labeled with target from it. Publishes the node in TopicNode.

func (*Network) TraceNodes

func (n *Network) TraceNodes(ctx context.Context, b *Booster) error

TraceNodes starts a tracer that is able to determine wether a remote interface is up or down in the network. When a node get's traced is added back to the connection as soon as it online again.

func (*Network) ValidatePacket

func (n *Network) ValidatePacket(p *packet.Packet, h *protocol.Header) error

ValidatePackets extracts the header from the packet and checks if the validity/reliability of its contents.

type Networks

type Networks map[string]*Network

Networks is a convenience type that wraps a map of Network instances.

func (Networks) Close

func (n Networks) Close(id string)

Close gets the network associated with id, then it closes each connection stored in it. No remote node will be traced.

func (Networks) Get

func (n Networks) Get(id string) *Network

Get returns a network associated with id. Panics if the network was not previously registered.

func (Networks) Set

func (n Networks) Set(id string, net *Network)

Set associates net with id inside of networks. Panics if the network labeled with id was alreaduy registered.

type Proxy

type Proxy interface {
	Sub(cmd *pubsub.Command) (pubsub.CancelFunc, error)

	// ListenAndServe should starts the actual proxy server, announcing it to the local
	// address.
	ListenAndServe(ctx context.Context, port int) error

	// Proto returns the string representation of the protocol used by the proxy.
	// Example: socks5.
	Proto() string
}

Proxy wraps that booster requires a proxy to implement.

type PubSub

type PubSub interface {
	Sub(cmd *pubsub.Command) (pubsub.CancelFunc, error)
	Pub(message interface{}, topic string)
}

PubSub describes the required functionalities of a publication/subscription object.

type SendCloser

type SendCloser interface {
	Close() error
	Send(p *packet.Packet) error
}

type SendConsumeCloser

type SendConsumeCloser interface {
	SendCloser
	Consume() (<-chan *packet.Packet, error)
}