engine

package
v0.1.20 Latest Latest
Warning

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

 Go to latest Published: Jul 19, 2023 License: Unlicense Imports: 55 Imported by: 0

Documentation

Overview

Package engine is the implementation of the core Indra relay and client.

Contains controlling code that interacts with the various subsystems of the engine such as the dispatcher, session manager, libp2p based peer to peer network transport and peer information gossip.

Index

Constants

View Source 
const ErrWrongTypeDecode = "magic '%s' but type is '%s'"

ErrWrongTypeDecode indicates a message has the wrong magic.

View Source 
const (
	// PubSubTopic is the pubsub topic identifier for indra peer information advertisements.
	PubSubTopic = "indra"
)

Variables

This section is empty.

Functions

func MakeReplyHeader 

func MakeReplyHeader(ng *Engine) (returnHeader *hidden.ReplyHeader)

MakeReplyHeader constructs a reply header for hidden service messages.

func PostAcctOnion 

func PostAcctOnion(sm *sess.Manager, o Skins) (res *sess.Data)

PostAcctOnion takes a slice of Skins and calculates their costs and the list of sessions inside them and attaches accounting operations to apply when the associated confirmation(s) or response hooks are executed.

func SetupGossip added in v0.1.16 

func SetupGossip(ctx context.Context, host host.Host,
	cancel func()) (PubSub *pubsub.PubSub, topic *pubsub.Topic,
	sub *pubsub.Subscription, e error)

SetupGossip establishes a connection of a Host to the pubsub gossip network used by Indra to propagate peer metadata.

Types

type Engine 

type Engine struct {
	Responses *responses.Pending

	NodeAds  *ads.NodeAds
	Listener *transport.Listener
	PubSub   *pubsub.PubSub

	KeySet       *crypto.KeySet
	Load         atomic.Uint32
	Pause        qu.C
	ShuttingDown atomic.Bool
	// contains filtered or unexported fields
}

Engine processes onion messages, forwarding the relevant data to other relays and locally accessible servers as indicated by the API function and message parameters.

func CreateAndStartMockEngines added in v0.1.20 

func CreateAndStartMockEngines(n int, ctx context.Context) (engines []*Engine, cleanup func(), e error)

func CreateMockEngine 

func CreateMockEngine(seed, dataPath string, ctx context.Context) (ng *Engine)

CreateMockEngine creates an indra Engine with a random localhost listener.

func CreateNMockCircuits 

func CreateNMockCircuits(nCirc int, nReturns int,
	ctx context.Context) (cl []*Engine, e error)

CreateNMockCircuits creates an arbitrary number of mock circuits from the given specification, with an arbitrary number of mock sessions.

func CreateNMockCircuitsWithSessions 

func CreateNMockCircuitsWithSessions(nCirc int, nReturns int,
	ctx context.Context) (cl []*Engine, e error)

CreateNMockCircuitsWithSessions creates an arbitrary number of mock circuits from the given specification, with an arbitrary number of mock sessions.

func New 

func New(p Params) (ng *Engine, e error)

New creates a new Engine according to the Params given.

func (*Engine) BuyNewSessions 

func (ng *Engine) BuyNewSessions(amount lnwire.MilliSatoshi,
	fn func()) (e error)

BuyNewSessions performs the initial purchase of 5 sessions as well as adding different hop numbers to relays with existing Note that all 5 of the sessions will be paid the amount specified, not divided up.

func (*Engine) Cleanup 

func (ng *Engine) Cleanup()

Cleanup closes and flushes any resources the client opened that require sync in order to reopen correctly.

func (*Engine) ClearPeerRecord added in v0.1.16 

func (ng *Engine) ClearPeerRecord(id peer.ID, key string) (e error)

ClearPeerRecord places an empty slice into a peer record by way of deleting it.

todo: these should be purged from the peerstore in a GC pass.

func (*Engine) GetHidden 

func (ng *Engine) GetHidden() *hidden.Hidden

GetHidden returns the hidden services management handle.

func (*Engine) GetLoad 

func (ng *Engine) GetLoad() byte

GetLoad returns the current load level reported by the Engine.

func (*Engine) GetPeerRecord added in v0.1.16 

func (ng *Engine) GetPeerRecord(id peer.ID, key string) (add ad.Ad, e error)

GetPeerRecord queries the peerstore for an ad from a given peer.ID and the ad type key. The ad type keys are the same as the Magic of each ad type, to be simple.

func (*Engine) HandleAd added in v0.1.15 

func (ng *Engine) HandleAd(p *pubsub.Message) (e error)

HandleAd correctly recognises, validates, and stores the ads in the peerstore.

func (*Engine) HandleMessage 

func (ng *Engine) HandleMessage(s *splice.Splice, pr ont.Onion)

