go-p2p/specs/node.md

node

Import: dappco.re/go/core/p2p/node

Files: 12

Types

Core types

Type	Definition	Description
BundleType	type BundleType string	Deployment bundle kind used by Bundle and BundleManifest.
Bundle	struct{ Type BundleType; Name string; Data []byte; Checksum string }	Transferable deployment bundle. Data contains STIM-encrypted bytes or raw JSON, and Checksum is the SHA-256 hex digest of Data.
BundleManifest	struct{ Type BundleType; Name string; Version string; MinerType string; ProfileIDs []string; CreatedAt string }	Metadata describing the logical contents of a bundle payload.
Controller	struct{ /* unexported fields */ }	High-level controller client for remote peer operations. It keeps a pending-response map keyed by request ID and registers its internal response handler with the transport in NewController.
Dispatcher	struct{ /* unexported fields */ }	Concurrent-safe UEPS router. It applies the threat-score circuit breaker before dispatching to a handler map keyed by IntentID.
IntentHandler	type IntentHandler func(pkt *ueps.ParsedPacket) error	Callback signature used by Dispatcher for verified UEPS packets.
Message	struct{ ID string; Type MessageType; From string; To string; Timestamp time.Time; Payload RawMessage; ReplyTo string }	Generic P2P message envelope. Payload stores raw JSON, and ReplyTo links responses back to the originating request.
MessageDeduplicator	struct{ /* unexported fields */ }	TTL cache of recently seen message IDs used to suppress duplicates.
MessageHandler	type MessageHandler func(conn *PeerConnection, msg *Message)	Callback signature for decrypted inbound transport messages.
MessageType	type MessageType string	String message discriminator stored in Message.Type.
NodeIdentity	struct{ ID string; Name string; PublicKey string; CreatedAt time.Time; Role NodeRole }	Public node identity. ID is derived from the first 16 bytes of the SHA-256 hash of the public key.
NodeManager	struct{ /* unexported fields */ }	Identity and key manager that loads, generates, persists, and deletes X25519 node credentials.
NodeRole	type NodeRole string	Operational mode string for controller, worker, or dual-role nodes.
Peer	struct{ ID string; Name string; PublicKey string; Address string; Role NodeRole; AddedAt time.Time; LastSeen time.Time; PingMS float64; Hops int; GeoKM float64; Score float64; Connected bool }	Registry record for a remote node, including addressing, role, scoring metrics, and transient connection state.
PeerAuthMode	type PeerAuthMode int	Peer admission policy used by PeerRegistry when unknown peers attempt to connect.
PeerConnection	struct{ Peer *Peer; WebSocketConnection *websocket.Conn; SharedSecret []byte; LastActivity time.Time }	Active WebSocket session to a peer, including the negotiated shared secret and transport-owned write/close coordination.
PeerRateLimiter	struct{ /* unexported fields */ }	Per-peer token bucket limiter used by the transport hot path.
PeerRegistry	struct{ /* unexported fields */ }	Concurrent peer store with KD-tree selection, allowlist state, and debounced persistence to disk.
ProtocolError	struct{ Code int; Message string }	Structured remote error returned by protocol response helpers when a peer replies with MsgError.
RawMessage	type RawMessage []byte	Raw JSON payload bytes preserved without eager decoding.
ResponseHandler	struct{}	Helper for validating message envelopes and decoding typed responses.
Transport	struct{ /* unexported fields */ }	WebSocket transport that manages listeners, connections, encryption, deduplication, and shutdown coordination.
TransportConfig	struct{ ListenAddress string; ListenAddr string; WebSocketPath string; TLSCertPath string; TLSKeyPath string; MaxConnections int; MaxMessageSize int64; PingInterval time.Duration; PongTimeout time.Duration }	Listener, TLS, sizing, and keepalive settings for Transport.
Worker	struct{ DataDir string /* plus unexported fields */ }	Inbound command handler for worker nodes. It tracks uptime, optional miner/profile integrations, and the base directory used for deployments.

Payload and integration types

