netceptor

package
v1.1.1 Latest Latest
Warning

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

 Go to latest Published: Nov 17, 2021 License: Apache-2.0 Imports: 32 Imported by: 0

Documentation

Overview

Package netceptor is the networking layer of Receptor.

Index

Constants

View Source 
const (
	// MsgTypeData is a normal data-containing message.
	MsgTypeData = 0
	// MsgTypeRoute is a routing update.
	MsgTypeRoute = 1
	// MsgTypeServiceAdvertisement is an advertisement for a service.
	MsgTypeServiceAdvertisement = 2
	// MsgTypeReject indicates a rejection (closure) of a backend connection.
	MsgTypeReject = 3
)
View Source 
const (
	// ProblemServiceUnknown occurs when a message arrives for a non-listening service.
	ProblemServiceUnknown = "service unknown"
	// ProblemExpiredInTransit occurs when a message's HopsToLive expires in transit.
	ProblemExpiredInTransit = "message expired"
	// ProblemRejected occurs when a packet is rejected by a firewall rule.
	ProblemRejected = "blocked by firewall"
)
View Source 
const (
	// ConnTypeDatagram indicates a packetconn (datagram) service listener.
	ConnTypeDatagram = 0
	// ConnTypeStream indicates a conn (stream) service listener, without a user-defined TLS.
	ConnTypeStream = 1
	// ConnTypeStreamTLS indicates the service listens on a packetconn connection, with a user-defined TLS.
	ConnTypeStreamTLS = 2
)
View Source 
const (
	// VerifyServer indicates we are the client, verifying a server.
	VerifyServer = 1
	// VerifyClient indicates we are the server, verifying a client.
	VerifyClient = 2
)

Variables

View Source 
var ErrTimeout error = &TimeoutError{}

ErrTimeout is returned for an expired deadline.

Functions

func BackendAllowedPeers 

func BackendAllowedPeers(peers []string) func(*backendInfo)

BackendAllowedPeers is a modifier for AddBackend, which sets the list of peers allowed to connect.

func BackendConnectionCost 

func BackendConnectionCost(cost float64) func(*backendInfo)

BackendConnectionCost is a modifier for AddBackend, which sets the global connection cost.

func BackendNodeCost 

func BackendNodeCost(nodeCost map[string]float64) func(*backendInfo)

BackendNodeCost is a modifier for AddBackend, which sets the per-node connection costs.

Types

type Addr 

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

Addr represents an endpoint address on the Netceptor network.

func (Addr) Network 

func (a Addr) Network() string

Network returns the network name.

func (Addr) String 

func (a Addr) String() string

String formats this address as a string.

type Backend 

type Backend interface {
	Start(context.Context, *sync.WaitGroup) (chan BackendSession, error)
}

Backend is the interface for back-ends that the Receptor network can run over.

type BackendSession 

type BackendSession interface {
	Send([]byte) error
	Recv(time.Duration) ([]byte, error) // Must return netceptor.ErrTimeout if the timeout is exceeded
	Close() error
}

BackendSession is the interface for a single session of a back-end. Backends must be DATAGRAM ORIENTED, meaning that Recv() must return whole packets sent by Send(). If the underlying protocol is stream oriented, then the backend must deal with any required buffering.

type CompareFunc 

type CompareFunc func(md *MessageData) bool

type Conn 

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

Conn implements the net.Conn interface via the Receptor network.

func (*Conn) CancelRead 

func (c *Conn) CancelRead()

CancelRead cancels a pending read operation.

func (*Conn) Close 

func (c *Conn) Close() error

Close closes the writer side of the connection.

func (*Conn) CloseConnection 

func (c *Conn) CloseConnection() error

func (*Conn) LocalAddr 

func (c *Conn) LocalAddr() net.Addr

LocalAddr returns the local address of this connection.

func (*Conn) Read 

func (c *Conn) Read(b []byte) (n int, err error)

Read reads data from the connection.

func (*Conn) RemoteAddr 

func (c *Conn) RemoteAddr() net.Addr

RemoteAddr returns the remote address of this connection.

