kernel

package
v0.0.0-...-dca998d Latest Latest
Warning

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

Go to latest
Published: Nov 3, 2026 License: Apache-2.0, MIT Imports: 28 Imported by: 0

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

View Source
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.

View Source
const ConnectPeerTimeout = 10 * time.Second //default timeout for node to connect to another node
View Source
const DefaultTimeOut = 3 * time.Second
View Source
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

View Source
var (
	MinPort = 1024  // Minimum allowable port (exported)
	MaxPort = 65535 // Maximum allowable port (exported)
)
View Source
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",
}
View Source
var DEFAULT_CLUSTER_ID = uint16(16)
View Source
var DefaultContentTopic = "/test/1/default/proto"
View Source
var DefaultPubsubTopic = "/waku/2/rs/16/64"
View Source
var DefaultStoreQueryRequest common.StoreQueryRequest
View Source
var DefaultWakuConfig common.WakuConfig
View Source
var ErrClosed = errors.New("kernel: node is closed")

ErrClosed is returned by operations on a Node that has been closed.

View Source
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),
}
View Source
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 ConnectAllPeers(nodes []*Node) error

func FormatWakuRelayTopic

func FormatWakuRelayTopic(clusterID uint16, shard uint16) string

FormatWakuRelayTopic renders the pubsub topic for a cluster's shard.

func Handle

func Handle(n *Node) ffi.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 SetLogger

func SetLogger(newLogger *zap.Logger)

func SubscribeNodesToTopic

func SubscribeNodesToTopic(nodes []*Node, topic string) error

func WaitForAutoConnection

func WaitForAutoConnection(nodeList []*Node) error

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

type ConnectionChange struct {
	PeerID    peer.ID `json:"peerId"`
	PeerEvent string  `json:"peerEvent"`
}

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.

func (*DNSDiscovery) Resolve

func (d *DNSDiscovery) Resolve(
	ctx context.Context, enrTreeURL, nameDNSServer string,
) ([]multiaddr.Multiaddr, error)

Resolve resolves an ENR tree URL and returns the multiaddresses it advertises. A ctx without a deadline gets the package default of 30s.

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) ENR

func (d *Debug) ENR() (*enode.Node, error)

ENR returns the node's own ENR record.

func (*Debug) IsOnline

func (d *Debug) IsOnline() (bool, error)

IsOnline reports whether the node considers itself connected to the network.

func (*Debug) ListenAddresses

func (d *Debug) ListenAddresses() ([]multiaddr.Multiaddr, error)

ListenAddresses returns the multiaddresses the node listens on.

func (*Debug) MaxMessageSize

func (d *Debug) MaxMessageSize() (uint64, error)

MaxMessageSize returns the largest message, in bytes, the node accepts.

func (*Debug) Metrics

func (d *Debug) Metrics() (string, error)

Metrics returns the node's metrics in Prometheus text format.

func (*Debug) PeerID

func (d *Debug) PeerID() (peer.ID, error)

PeerID returns the node's own peer id.

func (*Debug) StoreNodes

func (d *Debug) StoreNodes() ([]multiaddr.Multiaddr, error)

StoreNodes returns the store nodes of the node's network preset.

func (*Debug) Version

func (d *Debug) Version() (string, error)

Version returns the library version the node runs.

type DiscV5

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

DiscV5 is a Node's DiscV5 peer discovery surface. Take one with Node.DiscV5.

func (*DiscV5) Start

func (d *DiscV5) Start() error

Start starts DiscV5 peer discovery.

func (*DiscV5) Stop

func (d *DiscV5) Stop() error

Stop stops DiscV5 peer discovery.

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 Mode

type Mode string

Mode selects how much of the stack a node runs.

const (
	// ModeCore runs a full node: relay plus the service protocols.
	ModeCore Mode = "Core"
	// ModeEdge runs a light client: lightpush, filter and store clients.
	ModeEdge Mode = "Edge"
)

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

func New(cfg Config) (*Node, error)

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

func (n *Node) Close() error

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) Closed

func (n *Node) Closed() bool

Closed reports whether the node has been closed.

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) Debug

func (n *Node) Debug() *Debug

Debug is the node's own identity and health surface.

func (*Node) DiscV5

func (n *Node) DiscV5() *DiscV5

DiscV5 is the DiscV5 peer discovery surface.

func (*Node) GetStoredMessages

func (n *Node) GetStoredMessages(storeNode *Node, storeRequest *common.StoreQueryRequest) (*common.StoreQueryResponse, error)

func (*Node) Messages

func (n *Node) Messages() <-chan common.Envelope

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) Peers

func (n *Node) Peers() *Peers

Peers is the peer management surface.

func (*Node) Relay

func (n *Node) Relay() *Relay

Relay is the relay protocol surface.

