discovery

Service Discovery Extension

Enterprise-grade service discovery and registry for distributed Forge applications.

Features

• ✅ Multiple Backends - Consul, etcd, mDNS/Bonjour, Kubernetes, Eureka, in-memory
• ✅ Service Registration - Automatic service registration on startup
• ✅ Health Checks - Continuous health monitoring
• ✅ Service Discovery - Find services by name, tags, health status
• ✅ Load Balancing - Round-robin, random, weighted strategies
• ✅ Service Watching - Real-time notifications of service changes
• ✅ Auto-Deregistration - Automatic cleanup on shutdown
• ✅ FARP Integration - Automatic API schema advertisement (OpenAPI, AsyncAPI, gRPC, GraphQL)
• ✅ mDNS/Bonjour - Zero-config local network discovery with schema propagation

Installation

go get github.com/xraph/forge/extensions/discovery

Quick Start

Basic Usage

package main

import (
    "github.com/xraph/forge"
    "github.com/xraph/forge/extensions/discovery"
)

func main() {
    app := forge.NewApp(forge.AppConfig{
        Extensions: []forge.Extension{
            discovery.NewExtension(
                discovery.WithEnabled(true),
                discovery.WithBackend("memory"),
                discovery.WithServiceName("my-api"),
                discovery.WithServiceAddress("localhost", 8080),
                discovery.WithServiceTags("api", "v1"),
                discovery.WithHTTPHealthCheck("http://localhost:8080/_/health", 10*time.Second),
            ),
        },
    })

    // Get discovery service
    discoveryService := forge.Must[*discovery.Service](app.Container(), "discovery.Service")

    // Discover other services
    router := app.Router()
    router.GET("/call-user-service", func(ctx forge.Context) error {
        // Find a healthy user-service instance
        instance, err := discoveryService.SelectInstance(
            ctx.Context(),
            "user-service",
            discovery.LoadBalanceRoundRobin,
        )
        if err != nil {
            return err
        }

        // Make request to selected instance
        url := instance.URL("http") + "/users"
        resp, err := http.Get(url)
        // ...
    })

    app.Run()
}

Configuration

YAML Configuration

extensions:
  discovery:
    enabled: true
    backend: "consul"

    # Service configuration
    service:
      name: "my-api"
      version: "1.0.0"
      address: "10.0.1.5"
      port: 8080
      tags:
        - "api"
        - "v1"
      metadata:
        region: "us-east-1"
        environment: "production"
      enable_auto_deregister: true

    # Health check configuration
    health_check:
      enabled: true
      interval: 10s
      timeout: 5s
      deregister_critical_service_after: 1m
      http: "http://localhost:8080/_/health"

    # Watch configuration
    watch:
      enabled: true
      services:
        - "user-service"
        - "payment-service"
      tags:
        - "production"

    # Consul backend
    consul:
      address: "consul.company.com:8500"
      token: "${CONSUL_TOKEN}"
      datacenter: "dc1"
      tls_enabled: true

Programmatic Configuration

discovery.NewExtension(
    discovery.WithEnabled(true),
    discovery.WithConsul("consul.company.com:8500", os.Getenv("CONSUL_TOKEN")),
    discovery.WithService(discovery.ServiceConfig{
        Name:     "my-api",
        Version:  "1.0.0",
        Address:  "10.0.1.5",
        Port:     8080,
        Tags:     []string{"api", "v1"},
        Metadata: map[string]string{
            "region": "us-east-1",
        },
    }),
    discovery.WithHTTPHealthCheck("http://localhost:8080/_/health", 10*time.Second),
)

Usage Examples

Service Registration

// Automatic registration on app startup
// Service is automatically registered when extension starts

// Manual registration
instance := &discovery.ServiceInstance{
    ID:       "my-api-1",
    Name:     "my-api",
    Version:  "1.0.0",
    Address:  "10.0.1.5",
    Port:     8080,
    Tags:     []string{"api"},
    Metadata: map[string]string{"region": "us-east-1"},
}

err := service.Register(ctx, instance)

Service Discovery

// Discover all instances of a service
instances, err := service.Discover(ctx, "user-service")
if err != nil {
    return err
}

for _, instance := range instances {
    fmt.Printf("Found: %s at %s:%d\n", instance.ID, instance.Address, instance.Port)
}

Discover with Tags

// Discover only services with specific tags
instances, err := service.DiscoverWithTags(ctx, "user-service", []string{"production", "v2"})