func (*Conn) SetDeadline 

func (c *Conn) SetDeadline(t time.Time) error

SetDeadline sets both read and write deadlines.

func (*Conn) SetReadDeadline 

func (c *Conn) SetReadDeadline(t time.Time) error

SetReadDeadline sets the read deadline.

func (*Conn) SetWriteDeadline 

func (c *Conn) SetWriteDeadline(t time.Time) error

SetWriteDeadline sets the write deadline.

func (*Conn) Write 

func (c *Conn) Write(b []byte) (n int, err error)

Write writes data to the connection.

type ConnStatus 

type ConnStatus struct {
	NodeID string
	Cost   float64
}

ConnStatus holds information about a single connection in the Status struct.

type ErrorFunc 

type ErrorFunc func(error, bool)

ErrorFunc is a function parameter used to process errors. The boolean parameter indicates whether the error is fatal (i.e. the associated process is going to exit).

type ExternalBackend 

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

ExternalBackend is a backend implementation for the situation when non-Receptor code is initiating connections, outside the control of a Receptor-managed accept loop.

func NewExternalBackend 

func NewExternalBackend() (*ExternalBackend, error)

NewExternalBackend initializes a new ExternalBackend object.

func (*ExternalBackend) NewConnection 

func (b *ExternalBackend) NewConnection(conn MessageConn, closeConnWithSession bool)

NewConnection is called by the external code when a new connection is available. The connection will be closed when the session ends if closeConnWithSession is true.

func (*ExternalBackend) Start 

func (b *ExternalBackend) Start(ctx context.Context, wg *sync.WaitGroup) (chan BackendSession, error)

Start launches the backend from Receptor's point of view, and waits for connections to happen.

type ExternalSession 

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

ExternalSession implements BackendSession for external backends.

func (*ExternalSession) Close 

func (es *ExternalSession) Close() error

Close closes the session.

func (*ExternalSession) Recv 

func (es *ExternalSession) Recv(timeout time.Duration) ([]byte, error)

Recv receives data via the session.

func (*ExternalSession) Send 

func (es *ExternalSession) Send(data []byte) error

Send sends data over the session.

type FirewallResult 

type FirewallResult int

FirewallResult enumerates the actions that can be taken as a result of a firewall rule. 

const (
	// FirewallResultContinue continues processing further rules (no result).
	FirewallResultContinue FirewallResult = iota
	// FirewallResultAccept accepts the message for normal processing.
	FirewallResultAccept
	// FirewallResultReject denies the message, sending an unreachable message to the originator.
	FirewallResultReject
	// FirewallResultDrop denies the message silently, leaving the originator to time out.
	FirewallResultDrop
)

type FirewallRule 

type FirewallRule struct {
	Action      string
	FromNode    string
	ToNode      string
	FromService string
	ToService   string
}

func (FirewallRule) BuildComps 

func (fr FirewallRule) BuildComps() []CompareFunc

type FirewallRuleData 

type FirewallRuleData map[interface{}]interface{}

func (FirewallRuleData) ParseFirewallRule 

func (frd FirewallRuleData) ParseFirewallRule() (FirewallRuleFunc, error)

ParseFirewallRule takes a single string describing a firewall rule, and returns a FirewallRuleFunc function.

type FirewallRuleFunc 

type FirewallRuleFunc func(*MessageData) FirewallResult

FirewallRuleFunc is a function that takes a message and returns a firewall decision.

func ParseFirewallRules 

func ParseFirewallRules(rules []FirewallRuleData) ([]FirewallRuleFunc, error)

ParseFirewallRules takes a slice of string describing firewall rules, and returns a slice of FirewallRuleFunc functions.

type Listener 

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

Listener implements the net.Listener interface via the Receptor network.

func (*Listener) Accept 

func (li *Listener) Accept() (net.Conn, error)

Accept accepts a connection via the listener.

func (*Listener) Addr 

func (li *Listener) Addr() net.Addr

Addr returns the local address of this listener.

func (*Listener) Close 

func (li *Listener) Close() error

Close closes the listener.

type MessageConn 