Type	Definition	Description
DeployAckPayload	struct{ Success bool; Name string; Error string }	Deployment acknowledgement with success state, optional deployed name, and optional error text.
DeployPayload	struct{ BundleType string; Data []byte; Checksum string; Name string }	Deployment request carrying STIM-encrypted bundle bytes (or other bundle data), checksum, and logical name.
DisconnectPayload	struct{ Reason string; Code int }	Disconnect notice with human-readable reason and optional disconnect code.
ErrorPayload	struct{ Code int; Message string; Details string }	Payload used by MsgError responses.
LogsRequestPayload	struct{ MinerName string; Lines int; Since int64 }	Request for miner console output, optionally bounded by line count and a Unix timestamp.
HandshakeAckPayload	struct{ Identity NodeIdentity; ChallengeResponse []byte; Accepted bool; Reason string }	Handshake reply containing the responder identity, optional challenge response, acceptance flag, and optional rejection reason.
HandshakePayload	struct{ Identity NodeIdentity; Challenge []byte; Version string }	Handshake request containing node identity, optional authentication challenge, and protocol version.
LogsPayload	struct{ MinerName string; Lines []string; HasMore bool }	Returned miner log lines plus an indicator that more lines are available.
MinerAckPayload	struct{ Success bool; MinerName string; Error string }	Acknowledgement for remote miner start and stop operations.
MinerInstance	interface{ GetName() string; GetType() string; GetStats() (any, error); GetConsoleHistory(lines int) []string }	Minimal runtime miner contract used by the worker to collect stats and logs without importing the mining package.
MinerManager	interface{ StartMiner(minerType string, config any) (MinerInstance, error); StopMiner(name string) error; ListMiners() []MinerInstance; GetMiner(name string) (MinerInstance, error) }	Worker-facing miner control contract.
MinerStatsItem	struct{ Name string; Type string; Hashrate float64; Shares int; Rejected int; Uptime int; Pool string; Algorithm string; CPUThreads int }	Protocol-facing summary of one miner's runtime statistics.
PingPayload	struct{ SentAt int64 }	Ping payload carrying the sender's millisecond timestamp.
PongPayload	struct{ SentAt int64; ReceivedAt int64 }	Ping response carrying the echoed send time and the receiver's millisecond timestamp.
ProfileManager	interface{ GetProfile(id string) (any, error); SaveProfile(profile any) error }	Worker-facing profile storage contract.
StartMinerPayload	struct{ MinerType string; ProfileID string; Config RawMessage }	Request to start a miner with an optional profile ID and raw JSON config override.
StatsPayload	struct{ NodeID string; NodeName string; Miners []MinerStatsItem; Uptime int64 }	Node-wide stats response with node identity fields, miner summaries, and uptime in seconds.
StopMinerPayload	struct{ MinerName string }	Request to stop a miner by name.

Functions

Bundle, protocol, and utility functions

