subscribe

Subscribe Package

The subscribe package provides gRPC service subscription and connection management for the Lynx framework. It enables applications to connect to upstream gRPC services with service discovery, TLS support, and connection health monitoring.

Overview

This package handles:

• gRPC Service Subscription - Connect to upstream services by name
• Service Discovery Integration - Automatic service node discovery
• TLS Support - Secure connections with certificate management
• Connection Health Monitoring - Automatic connection state tracking
• Load Balancing - Node filtering and routing support

File Structure

Usage

Basic Subscription

import (
    "github.com/go-lynx/lynx/subscribe"
)

// Create a gRPC subscription
sub := subscribe.NewGrpcSubscribe(
    subscribe.WithServiceName("user-service"),
    subscribe.WithDiscovery(discoveryInstance),
)

// Connect to the service (returns nil on failure; the error is logged)
conn := sub.Subscribe()
if conn == nil {
    return fmt.Errorf("failed to subscribe to user-service")
}
defer conn.Close()

// Use the connection
client := pb.NewUserServiceClient(conn)

With TLS

TLS requires either WithConfigProvider (when caName is set) or WithDefaultRootCA (when using app's root CA). BuildGrpcSubscriptions accepts *ClientTLSProviders to inject these automatically:

sub := subscribe.NewGrpcSubscribe(
    subscribe.WithServiceName("secure-service"),
    subscribe.WithDiscovery(discoveryInstance),
    subscribe.EnableTls(),
    subscribe.WithRootCAFileName("ca.crt"),
    subscribe.WithRootCAFileGroup("certificates"),
    subscribe.WithConfigProvider(controlPlane.GetConfig),
    subscribe.WithDefaultRootCA(func() []byte {
        if app := lynx.Lynx(); app != nil && app.Certificate() != nil {
            return app.Certificate().GetRootCACertificate()
        }
        return nil
    }),
)

conn := sub.Subscribe()

Required Dependencies

Mark a service as required to ensure it's available at startup:

sub := subscribe.NewGrpcSubscribe(
    subscribe.WithServiceName("critical-service"),
    subscribe.WithDiscovery(discoveryInstance),
    subscribe.Required(), // Will fail startup if unavailable
)

With Custom Routing

sub := subscribe.NewGrpcSubscribe(
    subscribe.WithServiceName("my-service"),
    subscribe.WithDiscovery(discoveryInstance),
    subscribe.WithNodeRouterFactory(func(service string) selector.NodeFilter {
        return myCustomNodeFilter
    }),
)

Configuration

YAML Configuration

lynx:
  subscriptions:
    grpc:
      - service: "user-service"
        required: true
        tls: false
      - service: "payment-service"
        required: true
        tls: true
        ca_name: "payment-ca.crt"
        ca_group: "certificates"
      - service: "notification-service"
        required: false
        tls: false

Proto Definition

message GrpcSubscription {
  string service = 1;    // Service name in service discovery
  bool required = 2;     // Strong dependency check at startup
  bool tls = 3;          // Enable TLS
  string ca_name = 4;    // CA certificate filename
  string ca_group = 5;   // CA certificate file group
}

Options

Connection States

The package monitors gRPC connection states:

Built-in Middleware

Connections are created with standard client middleware:

• Tracing - Distributed tracing support
• Logging - Request/response logging

Integration with Lynx

The subscription system integrates with the Lynx framework:

// In your plugin
func (p *MyPlugin) InitializeResources(rt plugins.Runtime) error {
    // Subscriptions are automatically built from configuration
    // Access them through the application context
    return nil
}

Best Practices

1. Mark critical services as required - Ensure dependencies are available at startup
2. Use TLS in production - Enable encryption for secure communication
3. Configure appropriate timeouts - Prevent hanging connections
4. Monitor connection states - Track connectivity for observability
5. Use service discovery - Avoid hardcoded endpoints

License

Apache License 2.0