type MessageConn interface {
	WriteMessage(ctx context.Context, data []byte) error
	ReadMessage(ctx context.Context, timeout time.Duration) ([]byte, error)
	SetReadDeadline(t time.Time) error
	Close() error
}

MessageConn is an abstract connection that sends and receives whole messages (datagrams).

func MessageConnFromNetConn 

func MessageConnFromNetConn(conn net.Conn) MessageConn

MessageConnFromNetConn returns a MessageConnection that wraps a net.Conn.

func MessageConnFromWebsocketConn 

func MessageConnFromWebsocketConn(conn *websocket.Conn) MessageConn

MessageConnFromWebsocketConn returns a MessageConnection that wraps a Gorilla websocket.Conn.

type MessageData 

type MessageData struct {
	FromNode    string
	FromService string
	ToNode      string
	ToService   string
	HopsToLive  byte
	Data        []byte
}

MessageData contains a single message packet from the network.

type Netceptor 

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

Netceptor is the main object of the Receptor mesh network protocol. 

var MainInstance *Netceptor

MainInstance is the global instance of Netceptor instantiated by the command-line main() function.

func New 

func New(ctx context.Context, nodeID string) *Netceptor

New constructs a new Receptor network protocol instance.

func NewWithConsts 

func NewWithConsts(ctx context.Context, nodeID string,
	mtu int, routeUpdateTime time.Duration, serviceAdTime time.Duration, seenUpdateExpireTime time.Duration,
	maxForwardingHops byte, maxConnectionIdleTime time.Duration) *Netceptor

NewWithConsts constructs a new Receptor network protocol instance, specifying operational constants.

func (*Netceptor) AddBackend 

func (s *Netceptor) AddBackend(backend Backend, modifiers ...func(*backendInfo)) error

AddBackend adds a backend to the Netceptor system.

func (*Netceptor) AddFirewallRules 

func (s *Netceptor) AddFirewallRules(rules []FirewallRuleFunc, clearExisting bool) error

AddFirewallRules adds firewall rules, optionally clearing existing rules first.

func (*Netceptor) AddWorkCommand 

func (s *Netceptor) AddWorkCommand(command string, secure bool) error

AddWorkCommand records a work command so it can be included in service announcements.

func (*Netceptor) BackendCount 

func (s *Netceptor) BackendCount() int

BackendCount returns the number of backends that ever registered with this Netceptor.

func (*Netceptor) BackendDone 

func (s *Netceptor) BackendDone()

BackendDone calls Done on the backendWaitGroup.

func (*Netceptor) BackendWait 

func (s *Netceptor) BackendWait()

BackendWait waits for the backend wait group.

func (*Netceptor) CancelBackends 

func (s *Netceptor) CancelBackends()

CancelBackends stops all backends by calling a context cancel.

func (*Netceptor) Context 

func (s *Netceptor) Context() context.Context

Context returns the context for this Netceptor instance.

func (*Netceptor) Dial 

func (s *Netceptor) Dial(node string, service string, tlscfg *tls.Config) (*Conn, error)

Dial returns a stream connection compatible with Go's net.Conn.

func (*Netceptor) DialContext 

func (s *Netceptor) DialContext(ctx context.Context, node string, service string, tlscfg *tls.Config) (*Conn, error)

DialContext is like Dial but uses a context to allow timeout or cancellation.

func (*Netceptor) GetClientTLSConfig 

func (s *Netceptor) GetClientTLSConfig(name string, expectedHostName string, expectedHostNameType string) (*tls.Config, error)

GetClientTLSConfig retrieves a client TLS config by name. Supported host name types are dns and receptor.

func (*Netceptor) GetServerTLSConfig 

func (s *Netceptor) GetServerTLSConfig(name string) (*tls.Config, error)

GetServerTLSConfig retrieves a server TLS config by name.

func (*Netceptor) GetServiceInfo 

func (s *Netceptor) GetServiceInfo(nodeID string, service string) (*ServiceAdvertisement, bool)

GetServiceInfo returns the advertising info, if any, for a service on a node.