Name	Signature	Description
CreateProfileBundle	func CreateProfileBundle(profileJSON []byte, name string, password string) (*Bundle, error)	Builds a TIM containing profileJSON, encrypts it to STIM with password, and returns a BundleProfile bundle with a SHA-256 checksum.
CreateProfileBundleUnencrypted	func CreateProfileBundleUnencrypted(profileJSON []byte, name string) (*Bundle, error)	Returns a BundleProfile bundle whose Data is the raw JSON payload and whose checksum is computed over that JSON.
CreateMinerBundle	func CreateMinerBundle(minerPath string, profileJSON []byte, name string, password string) (*Bundle, error)	Reads a miner binary, tars it, loads it into a TIM, optionally attaches profileJSON, encrypts the result to STIM, and returns a BundleMiner bundle.
ExtractProfileBundle	func ExtractProfileBundle(bundle *Bundle, password string) ([]byte, error)	Verifies bundle.Checksum, returns raw JSON directly when bundle.Data already looks like JSON, otherwise decrypts STIM and returns the embedded config bytes.
ExtractMinerBundle	func ExtractMinerBundle(bundle *Bundle, password string, destDir string) (string, []byte, error)	Verifies checksum, decrypts STIM, extracts the root filesystem tarball into destDir, and returns the first executable path plus the embedded config bytes.
VerifyBundle	func VerifyBundle(bundle *Bundle) bool	Returns whether bundle.Checksum matches the SHA-256 checksum of bundle.Data.
StreamBundle	func StreamBundle(bundle *Bundle, w io.Writer) error	JSON-encodes bundle and writes it to w.
ReadBundle	func ReadBundle(r io.Reader) (*Bundle, error)	Reads all bytes from r, JSON-decodes them into a Bundle, and returns the result.
GenerateChallenge	func GenerateChallenge() ([]byte, error)	Returns a new 32-byte random authentication challenge.
SignChallenge	func SignChallenge(challenge []byte, sharedSecret []byte) []byte	Computes the HMAC-SHA256 signature of challenge using sharedSecret.
VerifyChallenge	func VerifyChallenge(challenge, response, sharedSecret []byte) bool	Recomputes the expected challenge signature and compares it to response with hmac.Equal.
IsProtocolVersionSupported	func IsProtocolVersionSupported(version string) bool	Returns whether version is present in SupportedProtocolVersions.
MarshalJSON	func MarshalJSON(v any) ([]byte, error)	Encodes v with the core JSON helper, restores the package's historical no-EscapeHTML behaviour, and returns a caller-owned copy of the bytes.
NewMessage	func NewMessage(msgType MessageType, from, to string, payload any) (*Message, error)	Creates a message with a generated UUID, current timestamp, and JSON-encoded payload. A nil payload leaves Payload empty.
NewErrorMessage	func NewErrorMessage(from, to string, code int, message string, replyTo string) (*Message, error)	Creates a MsgError response containing an ErrorPayload and sets ReplyTo to the supplied request ID.
ValidateResponse	func ValidateResponse(resp *Message, expectedType MessageType) error	Convenience wrapper that delegates to DefaultResponseHandler.ValidateResponse.
ParseResponse	func ParseResponse(resp *Message, expectedType MessageType, target any) error	Convenience wrapper that delegates to DefaultResponseHandler.ParseResponse.
IsProtocolError	func IsProtocolError(err error) bool	Returns whether err is a *ProtocolError.
GetProtocolErrorCode	func GetProtocolErrorCode(err error) int	Returns err.(*ProtocolError).Code when err is a *ProtocolError, otherwise 0.

Constructors

Name	Signature	Description
DefaultTransportConfig	func DefaultTransportConfig() TransportConfig	Returns the transport defaults: ListenAddress=:9091, ListenAddr=:9091, WebSocketPath=/ws, MaxConnections=100, MaxMessageSize=1<<20, PingInterval=30s, and PongTimeout=10s.
NewController	func NewController(node *NodeManager, peers *PeerRegistry, transport *Transport) *Controller	Creates a controller, initialises its pending-response map, and installs its response handler on transport.
NewDispatcher	func NewDispatcher() *Dispatcher	Creates an empty dispatcher with a debug-level component logger named dispatcher.
NewMessageDeduplicator	func NewMessageDeduplicator(ttl time.Duration) *MessageDeduplicator	Creates a deduplicator that retains message IDs for the supplied TTL.
NewNodeManager	func NewNodeManager() (*NodeManager, error)	Resolves XDG key and config paths, then loads an existing identity if present.
NewNodeManagerFromPaths	func NewNodeManagerFromPaths(keyPath, configPath string) (*NodeManager, error)	Creates a node manager from explicit key and config paths.
NewPeerRateLimiter	func NewPeerRateLimiter(maxTokens, refillRate int) *PeerRateLimiter	Creates a token bucket seeded with maxTokens and refilled at refillRate tokens per second.
NewPeerRegistry	func NewPeerRegistry() (*PeerRegistry, error)	Resolves the XDG peers path, loads any persisted peers, and builds the selection KD-tree.
NewPeerRegistryFromPath	func NewPeerRegistryFromPath(peersPath string) (*PeerRegistry, error)	Creates a peer registry bound to peersPath with open authentication mode and an empty public-key allowlist.
NewTransport	func NewTransport(node *NodeManager, registry *PeerRegistry, config TransportConfig) *Transport	Creates a transport with lifecycle context, a 5-minute message deduplicator, and a WebSocket upgrader that only accepts local origins.
NewWorker	func NewWorker(node *NodeManager, transport *Transport) *Worker	Creates a worker, records its start time for uptime reporting, and defaults DataDir to xdg.DataHome.

