🏗️ Architecture

Tresor follows a clean layered structure with three core concerns: storage, engine, and API. The codebase is written in Go with no external web framework — it uses net/http ServeMux directly for all routing.

📁 Directory Structure

cmd/                        # CLI entry points (Cobra)
├── root.go                # Root command, --config flag
├── run.go                 # Daemon startup
├── rule.go                # Rule & alias subcommands
└── version.go             # Version display

internal/
├── config/                # YAML configuration loader with auto-detect
│   └── config.go
│
├── store/                 # SQLite data layer + upsert logic
│   ├── store.go          # Schema creation, migrations, busy timeout
│   ├── rule.go           # Rule CRUD + pattern matching
│   ├── downstream.go     # Downstream CRUD + model management
│   ├── alias.go          # Alias CRUD + group operations
│   └── write_config.go   # YAML write-back on mutation
│
├── engine/                # Core gateway handler + pipeline execution
│   ├── engine.go         # Gateway forwarding, model resolution, auth, auto-translation, retry on empty response
│   ├── pipeline.go       # Transformer orchestration, streaming
│   ├── retry.go          # Empty response detection + retry with exponential backoff
│   └── types.go          # Interfaces (RequestTransformer, etc.)
│
├── jsplugins/             # JavaScript API V2 packages, runtime, validation, cache
│   └── api.d.ts           # Public hook/effect/context contract
│
├── plugins/               # Composite registry + native format converters only
│   ├── registry.go       # Native converter and external package lookup
│   ├── openai2anthropic.go # OpenAI → Anthropic format conversion
│   ├── anthropic2openai.go # Anthropic → OpenAI format conversion
│   ├── openai2responses.go # OpenAI Chat Completions → Responses API
│   ├── anthropic2responses.go # Anthropic Messages → Responses API
│   ├── responses2openai.go # Responses API → OpenAI Chat Completions
│   ├── responses2anthropic.go # Responses API → Anthropic Messages
│   ├── openai2gemini.go   # OpenAI → Gemini format conversion
│   ├── anthropic2gemini.go # Anthropic → Gemini format conversion
│   ├── gemini2openai.go   # Gemini → OpenAI format conversion
│   ├── gemini2anthropic.go # Gemini → Anthropic format conversion
│   ├── gemini2responses.go # Gemini → Responses API conversion
│   ├── streaming.go      # SSE parsing and chunk transformation
│   └── streaming_test.go # Comprehensive streaming transform tests
│
├── api/                   # Admin REST API + embedded web UI
│   ├── router.go         # Route registration, method enforcement, auth endpoints
│   ├── rules.go          # Rule endpoints
│   ├── downstreams.go    # Downstream endpoints + plugins list + fetch-models
│   ├── aliases.go        # Alias endpoints + group operations
│   ├── config.go         # Runtime config endpoints (proxy mode, auth keys, password, default tab, retry on empty)
│   ├── icons.go          # Model icon serving (public endpoint)
│   ├── icons_admin.go    # Icon index refresh (admin endpoint)
│   └── embed.go          # Embedded web UI via //go:embed
│
├── middleware/            # Cookie-based session auth for admin API
│   └── auth.go
│
├── icons/                 # Model icon fetching, pattern matching, CDN caching
│   ├── fetcher.go        # Icon fetching and caching
│   ├── index.go          # CDN index management
│   ├── patterns.go       # Model-to-icon pattern matching
│   └── ratelimit.go      # Rate limiting for icon fetcher
│
├── inspect/              # Bounded in-memory store for captured request/response bodies
│   └── store.go          # Inspect store for Logs inspector
│
├── proxy/                 # Outbound proxy mode implementation
│   ├── proxy.go          # Mode resolution (auto/env/windows/none)
│   └── system_windows.go # Windows registry proxy reading
│
└── api/web/               # Embedded SPA
    ├── index.html
    ├── style.css
    └── app.js

e2e/                       # End-to-end integration tests
main.go                    # Binary entry point

🔌 Extensible traffic pipeline

Tresor combines built-in automatic API format conversion with a general-purpose JavaScript API V2 transformation layer. Plugins can modify request metadata and bodies, response headers and bodies, and SSE events, or collect upstream streams into buffered responses. Routing rules compose these transformations and scope them to selected traffic. Explore Ladbaby/Tresor-plugins for examples and inspiration; plugins are not limited to those examples.

internal/jsplugins/ validates manifests and source digests, manages an immutable package cache, and executes synchronous CommonJS hooks. The runtime supports hot reload without restarting the gateway: install and enable a new package version to update future requests.

See the Plugin System guide for lifecycle and trust boundaries.

🛠️ Technology Stack