func (*Netceptor) Listen 

func (s *Netceptor) Listen(service string, tlscfg *tls.Config) (*Listener, error)

Listen returns a stream listener compatible with Go's net.Listener. If service is blank, generates and uses an ephemeral service name.

func (*Netceptor) ListenAndAdvertise 

func (s *Netceptor) ListenAndAdvertise(service string, tlscfg *tls.Config, tags map[string]string) (*Listener, error)

ListenAndAdvertise listens for stream connections on a service and also advertises it via broadcasts.

func (*Netceptor) ListenContext 

func (s *Netceptor) ListenContext(ctx context.Context, service string, tlscfg *tls.Config) (*Listener, error)

ListenContext returns a stream listener compatible with Go's net.Listener. If service is blank, generates and uses an ephemeral service name.

func (*Netceptor) ListenContextAndAdvertise 

func (s *Netceptor) ListenContextAndAdvertise(ctx context.Context, service string, tlscfg *tls.Config, tags map[string]string) (*Listener, error)

ListenContextAndAdvertise listens for stream connections on a service and also advertises it via broadcasts.

func (*Netceptor) ListenPacket 

func (s *Netceptor) ListenPacket(service string) (*PacketConn, error)

ListenPacket returns a datagram connection compatible with Go's net.PacketConn. If service is blank, generates and uses an ephemeral service name.

func (*Netceptor) ListenPacketAndAdvertise 

func (s *Netceptor) ListenPacketAndAdvertise(service string, tags map[string]string) (*PacketConn, error)

ListenPacketAndAdvertise returns a datagram listener, and also broadcasts service advertisements to the Receptor network as long as the listener remains open.

func (*Netceptor) MTU 

func (s *Netceptor) MTU() int

MTU returns the configured MTU of this Netceptor instance.

func (*Netceptor) MaxConnectionIdleTime 

func (s *Netceptor) MaxConnectionIdleTime() time.Duration

MaxConnectionIdleTime returns the configured MaxConnectionIdleTime of this Netceptor instance.

func (*Netceptor) MaxForwardingHops 

func (s *Netceptor) MaxForwardingHops() byte

MaxForwardingHops returns the configured MaxForwardingHops of this Netceptor instance.

func (*Netceptor) NetceptorDone 

func (s *Netceptor) NetceptorDone() <-chan struct{}

NetceptorDone returns the channel for the netceptor context.

func (*Netceptor) NewAddr 

func (s *Netceptor) NewAddr(node string, service string) Addr

NewAddr generates a Receptor network address from a node ID and service name.

func (*Netceptor) NodeID 

func (s *Netceptor) NodeID() string

NodeID returns the local Node ID of this Netceptor instance.

func (*Netceptor) PathCost 

func (s *Netceptor) PathCost(nodeID string) (float64, error)

PathCost returns the cost to a given remote node, or an error if the node doesn't exist.

func (*Netceptor) RouteUpdateTime 

func (s *Netceptor) RouteUpdateTime() time.Duration

RouteUpdateTime returns the configured RouteUpdateTime of this Netceptor instance.

func (*Netceptor) SeenUpdateExpireTime 

func (s *Netceptor) SeenUpdateExpireTime() time.Duration

SeenUpdateExpireTime returns the configured SeenUpdateExpireTime of this Netceptor instance.

func (*Netceptor) ServiceAdTime 

func (s *Netceptor) ServiceAdTime() time.Duration

ServiceAdTime returns the configured ServiceAdTime of this Netceptor instance.

func (*Netceptor) SetClientTLSConfig 

func (s *Netceptor) SetClientTLSConfig(name string, config *tls.Config) error

SetClientTLSConfig stores a client TLS config by name.

func (*Netceptor) SetServerTLSConfig 

func (s *Netceptor) SetServerTLSConfig(name string, config *tls.Config) error

SetServerTLSConfig stores a server TLS config by name.

func (*Netceptor) Shutdown 

func (s *Netceptor) Shutdown()

Shutdown shuts down a Netceptor instance.

func (*Netceptor) Status 

func (s *Netceptor) Status() Status