RawMessage methods

Name	Signature	Description
MarshalJSON	func (m RawMessage) MarshalJSON() ([]byte, error)	Emits raw payload bytes unchanged, or null when the receiver is nil.
UnmarshalJSON	func (m *RawMessage) UnmarshalJSON(data []byte) error	Copies data into the receiver without decoding it. Passing a nil receiver returns an error.

*Message methods

Name	Signature	Description
Reply	func (m *Message) Reply(msgType MessageType, payload any) (*Message, error)	Creates a reply message that swaps From and To and sets ReplyTo to m.ID.
ParsePayload	func (m *Message) ParsePayload(v any) error	JSON-decodes Payload into v. A nil payload is treated as a no-op.

*NodeManager methods

Name	Signature	Description
HasIdentity	func (n *NodeManager) HasIdentity() bool	Returns whether an identity is currently loaded in memory.
GetIdentity	func (n *NodeManager) GetIdentity() *NodeIdentity	Returns a copy of the loaded public identity, or nil when no identity is initialised.
GenerateIdentity	func (n *NodeManager) GenerateIdentity(name string, role NodeRole) error	Generates a new X25519 keypair, derives the node ID from the public key hash, stores the public identity, and persists both key and config to disk.
DeriveSharedSecret	func (n *NodeManager) DeriveSharedSecret(peerPubKeyBase64 string) ([]byte, error)	Decodes the peer public key, performs X25519 ECDH with the node private key, hashes the result with SHA-256, and returns the symmetric key material.
Delete	func (n *NodeManager) Delete() error	Removes persisted key/config files when they exist and clears the in-memory identity and key state.

*Controller methods

Name	Signature	Description
GetRemoteStats	func (c *Controller) GetRemoteStats(peerID string) (*StatsPayload, error)	Sends MsgGetStats to peerID, waits for a response, and decodes the resulting MsgStats payload.
StartRemoteMiner	func (c *Controller) StartRemoteMiner(peerID, minerType, profileID string, configOverride RawMessage) error	Validates minerType, sends MsgStartMiner, waits for MsgMinerAck, and returns an error when the remote ack reports failure.
StopRemoteMiner	func (c *Controller) StopRemoteMiner(peerID, minerName string) error	Sends MsgStopMiner, waits for MsgMinerAck, and returns an error when the remote ack reports failure.
GetRemoteLogs	func (c *Controller) GetRemoteLogs(peerID, minerName string, lines int) ([]string, error)	Requests MsgLogs from a remote miner and returns the decoded log lines.
GetAllStats	func (c *Controller) GetAllStats() map[string]*StatsPayload	Requests stats from every currently connected peer and returns the successful responses keyed by peer ID.
PingPeer	func (c *Controller) PingPeer(peerID string) (float64, error)	Sends a ping, measures round-trip time in milliseconds, and updates the peer registry metrics for that peer.
ConnectToPeer	func (c *Controller) ConnectToPeer(peerID string) error	Looks up peerID in the registry and establishes a transport connection.
DisconnectFromPeer	func (c *Controller) DisconnectFromPeer(peerID string) error	Gracefully closes an active transport connection for peerID.

*Dispatcher methods

Name	Signature	Description
RegisterHandler	func (d *Dispatcher) RegisterHandler(intentID byte, handler IntentHandler)	Associates handler with intentID, replacing any existing handler for that intent.
Handlers	func (d *Dispatcher) Handlers() iter.Seq2[byte, IntentHandler]	Returns an iterator over the currently registered intent handlers.
Dispatch	func (d *Dispatcher) Dispatch(pkt *ueps.ParsedPacket) error	Rejects nil packets, drops packets whose ThreatScore exceeds ThreatScoreThreshold, rejects unknown intents, and otherwise invokes the matching handler.

