mesh

package
v0.0.0-...-df47f23 Latest Latest
Warning

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

Go to latest
Published: Sep 13, 2026 License: BSD-3-Clause Imports: 30 Imported by: 0

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type ApplyLawsPayload

type ApplyLawsPayload struct {
	LawFiles []string `json:"law_files"`
	DryRun   bool     `json:"dry_run,omitempty"`
}

type Client

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

Client is the CLI-side helper for talking to a local node's control socket.

func NewClient

func NewClient(baseURL string, logger zerolog.Logger) *Client

func (*Client) Broadcast

func (c *Client) Broadcast(ctx context.Context, cmd Command, timeout time.Duration) ([]*CommandResult, error)

Broadcast fans a command out to the whole mesh and returns all collected results.

func (*Client) Dispatch

func (c *Client) Dispatch(ctx context.Context, cmd Command, timeout time.Duration) ([]*CommandResult, error)

Dispatch sends a command to the peers listed in cmd.Target.PeerIDs.

func (*Client) ExecuteLocal

func (c *Client) ExecuteLocal(ctx context.Context, cmd Command, timeout time.Duration) (*CommandResult, error)

ExecuteLocal runs a command on the connected node only.

func (*Client) GetNodes

func (c *Client) GetNodes(ctx context.Context) ([]Node, error)

func (*Client) GetStatus

func (c *Client) GetStatus(ctx context.Context) (*MeshStatus, error)

type Command

type Command struct {
	ID        string            `json:"id"`
	Type      CommandType       `json:"type"`
	Payload   json.RawMessage   `json:"payload"`
	Metadata  map[string]string `json:"metadata,omitempty"`
	Target    Target            `json:"target,omitempty"`
	Origin    string            `json:"origin,omitempty"` // PeerID of the initiator
	Timestamp time.Time         `json:"timestamp"`
}

Command is the unit of work dispatched across the mesh. It is transport agnostic: the same struct is published to the GossipSub broadcast topic for fan-out and sent over a direct stream for targeted request/reply.

type CommandResult

type CommandResult struct {
	ID        string          `json:"id"`       // matches Command.ID
	PeerID    string          `json:"peer_id"`  // which node produced this result
	Hostname  string          `json:"hostname"` // human-friendly node identity
	Success   bool            `json:"success"`
	Output    json.RawMessage `json:"output,omitempty"`
	Error     string          `json:"error,omitempty"`
	Timestamp time.Time       `json:"timestamp"`
}

CommandResult is what a node returns after acting on a Command. Results flow back over the GossipSub results topic (for broadcasts) or directly down the request stream (for targeted RPC).

type CommandType

type CommandType string
const (
	CommandTypeExec      CommandType = "exec"
	CommandTypeFacts     CommandType = "facts"
	CommandTypeApplyLaws CommandType = "apply_laws"
)

type Config

type Config struct {
	ListenAddrs    []string
	BootstrapPeers []string
	Rendezvous     string
	DataDir        string
	// Private hints the node is behind NAT (enables AutoRelay reservations).
	Private bool
}

Config configures the mesh Service. It is intentionally small – there are no replica IDs, quorum sizes, or membership bookkeeping. A node needs to know where to listen, who to bootstrap from, and which mesh (rendezvous) to join.

type ExecPayload

type ExecPayload struct {
	Command string            `json:"command"`
	Args    []string          `json:"args,omitempty"`
	Env     map[string]string `json:"env,omitempty"`
	WorkDir string            `json:"work_dir,omitempty"`
}

type ExecResult

type ExecResult struct {
	ExitCode int    `json:"exit_code"`
	Stdout   string `json:"stdout"`
	Stderr   string `json:"stderr"`
}

type FactsPayload

type FactsPayload struct {
	Categories []string `json:"categories,omitempty"`
}

type HTTPServer

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

HTTPServer is a thin LOCAL control socket. The govern CLI talks to its own node over this API; the node then fans the request out across the mesh via libp2p (GossipSub broadcast or targeted RPC streams). It is intended to listen on localhost only – it is not the node-to-node transport.

func NewHTTPServer

func NewHTTPServer(service *Service, addr string, logger zerolog.Logger) *HTTPServer

func (*HTTPServer) Start

func (h *HTTPServer) Start() error

func (*HTTPServer) Stop

func (h *HTTPServer) Stop(ctx context.Context) error

type Host

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

Host wraps a libp2p host together with the discovery machinery that keeps the mesh's peer set populated.

func NewHost

func NewHost(ctx context.Context, cfg HostConfig, logger zerolog.Logger) (*Host, error)

NewHost builds and starts a libp2p host with encryption (Noise + TLS 1.3), QUIC and TCP transports, NAT traversal (AutoNAT, hole punching, AutoRelay), and both LAN (mDNS) and WAN (Kademlia DHT) peer discovery.

func (*Host) Addrs

func (m *Host) Addrs() []multiaddr.Multiaddr

Addrs returns the multiaddrs this node is reachable on.

func (*Host) Advertise

func (m *Host) Advertise(ctx context.Context)

Advertise announces this node under the rendezvous key and starts a background loop that continually re-advertises and discovers peers. It returns once the first discovery pass has been scheduled.

func (*Host) Close

func (m *Host) Close() error

Close shuts down discovery and the libp2p host.

func (*Host) FindPeer

func (m *Host) FindPeer(ctx context.Context, id peer.ID) (peer.AddrInfo, error)

FindPeer resolves a peer's addresses via the DHT. Used to reach the origin of a broadcast (to return results) when no direct connection exists yet.

func (*Host) Host

