Routing and Configuration

Relevant source files

The following files were used as context for generating this wiki page:

• src/config.rs
• src/routing.rs
• ARCHITECTURE.md
• src/proxy.rs
• blueprints/upstream/_generic.md

The Routing and Configuration system in shunt defines how inbound Large Language Model (LLM) requests are identified, processed, and dispatched to various upstream providers. It acts as a transparent proxy that maps specific model identifiers to target backends—such as OpenAI, Anthropic, or xAI—while maintaining compatibility with the Anthropic Messages protocol. The system ensures that unmapped traffic passes through to the default provider (typically Anthropic) unchanged.

Sources: ARCHITECTURE.md:4-13, src/routing.rs

Configuration System

The configuration is the foundation of shunt, driven by a typed schema loaded from TOML, YAML, or environment variables. It utilizes the figment library for flexible loading and arc-swap to support hot reloading without restarting the server process.

Configuration Structure

The gateway's behavior is dictated by several key configuration blocks:

• Server Settings: Defines listening addresses, ports, and authentication requirements.
• Upstreams: Definitions of remote providers, including their base URLs, authentication modes, and protocol kinds (e.g., anthropic, responses).
• Models/Routes: Explicit mappings between a requested model ID and a specific upstream provider.

Sources: src/config.rs, ARCHITECTURE.md:92-95, blueprints/upstream/_generic.md:25-30

Configuration Loading Flow

The following diagram illustrates how configuration is resolved and maintained within the application state.

The configuration is snapshotted once per request to ensure consistency during the execution of a single proxy cycle.
Sources: ARCHITECTURE.md:73-77, src/config.rs

Routing Logic

Routing is the process of resolving an inbound model ID from a request body into a specific Route. The resolution logic follows a strict hierarchy to determine the target provider.

Resolution Hierarchy

1. Exact Route: Matches the requested model ID against the [[routes]] table.
2. Prefix Route: Matches the start of the model ID against the [route_prefixes] map.
3. Default Provider: If no specific route is found, the request is directed to the default_provider (defaulting to anthropic).

Sources: src/routing.rs, ARCHITECTURE.md:11-13, ARCHITECTURE.md:42-43

The Model ID Resolution Flow

This sequence diagram shows how the proxy module interacts with the routing module to determine the destination of a request.

The router also handles special cases such as stripping context-window suffixes (e.g., [1m]) before performing the lookup.
Sources: src/routing.rs, ARCHITECTURE.md:42-45

Upstream Provider Definitions

Upstreams define the "how" and "where" for dispatched requests. Each upstream is associated with an AdapterKind which determines the translation logic required (e.g., translating Anthropic Messages to OpenAI Responses).

Supported Adapter Kinds

Kind	Protocol	Use Case
anthropic	Anthropic Messages	Native Anthropic API or compatible backends (Kimi, DeepSeek).
responses	OpenAI Responses	OpenAI API, xAI, or ChatGPT/Codex backends.
cursor	Cursor ConnectRPC	Direct integration with Cursor's proprietary protocol.

Sources: ARCHITECTURE.md:55-62, blueprints/upstream/_generic.md:12-20

Upstream Configuration Example

[[upstreams]]
name = "my-custom-provider"
kind = "responses"
base_url = "https://api.example.com/v1"
auth = { mode = "api_key", env = "MY_API_KEY" }

Sources: blueprints/upstream/_generic.md:33-38

Summary of Key Components

Component	Responsibility	Relevant Files
AppState	Per-request snapshot of config and auth.	src/server.rs
Route	Structure containing provider and adapter info.	src/routing.rs
SharedState	Hot-swappable storage using arc-swap.	src/reload.rs
AdapterTrait	Boundary interface for provider protocols.	src/adapters/mod.rs

Sources: ARCHITECTURE.md:34-52

The Routing and Configuration system provides the flexibility to extend shunt with new providers via simple configuration changes while maintaining high performance and protocol fidelity for Claude Code clients. By snapshotting state and using hierarchical routing, it ensures predictable request handling even during configuration updates.

Sources: ARCHITECTURE.md:68-72, src/proxy.rs