*MessageDeduplicator methods

Name	Signature	Description
IsDuplicate	func (d *MessageDeduplicator) IsDuplicate(msgID string) bool	Returns whether msgID is still present in the deduplicator's TTL window.
Mark	func (d *MessageDeduplicator) Mark(msgID string)	Records msgID with the current time.
Cleanup	func (d *MessageDeduplicator) Cleanup()	Removes expired message IDs whose age exceeds the configured TTL.

*PeerRateLimiter methods

Name	Signature	Description
Allow	func (r *PeerRateLimiter) Allow() bool	Refills tokens according to elapsed whole seconds and returns whether one token could be consumed for the current message.

*PeerRegistry methods

Name	Signature	Description
SetAuthMode	func (r *PeerRegistry) SetAuthMode(mode PeerAuthMode)	Replaces the current peer admission mode.
GetAuthMode	func (r *PeerRegistry) GetAuthMode() PeerAuthMode	Returns the current peer admission mode.
AllowPublicKey	func (r *PeerRegistry) AllowPublicKey(publicKey string)	Adds publicKey to the explicit allowlist.
RevokePublicKey	func (r *PeerRegistry) RevokePublicKey(publicKey string)	Removes publicKey from the explicit allowlist.
IsPublicKeyAllowed	func (r *PeerRegistry) IsPublicKeyAllowed(publicKey string) bool	Returns whether publicKey is currently allowlisted.
IsPeerAllowed	func (r *PeerRegistry) IsPeerAllowed(peerID string, publicKey string) bool	Returns true in open mode, or in allowlist mode when the peer is already registered or the supplied public key is allowlisted.
ListAllowedPublicKeys	func (r *PeerRegistry) ListAllowedPublicKeys() []string	Returns a slice snapshot of allowlisted public keys.
AllowedPublicKeys	func (r *PeerRegistry) AllowedPublicKeys() iter.Seq[string]	Returns an iterator over allowlisted public keys.
AddPeer	func (r *PeerRegistry) AddPeer(peer *Peer) error	Validates the peer, sets AddedAt when zero, defaults Score to 50, adds it to the registry, rebuilds the KD-tree, and schedules a debounced save.
UpdatePeer	func (r *PeerRegistry) UpdatePeer(peer *Peer) error	Replaces an existing peer entry, rebuilds the KD-tree, and schedules a debounced save.
RemovePeer	func (r *PeerRegistry) RemovePeer(id string) error	Deletes an existing peer, rebuilds the KD-tree, and schedules a debounced save.
GetPeer	func (r *PeerRegistry) GetPeer(id string) *Peer	Returns a copy of the peer identified by id, or nil when absent.
ListPeers	func (r *PeerRegistry) ListPeers() []*Peer	Returns a slice of peer copies.
Peers	func (r *PeerRegistry) Peers() iter.Seq[*Peer]	Returns an iterator over peer copies so callers cannot mutate registry state directly.
UpdateMetrics	func (r *PeerRegistry) UpdateMetrics(id string, pingMS, geoKM float64, hops int) error	Updates latency, distance, hop count, and LastSeen, rebuilds the KD-tree, and schedules a debounced save.
UpdateScore	func (r *PeerRegistry) UpdateScore(id string, score float64) error	Clamps score into [0,100], updates the peer, rebuilds the KD-tree, and schedules a debounced save.
SetConnected	func (r *PeerRegistry) SetConnected(id string, connected bool)	Updates the connection flag for a peer and refreshes LastSeen when marking the peer connected.
RecordSuccess	func (r *PeerRegistry) RecordSuccess(id string)	Increases the peer score by ScoreSuccessIncrement up to ScoreMaximum, updates LastSeen, and schedules a save.
RecordFailure	func (r *PeerRegistry) RecordFailure(id string)	Decreases the peer score by ScoreFailureDecrement down to ScoreMinimum and schedules a save.
RecordTimeout	func (r *PeerRegistry) RecordTimeout(id string)	Decreases the peer score by ScoreTimeoutDecrement down to ScoreMinimum and schedules a save.
GetPeersByScore	func (r *PeerRegistry) GetPeersByScore() []*Peer	Returns peers sorted by descending score.
PeersByScore	func (r *PeerRegistry) PeersByScore() iter.Seq[*Peer]	Returns an iterator over peers sorted by descending score.
SelectOptimalPeer	func (r *PeerRegistry) SelectOptimalPeer() *Peer	Uses the KD-tree to find the peer closest to the ideal metrics vector and returns a copy of that peer.
SelectNearestPeers	func (r *PeerRegistry) SelectNearestPeers(n int) []*Peer	Returns copies of the n nearest peers from the KD-tree according to the weighted metrics.
GetConnectedPeers	func (r *PeerRegistry) GetConnectedPeers() []*Peer	Returns a slice of copies for peers whose Connected flag is true.
ConnectedPeers	func (r *PeerRegistry) ConnectedPeers() iter.Seq[*Peer]	Returns an iterator over connected peer copies.
Count	func (r *PeerRegistry) Count() int	Returns the number of registered peers.
Close	func (r *PeerRegistry) Close() error	Stops any pending save timer and immediately flushes dirty peer data to disk when needed.