HandleMessage is called to process a message received via the Transport, and invokes the onion's Handle function to process it.

func (*Engine) Handler 

func (ng *Engine) Handler() (terminate bool)

Handler is the main select switch for handling events for the Engine.

func (*Engine) Keyset 

func (ng *Engine) Keyset() *crypto.KeySet

Keyset returns the engine's private key generator.

func (*Engine) Mgr 

func (ng *Engine) Mgr() *sess.Manager

Mgr gives access to the session manager.

func (*Engine) Pending 

func (ng *Engine) Pending() *responses.Pending

Pending gives access to the pending responses' manager.

func (*Engine) RunAdHandler added in v0.1.15 

func (ng *Engine) RunAdHandler(handler func(p *pubsub.Message) (e error))

RunAdHandler listens to the gossip and dispatches messages to be handled and update the peerstore.

func (*Engine) SendAd added in v0.1.15 

func (ng *Engine) SendAd(a slice.Bytes) (e error)

SendAd dispatches an encoded byte slice ostensibly of a peer advertisement to gossip to the rest of the network.

func (*Engine) SendExit 

func (ng *Engine) SendExit(port uint16, msg slice.Bytes, id nonce.ID,
	alice, bob *sessions.Data, hook responses.Callback)

SendExit constructs and dispatches an exit message containing the desired message for the service at the exit.

func (*Engine) SendGetBalance 

func (ng *Engine) SendGetBalance(alice, bob *sessions.Data, hook responses.Callback)

SendGetBalance sends out a balance request to a specific relay we have a session with.

func (*Engine) SendHiddenService 

func (ng *Engine) SendHiddenService(id nonce.ID, key *crypto.Prv, relayRate uint32,
	port uint16, expiry time.Time, alice, bob *sessions.Data, svc *services.Service,
	hook responses.Callback) (in *intro.Ad, e error)

SendHiddenService dispatches a services message, providing a relay the ability to refer clients to the hidden service and initiate connections.

func (*Engine) SendIntroQuery 

func (ng *Engine) SendIntroQuery(id nonce.ID, hsk *crypto.Pub,
	alice, bob *sessions.Data, hook func(in *intro.Ad))

SendIntroQuery delivers a query for a specified hidden service public key.

func (*Engine) SendMessage 

func (ng *Engine) SendMessage(mp *whisper.Message, hook responses.Callback) (id nonce.ID)

SendMessage delivers a message to a hidden service for which we have an existing routing header from a previous or initial message cycle.

func (*Engine) SendPing 

func (ng *Engine) SendPing(c sessions.Circuit, hook responses.Callback)

SendPing sends out a ping message, which provides some low-precision information about the online status and latency of a set of 5 peers we have sessions with.

func (*Engine) SendRoute 

func (ng *Engine) SendRoute(k *crypto.Pub, ap *netip.AddrPort,
	hook responses.Callback)

SendRoute delivers a message to establish a connection to a hidden service via an introducing relay found either through gossip or introquery.

func (*Engine) SetLoad 

func (ng *Engine) SetLoad(load byte)

SetLoad puts a value in the Engine Load level.

func (*Engine) Shutdown 

func (ng *Engine) Shutdown()

Shutdown triggers the shutdown of the client and the Cleanup before finishing.

func (*Engine) Start 

func (ng *Engine) Start()

Start a single thread of the Engine.

func (*Engine) WaitForShutdown added in v0.1.16 

func (ng *Engine) WaitForShutdown() <-chan struct{}

WaitForShutdown returns when the engine has been triggered to stop.

type Params 

type Params struct {
	Transport       tpt.Transport
	Listener        *transport.Listener
	Keys            *crypto.Keys
	Node            *node.Node
	Nodes           []*node.Node
	NReturnSessions int
}

Params are the inputs required to create a new Engine.

type RoutingHeader 

type RoutingHeader struct {
	Layers [3]RoutingLayer
}

RoutingHeader is a stack of 3 RoutingLayer used to construct replies in a source routed architecture.

type RoutingLayer 

type RoutingLayer struct {
	*reverse.Reverse
	*crypt.Crypt
}

RoutingLayer is the reverse and crypt message layers used in a RoutingHeader.

type Skins 

type Skins []ont.Onion

Skins is a slice of onions that can be assembled into a message.

Note that if an address is not found for the enabled protocols the segment will be omitted from the chain, and report the error. It is thus expected that sessions and nodes referenced in a Skins constructor were selected because they have an available protocol.

It would be very uncommon to not have at least IPv4 anyway, but we handle this in an ugly way that should never see the light outside a dev lab.

func MakeExit 

func MakeExit(p exit.Params, np protocols.NetworkProtocols) Skins

MakeExit constructs a message containing an arbitrary payload to a node (3rd hop) with a set of 3 ciphers derived from the hidden PayloadPub of the return hops that are layered progressively after the Exit message.

