📜Agnistack Routing Design Contract

Version: 1.0, Status: Final ( Not Changeable )

Preamble

This document outlines the core, non-negotiable routing principles that define how Agnistack resolves and tunnels traffic to end-user services. This contract represents a stable interface and must be upheld across all future protocol evolutions, scaling strategies, and feature expansions to ensure a consistent, reliable, and user-centric experience.

Core Routing Principles

1. Client-Agnostic Routing

Principle: Clients must not be required to send custom headers, proprietary query parameters, or use specific client libraries to access user applications. Routing decisions must be transparent to the end-user's client software.

Client compatibility must include, but is not limited to:

• Standard web browsers (Chrome, Firefox, Safari, etc.)

• Command-line utilities (curl, wget)

• Automated webhooks (e.g., from Stripe, GitHub, Slack)

• Native mobile applications

• IoT devices and other headless clients

Routing shall be based exclusively on:

• The Host header in an incoming HTTP(S) request.

• The resolved domain via DNS, whether it is a user-provided custom domain or an Agnistack-provided subdomain.

2. User Domain Freedom

Principle: Users must have the freedom to associate their services with either a custom domain they own (BYOD - Bring Your Own Domain) or a provided Agnistack subdomain.

Supported Domain Structures:

• Agnistack Subdomain: [subdomain].agnistack.dev (or another platform-managed domain)

• Custom Domain: api.userdomain.com, app.project.net, etc.

Agnistack's routing layer shall never hardcode or force traffic to be served under a single, platform-owned parent domain.

3. Deterministic Domain-Based Routing

Principle: Every incoming request must be routed to its destination based on a deterministic lookup of its Host header against a central domain registry.

Routing Flow:

1. A request arrives at an Agnistack Global Proxy / Ingress Node.

2. The Host The header is parsed from the request.

3. The domain is looked up in the Domain Lookup Registry:

   • xyz.agnistack.dev → Resolved via the subdomain registry.

   • api.company.com → Resolved via the custom domain registry.

4. The lookup returns the target Agent/Gateway responsible for the domain.

5. A tunnel is initiated or utilized to stream data from the requester to the target service via the identified Agent.

Domain Lookup Registry Implementation:

• The registry may be backed by a low-latency cache (e.g., Redis) for improved performance and a persistent database (e.g., PostgreSQL, DynamoDB) for durability and as the source of truth for storage.

4. TLS & HTTPS Handling

Principle: All routes must support and default to encrypted HTTPS traffic. The platform is responsible for simplifying and managing the TLS lifecycle.

Supported TLS Modes:

• For Agnistack Subdomains: TLS certificate issuance and renewal must be fully automated, preferably using Let's Encrypt. Wildcard certificates (e.g., *.agnistack.dev) are encouraged to facilitate this.

• For Custom Domains (BYOD):

  • Provide automated certificate management via Let's Encrypt as the default, preferred option.

  • Allow users to supply their own valid TLS certificate and private key if required for compliance or policy reasons.

5. Agent Exposure & Registration Lifecycle

Principle: The agent is responsible for initiating its registration with the routing layer and maintaining its availability through a persistent connection.

Exposure & Registration Flow:

1. A user initiates an exposure command on their machine:

   agni expose --subdomain xyz
   
   

2. The Agent performs the following actions:

   • Authenticates with the Agnistack control plane.

   • Requests to register the specified domain (xyz.agnistack.dev or a custom domain).

   • Establishes a persistent connection (the "tunnel") with a Router node and maintains it with a heartbeat mechanism.

3. The Router performs the following actions:

   • Validates the agent's authentication and domain registration request.

   • Stores the domain ↔ agent mapping in the Domain Lookup Registry.

   • Propagates this update to ensure global availability.

4. Any subsequent request to xyz.agnistack.dev is now tunneled to the correct agent.

6. Extensibility Without Contract Violation

Principle: Future architectural changes—including but not limited to service mesh rewrites, routing protocol updates, or a transition to multi-cloud infrastructure—must preserve this domain-based routing contract as a stable, backward-compatible interface.

If a routing decision fails for any reason (e.g., no registered agent for a domain), the system must return a deterministic, structured error (e.g., HTTP 404 Not Found or 503 Service Unavailable). The system must not silently fail, guess a destination, or proxy the request to a default or unrelated service.

Prohibited Implementations

The following patterns are explicitly forbidden as they violate the core principles of this contract:

• ❌ Requiring Agni-* Headers: Mandating custom HTTP headers for routing purposes.

• ❌ Path-Based Routing: Hiding user applications under a shared domain path (e.g., agnistack.dev/my-app). Routing must be by hostname.

• ❌ Static or Manual Routing: Implementing routing tables that cannot be updated dynamically and programmatically by the agent lifecycle.

• ❌ Centralized State Dependencies in Decentralized Models: If the mesh becomes decentralized, it must not have a hard dependency on a single, centralized point of failure for routing lookups.

Contract Summary

Feature / Principle	Status	Notes
Domain-Based Routing Only	✅ Yes	The Host The header is the sole source of truth.
BYOD & Subdomain Support	✅ Yes	Users have full flexibility.
Automated TLS Termination	✅ Yes	Auto-managed via Let's Encrypt.
User-Supplied Certificates (BYOC)	✅ Yes	Supported for custom domains.
Dynamic Agent ↔ Domain Registry	✅ Yes	Agents control their registration.
No Special Client Headers Required	✅ Yes	Ensures maximum client compatibility.
Stable Interface Across Rewrites	✅ Yes	This contract is a long-term guarantee.