*ResponseHandler methods

Name	Signature	Description
ValidateResponse	func (h *ResponseHandler) ValidateResponse(resp *Message, expectedType MessageType) error	Rejects nil responses, unwraps MsgError into a ProtocolError, and checks that resp.Type matches expectedType.
ParseResponse	func (h *ResponseHandler) ParseResponse(resp *Message, expectedType MessageType, target any) error	Runs ValidateResponse and then decodes the payload into target when target is not nil.

*Transport methods

Name	Signature	Description
Start	func (t *Transport) Start() error	Starts the WebSocket listener and begins accepting inbound peer connections.
Stop	func (t *Transport) Stop() error	Cancels transport context, closes active connections, and shuts down the listener.
OnMessage	func (t *Transport) OnMessage(handler MessageHandler)	Installs the inbound message callback used after decryption. It must be set before Start to avoid races.
Connect	func (t *Transport) Connect(peer *Peer) (*PeerConnection, error)	Dials peer, performs the handshake, derives the shared secret, and returns the active peer connection.
Send	func (t *Transport) Send(peerID string, msg *Message) error	Looks up the active connection for peerID and sends msg over it.
Connections	func (t *Transport) Connections() iter.Seq[*PeerConnection]	Returns an iterator over active peer connections.
Broadcast	func (t *Transport) Broadcast(msg *Message) error	Sends msg to every connected peer except the sender identified by msg.From.
GetConnection	func (t *Transport) GetConnection(peerID string) *PeerConnection	Returns the active connection for peerID, or nil when not connected.
ConnectedPeerCount	func (t *Transport) ConnectedPeerCount() int	Returns the number of active peer connections.

*PeerConnection methods

Name	Signature	Description
Send	func (pc *PeerConnection) Send(msg *Message) error	Encrypts and writes a message over the WebSocket connection.
Close	func (pc *PeerConnection) Close() error	Closes the underlying connection once and releases transport state for that peer.
GracefulClose	func (pc *PeerConnection) GracefulClose(reason string, code int) error	Sends a MsgDisconnect notification before closing the connection.

*Worker methods

Name	Signature	Description
SetMinerManager	func (w *Worker) SetMinerManager(manager MinerManager)	Installs the miner manager used for start, stop, stats, and log requests.
SetProfileManager	func (w *Worker) SetProfileManager(manager ProfileManager)	Installs the profile manager used during deployment handling.
HandleMessage	func (w *Worker) HandleMessage(conn *PeerConnection, msg *Message)	Dispatches supported message types, sends normal replies on success, and emits MsgError responses when a handled command fails.
RegisterOnTransport	func (w *Worker) RegisterOnTransport()	Registers HandleMessage as the transport's inbound message callback.

*ProtocolError methods

Name	Signature	Description
Error	func (e *ProtocolError) Error() string	Formats the remote error as remote error (<code>): <message>.