The Exit node forwards the packet it receives to the local port specified in the Exit message, and then uses the ciphers to encrypt the reply with the three ciphers provided, which don't enable it to decrypt the header, only to encrypt the payload.

The header remains a constant size and each node in the Reverse trims off their section at the top, moves the next crypt header to the top and pads the remainder with noise, so it always looks like the first hop.

func MakeGetBalance 

func MakeGetBalance(p getbalance.GetBalanceParams,
	np protocols.NetworkProtocols) Skins

MakeGetBalance sends out a request in a similar way to Exit except the node being queried can be any of the 5.

func MakeHiddenService 

func MakeHiddenService(in *intro.Ad, alice, bob *sessions.Data,
	c sessions.Circuit, ks *crypto.KeySet,
	p protocols.NetworkProtocols) Skins

MakeHiddenService constructs a services message for designating introducers to refer clients to hidden services.

func MakeIntroQuery 

func MakeIntroQuery(id nonce.ID, hsk *crypto.Pub, alice, bob *sessions.Data,
	c sessions.Circuit, ks *crypto.KeySet,
	p protocols.NetworkProtocols) Skins

MakeIntroQuery constructs a message to query a peer for an intro for a designated hidden service address.

func MakeRoute 

func MakeRoute(id nonce.ID, k *crypto.Pub, ks *crypto.KeySet,
	alice, bob *sessions.Data, c sessions.Circuit,
	p protocols.NetworkProtocols) Skins

MakeRoute constructs a Route message, which a client sends a RoutingHeader to a hidden service for them to reply with a Ready message for establishing a session with a hidden service.

func MakeSession 

func MakeSession(id nonce.ID, s [5]*session.Session,
	client *sessions.Data, hop []*node.Node, ks *crypto.KeySet,
	p protocols.NetworkProtocols) Skins

MakeSession constructs a set of 5 ForwardSession messages to deliver the session keys to newly established sessions paid for via LN.

func Ping 

func Ping(id nonce.ID, client *sessions.Data, s sessions.Circuit,
	ks *crypto.KeySet, p protocols.NetworkProtocols) Skins

Ping is a message which checks the liveness of relays by ensuring they are correctly relaying messages.

The pending ping records keep the identifiers of the 5 nodes that were in a ping onion and when the Confirmation is correctly received these nodes get an increment of their liveness score. By using this scheme, when nodes are offline their scores will fall to zero after a time whereas live nodes will have steadily increasing scores from successful pings.

func (Skins) Confirmation 

func (o Skins) Confirmation(id nonce.ID, load byte) Skins

func (Skins) Crypt 

func (o Skins) Crypt(toHdr, toPld *crypto.Pub, from *crypto.Prv, iv nonce.IV,
	depth int) Skins

Crypt is a layer providing the recipient cloaked address, one-time sender private key and nonce needed to decrypt the remainder of the onion message.

func (Skins) End 

func (o Skins) End() Skins

End is a terminator, construction of a message will halt when it hits one of these.

func (Skins) Exit 

func (o Skins) Exit(id nonce.ID, port uint16, payload slice.Bytes,
	ep *exit.ExitPoint) Skins

Exit inserts an exit message with its request payload.

func (Skins) Forward 

func (o Skins) Forward(addr *netip.AddrPort) Skins

Forward is a simple forwarding instruction, usually followed by a crypt for the recipient.

func (Skins) ForwardCrypt 

func (o Skins) ForwardCrypt(s *sessions.Data, k *crypto.Prv, n nonce.IV, p protocols.NetworkProtocols) Skins

ForwardCrypt is a forwarding and encryption layer for simple forwarding of a message. Used with hidden service messages and pings for legs of the route that do not need to carry a reply.

func (Skins) ForwardSession 

func (o Skins) ForwardSession(s *node.Node,
	k *crypto.Prv, n nonce.IV, sess *session.Session,
	p protocols.NetworkProtocols) Skins

ForwardSession is an onion layer that delivers the two session keys matching a payment preimage to establish a new session.

func (Skins) GetBalance 

func (o Skins) GetBalance(id nonce.ID, ep *exit.ExitPoint) Skins

GetBalance is a message request to reply using a RoutingHeader with the balance of the session, indicated by the key of the Crypt in the previous layer.

func (Skins) HiddenService 

func (o Skins) HiddenService(in *intro.Ad, point *exit.ExitPoint) Skins

HiddenService is a message that delivers an intro and a referral RoutingHeader to enable a relay to introduce a client to a hidden service.

func (Skins) IntroQuery 

func (o Skins) IntroQuery(id nonce.ID, hsk *crypto.Pub, exit *exit.ExitPoint) Skins

IntroQuery is a message that carries a query for a hidden service with a given public key, if the recipient has this intro, it returns it and the client can then form a Route message to establish a connection to it.

