Documentation
¶
Index ¶
- type ApplyLawsPayload
- type Client
- func (c *Client) Broadcast(ctx context.Context, cmd Command, timeout time.Duration) ([]*CommandResult, error)
- func (c *Client) Dispatch(ctx context.Context, cmd Command, timeout time.Duration) ([]*CommandResult, error)
- func (c *Client) ExecuteLocal(ctx context.Context, cmd Command, timeout time.Duration) (*CommandResult, error)
- func (c *Client) GetNodes(ctx context.Context) ([]Node, error)
- func (c *Client) GetStatus(ctx context.Context) (*MeshStatus, error)
- type Command
- type CommandResult
- type CommandType
- type Config
- type ExecPayload
- type ExecResult
- type FactsPayload
- type HTTPServer
- type Host
- type HostConfig
- type MeshService
- type MeshStatus
- type Node
- type Service
- func (s *Service) Broadcast(ctx context.Context, cmd Command) ([]*CommandResult, error)
- func (s *Service) Dispatch(ctx context.Context, cmd Command, peerIDs []string) ([]*CommandResult, error)
- func (s *Service) ExecuteCommand(ctx context.Context, cmd Command) *CommandResult
- func (s *Service) GetNodes() []Node
- func (s *Service) GetStatus() *MeshStatus
- func (s *Service) Start(ctx context.Context) error
- func (s *Service) Stop() error
- type Target
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type ApplyLawsPayload ¶
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 (*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.
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 ExecResult ¶
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
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 ¶
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) Advertise ¶
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) FindPeer ¶
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.
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 ¶
NewService builds the libp2p host and wires up pubsub + the RPC handler.
func (*Service) Broadcast ¶
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) GetStatus ¶
func (s *Service) GetStatus() *MeshStatus
GetStatus returns this node's current view of the mesh.
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.