fix(api): document and validate created alert rules

This commit is contained in:
moe-berri 2026-11-05 12:19:21 +08:00 • committed by ishaan-j-berri
parent f8e681bf61
commit 4f95407a1b
7 changed files with 34 additions and 8 deletions

View file

@ -863,12 +863,12 @@ class LiteLLMRoutes(enum.Enum):
]
)
usage_alert_routes = [
usage_alert_routes = (
"/usage/alert-rules",
"/usage/alert-rules/{rule_id}",
"/usage/alerts",
"/usage/alerts/{alert_id}",
]
)
self_managed_routes = [
*usage_alert_routes,

View file

@ -101,6 +101,7 @@ async def list_usage_alert_rules(
@router.post("/alert-rules", response_model=UsageAlertRule, status_code=201)
async def create_usage_alert_rule(data: UsageAlertRuleInput, user: User, repository: Repository) -> UsageAlertRule:
"""Create a daily usage alert rule for a scope the caller can manage."""
store: Final = require_repository(repository)
await require_scope(user, store, data.scope_type, data.scope_id, write=True)
saved: Final = await store.save_rule(data, user.user_id)

View file

@ -36,7 +36,11 @@ class UsageAlertRuleInput(BaseModel):
raise ValueError("min_history_days must not exceed baseline_days")
if self.scope_type == "deployment" and self.scope_id is not None:
raise ValueError("Deployment alerts cover the whole gateway; omit scope_id")
if self.scope_type == "key" and self.scope_id is not None and self.scope_id.removeprefix("raw:").startswith("sk-"):
if (
self.scope_type == "key"
and self.scope_id is not None
and self.scope_id.removeprefix("raw:").startswith("sk-")
):
raise ValueError("Use the key's reporting ID, never the secret key")
if len(set(self.notification_channels)) != len(self.notification_channels):
raise ValueError("notification_channels must be unique")

View file

@ -7,7 +7,7 @@ count them per rule the same delta-vs-base way as the other lint gates. The rule
OA001 no request body schema (the handler reads ``request.body()`` and never told FastAPI
what is in it, see ``inline_request_body`` in custom_openapi_spec.py for the fix)
OA002 no description (the handler has no docstring and the route no ``description=``)
OA003 the 200 response has no schema (no ``response_model`` and no ``responses={200: ...}``)
OA003 the 200 or 201 response has no schema (no ``response_model`` or explicit response schema)
"""
from __future__ import annotations
@ -45,7 +45,8 @@ def _operation_codes(operation: Mapping[str, object]) -> Iterator[str]:
description: Final = operation.get("description")
if not isinstance(description, str) or not description.strip():
yield "OA002"
if not _content_schema(_as_mapping(operation.get("responses")).get("200")):
responses: Final = _as_mapping(operation.get("responses"))
if not _content_schema(responses.get("200", responses.get("201"))):
yield "OA003"

View file

@ -5,7 +5,7 @@ Sibling of scripts/test_quality_gate.py, pointed at the proxy's OpenAPI document
instead of a source tree. Each rule is counted over every POST operation the proxy
serves at HEAD and at the merge-base with the branch this change merges into, and the
gate fails only when a rule grew past the merge-base count, so a new endpoint has to
ship with a request schema, a description and a 200 schema while the undocumented
ship with a request schema, a description and a 200/201 schema while the undocumented
routes that already exist are only ever allowed to shrink.
The merge-base counts come from scripts/lint_base_counts.py: the disk cache, then the
@ -167,7 +167,7 @@ def cmd_check(base: str) -> None:
print(
"Give every new POST route a request body schema (a typed body parameter, or "
"`openapi_extra={'requestBody': inline_request_body(Model, example)}` when the handler reads "
"`request.body()`), a docstring, and a 200 schema (`response_model=` or `responses={200: {'model': ...}}`), "
"`request.body()`), a docstring, and a 200/201 schema (`response_model=` or an explicit response schema), "
"or document an equal number of existing routes; the ceiling is the merge-base count. Run "
"`python scripts/check_openapi_docs.py` to see every finding."
)

View file

@ -40,6 +40,23 @@ def test_each_missing_piece_is_its_own_rule() -> None:
assert codes == {"OA001", "OA002", "OA003"}
def test_created_response_schema_satisfies_the_success_contract() -> None:
operation: Final = {**_DOCUMENTED, "responses": {"201": _RESPONSES["200"]}}
assert checker.violations({"paths": {"/v1/thing": {"post": operation}}}) == ()
@pytest.mark.parametrize("responses", [
{"201": {"description": "Created"}},
{"400": _RESPONSES["200"]},
{"200": {}, "201": _RESPONSES["200"]},
])
def test_success_response_must_still_have_a_schema(responses: Mapping[str, object]) -> None:
operation: Final = {**_DOCUMENTED, "responses": responses}
assert checker.violations({"paths": {"/v1/thing": {"post": operation}}}) == (
checker.Violation("POST", "/v1/thing", "OA003"),
)
@pytest.mark.parametrize("body", [{}, {"content": {"multipart/form-data": {}}}])
def test_only_the_missing_piece_is_reported(body: Mapping[str, object]) -> None:
no_body: Final = {**_DOCUMENTED, "requestBody": body}

View file

@ -18844,7 +18844,10 @@ export interface paths {
/** List Usage Alert Rules */
get: operations["list_usage_alert_rules_usage_alert_rules_get"];
put?: never;
/** Create Usage Alert Rule */
/**
* Create Usage Alert Rule
* @description Create a daily usage alert rule for a scope the caller can manage.
*/
post: operations["create_usage_alert_rule_usage_alert_rules_post"];
delete?: never;
options?: never;