gateway: Instructions file for Codex

AGENTS.md

This file provides guidance to AI coding agents when working with code in this repository.

Mission And Scope

OngoingAI Gateway is a transparent, auditable proxy between applications and AI providers. It should enforce access control and capture trustworthy trace/usage data while staying invisible to client workflows.

• Security first: no credential leakage, strong tenant isolation, least-privilege access, auditable behavior.
• Reliability first: streaming integrity, predictable failure modes, and stable operation under load.
• Practical developer experience: fast local setup, clear config, and easy-to-extend provider integrations.
• Scope boundary: this repo is a headless AI gateway and owns gateway M2M auth/enforcement; UI/user-session concerns are out of scope.

Design intent:

• Self-hosted default: single binary, SQLite by default.
• Team/multi-instance mode: Postgres-backed storage and dynamic key management.
• Upstream provider API keys are pass-through only and must never be persisted.
• Gateway keys are identity/authorization credentials for the proxy and are distinct from provider credentials.

High-Priority Outcomes

When implementing features or fixes, optimize for these outcomes in order:

1. Prevent security regressions.
2. Preserve correctness and tenant boundaries.
3. Preserve low-latency proxy behavior.
4. Keep architecture simple and maintainable.
5. Improve observability and operator experience.

Go Engineering Standards

• Write idiomatic Go. Keep functions small, cohesive, and explicit.
• Keep interfaces at boundaries (trace, configstore, providers); avoid speculative abstractions.
• Pass context.Context as the first parameter for request-bound or storage calls.
• Wrap errors with actionable context (fmt.Errorf("load gateway key: %w", err)).
• Use deterministic behavior for critical logic (auth, limits, tenant scoping, redaction policies).
• Avoid global mutable state. Prefer dependency injection via constructors.
• Keep hot-path allocations low in middleware/proxy code.
• Protect concurrency edges: no data races, leaked goroutines, or unbounded queues.
• Use structured logs and never log secrets, tokens, raw credentials, or unredacted sensitive payloads.
• Add comments where helpful, especially for non-obvious "why" decisions. Do not add redundant comments.
• Keep exported symbols documented with concise Go doc comments.