Discover Healthy Services

// Discover only healthy instances
instances, err := service.DiscoverHealthy(ctx, "user-service")

Load Balancing

// Select a single instance using round-robin
instance, err := service.SelectInstance(
    ctx,
    "user-service",
    discovery.LoadBalanceRoundRobin,
)

// Get service URL
url, err := service.GetServiceURL(
    ctx,
    "user-service",
    "http",
    discovery.LoadBalanceRandom,
)

Service Watching

// Watch for service changes
err := service.Watch(ctx, "user-service", func(instances []*discovery.ServiceInstance) {
    logger.Info("user-service instances changed",
        forge.F("count", len(instances)),
    )

    // Update load balancer pool
    updatePool(instances)
})

Backends

Memory Backend (Development)

discovery.NewExtension(
    discovery.WithBackend("memory"),
)

mDNS/Bonjour Backend (Zero-Config)

NEW: Zero-configuration service discovery with automatic API schema advertisement!

discovery.NewExtension(
    discovery.WithBackend("mdns"),
    discovery.WithServiceName("my-api"),
    discovery.WithServiceAddress("", 8080), // Auto-detect address
    discovery.WithFARP(discovery.FARPConfig{
        Enabled:      true,
        AutoRegister: true,
        Endpoints: discovery.FARPEndpointsConfig{
            OpenAPI:  "/openapi.json",
            AsyncAPI: "/asyncapi.json",
        },
        Capabilities: []string{"rest", "websocket"},
    }),
)

Features:

• ✅ Native OS support (macOS Bonjour, Linux Avahi, Windows DNS-SD)
• ✅ Automatic API schema advertisement in TXT records
• ✅ Zero infrastructure - works out of the box
• ✅ Perfect for local development and IoT devices

See: FARP + mDNS Integration Guide | Quick Start

Consul Backend

discovery.NewExtension(
    discovery.WithConsul("consul.company.com:8500", os.Getenv("CONSUL_TOKEN")),
)

etcd Backend

discovery.NewExtension(
    discovery.WithEtcd([]string{
        "etcd1.company.com:2379",
        "etcd2.company.com:2379",
        "etcd3.company.com:2379",
    }),
)

Kubernetes Backend

discovery.NewExtension(
    discovery.WithKubernetes("default", true), // namespace, in-cluster
)

Eureka Backend

discovery.NewExtension(
    discovery.WithEureka([]string{
        "http://eureka1.company.com:8761/eureka",
        "http://eureka2.company.com:8761/eureka",
    }),
)

Load Balancing Strategies

Round Robin

// Distribute requests evenly across instances
instance, err := service.SelectInstance(ctx, "user-service", discovery.LoadBalanceRoundRobin)

Random

// Random selection for simple load distribution
instance, err := service.SelectInstance(ctx, "user-service", discovery.LoadBalanceRandom)

Least Connections

// Select instance with fewest active connections
instance, err := service.SelectInstance(ctx, "user-service", discovery.LoadBalanceLeastConnections)

Health Checks

HTTP Health Check

health_check:
  enabled: true
  interval: 10s
  timeout: 5s
  http: "http://localhost:8080/_/health"

TCP Health Check

health_check:
  enabled: true
  interval: 10s
  timeout: 5s
  tcp: "localhost:8080"

gRPC Health Check

health_check:
  enabled: true
  interval: 10s
  timeout: 5s
  grpc: "localhost:9090"

Service Metadata

// Register service with metadata
instance := &discovery.ServiceInstance{
    Name: "my-api",
    Metadata: map[string]string{
        "version":     "1.0.0",
        "region":      "us-east-1",
        "environment": "production",
        "datacenter":  "dc1",
    },
}

// Query metadata
if region, ok := instance.GetMetadata("region"); ok {
    fmt.Printf("Service is in region: %s\n", region)
}

Client-Side Load Balancing

// Create HTTP client with service discovery
type DiscoveryClient struct {
    service     *discovery.Service
    serviceName string
    strategy    discovery.LoadBalanceStrategy
}

func (c *DiscoveryClient) Get(ctx context.Context, path string) (*http.Response, error) {
    url, err := c.service.GetServiceURL(ctx, c.serviceName, "http", c.strategy)
    if err != nil {
        return nil, err
    }

    return http.Get(url + path)
}

// Usage
client := &DiscoveryClient{
    service:     discoveryService,
    serviceName: "user-service",
    strategy:    discovery.LoadBalanceRoundRobin,
}

