dlslime-ctrl

dlslime-ctrl is the control plane for DLSlime microservice governance. It provides a Redis-backed registry for discoverable services, heartbeat-based liveness, scope-based isolation, PeerAgent coordination, RDMA memory-region lookup, and declarative peer topology management.

dlslime-ctrl intentionally treats services generically. A cache service, RPC worker, prefill service, decode service, router, or future DLSlime component all register through the same entity lifecycle API and put service-specific fields inside JSON metadata.

Responsibilities

Concepts

Entity

An entity is a discoverable object managed by dlslime-ctrl. The default entity_type is service.

{
  "entity_type": "service",
  "entity_id": "cache:0",
  "kind": "cache",
  "endpoint": {
    "host": "127.0.0.1",
    "port": 8765,
    "protocol": "http"
  },
  "metadata": {
    "p2p_host": "127.0.0.1",
    "p2p_port": 8765
  }
}

dlslime-ctrl stores the entity as JSON and does not interpret the contents of endpoint, metadata, or resource beyond preserving them for discovery.

Kind

kind is the service category used for discovery and filtering. Examples:

• cache
• rpc-worker
• prefill
• decode
• router

Scope

scope is an optional namespace. When present, all Redis keys are prefixed with {scope}:. This lets multiple jobs, tests, or applications share one dlslime-ctrl and Redis instance without colliding.

Prerequisites

• Redis server
• Rust toolchain when building dlslime-ctrl from source
• Python 3.8+ when using the dlslime-ctrl Python client package

Build

cd dlslime-ctrl
cargo build --release

# Build a Python wheel that includes the Rust dlslime-ctrl binary
maturin build --release

Run

# Default: Redis at redis://127.0.0.1:6379
cargo run --release -- server

# Specify Redis explicitly
cargo run --release -- server --redis-url redis://your-redis-host:6379

# Or use the environment
export DLSLIME_CTRL_REDIS_URL=redis://your-redis-host:6379
cargo run --release -- server

The HTTP server listens on http://0.0.0.0:4479 by default.

Background Lifecycle

dlslime-ctrl includes a service-style CLI:

pip install -e dlslime-ctrl/

dlslime-ctrl start
dlslime-ctrl status
dlslime-ctrl stop

Useful options:

dlslime-ctrl start --redis-url redis://your-redis-host:6379 --log-file /tmp/dlslime-ctrl.log
dlslime-ctrl server --host 0.0.0.0 --port 3000
dlslime-ctrl stop --force

Runtime metadata is stored under $DLSLIME_CTRL_RUNTIME_DIR, or $XDG_RUNTIME_DIR/dlslime-ctrl, or /tmp/dlslime-ctrl.

API

Service Registry

PeerAgent and RDMA

Utility

Entity API Examples

Register a Cache Service

curl http://127.0.0.1:4479/register \
  -H "Content-Type: application/json" \
  -d '{
    "entity_type": "service",
    "entity_id": "cache:0",
    "kind": "cache",
    "endpoint": {
      "host": "127.0.0.1",
      "port": 8765,
      "protocol": "http"
    },
    "metadata": {
      "p2p_host": "127.0.0.1",
      "p2p_port": 8765
    },
    "scope": "job-a"
  }'

Register a ZMQ Service

curl http://127.0.0.1:4479/register \
  -H "Content-Type: application/json" \
  -d '{
    "entity_id": "prefill:0",
    "kind": "prefill",
    "endpoint": {
      "host": "10.0.0.2",
      "port": 6001,
      "protocol": "zmq"
    },
    "metadata": {
      "world_size": 8,
      "num_blocks": 15000,
      "peer_addrs": ["10.0.0.2:5000"]
    }
  }'

entity_type defaults to service when omitted.

Heartbeat

curl http://127.0.0.1:4479/heartbeat \
  -H "Content-Type: application/json" \
  -d '{
    "entity_type": "service",
    "entity_id": "cache:0",
    "scope": "job-a"
  }'

Discover Cache Services

curl http://127.0.0.1:4479/list_entities \
  -H "Content-Type: application/json" \
  -d '{
    "entity_type": "service",
    "kind": "cache",
    "scope": "job-a"
  }'

Response:

{
  "status": "ok",
  "entities": [
    {
      "entity_type": "service",
      "entity_id": "cache:0",
      "id": "cache:0",
      "kind": "cache",
      "endpoint": {
        "host": "127.0.0.1",
        "port": 8765,
        "protocol": "http"
      },
      "metadata": {
        "p2p_host": "127.0.0.1",
        "p2p_port": 8765
      },
      "resource": null
    }
  ]
}

Python Client

The Python client lives in the dlslime package (see dlslime.ctrl.NanoCtrlClient).

from dlslime.ctrl import NanoCtrlClient

client = NanoCtrlClient("127.0.0.1:4479", scope="job-a")
client.check_connection()

def register_cache() -> bool:
    return client.register(
        "cache:0",
        "cache",
        endpoint={"host": "127.0.0.1", "port": 8765, "protocol": "http"},
        metadata={"p2p_host": "127.0.0.1", "p2p_port": 8765},
    )

if register_cache():
    client.start_heartbeat(on_not_found=register_cache)

cache = client.get_entity_info("cache:0")
caches = client.list_entities(kind="cache")

client.stop()

Client Methods

PeerAgent helpers are also available on the same client:

• register_peer(...)
• cleanup_peer(agent_name)
• heartbeat_peer(agent_name)
• set_desired_topology(...)
• query_peers()

DLSlimeCache Registration

dlslime-cache start --ctrl ... registers itself as a generic service:

{
  "entity_type": "service",
  "entity_id": "cache:0",
  "kind": "cache",
  "endpoint": {
    "host": "<advertised-host>",
    "port": 8765,
    "protocol": "http"
  },
  "metadata": {
    "p2p_host": "<advertised-host>",
    "p2p_port": 8765
  }
}

Clients discover it with list_entities(kind="cache") or get_entity_info("cache:0").

Redis Key Structure

With scope:

{scope}:{entity_type}:{entity_id}
{scope}:nano_meta:{entity_type}_revision
{scope}:nano_events:{entity_type}_update
{scope}:agent:{agent_id}
{scope}:mr:{agent_id}:{mr_name}
{scope}:spec:topology:{agent_id}
{scope}:stream:{agent_id}
{scope}:inbox:{agent_id}

Without scope, the same keys are used without the prefix, for example service:cache:0.

Environment Variables

Notes

• dlslime-ctrl is stateless; Redis is the source of truth.
• Registered entities expire if they stop heartbeating.
• Service-specific fields belong in metadata; dlslime-ctrl should not grow kind-specific schemas.
• Use scope for tests, multiple jobs, and multi-tenant deployments.