ADR-010: Unified Gateway Architecture

Status: Accepted Date: 2026-02-11 Authors: Go Micro Team

Context

Previously, the go-micro CLI had two separate gateway implementations:

1. micro run gateway (cmd/micro/run/gateway/) - Simple HTTP-to-RPC proxy for development
2. micro server gateway (cmd/micro/server/) - Production gateway with authentication, web UI, and API documentation

This duplication created several problems:

• Code maintenance: Gateway logic (HTTP-to-RPC translation, service discovery, health checks) was implemented twice
• Feature parity: Improvements to one gateway didn't automatically benefit the other
• Complexity: New features (like MCP integration) would need to be implemented twice
• Testing burden: Each gateway required separate testing

Decision

We unified the gateway implementation by:

1. Extracting reusable gateway module (cmd/micro/server/gateway.go):

   • GatewayOptions struct for configuration
   • StartGateway() function that returns a *Gateway immediately
   • RunGateway() function that blocks until shutdown
   • Configurable authentication (enabled/disabled)

2. Refactoring micro server:

   • Gateway logic remains in cmd/micro/server/
   • registerHandlers() now uses instance-specific *http.ServeMux instead of global mux
   • Authentication middleware is conditional based on GatewayOptions.AuthEnabled
   • Auth routes only register when authentication is enabled

3. Updating micro run:

   • Removed duplicate gateway implementation (cmd/micro/run/gateway/)
   • Now calls server.StartGateway() with AuthEnabled: true
   • Retains process management and hot reload functionality
   • Same auth, scopes, and token management as micro server

Architecture

┌─────────────────────────────────────────────────────────────┐
│                     Unified Gateway                         │
│              (cmd/micro/server/gateway.go)                  │
│                                                             │
│  • HTTP → RPC translation                                  │
│  • Service discovery via registry                          │
│  • Web UI (dashboard, logs, API docs)                      │
│  • Health checks                                           │
│  • Configurable authentication                             │
│  • Endpoint scopes for access control                      │
│  • MCP tool integration with scope enforcement             │
└─────────────────────────────────────────────────────────────┘
           ▲                              ▲
           │                              │
    ┌──────┴──────┐              ┌────────┴────────┐
    │  micro run  │              │  micro server   │
    │             │              │                 │
    │  + Process  │              │  + Auth enabled │
    │    mgmt     │              │  + JWT tokens   │
    │  + Hot      │              │  + Scopes       │
    │    reload   │              │  + Production   │
    │  + Auth     │              │                 │
    │  + Scopes   │              │                 │
    └─────────────┘              └─────────────────┘

Usage

Development Mode (micro run)

# Start services with gateway (auth enabled, default admin/micro)
micro run

# Gateway provides:
# - HTTP API at /api/{service}/{endpoint}
# - Web dashboard at /
# - JWT authentication (admin/micro default)
# - Endpoint scopes at /auth/scopes

Production Mode (micro server)

# Start gateway with authentication
micro server --address :8080

# Gateway provides:
# - HTTP API at /api/{service}/{endpoint} (auth required)
# - Web dashboard with login
# - JWT-based authentication
# - User/token management UI
# - Endpoint scopes at /auth/scopes

Benefits

1. Single Source of Truth: Gateway logic lives in one place
2. Automatic Feature Propagation: New features (like MCP) added to the unified gateway benefit both commands
3. Simplified Testing: Test gateway once, works everywhere
4. Reduced Code Size: Eliminated ~300 lines of duplicate code
5. Clear Separation:
   • micro server = API gateway (HTTP + future MCP)
   • micro run = Development tool (gateway + process management + hot reload)

Implementation Details

GatewayOptions

type GatewayOptions struct {
    Address     string        // Listen address (e.g., ":8080")
    AuthEnabled bool          // Enable JWT authentication
    Store       store.Store   // Storage for auth data
    Context     context.Context // Cancellation context
}

Starting the Gateway

// Non-blocking start
gw, err := server.StartGateway(server.GatewayOptions{
    Address:     ":8080",
    AuthEnabled: false,
})

// Blocking start
err := server.RunGateway(server.GatewayOptions{
    Address:     ":8080",
    AuthEnabled: true,
})

Authentication

When AuthEnabled: true:

• Auth middleware checks JWT tokens on all requests
• Auth routes are registered: /auth/login, /auth/logout, /auth/tokens, /auth/users
• Web UI requires login
• API endpoints require Authorization: Bearer <token> header

When AuthEnabled: false (dev mode):

• No authentication middleware
• Auth routes are not registered
• All endpoints are publicly accessible

Consequences

Positive

• Easier to add new features (only implement once)
• Better code maintainability
• Consistent behavior between development and production
• Foundation for MCP integration

Negative

• cmd/micro/run now depends on cmd/micro/server (acceptable for CLI tools)
• Slightly more complex initialization in micro run (but cleaner overall)

Future Work

With unified gateway architecture, we can now add:

1. MCP Integration: Add mcp.go to server package, both commands get MCP support
2. GraphQL API: Single implementation serves both dev and prod
3. gRPC Gateway: Expose services via gRPC alongside HTTP
4. API Versioning: Consistent versioning strategy across all deployments

References

• Original issue: Gateway duplication between micro run and micro server
• Implementation: PR #XXX (gateway unification)
• Related: ADR-001 (Plugin Architecture), ADR-009 (Progressive Configuration)