Project Registry & Discovery

In a distributed service mesh, services need to know where other services live and who is allowed to execute specific tools. ContextCore provides a unified Redis-based registry for both Service Discovery and Project Ownership.

The Big Picture: Project Ownership

When an external project (e.g., a medical portal or an online store) connects to ContextRouter to register its local tools (via ToolExecutorStream), how does the Router know that this connection is legitimate?

If we only rely on the ContextToken, we know the token is valid, but we don’t know if the tenant possessing that token actually owns the project they are trying to bind to. Without an explicit registry, “Tenant B” could maliciously connect and claim to be “Project A”, intercepting Project A’s tool execution requests.

To solve this, ContextUnity uses the Project Registry.

1. Adding a Project

When a new project is provisioned (usually via the ContextView admin dashboard), it must be explicitly registered. This establishes a physical bond between the logical project_id and the cryptographic tenant_id that owns it.

from contextunity.core import register_project

# Binds the "contextmed_portal" project to the "tenant_contextmed_auth" identity.
# It also declares exactly which external tools this project is allowed to host.
register_project(
    project_id="contextmed_portal",
    owner_tenant="tenant_contextmed_auth",
    tools=["search_medical_records", "create_patient"],
)

2. Service Verification (Anti-Spoofing)

When the project later connects to the Router using its ContextToken, the gRPC endpoints responsible for tool registration and bidirectional streaming immediately challenge the connection:

from contextunity.core import verify_project_owner

# Inside the gRPC Handler:
# 1. We read the project_id from the incoming gRPC message.
# 2. We read the verified tenant_id from the interceptor's ContextToken.

is_owner = verify_project_owner(
    project_id=request.project_id,
    tenant_id=context_token.tenant_id
)

if not is_owner:
    raise SecurityError("Tenant spoofing detected: Token does not own this project.")

If the token belongs to tenant_malicious, the verify_project_owner function checks Redis, sees that contextmed_portal belongs to tenant_contextmed_auth, and immediately terminates the connection.

Service Discovery

Beyond project ownership, the registry tracks the physical networking endpoints of running services.

When a service like ContextBrain boots, it starts a background heartbeat thread that registers its presence:

from contextunity.core import register_service

# Announce presence to the mesh
register_service(
    service="brain",
    instance="pod-123",
    endpoint="brain-service.internal:50051",
    tenants=["project_a", "project_b"], # Optional: Sharding by tenant
    metadata={"version": "1.0"},
)

Other services can then dynamically discover it without hardcoded IP configurations:

from contextunity.core import discover_endpoints

# Finds the gRPC address for the brain service handling 'project_a'
endpoints = discover_endpoints(service="brain", tenant_id="project_a")
# Returns: {"pod-123": "brain-service.internal:50051"}

Redis Infrastructure & Graceful Fallback

Both the Project Registry and Service Discovery rely on Redis as their fast, centralized state store.

Encryption in Transit (TLS)

The connection between ContextUnity services and Redis is configured globally via the REDIS_URL environment variable.

By default, developers often use redis:// for local, unencrypted testing. However, ContextCore’s Pydantic configuration (SharedConfig) explicitly validates and supports TLS Encrypted connections.

For production (especially in multi-cloud or cross-VPC setups), you MUST use the rediss:// scheme:

# Secure, TLS-encrypted connection to Managed Redis (e.g. AWS ElastiCache / MemoryDB)
export REDIS_URL="rediss://default:password@my-redis-host:6379/0"

When rediss:// is provided, the underlying redis-py asynchronously establishes a secure TLS connection, ensuring that all Project Registry heartbeats and token bindings are encrypted in transit.

What if Redis is not installed? (Fail-Open for Dev)

ContextUnity is explicitly designed for a painless local development experience. The redis Python package is an optional dependency in contextunity.core, and a running Redis server is not mandatory for the system to boot.

If ContextCore attempts to register a project or verify an owner, and redis is missing (or fails to connect), the system degrades gracefully:

Logs a Warning: The system prints a debug/warning log:

“Project registry: redis not installed — ownership enforcement DISABLED for ‘contextmed_portal’. Install redis to enable project hijack protection.”
Fails Open: verify_project_owner() will automatically return True.

Why Fail-Open? When you are running a single script locally or prototyping a new agent, you shouldn’t need to spin up a Dockerized Redis instance just to test your code.

Production Requirement: In production deployments, you MUST install the redis package and define REDIS_URL. ContextView health-checks will fail if the registry is unreachable in production environments, ensuring that project hijack protection is strictly enforced.