func (Skins) Message 

func (o Skins) Message(msg *whisper.Message, ks *crypto.KeySet,
	p protocols.NetworkProtocols) Skins

Message constructs a hidden service message, used on both ends, with the RoutingHeader received in the previosu message from the client or hidden service.

func (Skins) Ready 

func (o Skins) Ready(id nonce.ID, addr *crypto.Pub, fwHdr,
	rvHdr hidden.RoutingHeaderBytes, fc, rc crypto.Ciphers, fn, rn crypto.Nonces) Skins

Ready is a message carrying a reply RoutingHeader for a client to send their first request message to a hidden service.

func (Skins) Response 

func (o Skins) Response(id nonce.ID, res slice.Bytes, port uint16, load byte) Skins

Response constructs a message sent back from an Exit service to a client in response to an Exit message, containing a request.

func (Skins) Reverse 

func (o Skins) Reverse(ip *netip.AddrPort) Skins

Reverse is a special variant of the Forward message that is only used in groups of three to create a RoutingHeader;

func (Skins) ReverseCrypt 

func (o Skins) ReverseCrypt(s *sessions.Data, k *crypto.Prv, n nonce.IV,
	seq int, p protocols.NetworkProtocols) (oo Skins)

ReverseCrypt is a single layer of a RoutingHeader designating the session and relay for one of the hops in a Route.

func (Skins) Route 

func (o Skins) Route(id nonce.ID, k *crypto.Pub, ks *crypto.KeySet, ep *exit.ExitPoint) Skins

Route constructs a new Route message to establish a hidden service connection.

func (Skins) RoutingHeader 

func (o Skins) RoutingHeader(r *exit.Routing,
	p protocols.NetworkProtocols) Skins

RoutingHeader constructs a RoutingHeader using inputs from an exit.Routing. These are used in all hidden service messages too as the path back to both ends of the path provided by the recipient at it.

func (Skins) Session 

func (o Skins) Session(sess *session.Session) Skins

Session generates a message layer carrying the two private keys of a session.

Source Files

View all Source files

Directories

Path Synopsis
Package ads provides a bundle for peer information advertisement types and initial generation of them, and deriving a peer node data structure from the ad set received over the gossip network.
 Package ads provides a bundle for peer information advertisement types and initial generation of them, and deriving a peer node data structure from the ad set received over the gossip network.
Package consts is a series of constants common to several different onion message types.
 Package consts is a series of constants common to several different onion message types.
Package dispatcher is a network packet send/receive handler for peer to peer connections between relays.
 Package dispatcher is a network packet send/receive handler for peer to peer connections between relays.
Package magic is a simple specification and error helper for message identifying 4 byte strings that are used for the switching logic of a relay.
 Package magic is a simple specification and error helper for message identifying 4 byte strings that are used for the switching logic of a relay.
Package node is a specification for the in-memory metadata related to an indra network peer.
 Package node is a specification for the in-memory metadata related to an indra network peer.
Package packet handles segmenting messages into uniform sized packets and generating a stream of cipher halves and receiver cloaked addresses to encrypt them with, and reassembling the segments into the original messages.
 Package packet handles segmenting messages into uniform sized packets and generating a stream of cipher halves and receiver cloaked addresses to encrypt them with, and reassembling the segments into the original messages.
Package payments provides an abstraction above the implementation for handling Lightning Network payments and storing pending payments awaiting session keys.
 Package payments provides an abstraction above the implementation for handling Lightning Network payments and storing pending payments awaiting session keys.
Package responses handles waiting for and responding to received responses, including tracking the session billing and custom callback hooks when responses arrive.
 Package responses handles waiting for and responding to received responses, including tracking the session billing and custom callback hooks when responses arrive.
Package services defines the base data structure for a service.
 Package services defines the base data structure for a service.
Package sess provides the Session Manager, which keeps track of a client's sessions.
 Package sess provides the Session Manager, which keeps track of a client's sessions.
Package sessions defines some key data structures relating to the data for sessions, imported by sess package for reading and writing session and circuit metadata.
 Package sessions defines some key data structures relating to the data for sessions, imported by sess package for reading and writing session and circuit metadata.
Package tpt provides the definition of the interface Transport, which is an abstraction used for reading and writing to peers via transport.Transport.
 Package tpt provides the definition of the interface Transport, which is an abstraction used for reading and writing to peers via transport.Transport.
Package transport provides a set of definitions of abstractions that layer above the implementation enabling the use of simple functions that interact on channels to queue and receive messages from the tpt.Transport of which several variants are here implemented.
 Package transport provides a set of definitions of abstractions that layer above the implementation enabling the use of simple functions that interact on channels to queue and receive messages from the tpt.Transport of which several variants are here implemented.

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.