API Reference
This document covers the public API of aegis.
Node Builder
NewNodeBuilder
func NewNodeBuilder() *NodeBuilder
Creates a new node builder with defaults:
- Type:
NodeTypeGeneric - CertDir:
"./certs"
Example:
builder := aegis.NewNodeBuilder()
NodeBuilder.WithID
func (nb *NodeBuilder) WithID(id string) *NodeBuilder
Sets the node ID. Required.
NodeBuilder.WithName
func (nb *NodeBuilder) WithName(name string) *NodeBuilder
Sets the node name. Required.
NodeBuilder.WithType
func (nb *NodeBuilder) WithType(nodeType NodeType) *NodeBuilder
Sets the node type. Optional, defaults to NodeTypeGeneric.
NodeBuilder.WithAddress
func (nb *NodeBuilder) WithAddress(address string) *NodeBuilder
Sets the node address (host:port). Required.
NodeBuilder.WithServices
func (nb *NodeBuilder) WithServices(services ...ServiceInfo) *NodeBuilder
Declares services this node provides. Optional.
NodeBuilder.WithServiceRegistration
func (nb *NodeBuilder) WithServiceRegistration(r ServiceRegistrar) *NodeBuilder
Adds a callback to register gRPC services. Called when server starts.
Example:
WithServiceRegistration(func(s *grpc.Server) {
identity.RegisterIdentityServiceServer(s, &myServer{})
})
NodeBuilder.WithCertDir
func (nb *NodeBuilder) WithCertDir(certDir string) *NodeBuilder
Sets the certificate directory. Certificates are generated if missing.
NodeBuilder.WithTLSOptions
func (nb *NodeBuilder) WithTLSOptions(opts *TLSOptions) *NodeBuilder
Sets custom TLS options. Overrides WithCertDir.
NodeBuilder.Build
func (nb *NodeBuilder) Build() (*Node, error)
Creates the node. Returns error if required fields missing or TLS setup fails.
Node
Node.StartServer
func (n *Node) StartServer() error
Starts the gRPC server. Returns error if TLS not configured or bind fails.
Node.Shutdown
func (n *Node) Shutdown() error
Gracefully shuts down server and closes peer connections.
Node.AddPeer
func (n *Node) AddPeer(info PeerInfo) error
Adds a peer connection. Connection established on first use.
Node.RemovePeer
func (n *Node) RemovePeer(peerID string) error
Removes a peer and closes its connection.
Node.GetPeer
func (n *Node) GetPeer(peerID string) (*Peer, bool)
Returns a peer by ID.
Node.GetAllPeers
func (n *Node) GetAllPeers() []*Peer
Returns all connected peers.
Node.PingPeer
func (n *Node) PingPeer(ctx context.Context, peerID string) (*PingResponse, error)
Pings a peer and returns response with latency.
Node.GetPeerHealth
func (n *Node) GetPeerHealth(ctx context.Context, peerID string) (*HealthResponse, error)
Gets health status from a peer.
Node.SyncTopology
func (n *Node) SyncTopology(ctx context.Context, peerID string) error
Synchronizes topology with a specific peer.
Node.SyncTopologyWithAllPeers
func (n *Node) SyncTopologyWithAllPeers(ctx context.Context) error
Synchronizes topology with all connected peers.
Node.SetHealth
func (n *Node) SetHealth(status HealthStatus, message string, err error)
Sets the node's health status.
Node.CheckHealth
func (n *Node) CheckHealth(ctx context.Context, checker HealthChecker) error
Runs a health checker and updates status.
Node.IsHealthy
func (n *Node) IsHealthy() bool
Returns true if node status is healthy.
Topology
Topology.AddNode
func (t *Topology) AddNode(info NodeInfo) error
Adds a node to topology. Error if node already exists.
Topology.RemoveNode
func (t *Topology) RemoveNode(nodeID string) error
Removes a node from topology. Error if not found.
Topology.GetNode
func (t *Topology) GetNode(nodeID string) (NodeInfo, bool)
Returns a node by ID.
Topology.GetAllNodes
func (t *Topology) GetAllNodes() []NodeInfo
Returns all nodes in topology.
Topology.GetServiceProviders
func (t *Topology) GetServiceProviders(name, version string) []NodeInfo
Returns nodes providing the specified service and version.
Topology.GetNodesByService
func (t *Topology) GetNodesByService(name string) []NodeInfo
Returns nodes providing any version of the specified service.
Topology.GetVersion
func (t *Topology) GetVersion() int64
Returns the topology version number.
ServiceClientPool
NewServiceClientPool
func NewServiceClientPool(node *Node) *ServiceClientPool
Creates a connection pool for service clients.
ServiceClientPool.GetConn
func (p *ServiceClientPool) GetConn(ctx context.Context, name, version string) (*grpc.ClientConn, error)
Returns a connection to a service provider. Uses round-robin across providers.
Errors:
ErrNoProviders— No nodes provide this serviceErrNoTLSConfig— Node has no TLS configuration
ServiceClientPool.Close
func (p *ServiceClientPool) Close() error
Closes all connections in the pool.
ServiceClient
NewServiceClient
func NewServiceClient[T any](pool *ServiceClientPool, name, version string, newClient func(grpc.ClientConnInterface) T) *ServiceClient[T]
Creates a typed service client.
Example:
client := aegis.NewServiceClient(pool, "identity", "v1", identity.NewIdentityServiceClient)
ServiceClient.Get
func (sc *ServiceClient[T]) Get(ctx context.Context) (T, error)
Returns a client connected to a provider.
Context
CallerFromContext
func CallerFromContext(ctx context.Context) (*Caller, error)
Extracts caller identity from gRPC context.
Errors:
ErrNoPeerInfo— No peer info in contextErrNoTLSInfo— Peer has no TLS infoErrNoCertificate— No client certificate
MustCallerFromContext
func MustCallerFromContext(ctx context.Context) *Caller
Extracts caller identity, panics on error. Use only when mTLS is guaranteed.
Health
NewHealthInfo
func NewHealthInfo() *HealthInfo
Creates health info with unknown status.
NewFunctionHealthChecker
func NewFunctionHealthChecker(name string, fn func(context.Context) error) *FunctionHealthChecker
Creates a health checker from a function.
TLS
LoadOrGenerateTLS
func LoadOrGenerateTLS(nodeID, certDir string) (*TLSConfig, error)
Loads certificates from directory, generating if missing.
LoadTLSConfig
func LoadTLSConfig(opts *TLSOptions) (*TLSConfig, error)
Loads TLS configuration from options.
Next Steps
- Types Reference — Type definitions
- Concepts — Mental models