Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 4 additions & 0 deletions .github/workflows/release.yml
Original file line number Diff line number Diff line change
Expand Up @@ -86,6 +86,10 @@ jobs:
image-ref: ghcr.io/${{ github.repository }}:${{ github.ref_name }}
# CRITICAL blocks the release; HIGH is visible in the scan output but the
# Debian base image rotates packages too often to gate on it.
#
# The ignore file is passed explicitly: its YAML form (which supports an
# expiry date, so an exception cannot rot) is not auto-detected.
ignorefile: .trivyignore.yaml
severity: CRITICAL
exit-code: "1"
ignore-unfixed: true
Expand Down
24 changes: 24 additions & 0 deletions .trivyignore.yaml
Original file line number Diff line number Diff line change
@@ -0,0 +1,24 @@
# Time-boxed, reviewable exceptions for the container gate.
#
# Everything here is a CRITICAL that the gate would otherwise block on, with a date after
# which the ignore stops working and the release fails again — so this cannot rot quietly.
#
# Re-check when Spring Boot 4 lands: both are fixed only in Spring Framework 7.0.9, and
# Boot 3.5.x (the latest 3.5 line) still ships 6.2.19.
vulnerabilities:
- id: CVE-2026-47884
statement: >-
RCE via XsltView path limitation in spring-webmvc. Fixed only in Spring Framework
7.0.9 (Spring Boot 4). Path is a REST-only application: every controller returns
JSON or SSE via @RestController, there is no view resolver, no View implementation
and no JSP or XSLT rendering on the classpath, so the affected code path is not
reachable. Revisit with the Spring Boot 4 migration.
expired_at: 2027-02-01

- id: CVE-2026-47890
statement: >-
SSE stream corruption when view rendering is involved, fixed only in Spring
Framework 7.0.9 (Spring Boot 4). Path does stream SSE, but it writes the response
body directly from StreamService rather than through a view, and the advisory's
affected path is view rendering. Revisit with the Spring Boot 4 migration.
expired_at: 2027-02-01
1 change: 1 addition & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,6 +5,7 @@ verbatim as the body of the matching GitHub release.

| Version | Date | Notes |
|---|---|---|
| v0.2.1 | 2026-11-17 | [changelog/v0.2.1.md](changelog/v0.2.1.md) |
| v0.2.0 | 2026-11-17 | [changelog/v0.2.0.md](changelog/v0.2.0.md) |
| v0.1.0 | 2026-11-17 | [changelog/v0.1.0.md](changelog/v0.1.0.md) |

Expand Down
104 changes: 104 additions & 0 deletions changelog/v0.2.1.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,104 @@
# v0.2.1

Supersedes `v0.2.0`, which never completed: its container image was pushed but the release
job stopped at the vulnerability scan, so no GitHub release or notes were published.

Adds the dependency updates that scan demanded. Everything else since the `v0.1.0` tag: the gateway gains a second routing strategy, guardrails,
an end-user billing axis, a semantic cache, Azure OpenAI and a Helm chart — plus the
fixes from a twelve-point security and billing audit.

## Added

### Routing and model selection

- **Adaptive routing.** A route can declare `strategy`: `priority` (the default, unchanged),
`fastest` (ordered by an exponentially weighted latency) or `cheapest-viable` (cheapest
route under a `latency_slo_ms`, the rest demoted to fallback). Route views expose
`ewma_latency_ms` and `ewma_error_rate` so the decision is auditable, and `provider.order`
still overrides any strategy.
- **Operator-defined aliases.** `GET/POST /admin/aliases` stores an ordered chain
(`prod-chat` → `claude-sonnet-4.5`, then `gpt-4o`). Chains are validated at write time —
an unknown model, a self-reference or more than ten hops is a 400, so a broken alias
cannot become a 500 on a customer request. The four computed aliases (`cheap`, `fast`,
`long-context`, `vision`) are unchanged.

### Billing and limits

