Documentation
¶
Overview ¶
Package kernel is the Go wrapper over a logos-delivery node.
Node owns the library context, and is the only place the underlying FFI handle lives. The kernel protocols are reached through facades taken from a Node, one per protocol:
node, err := kernel.New(kernel.Config{Preset: kernel.PresetLogosDev})
defer node.Close()
node.Start()
node.Relay().Subscribe(pubsubTopic)
node.Peers().Connect(ctx, addr)
resp, err := node.Store().Query(ctx, request, peerInfo)
id, err := node.Debug().PeerID()
The grouping mirrors the C library's own modules: Relay, Store, Peers, DiscV5, PeerExchange, DNSDiscovery and Debug map onto kernel_api/protocols/relay_api.nim, store_api.nim, peer_manager_api.nim, discovery_api.nim and debug_node_api.nim. Node itself carries only the lifecycle.
This package knows nothing of the Messaging API. That tier lives in pkg/messaging, whose MessagingClient drives a Node and exposes it, so both tiers run against one node.
Index ¶
- Constants
- Variables
- func ConnectAllPeers(nodes []*Node) error
- func FormatWakuRelayTopic(clusterID uint16, shard uint16) string
- func Handle(n *Node) ffi.Handle
- func RetryWithBackOff(o func() error, options ...BackOffOption) error
- func SetLogger(newLogger *zap.Logger)
- func SubscribeNodesToTopic(nodes []*Node, topic string) error
- func WaitForAutoConnection(nodeList []*Node) error
- type BackOffOption
- type Config
- type ConnectionChange
- type DNSDiscovery
- type Debug
- func (d *Debug) ENR() (*enode.Node, error)
- func (d *Debug) IsOnline() (bool, error)
- func (d *Debug) ListenAddresses() ([]multiaddr.Multiaddr, error)
- func (d *Debug) MaxMessageSize() (uint64, error)
- func (d *Debug) Metrics() (string, error)
- func (d *Debug) PeerID() (peer.ID, error)
- func (d *Debug) StoreNodes() ([]multiaddr.Multiaddr, error)
- func (d *Debug) Version() (string, error)
- type DiscV5
- type EventHandler
- type ListenerID
- type Mode
- type Node
- func (n *Node) AddEventListener(eventName string, fn EventHandler) (ListenerID, error)
- func (n *Node) Close() error
- func (n *Node) Closed() bool
- func (n *Node) Config() *common.WakuConfig
- func (n *Node) ConnectionChanges() <-chan ConnectionChange
- func (n *Node) CreateMessage(customMessage ...*pb.WakuMessage) *pb.WakuMessage
- func (n *Node) DNSDiscovery() *DNSDiscovery
- func (n *Node) Debug() *Debug
- func (n *Node) DiscV5() *DiscV5
- func (n *Node) GetStoredMessages(storeNode *Node, storeRequest *common.StoreQueryRequest) (*common.StoreQueryResponse, error)
- func (n *Node) Messages() <-chan common.Envelope
- func (n *Node) OnClose(fn func())
- func (n *Node) PeerExchange() *PeerExchange
- func (n *Node) Peers() *Peers
- func (n *Node) Relay() *Relay
- func (n *Node) RemoveEventListener(id ListenerID) error
- func (n *Node) Start() error
- func (n *Node) Stop() error
- func (n *Node) Store() *Store
- func (n *Node) TopicHealthChanges() <-chan TopicHealth
- func (n *Node) VerifyMessageReceived(expectedMessage *pb.WakuMessage, expectedHash common.MessageHash, ...) error
- type NwakuInfo
- type Overrides
- type PeerExchange
- type Peers
- func (p *Peers) ByProtocol(protocol libp2pproto.ID) (peer.IDSlice, error)
- func (p *Peers) Connect(ctx context.Context, addr multiaddr.Multiaddr) error
- func (p *Peers) ConnectTo(ctx context.Context, target *Node) error
- func (p *Peers) Connected() (peer.IDSlice, error)
- func (p *Peers) ConnectedInfo() (common.PeersData, error)
- func (p *Peers) Dial(ctx context.Context, addr multiaddr.Multiaddr, protocol libp2pproto.ID) error
- func (p *Peers) DialByID(ctx context.Context, id peer.ID, protocol libp2pproto.ID) error
- func (p *Peers) Disconnect(id peer.ID) error
- func (p *Peers) DisconnectAll() error
- func (p *Peers) DisconnectFrom(target *Node) error
- func (p *Peers) FromPeerStore() (peer.IDSlice, error)
- func (p *Peers) NumConnected() (int, error)
- func (p *Peers) Ping(ctx context.Context, peerInfo peer.AddrInfo) (time.Duration, error)
- type Relay
- func (r *Relay) AddProtectedShard(clusterID, shardID uint16, pubkey *ecdsa.PublicKey) error
- func (r *Relay) ConnectedPeers(optPubsubTopic ...string) (peer.IDSlice, error)
- func (r *Relay) NumConnectedPeers(optPubsubTopic ...string) (int, error)
- func (r *Relay) NumPeersInMesh(pubsubTopic string) (int, error)
- func (r *Relay) PeersInMesh(pubsubTopic string) (peer.IDSlice, error)
- func (r *Relay) Publish(ctx context.Context, pubsubTopic string, message *pb.WakuMessage) (common.MessageHash, error)
- func (r *Relay) Subscribe(pubsubTopic string) error
- func (r *Relay) Unsubscribe(pubsubTopic string) error
- type Store
- type TopicHealth
Constants ¶
const ( PresetTWN = "twn" // The Waku Network PresetLogosDev = "logos.dev" // Logos Dev Network PresetLogosTest = "logos.test" // Logos Test Network PresetStatusProd = "status.prod" // Status Production Network )
Network presets. A preset fixes the cluster id, sharding, entry nodes and RLN settings for a known network, so a Config usually needs nothing else.
const ConnectPeerTimeout = 10 * time.Second //default timeout for node to connect to another node
const DefaultTimeOut = 3 * time.Second
const EventChanBufferSize = 1024
EventChanBufferSize bounds each of a node's event streams. Events are dropped rather than blocked when a consumer falls behind, so the library's event thread is never stalled by a slow reader.
Variables ¶
var ( MinPort = 1024 // Minimum allowable port (exported) MaxPort = 65535 // Maximum allowable port (exported) )
var CONTENT_TOPICS_DIFFERENT_SHARDS = []string{
"/myapp/1/latest/proto",
"/waku/2/content/test.js",
"/app/22/sometopic/someencoding",
"/toychat/2/huilong/proto",
"/statusim/1/community/cbor",
"/app/27/sometopic/someencoding",
"/app/29/sometopic/someencoding",
"/app/20/sometopic/someencoding",
}
var DEFAULT_CLUSTER_ID = uint16(16)
var DefaultContentTopic = "/test/1/default/proto"
var DefaultPubsubTopic = "/waku/2/rs/16/64"
var DefaultStoreQueryRequest common.StoreQueryRequest
var DefaultWakuConfig common.WakuConfig
var ErrClosed = errors.New("kernel: node is closed")
ErrClosed is returned by operations on a Node that has been closed.
var PUBSUB_TOPICS_STORE = []string{ fmt.Sprintf("/waku/2/rs/%d/0", DEFAULT_CLUSTER_ID), fmt.Sprintf("/waku/2/rs/%d/1", DEFAULT_CLUSTER_ID), fmt.Sprintf("/waku/2/rs/%d/2", DEFAULT_CLUSTER_ID), fmt.Sprintf("/waku/2/rs/%d/3", DEFAULT_CLUSTER_ID), fmt.Sprintf("/waku/2/rs/%d/4", DEFAULT_CLUSTER_ID), fmt.Sprintf("/waku/2/rs/%d/5", DEFAULT_CLUSTER_ID), fmt.Sprintf("/waku/2/rs/%d/6", DEFAULT_CLUSTER_ID), fmt.Sprintf("/waku/2/rs/%d/7", DEFAULT_CLUSTER_ID), fmt.Sprintf("/waku/2/rs/%d/8", DEFAULT_CLUSTER_ID), }
var SAMPLE_INPUTS = []struct { Description string Value string }{ {"A simple string", "Hello World!"}, {"An integer", "1234567890"}, {"A dictionary", `{"key": "value"}`}, {"Chinese characters", "这是一些中文"}, {"Emojis", "🚀🌟✨"}, {"Lorem ipsum text", "Lorem ipsum dolor sit amet"}, {"HTML content", "<html><body>Hello</body></html>"}, {"Cyrillic characters", "\u041f\u0440\u0438\u0432\u0435\u0442"}, {"Base64 encoded string", "Base64==dGVzdA=="}, {"Binary data", "d29ya2luZyB3aXRoIGJpbmFyeSBkYXRh: \x50\x51"}, {"Special characters with whitespace", "\t\nSpecial\tCharacters\n"}, {"Boolean false as a string", "False"}, {"A float number", "3.1415926535"}, {"A list", "[1, 2, 3, 4, 5]"}, {"Hexadecimal number as a string", "0xDEADBEEF"}, {"Email format", "user@example.com"}, {"URL format", "http://example.com"}, {"Date and time in ISO format", "2023-11-01T12:00:00Z"}, {"String with escaped quotes", `"Escaped" \"quotes\"`}, {"A regular expression", "Regular expression: ^[a-z0-9_-]{3,16}$"}, {"A very long string", "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"}, {"A JSON string", `{"name": "John", "age": 30, "city": "New York"}`}, {"A Unix path", "/usr/local/bin"}, {"A Windows path", "C:\\Windows\\System32"}, {"An SQL query", "SELECT * FROM users WHERE id = 1;"}, {"JavaScript code snippet", "function test() { console.log('Hello World'); }"}, {"A CSS snippet", "body { background-color: #fff; }"}, {"A Python one-liner", "print('Hello World')"}, {"An IP address", "192.168.1.1"}, {"A domain name", "www.example.com"}, {"A user agent string", "Mozilla/5.0 (Windows NT 10.0; Win64; x64)"}, {"A credit card number", "1234-5678-9012-3456"}, {"A phone number", "+1234567890"}, {"A UUID", "123e4567-e89b-12d3-a456-426614174000"}, {"A hashtag", "#helloWorld"}, {"A Twitter handle", "@username"}, {"A password", "P@ssw0rd!"}, {"A date in common format", "01/11/2023"}, {"A time string", "12:00:00"}, {"A mathematical equation", "E = mc^2"}, }
Functions ¶
func ConnectAllPeers ¶
func FormatWakuRelayTopic ¶
FormatWakuRelayTopic renders the pubsub topic for a cluster's shard.
func Handle ¶
Handle returns the library context a node owns, for the API tiers this module builds on top of one. Use the facades instead.
func RetryWithBackOff ¶
func RetryWithBackOff(o func() error, options ...BackOffOption) error
func SubscribeNodesToTopic ¶
func WaitForAutoConnection ¶
Types ¶
type BackOffOption ¶
type BackOffOption func(*backoff.ExponentialBackOff)
type Config ¶
type Config struct {
// Mode is the node role. Defaults to ModeCore when empty.
Mode Mode `json:"mode,omitempty"`
// Preset names the network to join, e.g. PresetLogosDev.
Preset string `json:"preset,omitempty"`
// MessagingOverrides overrides individual node configuration fields, e.g.
// {"tcp-port": 60000, "listen-address": "0.0.0.0"}.
MessagingOverrides Overrides `json:"messagingOverrides,omitempty"`
// ChannelsOverrides overrides reliable-channel configuration fields.
ChannelsOverrides Overrides `json:"channelsOverrides,omitempty"`
}
TODO: mode and preset are MessagingClient concerns, not kernel ones. They live here because one library call configures every layer at once; once logos-delivery splits those responsibilities and each layer can be configured on its own, the kernel's configuration will look different.
Config is a node's configuration. It marshals to the layered configuration JSON that logosdelivery_create_node consumes: a network preset plus, optionally, overrides for the messaging and reliable-channel layers.
Every marshalled field is omitted when empty, and that matters: the library still accepts a legacy flat configuration blob, and it decides between the two shapes by looking for bare top-level keys. A Config that emitted zero values would be read as a flat blob and silently ignore the layered defaults, so do not add fields here without `omitempty`.
type ConnectionChange ¶
ConnectionChange reports a peer connecting to or disconnecting from the node.
type DNSDiscovery ¶
type DNSDiscovery struct {
// contains filtered or unexported fields
}
DNSDiscovery is a Node's DNS-based peer discovery surface. Take one with Node.DNSDiscovery.
type Debug ¶
type Debug struct {
// contains filtered or unexported fields
}
Debug is a Node's own identity and health surface. Take one with Node.Debug.
func (*Debug) IsOnline ¶
IsOnline reports whether the node considers itself connected to the network.
func (*Debug) ListenAddresses ¶
ListenAddresses returns the multiaddresses the node listens on.
func (*Debug) MaxMessageSize ¶
MaxMessageSize returns the largest message, in bytes, the node accepts.
func (*Debug) StoreNodes ¶
StoreNodes returns the store nodes of the node's network preset.
type DiscV5 ¶
type DiscV5 struct {
// contains filtered or unexported fields
}
DiscV5 is a Node's DiscV5 peer discovery surface. Take one with Node.DiscV5.
type EventHandler ¶
type EventHandler func(eventJSON string)
EventHandler receives the raw JSON of every event emitted under the name it was registered for. It runs on the library's event thread, so it must not block: hand work off to a buffered channel or a goroutine.
type ListenerID ¶
type ListenerID uint64
ListenerID identifies one event listener registered on a Node.
type Node ¶
type Node struct {
// contains filtered or unexported fields
}
Node is a logos-delivery node: the owner of the library context, and the only place the underlying FFI handle lives. The protocols are reached through the facades taken from it — Relay, Store, Peers, DiscV5, PeerExchange, DNSDiscovery and Debug.
The lifecycle is New -> Start -> ... -> Stop -> Close. Close is idempotent and releases the context, so it is safe to defer it right after New.
A Node is safe for concurrent use.
func New ¶
New builds a node from a layered configuration and returns it ready to Start. Release it with Close, started or not.
func NewFromWakuConfig ¶
func NewFromWakuConfig(cfg *common.WakuConfig) (*Node, error)
NewFromWakuConfig builds a node from the legacy flat configuration blob. New is the preferred door: it takes the layered configuration the library expects, and a preset covers most of what this struct spells out by hand.
func (*Node) AddEventListener ¶
func (n *Node) AddEventListener(eventName string, fn EventHandler) (ListenerID, error)
AddEventListener registers fn to receive the named event, and returns the id that removes it again. Event names are the library's wire names, e.g. "onMessageReceived". Register before Start so no event is missed; a listener left registered at Close is removed with the node.
func (*Node) Close ¶
Close stops the node if it is running, releases the library context and runs the hooks registered with OnClose. It is idempotent. The node and every facade taken from it must not be used afterwards, and no other method may be in flight when it is called.
func (*Node) Config ¶
func (n *Node) Config() *common.WakuConfig
Config returns the legacy flat configuration the node was built from, or nil when it was built from a Config.
func (*Node) ConnectionChanges ¶
func (n *Node) ConnectionChanges() <-chan ConnectionChange
ConnectionChanges is the stream of peer connect and disconnect events. It has the same buffered, lossy delivery as Messages.
func (*Node) CreateMessage ¶
func (n *Node) CreateMessage(customMessage ...*pb.WakuMessage) *pb.WakuMessage
func (*Node) DNSDiscovery ¶
func (n *Node) DNSDiscovery() *DNSDiscovery
DNSDiscovery is the DNS-based peer discovery surface.
func (*Node) GetStoredMessages ¶
func (n *Node) GetStoredMessages(storeNode *Node, storeRequest *common.StoreQueryRequest) (*common.StoreQueryResponse, error)
func (*Node) Messages ¶
Messages is the stream of messages received on the pubsub topics the node relays. The channel is buffered and lossy: a message is dropped when a consumer falls behind rather than stalling the library's event thread.
func (*Node) OnClose ¶
func (n *Node) OnClose(fn func())
OnClose registers fn to run while the node is closing, after its event listeners are removed and before the library context is released. Layers built on a Node use it to tear down their own state exactly once.
func (*Node) PeerExchange ¶
func (n *Node) PeerExchange() *PeerExchange
PeerExchange is the peer exchange protocol surface.
func (*Node) RemoveEventListener ¶
func (n *Node) RemoveEventListener(id ListenerID) error
RemoveEventListener removes a listener previously added with AddEventListener.
func (*Node) TopicHealthChanges ¶
func (n *Node) TopicHealthChanges() <-chan TopicHealth
TopicHealthChanges is the stream of relay mesh health changes. It has the same buffered, lossy delivery as Messages.
func (*Node) VerifyMessageReceived ¶
func (n *Node) VerifyMessageReceived(expectedMessage *pb.WakuMessage, expectedHash common.MessageHash, timeout ...time.Duration) error
type NwakuInfo ¶
type Overrides ¶
Overrides is a bag of per-field configuration overrides. Keys are node configuration field names or their CLI switch equivalents ("clusterId" or "cluster-id"); the library rejects keys it does not recognise.
type PeerExchange ¶
type PeerExchange struct {
// contains filtered or unexported fields
}
PeerExchange is a Node's peer exchange protocol surface. Take one with Node.PeerExchange.
type Peers ¶
type Peers struct {
// contains filtered or unexported fields
}
Peers is a Node's peer management surface: dialling, disconnecting and inspecting the peer store. Take one with Node.Peers.
func (*Peers) ByProtocol ¶
ByProtocol returns the known peers that support a protocol.
func (*Peers) Connect ¶
Connect dials a peer multiaddress. A ctx without a deadline gets the package default of 30s.
func (*Peers) ConnectedInfo ¶
ConnectedInfo returns the protocols and addresses of every connected peer.
func (*Peers) Dial ¶
Dial dials a peer multiaddress over a specific protocol. A ctx without a deadline gets the package default of 30s.
func (*Peers) DialByID ¶
DialByID dials a known peer over a specific protocol. A ctx without a deadline gets the package default of 30s.
func (*Peers) Disconnect ¶
Disconnect drops the connection to a peer.
func (*Peers) DisconnectAll ¶
DisconnectAll drops every peer connection.
func (*Peers) DisconnectFrom ¶
DisconnectFrom drops the connection to another node.
func (*Peers) FromPeerStore ¶
FromPeerStore returns every peer the peer store knows about, connected or not.
func (*Peers) NumConnected ¶
NumConnected returns the number of currently connected peers.
type Relay ¶
type Relay struct {
// contains filtered or unexported fields
}
Relay is a Node's relay protocol surface: gossipsub subscriptions, publishing and the state of the relay mesh. Take one with Node.Relay.
func (*Relay) AddProtectedShard ¶
AddProtectedShard registers the public key allowed to sign messages on a protected shard.
func (*Relay) ConnectedPeers ¶
ConnectedPeers returns the connected relay peers, optionally narrowed to one pubsub topic.
func (*Relay) NumConnectedPeers ¶
NumConnectedPeers returns the connected relay peer count, optionally narrowed to one pubsub topic.
func (*Relay) NumPeersInMesh ¶
NumPeersInMesh returns the relay mesh peer count for a pubsub topic.
func (*Relay) PeersInMesh ¶
PeersInMesh returns the relay mesh peers for a pubsub topic.
func (*Relay) Publish ¶
func (r *Relay) Publish( ctx context.Context, pubsubTopic string, message *pb.WakuMessage, ) (common.MessageHash, error)
Publish publishes a message on a pubsub topic and returns its hash. A ctx without a deadline gets the package default of 30s.
func (*Relay) Subscribe ¶
Subscribe joins the relay mesh for a pubsub topic. Messages received on it arrive on Node.Messages.
func (*Relay) Unsubscribe ¶
Unsubscribe leaves the relay mesh for a pubsub topic.
type Store ¶
type Store struct {
// contains filtered or unexported fields
}
Store is a Node's store protocol surface. Take one with Node.Store.
type TopicHealth ¶
type TopicHealth struct {
PubsubTopic string `json:"pubsubTopic"`
TopicHealth string `json:"topicHealth"`
}
TopicHealth reports how well a pubsub topic's relay mesh is populated.