Documentation ¶
Overview ¶
Package netceptor is the networking layer of Receptor.
Index ¶
- Constants
- Variables
- func BackendAllowedPeers(peers []string) func(*backendInfo)
- func BackendConnectionCost(cost float64) func(*backendInfo)
- func BackendNodeCost(nodeCost map[string]float64) func(*backendInfo)
- func ReceptorVerifyFunc(tlscfg *tls.Config, pinnedFingerprints [][]byte, expectedHostname string, ...) func(rawCerts [][]byte, verifiedChains [][]*x509.Certificate) error
- type Addr
- type Backend
- type BackendSession
- type CompareFunc
- type Conn
- func (c *Conn) CancelRead()
- func (c *Conn) Close() error
- func (c *Conn) CloseConnection() error
- func (c *Conn) LocalAddr() net.Addr
- func (c *Conn) Read(b []byte) (n int, err error)
- func (c *Conn) RemoteAddr() net.Addr
- func (c *Conn) SetDeadline(t time.Time) error
- func (c *Conn) SetReadDeadline(t time.Time) error
- func (c *Conn) SetWriteDeadline(t time.Time) error
- func (c *Conn) Write(b []byte) (n int, err error)
- type ConnStatus
- type ErrorFunc
- type ExpectedHostnameType
- type ExternalBackend
- type ExternalSession
- type FirewallResult
- type FirewallRule
- type FirewallRuleData
- type FirewallRuleFunc
- type Listener
- type MessageConn
- type MessageData
- type Netceptor
- func (s *Netceptor) AddBackend(backend Backend, modifiers ...func(*backendInfo)) error
- func (s *Netceptor) AddFirewallRules(rules []FirewallRuleFunc, clearExisting bool) error
- func (s *Netceptor) AddWorkCommand(command string, secure bool) error
- func (s *Netceptor) BackendCount() int
- func (s *Netceptor) BackendDone()
- func (s *Netceptor) BackendWait()
- func (s *Netceptor) CancelBackends()
- func (s *Netceptor) Context() context.Context
- func (s *Netceptor) Dial(node string, service string, tlscfg *tls.Config) (*Conn, error)
- func (s *Netceptor) DialContext(ctx context.Context, node string, service string, tlscfg *tls.Config) (*Conn, error)
- func (s *Netceptor) GetClientTLSConfig(name string, expectedHostName string, ...) (*tls.Config, error)
- func (s *Netceptor) GetServerTLSConfig(name string) (*tls.Config, error)
- func (s *Netceptor) GetServiceInfo(nodeID string, service string) (*ServiceAdvertisement, bool)
- func (s *Netceptor) Listen(service string, tlscfg *tls.Config) (*Listener, error)
- func (s *Netceptor) ListenAndAdvertise(service string, tlscfg *tls.Config, tags map[string]string) (*Listener, error)
- func (s *Netceptor) ListenContext(ctx context.Context, service string, tlscfg *tls.Config) (*Listener, error)
- func (s *Netceptor) ListenContextAndAdvertise(ctx context.Context, service string, tlscfg *tls.Config, ...) (*Listener, error)
- func (s *Netceptor) ListenPacket(service string) (*PacketConn, error)
- func (s *Netceptor) ListenPacketAndAdvertise(service string, tags map[string]string) (*PacketConn, error)
- func (s *Netceptor) MTU() int
- func (s *Netceptor) MaxConnectionIdleTime() time.Duration
- func (s *Netceptor) MaxForwardingHops() byte
- func (s *Netceptor) NetceptorDone() <-chan struct{}
- func (s *Netceptor) NewAddr(node string, service string) Addr
- func (s *Netceptor) NodeID() string
- func (s *Netceptor) PathCost(nodeID string) (float64, error)
- func (s *Netceptor) Ping(ctx context.Context, target string, hopsToLive byte) (time.Duration, string, error)
- func (s *Netceptor) RouteUpdateTime() time.Duration
- func (s *Netceptor) SeenUpdateExpireTime() time.Duration
- func (s *Netceptor) ServiceAdTime() time.Duration
- func (s *Netceptor) SetClientTLSConfig(name string, config *tls.Config, pinnedFingerprints [][]byte) error
- func (s *Netceptor) SetServerTLSConfig(name string, config *tls.Config) error
- func (s *Netceptor) Shutdown()
- func (s *Netceptor) Status() Status
- func (s *Netceptor) SubscribeRoutingUpdates() chan map[string]string
- func (s *Netceptor) Traceroute(ctx context.Context, target string) <-chan *TracerouteResult
- type PacketConn
- func (pc *PacketConn) Close() error
- func (pc *PacketConn) LocalAddr() net.Addr
- func (pc *PacketConn) LocalService() string
- func (pc *PacketConn) ReadFrom(p []byte) (n int, addr net.Addr, err error)
- func (pc *PacketConn) SetDeadline(t time.Time) error
- func (pc *PacketConn) SetHopsToLive(hopsToLive byte)
- func (pc *PacketConn) SetReadDeadline(t time.Time) error
- func (pc *PacketConn) SetWriteDeadline(t time.Time) error
- func (pc *PacketConn) SubscribeUnreachable(doneChan chan struct{}) chan UnreachableNotification
- func (pc *PacketConn) WriteTo(p []byte, addr net.Addr) (n int, err error)
- type ReceptorCertNameError
- type ServiceAdvertisement
- type Status
- type TimeoutError
- type TracerouteResult
- type UnreachableMessage
- type UnreachableNotification
- type VerifyType
- type WorkCommand
Constants ¶
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 )
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" )
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 )
Variables ¶
var ErrTimeout error = &TimeoutError{}
ErrTimeout is returned for an expired deadline.
var KeepAliveForQuicConnections = true
KeepAliveForQuicConnections is variablized to enable testing of the timeout. If you are doing a heartbeat your connection wont timeout without severing the connection i.e. firewall. Having this variablized allows the tests to set KeepAliveForQuicConnections = False so that things will properly fail.
var MaxIdleTimeoutForQuicConnections = 30 * time.Second
MaxIdleTimeoutForQuicConnections for quic connections. The default is 30 which we have replicated here. This value is set on both Dial and Listen connections as the quic library would take the smallest of either connection.
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 ¶
BackendNodeCost is a modifier for AddBackend, which sets the per-node connection costs.
func ReceptorVerifyFunc ¶ added in v1.2.0
func ReceptorVerifyFunc(tlscfg *tls.Config, pinnedFingerprints [][]byte, expectedHostname string, expectedHostnameType ExpectedHostnameType, verifyType VerifyType, ) func(rawCerts [][]byte, verifiedChains [][]*x509.Certificate) error
ReceptorVerifyFunc generates a function that verifies a Receptor node ID.
Types ¶
type Addr ¶
type Addr struct {
// contains filtered or unexported fields
}
Addr represents an endpoint address on the Netceptor network.
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) CloseConnection ¶
func (*Conn) RemoteAddr ¶
RemoteAddr returns the remote address of this connection.
func (*Conn) SetDeadline ¶
SetDeadline sets both read and write deadlines.
func (*Conn) SetReadDeadline ¶
SetReadDeadline sets the read deadline.
func (*Conn) SetWriteDeadline ¶
SetWriteDeadline sets the write deadline.
type ConnStatus ¶
ConnStatus holds information about a single connection in the Status struct.
type ErrorFunc ¶
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 ExpectedHostnameType ¶ added in v1.2.0
type ExpectedHostnameType int
ExpectedHostnameType indicates whether we are connecting to a DNS hostname or a Receptor Node ID.
const ( // ExpectedHostnameTypeDNS indicates we are expecting a DNS style hostname. ExpectedHostnameTypeDNS ExpectedHostnameType = 1 // ExpectedHostnameTypeReceptor indicates we are expecting a Receptor node ID. ExpectedHostnameTypeReceptor = 2 )
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) context.Context
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. The returned context will be cancelled after the connection closes.
func (*ExternalBackend) Start ¶
func (b *ExternalBackend) Start(ctx context.Context, _ *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) 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.
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 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 ¶
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 ¶
AddWorkCommand records a work command so it can be included in service announcements.
func (*Netceptor) BackendCount ¶
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) 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 ExpectedHostnameType) (*tls.Config, error)
GetClientTLSConfig retrieves a client TLS config by name. Supported host name types are dns and receptor.
func (*Netceptor) GetServerTLSConfig ¶
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 ¶
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) MaxConnectionIdleTime ¶
MaxConnectionIdleTime returns the configured MaxConnectionIdleTime of this Netceptor instance.
func (*Netceptor) MaxForwardingHops ¶
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 ¶
NewAddr generates a Receptor network address from a node ID and service name.
func (*Netceptor) PathCost ¶
PathCost returns the cost to a given remote node, or an error if the node doesn't exist.
func (*Netceptor) Ping ¶ added in v1.2.0
func (s *Netceptor) Ping(ctx context.Context, target string, hopsToLive byte) (time.Duration, string, error)
Ping sends a single test packet and waits for a reply or error.
func (*Netceptor) RouteUpdateTime ¶
RouteUpdateTime returns the configured RouteUpdateTime of this Netceptor instance.
func (*Netceptor) SeenUpdateExpireTime ¶
SeenUpdateExpireTime returns the configured SeenUpdateExpireTime of this Netceptor instance.
func (*Netceptor) ServiceAdTime ¶
ServiceAdTime returns the configured ServiceAdTime of this Netceptor instance.
func (*Netceptor) SetClientTLSConfig ¶
func (s *Netceptor) SetClientTLSConfig(name string, config *tls.Config, pinnedFingerprints [][]byte) error
SetClientTLSConfig stores a client TLS config by name.
func (*Netceptor) SetServerTLSConfig ¶
SetServerTLSConfig stores a server TLS config by name.
func (*Netceptor) Shutdown ¶
func (s *Netceptor) Shutdown()
Shutdown shuts down a Netceptor instance.
func (*Netceptor) SubscribeRoutingUpdates ¶
SubscribeRoutingUpdates subscribes for messages when the routing table is changed.
func (*Netceptor) Traceroute ¶ added in v1.2.0
func (s *Netceptor) Traceroute(ctx context.Context, target string) <-chan *TracerouteResult
Traceroute returns a channel which will receive a series of hops between this node and the target.
type PacketConn ¶
type PacketConn struct {
// contains filtered or unexported fields
}
PacketConn implements the net.PacketConn interface via the Receptor network.
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 ¶
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.
type ReceptorCertNameError ¶
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 TracerouteResult ¶ added in v1.2.0
TracerouteResult is the result of one hop of a traceroute.
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 VerifyType ¶ added in v1.2.0
type VerifyType int
VerifyType indicates whether we are verifying a server or client.
const ( // VerifyServer indicates we are the client, verifying a server. VerifyServer VerifyType = 1 // VerifyClient indicates we are the server, verifying a client. VerifyClient = 2 )
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.