Status returns the current state of the Netceptor object.

func (*Netceptor) SubscribeRoutingUpdates 

func (s *Netceptor) SubscribeRoutingUpdates() chan map[string]string

SubscribeRoutingUpdates subscribes for messages when the routing table is changed.

type PacketConn 

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

PacketConn implements the net.PacketConn interface via the Receptor network.

func (*PacketConn) Close 

func (pc *PacketConn) Close() error

Close closes the connection.

func (*PacketConn) LocalAddr 

func (pc *PacketConn) LocalAddr() net.Addr

LocalAddr returns the local address the connection is bound to.

func (*PacketConn) LocalService 

func (pc *PacketConn) LocalService() string

LocalService returns the local service name of the connection.

func (*PacketConn) ReadFrom 

func (pc *PacketConn) ReadFrom(p []byte) (n int, addr net.Addr, err error)

ReadFrom reads a packet from the network and returns its data and address.

func (*PacketConn) SetDeadline 

func (pc *PacketConn) SetDeadline(t time.Time) error

SetDeadline sets both the read and write deadlines.

func (*PacketConn) SetHopsToLive 

func (pc *PacketConn) SetHopsToLive(hopsToLive byte)

SetHopsToLive sets the HopsToLive value for future outgoing packets on this connection.

func (*PacketConn) SetReadDeadline 

func (pc *PacketConn) SetReadDeadline(t time.Time) error

SetReadDeadline sets the read deadline.

func (*PacketConn) SetWriteDeadline 

func (pc *PacketConn) SetWriteDeadline(t time.Time) error

SetWriteDeadline sets the write deadline.

func (*PacketConn) SubscribeUnreachable 

func (pc *PacketConn) SubscribeUnreachable(doneChan chan struct{}) chan UnreachableNotification

SubscribeUnreachable subscribes for unreachable messages relevant to this PacketConn.

func (*PacketConn) WriteTo 

func (pc *PacketConn) WriteTo(p []byte, addr net.Addr) (n int, err error)

WriteTo writes a packet to an address on the network.

type ReceptorCertNameError 

type ReceptorCertNameError struct {
	ValidNodes   []string
	ExpectedNode string
}

ReceptorCertNameError is the error produced when Receptor certificate name verification fails.

func (ReceptorCertNameError) Error 

func (rce ReceptorCertNameError) Error() string

type ServiceAdvertisement 

type ServiceAdvertisement struct {
	NodeID       string
	Service      string
	Time         time.Time
	ConnType     byte
	Tags         map[string]string
	WorkCommands []WorkCommand
}

ServiceAdvertisement is the data associated with a service advertisement.

type Status 

type Status struct {
	NodeID               string
	Connections          []*ConnStatus
	RoutingTable         map[string]string
	Advertisements       []*ServiceAdvertisement
	KnownConnectionCosts map[string]map[string]float64
}

Status is the struct returned by Netceptor.Status(). It represents a public view of the internal status of the Netceptor object.

type TimeoutError 

type TimeoutError struct{}

TimeoutError is returned for an expired deadline.

func (*TimeoutError) Error 

func (e *TimeoutError) Error() string

Error returns a string describing the error.

func (*TimeoutError) Temporary 

func (e *TimeoutError) Temporary() bool

Temporary returns true if a retry is likely a good idea.

func (*TimeoutError) Timeout 

func (e *TimeoutError) Timeout() bool

Timeout returns true if this error was a timeout.

type UnreachableMessage 

type UnreachableMessage struct {
	FromNode    string
	ToNode      string
	FromService string
	ToService   string
	Problem     string
}

UnreachableMessage is the on-the-wire data associated with an unreachable message.

type UnreachableNotification 

type UnreachableNotification struct {
	UnreachableMessage
	ReceivedFromNode string
}

UnreachableNotification includes additional information returned from SubscribeUnreachable.

type WorkCommand 

type WorkCommand struct {
	WorkType string
	// Secure true means receptor will verify the signature of the work submit payload
	Secure bool
}

WorkCommand tracks available work types and whether they verify work submissions.

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.