Concern	Choice	Reason
Language	Go 1.26+	Fast compilation, cross-platform CLI, native concurrency
Router	net/http ServeMux	No external framework dependency
CLI Framework	cobra	De facto standard for Go CLI applications
Database	modernc.org/sqlite	Pure Go SQLite — no CGO dependency
Config	YAML	Human-readable, portable, version-controllable
Web UI	Embedded via //go:embed	No separate frontend deployment needed

🔄 Request Flow

Client Request
      │
      ▼
┌──────────────────┐
│ 1. Auth Check     │  ← Validate proxy_api_keys if configured
└────────┬─────────┘
         │
┌────────▼────────┐
│ 2. Model Extract │  ← Parse model name from request body
└────────┬────────┘
         │
┌────────▼────────┐
│ 3. Model Resolve │  ← The forwarding gate:
│                   │     • Active exact alias? → use alias downstream, rewrite model
│                   │     • Active regex alias? → pattern match, use downstream, rewrite
│                   │     • No alias? → find downstream by output_model_ids
│                   │     • Neither? → return 404 "unknown model"
└────────┬────────┘
         │
┌────────▼────────┐
│ 4. Rule Match    │  ← Collect ALL matching enabled rules (path+model)
│                   │     Priority: exact path+model > exact path > wildcard *
│                   │     Filter by: match_format, match_downstream_format,
│                   │     match_downstreams. Rules never override downstream.
│                   │     Pipelines from all matching rules are concatenated.
└────────┬────────┘
         │
┌────────▼────────┐
│ 5. Auto-         │  ← If request format != downstream api_formats,
│    Translation   │     automatically insert format converter (prepended/
│                   │     appended around rule pipelines)
│                   │     Supports: OpenAI Chat Completions, Anthropic Messages,
│                   │     OpenAI Responses API
└────────┬────────┘
         │
┌────────▼────────┐
│ 6. Request       │  ← Execute request transformers sequentially
│    Pipeline      │     (body + headers may change)
└────────┬────────┘
         │
┌────────▼────────┐
│ 7. Forward       │  ← Send transformed request to downstream server
│    to Downstream │     Strip client auth, inject downstream API key
└────────┬────────┘
         │
┌────────▼────────┐
│ 8. Retry on     │  ← (if retry_on_empty is enabled)
│    Empty        │     If downstream returns HTTP 200 but produces no
│    Response     │     content (empty choices, thinking-only output,
│                 │     etc.), retry up to 3 times with exponential
│                 │     backoff. Retries are transparent to the client.
└────────┬────────┘
         │
┌────────▼────────┐
│ 9. Response      │  ← Execute response transformers sequentially
│    Pipeline      │     Non-streaming: full body transform
│                   │     Streaming (SSE): event-by-event transform
└────────┬────────┘
         │
┌────────▼────────┐
│ 10. Return to    │  ← Final response to client
│    Client        │
└──────────────────┘

Retry

When retry_on_empty: true is set in the config, the gateway automatically retries downstream requests that return HTTP 200 OK but produce no useful content. This protects against scenarios where:

• The downstream LLM server accepts the request but produces no text output (transient server-side issues)
• A model generates only "thinking" or "reasoning" blocks without actual text content
• The response is garbled or empty for other reasons

How it works:

• Only retries on HTTP 200 with empty content. Non-200 responses (4xx, 5xx) are never retried — LLM client SDKs handle their own retry logic for HTTP errors.
• Maximum 3 retries with exponential backoff (500ms, 1s, 2s base) and 0–25% random jitter.
• Streaming responses: A bufferedWriter holds all SSE events until content is confirmed. When the first content-producing line is detected (text, tool calls, etc.), the buffer flushes to the client. If no content arrives, the stream is discarded and retried.
• Non-streaming responses: The full body is read, response transformers are applied, then the format-specific empty check runs. Empty bodies are discarded and retried.
• Empty detection per format:
  • OpenAI Chat Completions: Empty choices, or no text/tool_calls/refusal in both message and delta fields
  • Anthropic Messages: Empty content array, or blocks containing only thinking (no text, no tool_use)
  • OpenAI Responses: Empty output array, or message items with no output_text
  • Google Gemini: Empty candidates, or parts with no text/functionCall (parts with thought:true excluded)
• Transparent to client: The client sees nothing during retries. Only the final successful response is delivered.
• Exhaustion: If all retries are exhausted, the gateway returns HTTP 502 with error "empty response after retries exhausted".
• Client disconnection during retry aborts the loop immediately.

📡 Aggregated Model List

Tresor exposes /v1/models and /models endpoints that aggregate all known model IDs from downstream output_model_ids and alias input/output model IDs. Regex aliases are excluded from the input model ID list since they represent patterns rather than concrete model names. The response is formatted as an OpenAI-style model list, so OpenAI-compatible clients can discover available models through Tresor.

💾 Data Layer

🗄️ SQLite Schema