resp, err := client.Get(ctx, "/users/123")

Service Tags

// Register with tags
service.Register(ctx, &discovery.ServiceInstance{
    Name: "api",
    Tags: []string{"production", "v2", "us-east"},
})

// Discover by tags
instances, err := service.DiscoverWithTags(ctx, "api", []string{"production", "v2"})

Best Practices

1. Use Health Checks

// ✅ Always enable health checks
discovery.WithHTTPHealthCheck("http://localhost:8080/_/health", 10*time.Second)

// ❌ Don't disable health checks in production

2. Include Meaningful Tags

// ✅ Good tags
Tags: []string{"production", "v2", "us-east-1", "canary"}

// ❌ Bad tags
Tags: []string{"server", "app"}

3. Auto-Deregister on Shutdown

// ✅ Always enable auto-deregister
service:
  enable_auto_deregister: true

4. Use Metadata for Configuration

// ✅ Store configuration in metadata
Metadata: map[string]string{
    "max_connections": "1000",
    "timeout": "30s",
    "protocol": "http2",
}

5. Watch Critical Services

// ✅ Watch dependencies for changes
watch:
  enabled: true
  services:
    - "database"
    - "cache"
    - "payment-gateway"

Patterns

Circuit Breaker Integration

// Combine with circuit breaker for resilience
circuitBreaker := NewCircuitBreaker(options)

instance, err := discoveryService.SelectInstance(ctx, "user-service", strategy)
if err != nil {
    return err
}

return circuitBreaker.Call(func() error {
    return callService(instance)
})

Retry with Different Instance

func callWithRetry(ctx context.Context, serviceName string, maxRetries int) error {
    for i := 0; i < maxRetries; i++ {
        instance, err := service.SelectInstance(ctx, serviceName, discovery.LoadBalanceRandom)
        if err != nil {
            return err
        }

        if err := callService(instance); err == nil {
            return nil
        }

        logger.Warn("call failed, retrying with different instance",
            forge.F("attempt", i+1),
        )
    }
    return fmt.Errorf("all retries failed")
}

Dynamic Service Pool

type ServicePool struct {
    instances []*discovery.ServiceInstance
    mu        sync.RWMutex
}

// Watch and update pool
service.Watch(ctx, "user-service", func(instances []*discovery.ServiceInstance) {
    pool.mu.Lock()
    defer pool.mu.Unlock()
    pool.instances = instances
})

Testing

func TestServiceDiscovery(t *testing.T) {
    // Use memory backend for testing
    backend := discovery.NewMemoryBackend()
    service := discovery.NewService(backend, logger)

    // Register test service
    instance := &discovery.ServiceInstance{
        ID:      "test-1",
        Name:    "test-service",
        Address: "localhost",
        Port:    8080,
        Status:  discovery.HealthStatusPassing,
    }
    service.Register(context.Background(), instance)

    // Discover
    instances, err := service.Discover(context.Background(), "test-service")
    assert.NoError(t, err)
    assert.Len(t, instances, 1)
}

Monitoring

// Expose service discovery metrics
router.GET("/_/discovery/services", func(ctx forge.Context) error {
    services, err := discoveryService.ListServices(ctx.Context())
    if err != nil {
        return err
    }

    return ctx.JSON(200, map[string]interface{}{
        "services": services,
    })
})

router.GET("/_/discovery/instances/:service", func(ctx forge.Context) error {
    serviceName := ctx.Param("service")
    instances, err := discoveryService.Discover(ctx.Context(), serviceName)
    if err != nil {
        return err
    }

    return ctx.JSON(200, map[string]interface{}{
        "service":   serviceName,
        "instances": instances,
    })
})

Performance Considerations

• Caching: Service discovery results are cached by backends
• Health Checks: Balance frequency vs. load (10s recommended)
• Watch Updates: Debounce rapid changes to avoid thrashing
• Connection Pooling: Reuse connections to backend (Consul, etcd)

Migration Guide

From Hardcoded URLs

// Before
userServiceURL := "http://user-service:8080"

// After
url, err := discoveryService.GetServiceURL(ctx, "user-service", "http", strategy)

From Environment Variables

// Before
services := map[string]string{
    "user-service": os.Getenv("USER_SERVICE_URL"),
    "payment":      os.Getenv("PAYMENT_SERVICE_URL"),
}

// After
// Services discovered automatically via service discovery

License

MIT License - see LICENSE file for details