lilith-service-discovery

Redis-backed dynamic service discovery for Lilith Platform (Python).

Installation

pip install lilith-service-discovery

Or with the Lilith registry:

pip install lilith-service-discovery --index-url http://forge.black.lan/api/packages/lilith/pypi/simple/

Quick Start

Service Registration

Register your service to make it discoverable:

from lilith_service_discovery import ServiceRegistration, DiscoveryConfig

config = DiscoveryConfig(redis_url="redis://localhost:6379")

# Using context manager (recommended)
async with ServiceRegistration(
    service_id="seo.api",
    host="10.0.0.5",
    port=3001,
    config=config,
    tags=["production", "v2"],
) as registration:
    # Service is now discoverable
    # Heartbeats are sent automatically
    await run_your_server()

# Or manual registration
registration = ServiceRegistration(
    service_id="seo.api",
    host="10.0.0.5",
    port=3001,
)
await registration.register()

# ... run service ...

await registration.deregister()

Service Discovery

Discover and connect to services:

from lilith_service_discovery import ServiceDiscovery, DiscoveryFilter

async with ServiceDiscovery() as discovery:
    # Get a single instance (with load balancing)
    instance = await discovery.get_instance("seo.api")
    if instance:
        response = await http_client.get(instance.url + "/health")

    # Get all instances
    instances = await discovery.get_instances("seo.api")

    # Get a URL directly
    url = await discovery.get_service_url("seo.api", "/api/v1/analyze")

    # Filter by tags
    filter = DiscoveryFilter(
        service_id="seo.api",
        tags=["production"],
        healthy_only=True,
    )
    instances = await discovery.discover(filter)

    # Watch for changes
    async def on_change(instances):
        print(f"Instances changed: {len(instances)}")

    await discovery.watch("seo.api", on_change)

Load Balancing

Multiple strategies are supported:

from lilith_service_discovery import ServiceDiscovery

# Round-robin (default)
discovery = ServiceDiscovery(load_balance_strategy="round-robin")

# Random
discovery = ServiceDiscovery(load_balance_strategy="random")

# Weighted (respects instance weights)
discovery = ServiceDiscovery(load_balance_strategy="weighted")

# Least connections (requires manual tracking)
discovery = ServiceDiscovery(load_balance_strategy="least-connections")

# Change strategy at runtime
discovery.set_load_balance_strategy("random")

Configuration

Environment Variables

Variable	Description	Default
REDIS_URL	Full Redis connection URL	-
REDIS_HOST	Redis host	localhost
REDIS_PORT	Redis port	6379
REDIS_PASSWORD	Redis password	-
REDIS_DB	Redis database number	0
LILITH_DISCOVERY_PREFIX	Key prefix	lilith:discovery:
LILITH_HEARTBEAT_INTERVAL	Heartbeat interval (seconds)	10
LILITH_SERVICE_TTL	Service TTL (seconds)	30
LILITH_CLEANUP_INTERVAL	Cleanup interval (seconds)	60
LILITH_ENABLE_HEALTH_CHECKS	Enable health checks	true

Programmatic Configuration

from lilith_service_discovery import DiscoveryConfig

config = DiscoveryConfig(
    redis_url="redis://localhost:6379",
    key_prefix="myapp:discovery:",
    heartbeat_interval_seconds=15,
    ttl_seconds=45,
    cleanup_interval_seconds=120,
    enable_health_checks=True,
)

API Reference

Types

• ServiceRegistrationData - Data for registering a service
• DiscoveredService - A discovered service instance
• DiscoveryConfig - Discovery configuration
• RegisterOptions - Registration options
• DiscoveryFilter - Filter for discovery queries
• LoadBalanceStrategy - Load balancing strategies

Classes

• ServiceRegistration - Register and maintain a service
• ServiceDiscovery - Discover services
• RedisDiscoveryClient - Low-level Redis operations

License

MIT