The database uses WAL mode with a 5000ms busy timeout. Four tables:

downstreams — Provider endpoints

Column	Type	Description
id	TEXT PRIMARY KEY	Unique identifier
name	TEXT NOT NULL	Display name
base_url	TEXT NOT NULL	API base URL
api_key	TEXT NOT NULL	Authentication key
api_formats	TEXT (JSON)	API format(s) this downstream speaks
created_at	DATETIME	Creation timestamp
updated_at	DATETIME	Last update timestamp

output_model_ids — Model-to-downstream mapping

Column	Type	Description
downstream_id	TEXT REFERENCES downstreams	Foreign key
model_id	TEXT	Model identifier

(Composite unique on both columns)

rules — Conditional transform pipelines with format-aware matching

Column	Type	Description
id	TEXT PRIMARY KEY	Unique identifier
name	TEXT NOT NULL	Display name
pattern_path	TEXT NOT NULL	URL path to match
pattern_model	TEXT	Optional model filter
match_format	TEXT (JSON)	Input request formats to match
match_downstream_format	TEXT (JSON)	Downstream API formats to match
match_downstreams	TEXT (JSON)	Downstream IDs to match
pipeline_config	TEXT (JSON)	Ordered plugin list
is_enabled	INTEGER	Toggle (0/1)
created_at	DATETIME	Creation timestamp
updated_at	DATETIME	Last update timestamp

aliases — Model name mappings

Column	Type	Description
id	TEXT PRIMARY KEY	Unique identifier
input_model_id	TEXT NOT NULL	Client-facing model name (group key)
downstream_id	TEXT NOT NULL REFERENCES downstreams	Target provider
output_model_id	TEXT NOT NULL	Actual model to forward as
is_active	INTEGER DEFAULT 0	Active flag (one per group)
is_regex	INTEGER DEFAULT 0	Treat input_model_id as a regex pattern
group_order	INTEGER DEFAULT 0	Display order for group reordering
created_at	DATETIME	Creation timestamp
updated_at	DATETIME	Last update timestamp

sessions — Active admin sessions (multi-session support)

Column	Type	Description
token	TEXT PRIMARY KEY	Session token (UUID)
created_at	DATETIME	Session creation timestamp

Indexes on foreign keys and query patterns ensure efficient lookups. Regex patterns are cached (via sync.Map) to avoid recompilation on every request.

🔄 Upsert Semantics

On startup, YAML data is merged into the database:

• Downstreams: Matched by ID — updated if exists, inserted if new. api_formats carried over.
• Rules: Matched by ID — updated if exists, inserted if new. match_format, match_downstream_format, match_downstreams serialized as JSON arrays.
• Aliases: Special logic — runtime-active aliases not in YAML are preserved (protects hot-switched state); stale YAML aliases not matching DB are deleted; new YAML aliases are created
• Model IDs: All YAML models replace existing ones for each downstream

Rows that exist only in the database (created via web UI or API) are preserved.

💥 Cascade Delete

Deleting a downstream:

• Removes the downstream ID from match_downstreams arrays on all referencing rules
• Deletes all aliases pointing to that downstream

🌐 Admin API

Public Endpoints (no auth required)

Method	Path	Purpose
GET	/api/health	Health check
GET	/api/auth/status	Check whether auth is enabled
POST	/api/auth/login	Verify password, obtain session
GET	/api/version	Binary version and build time

Protected Endpoints

All other /api/* endpoints require authentication. The admin API uses cookie-based session authentication with multi-session support: after logging in via POST /api/auth/login, a session cookie (tresor_token, Path=/api/, HttpOnly, SameSite=Lax, 365-day expiry) is issued. Multiple simultaneous sessions are supported — logging in from a second browser doesn't invalidate the first. Logging out from one browser only clears that session; others remain active. Authenticated requests send the cookie (for browser/SSE) or use it as a Bearer header. CLI commands use the raw admin_password as Bearer token (backwards compat). Session tokens persist across daemon restarts (stored in SQLite). Login is rate-limited (5 attempts per 60s per IP). Changing the admin password clears all active sessions.

Key alias endpoints include POST /api/aliases/reorder for drag-and-drop group reordering, which accepts {"order": ["gpt-4o", "claude-sonnet"]}.

Log Endpoints

Method	Path	Purpose
GET	/api/logs	Get recent log entries (newest first, filtered by log level)
GET	/api/logs/stream	SSE stream of log entries (sends initial batch + live updates)
GET	/api/log_level	Get current log level
PUT/POST	/api/log_level	Update log level

Runtime Configuration Endpoint

Method	Path	Purpose
GET	/api/config	Get current runtime settings (proxy mode, proxy keys, password status, default tab, log level, retry on empty)
PUT	/api/config	Update runtime settings live (pushes changes to running engine + auth middleware, writes back to YAML)