func (*Node) RemoveEventListener

func (n *Node) RemoveEventListener(id ListenerID) error

RemoveEventListener removes a listener previously added with AddEventListener.

func (*Node) Start

func (n *Node) Start() error

Start starts the node's protocols and services.

func (*Node) Stop

func (n *Node) Stop() error

Stop stops the node. A stopped node can be started again.

func (*Node) Store

func (n *Node) Store() *Store

Store is the store protocol surface.

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 NwakuInfo struct {
	ListenAddresses []string `json:"listenAddresses"`
	EnrUri          string   `json:"enrUri"`
}

func GetNwakuInfo

func GetNwakuInfo(host *string, port *int) (NwakuInfo, error)

type Overrides

type Overrides map[string]any

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.

func (*PeerExchange) Request

func (p *PeerExchange) Request(numPeers uint64) (uint64, error)

Request asks peer exchange for numPeers peers and returns how many were received.

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

func (p *Peers) ByProtocol(protocol libp2pproto.ID) (peer.IDSlice, error)

ByProtocol returns the known peers that support a protocol.

func (*Peers) Connect

func (p *Peers) Connect(ctx context.Context, addr multiaddr.Multiaddr) error

Connect dials a peer multiaddress. A ctx without a deadline gets the package default of 30s.

func (*Peers) ConnectTo

func (p *Peers) ConnectTo(ctx context.Context, target *Node) error

ConnectTo dials another node by its first listen address.

func (*Peers) Connected

func (p *Peers) Connected() (peer.IDSlice, error)

Connected returns the currently connected peers.

func (*Peers) ConnectedInfo

func (p *Peers) ConnectedInfo() (common.PeersData, error)

ConnectedInfo returns the protocols and addresses of every connected peer.

func (*Peers) Dial

func (p *Peers) Dial(ctx context.Context, addr multiaddr.Multiaddr, protocol libp2pproto.ID) error

Dial dials a peer multiaddress over a specific protocol. A ctx without a deadline gets the package default of 30s.

func (*Peers) DialByID

func (p *Peers) DialByID(ctx context.Context, id peer.ID, protocol libp2pproto.ID) error

DialByID dials a known peer over a specific protocol. A ctx without a deadline gets the package default of 30s.

func (*Peers) Disconnect

func (p *Peers) Disconnect(id peer.ID) error

Disconnect drops the connection to a peer.

func (*Peers) DisconnectAll

func (p *Peers) DisconnectAll() error

DisconnectAll drops every peer connection.

func (*Peers) DisconnectFrom

func (p *Peers) DisconnectFrom(target *Node) error

DisconnectFrom drops the connection to another node.

func (*Peers) FromPeerStore

func (p *Peers) FromPeerStore() (peer.IDSlice, error)

FromPeerStore returns every peer the peer store knows about, connected or not.

func (*Peers) NumConnected

func (p *Peers) NumConnected() (int, error)

NumConnected returns the number of currently connected peers.

func (*Peers) Ping

func (p *Peers) Ping(ctx context.Context, peerInfo peer.AddrInfo) (time.Duration, error)

Ping measures the round-trip time to a peer. A ctx without a deadline gets the package default of 30s.

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

func (r *Relay) AddProtectedShard(clusterID, shardID uint16, pubkey *ecdsa.PublicKey) error

AddProtectedShard registers the public key allowed to sign messages on a protected shard.

func (*Relay) ConnectedPeers

func (r *Relay) ConnectedPeers(optPubsubTopic ...string) (peer.IDSlice, error)

ConnectedPeers returns the connected relay peers, optionally narrowed to one pubsub topic.

func (*Relay) NumConnectedPeers

func (r *Relay) NumConnectedPeers(optPubsubTopic ...string) (int, error)

NumConnectedPeers returns the connected relay peer count, optionally narrowed to one pubsub topic.

func (*Relay) NumPeersInMesh

func (r *Relay) NumPeersInMesh(pubsubTopic string) (int, error)

NumPeersInMesh returns the relay mesh peer count for a pubsub topic.

func (*Relay) PeersInMesh

func (r *Relay) PeersInMesh(pubsubTopic string) (peer.IDSlice, error)

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

func (r *Relay) Subscribe(pubsubTopic string) error

Subscribe joins the relay mesh for a pubsub topic. Messages received on it arrive on Node.Messages.

func (*Relay) Unsubscribe

func (r *Relay) Unsubscribe(pubsubTopic string) error

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.

func (*Store) Query

func (s *Store) Query(
	ctx context.Context, request *common.StoreQueryRequest, peerInfo peer.AddrInfo,
) (*common.StoreQueryResponse, error)

Query runs a store query against a store peer and returns its response. A ctx without a deadline gets the package default of 30s.

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.

Directories

Path Synopsis

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
⌂ 换网址