func (m *Host) Host() host.Host

Host exposes the underlying libp2p host for protocol wiring.

func (*Host) ID

func (m *Host) ID() peer.ID

ID returns this node's stable peer identity.

func (*Host) Peers

func (m *Host) Peers() []peer.AddrInfo

Peers returns the currently known mesh peers (excluding self).

type HostConfig

type HostConfig struct {
	// ListenAddrs are the multiaddrs to listen on. If empty, sensible
	// defaults covering TCP and QUIC on all interfaces are used.
	ListenAddrs []string
	// BootstrapPeers are multiaddrs of well-known peers used to seed the DHT
	// and the initial connection graph. Any node with a routable address can
	// serve as one; they carry no special authority.
	BootstrapPeers []string
	// Rendezvous is the DHT advertisement string. All nodes sharing a
	// rendezvous string form one logical mesh. Defaults to "govern-mesh".
	Rendezvous string
	// DataDir is where the node's persistent identity key is stored so the
	// PeerID is stable across restarts.
	DataDir string
	// ForceReachabilityPrivate hints that this node is behind a NAT and should
	// proactively reserve relay slots (AutoRelay) and attempt hole punching.
	// When false (the default) libp2p auto-detects reachability via AutoNAT.
	ForceReachabilityPrivate bool
}

HostConfig configures the libp2p networking layer for a govern node. There is deliberately no notion of replica IDs, initial members, or join semantics – nodes are peers, discovered dynamically, with no coordinator holding cluster state. The only "infrastructure" is the optional set of bootstrap/relay peers, which hold no authority and exist purely to help NAT'd nodes find and reach each other.

type MeshService

type MeshService interface {
	Start(ctx context.Context) error
	Stop() error
	// ExecuteCommand runs a command on the local node only.
	ExecuteCommand(ctx context.Context, cmd Command) *CommandResult
	// Broadcast fans a command out to all matching peers and collects results
	// until the context deadline elapses.
	Broadcast(ctx context.Context, cmd Command) ([]*CommandResult, error)
	// Dispatch sends a command directly to specific peers and collects their
	// replies (targeted request/reply).
	Dispatch(ctx context.Context, cmd Command, peerIDs []string) ([]*CommandResult, error)
	GetStatus() *MeshStatus
	GetNodes() []Node
}

MeshService is the transport-agnostic contract the CLI/HTTP layers depend on.

type MeshStatus

type MeshStatus struct {
	PeerID     string    `json:"peer_id"`
	Hostname   string    `json:"hostname"`
	Addrs      []string  `json:"addrs"`
	Rendezvous string    `json:"rendezvous"`
	Peers      []Node    `json:"peers"`
	Timestamp  time.Time `json:"timestamp"`
}

MeshStatus summarizes the local node's view of the mesh. There is no leader and no shared cluster state – this is simply what this node currently knows.

type Node

type Node struct {
	PeerID   string   `json:"peer_id"`
	Addrs    []string `json:"addrs,omitempty"`
	Hostname string   `json:"hostname,omitempty"`
}

Node is a discovered mesh peer, reported by status/nodes queries.

type Service

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

Service is the masterless mesh node. It owns the libp2p host, a GossipSub router for broadcast/collect, and a stream handler for targeted RPC.

It replaces the previous Raft (dragonboat) implementation. There is no leader, no replicated log, and no shared cluster state: every operation is fire-and-forget fan-out with best-effort result collection.

func NewService

func NewService(ctx context.Context, cfg Config, logger zerolog.Logger) (*Service, error)

NewService builds the libp2p host and wires up pubsub + the RPC handler.

func (*Service) Broadcast

func (s *Service) Broadcast(ctx context.Context, cmd Command) ([]*CommandResult, error)

Broadcast publishes a command to the whole mesh and collects results from all matching peers until the context deadline. The local node is included.

func (*Service) Dispatch

func (s *Service) Dispatch(ctx context.Context, cmd Command, peerIDs []string) ([]*CommandResult, error)

Dispatch sends a command directly to specific peers over an RPC stream and collects their replies. This is targeted request/reply – no pubsub involved.

func (*Service) ExecuteCommand

func (s *Service) ExecuteCommand(ctx context.Context, cmd Command) *CommandResult

ExecuteCommand runs a command on the local node and returns its result.

func (*Service) GetNodes

func (s *Service) GetNodes() []Node

GetNodes returns the peers this node currently knows about.

func (*Service) GetStatus

func (s *Service) GetStatus() *MeshStatus

GetStatus returns this node's current view of the mesh.

func (*Service) Start

func (s *Service) Start(ctx context.Context) error

Start begins advertising on the rendezvous key and consuming the pubsub topics. It returns immediately; the loops run until Stop or ctx cancellation.

func (*Service) Stop

func (s *Service) Stop() error

Stop shuts down the service and underlying host.

type Target

type Target struct {
	// Hostnames, if set, restricts execution to nodes whose hostname is listed.
	Hostnames []string `json:"hostnames,omitempty"`
	// PeerIDs, if set, restricts execution to the listed peer identities.
	PeerIDs []string `json:"peer_ids,omitempty"`
	// All forces a match on every node regardless of other fields.
	All bool `json:"all,omitempty"`
}

Target selects which nodes should act on a broadcast Command. An empty Target matches every node. Selectors are evaluated locally by each receiving node against its own facts, so there is no central place that needs to know the fleet inventory.

func (Target) IsEmpty

func (t Target) IsEmpty() bool

IsEmpty reports whether the target matches all nodes by default.

Jump to

Keyboard shortcuts

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