aegis

Service mesh for Go microservices — mTLS everywhere, zero configuration. Nodes discover each other, authenticate via certificates, and call domain services without managing PKI infrastructure.

Zero-Trust by Default

node, _ := aegis.NewNodeBuilder().
    WithID("api-1").
    WithName("API Server").
    WithAddress("localhost:8443").
    WithServices(aegis.ServiceInfo{Name: "identity", Version: "v1"}).
    WithCertDir("./certs").
    Build()

node.StartServer()
// Certificates generated automatically. All connections use mTLS.
// Other nodes can now discover this service and call it securely.

Install

go get github.com/zoobz-io/aegis

Requires Go 1.24+.

Quick Start

A provider node exposes a service. A consumer node discovers and calls it.

package main

import (
    "context"
    "log"

    "github.com/zoobz-io/aegis"
    identity "github.com/zoobz-io/aegis/proto/identity"
    "google.golang.org/grpc"
)

func main() {
    // Provider: morpheus serves identity
    morpheus, _ := aegis.NewNodeBuilder().
        WithID("morpheus-1").
        WithName("Morpheus").
        WithAddress("localhost:8443").
        WithServices(aegis.ServiceInfo{Name: "identity", Version: "v1"}).
        WithServiceRegistration(func(s *grpc.Server) {
            identity.RegisterIdentityServiceServer(s, &myIdentityServer{})
        }).
        WithCertDir("./certs").
        Build()

    morpheus.StartServer()
    defer morpheus.Shutdown()

    // Consumer: vicky calls identity service
    vicky, _ := aegis.NewNodeBuilder().
        WithID("vicky-1").
        WithName("Vicky").
        WithAddress("localhost:9443").
        WithCertDir("./certs").
        Build()

    pool := aegis.NewServiceClientPool(vicky)
    defer pool.Close()

    client := aegis.NewServiceClient(pool, "identity", "v1", identity.NewIdentityServiceClient)

    // Get a connection (round-robin across providers)
    ctx := context.Background()
    identityClient, _ := client.Get(ctx)
    resp, _ := identityClient.ValidateSession(ctx, &identity.ValidateSessionRequest{
        Token: "user-session-token",
    })

    log.Printf("Session valid: %v, user: %s", resp.Valid, resp.UserId)
}

Capabilities

Capability	Description	Docs
Node identity	Build nodes with ID, name, type, address	node_builder.go
Automatic mTLS	Certificates generated on first run, loaded thereafter	tls.go
Service registry	Declare services, discover providers across mesh	service.go
Topology sync	Nodes share topology; version-based merge	topology.go
Health checks	Extensible health checker interface	health.go
Service client	Connection pooling, round-robin load balancing	client.go
Caller identity	Extract calling node from mTLS context	context.go

Why aegis?

• Automatic mTLS — Nodes generate and exchange certificates on startup. No PKI infrastructure to manage.
• Service discovery built-in — Declare services, query providers, topology syncs across the mesh.
• One import — Node, peer connections, health checks, and gRPC server in a single package.
• Caller identity on every request — CallerFromContext(ctx) extracts the calling node from mTLS certificates.
• Round-robin client pooling — Service clients load-balance across providers automatically.

The Ecosystem

aegis is the transport layer. Domain services build on top:

Package	Role
capitan	Event coordination within a process
herald	Bridge capitan events to message brokers (future: aegis provider)
morpheus	Identity service — implements IdentityService
vicky	Storage service — consumes identity via mesh

Documentation

Learn

• Overview — What aegis is and why
• Quickstart — Build your first mesh
• Concepts — Nodes, peers, topology, services
• Architecture — How it works internally

Guides

• Testing — Testing code that uses aegis
• Troubleshooting — Common errors and solutions
• Services — Defining and consuming services
• Certificates — Certificate management

Reference

• API — Function signatures
• Types — Type definitions
• pkg.go.dev — Generated documentation

Contributing

Contributions welcome — see CONTRIBUTING.md for guidelines.

License

MIT License — see LICENSE.