- **End-user attribution.** `end_user` (or OpenAI's `user`) is stored on every usage row
and indexed, `/v1/usage` returns a per-end-user breakdown, `/admin/usage` and the CSV
export filter by it, and a key can cap each customer with `end_user_daily_limit_usd` —
reserved with an atomic conditional update, so concurrency cannot overshoot.
- **Project rate limits.** Projects carry `rpm_limit` and `max_concurrent_requests`,
enforced in addition to each key's caps, and shared across replicas through the Valkey
limiter.
- **Project budget alerts.** `project.budget_low` and `project.budget_exhausted` fire once
per project, window and period.
- **`POST /v1/tokens/count`.** Free but authenticated: reports prompt tokens and whether the
prompt fits, counting tool definitions, which is where estimates are usually wrong.
- **Idempotent embeddings.** `/v1/embeddings` honours `Idempotency-Key`; a retried batch is
no longer billed twice.

### Safety and privacy

- **Guardrails.** PII redaction for prompt logs (on by default) and optionally before send,
plus opt-in moderation passthrough that refuses a flagged prompt with 400
`content_flagged`. `GET /admin/settings` reports what is active.
- **Semantic cache tier.** With `semantic_cache_enabled` on a route and
`GATEWAY_SEMANTIC_MODEL` set, a near-duplicate prompt can reuse a stored completion,
under the same `temperature: 0`, tool-free, per-key rules as the exact cache.

### Providers and deployment

- **Azure OpenAI.** Setting `api_version` on a provider puts the deployment in the path, the
version in `?api-version` and the credential in the `api-key` header, for chat,
embeddings, moderation and the probe.
- **Helm chart** in `deploy/helm/path`: drain-aware grace period enforced at render time,
HPA with a custom-metric hook, PDB, optional Postgres and Valkey, ServiceMonitor.
- **Per-provider health** at `/actuator/health/providers`; overall health only reports
OUT_OF_SERVICE when every enabled provider is circuit-open.

## Fixed

The post-0.1.0 audit found twelve issues; all are fixed:

- `models/sync` imported unpriced routes enabled, serving inference for free.
- 500 responses returned internal exception messages; they now return a reference id and
log the detail server-side.
- Chunked request bodies bypassed the size limit; reading is now counted and 413s.
- The demo API key was created by default, including in the `prod` profile.
- A large `max_tokens` could reserve credit the call would never use.
- Reservation now uses the expected cost while still refusing when it does not fit.
- `/v3/api-docs` was served in production; off in the `prod` profile.
- The in-memory rate-limit windows were never evicted.
- Release tags were not verified to be on `main`.
- `UpstreamClient` allocated an `ObjectMapper` per error.
- Project filters were missing from `/admin/usage`, `/admin/stats` and the CSV export.
- Admin auth had no lockout; ten failures in five minutes now return 429.

Also fixed: the end-user cap was skipped for keys without a credit limit, and `api_version`
was ignored on provider `PATCH`.

## Security

- **Tomcat 10.1.55 → 10.1.62** and **Netty 4.1.135 → 4.1.141**, both of which Spring Boot
3.5.16 still pins and both of which carry CRITICAL advisories. Overridden in the pom
rather than by moving the framework version; drop the overrides when Boot manages them.
- **Two Spring Framework CVEs are accepted, with a deadline.** `CVE-2026-47884` (RCE via
`XsltView` path limitation) and `CVE-2026-47890` (SSE corruption during view rendering)
are fixed only in Spring Framework 7.0.9, which means Spring Boot 4. Path registers no
view resolver and renders nothing through a `View`, so neither path is reachable. They
are listed in `.trivyignore.yaml` with a `statement` and an `expired_at` of 2027-02-01,
after which the release gate fails again until they are revisited.

- Every GitHub Action is pinned to a commit SHA; a mutable tag can be repointed at any
commit and would run with this repository's token.
- Master key rotation (`POST /admin/rotate-master-key`) re-encrypts stored credentials
before switching the active key.

## Notes

- Maven Central publishing is configured (`-P release`, `io.github.an1ndra:path`) and
verified locally against a throwaway key; the upload itself is pending a namespace and a
Portal token. See `docs/PUBLISHING.md`.
- Five stories remain open: Spring AI module, Vertex/Gemini native, Valkey-shared breaker,
usage partitioning, and the Central publication.
4 changes: 2 additions & 2 deletions deploy/helm/path/Chart.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -2,8 +2,8 @@ apiVersion: v2
name: path
description: Path — a provider-agnostic LLM gateway with routing, fallback, credits and cache-aware token metering
type: application
version: 0.2.0
appVersion: "0.2.0"
version: 0.2.1
appVersion: "0.2.1"
kubeVersion: ">=1.27.0-0"
home: https://github.com/an1ndra/path
sources:
Expand Down
11 changes: 10 additions & 1 deletion pom.xml
Original file line number Diff line number Diff line change
Expand Up @@ -13,7 +13,7 @@

<groupId>io.github.an1ndra</groupId>
<artifactId>path</artifactId>
<version>0.2.0</version>
<version>0.2.1</version>
<name>path</name>
<description>Provider-agnostic LLM gateway: routing, fallback, credits and cache-aware token metering for OpenAI, Anthropic and any OpenAI-compatible API</description>
<url>https://github.com/an1ndra/path</url>
Expand Down Expand Up @@ -43,6 +43,15 @@

<properties>
<java.version>21</java.version>

<!--
Spring Boot 3.5.16 manages tomcat 10.1.55 and netty 4.1.135, both of which carry
CRITICAL advisories already fixed upstream. Pinning them keeps the container scan
clean without waiting for a Boot patch release; drop the overrides once Boot
manages the fixed versions itself.
-->
<tomcat.version>10.1.62</tomcat.version>
<netty.version>4.1.141.Final</netty.version>
</properties>

<dependencies>
Expand Down
Loading