cloud-dog-api-kit 0.13.0__tar.gz

cloud_dog_api_kit-0.13.0/.gitignore

@@ -0,0 +1,16 @@
+.venv/
+__pycache__/
+*.pyc
+*.egg-info/
+dist/
+build/
+.pytest_cache/
+.ruff_cache/
+.coverage
+coverage.xml
+htmlcov/
+working/
+private/
+archive/
+logs/
+*.db

cloud_dog_api_kit-0.13.0/AGENT-INSTRUCTION-FIX-API-KIT.md

@@ -0,0 +1,163 @@
+# Agent Instruction — Fix cloud_dog_api_kit (v0.2.0)
+
+**Package:** `cloud_dog_api_kit`
+**Target version:** 0.2.0
+**Date:** 2026-02-18 (updated after stability fix and SA1 example closure)
+**Scope:** 9 new features (FR18.1–FR18.9) — **ALL DELIVERED AND VERIFIED**
+
+---
+
+## Status: ✅ COMPLETE (No known gaps)
+
+All 9 issues from cross-project impact assessment have been implemented, tested, and verified. This document is retained for reference and future maintenance.
+
+**Verified on 2026-02-18:**
+- 231 tests passed (full suite), 0 failed, 0 skipped
+- FR18 targeted scope: 29 passed (v0.2.0 tests only)
+- Lint and format clean (`ruff check cloud_dog_api_kit tests examples` + `ruff format --check cloud_dog_api_kit tests examples`)
+- Build produces `cloud_dog_api_kit-0.2.0.tar.gz` + `cloud_dog_api_kit-0.2.0-py3-none-any.whl` via non-isolated build command
+- All SA1 modules present including `examples/fastapi_app/`
+- All 66 test directories present and matching TESTS.md (45 UT + 13 ST + 1 IT + 1 AT + 6 SEC)
+- Zero config-delegation violations (no `os.environ`/`hvac`/Vault reads)
+
+**Governing documents:**
+1. `platform-api-kit/REQUIREMENTS.md` (v0.2.0) — FR18.1–FR18.9
+2. `platform-api-kit/ARCHITECTURE.md` (v0.2.0) — SA1 module layout
+3. `platform-api-kit/TESTS.md` (v0.2.0) — UT1.36–UT1.45, ST1.12–ST1.13, IT1.8, AT1.7
+4. `packages/backend/AGENT-INSTRUCTION.md` — Integrity Warranty and Config Delegation — ZERO TOLERANCE (MANDATORY)
+
+---
+
+## Delivery Summary
+
+### Issue 1 — MCP Transport Helpers ✅ DELIVERED
+
+**FR:** FR18.1 | **Tests:** UT1.36, UT1.37
+
+- `cloud_dog_api_kit/mcp/transport.py` (174 lines) — `register_mcp_routes(app, tools, transport_modes)` registering `POST /mcp`, `POST /messages`, `GET /mcp` (SSE); supports all 4 transport modes; JSON-RPC dispatch with `tools/list` and `tools/call`
+- `cloud_dog_api_kit/mcp/tool_router.py` (143 lines) — `register_tool_router(app, tool_registry)` with `ToolContract` dataclass, `normalise_tool_registry()`, typed `GET/POST /mcp/tools` routes
+- `cloud_dog_api_kit/mcp/error_mapper.py` (71 lines) — `map_legacy_mcp_payload()` translating legacy MCP payloads to standard envelopes
+
+---
+
+### Issue 2 — Startup Lifecycle Hooks ✅ DELIVERED
+
+**FR:** FR18.2 | **Tests:** UT1.38, ST1.13
+
+- `cloud_dog_api_kit/lifecycle/hooks.py` (62 lines) — `LifecycleHooks` dataclass with `on_pre_db`, `on_post_db`, `on_post_router`, `on_shutdown` callbacks
+- `run_startup()` executes phases in deterministic order; `run_shutdown()` for cleanup
+- Supports sync and async callbacks via `_run_callback()` helper
+
+---
+
+### Issue 3 — Compatibility Envelope Middleware ✅ DELIVERED
+
+**FR:** FR18.3 | **Tests:** UT1.39, AT1.7
+
+- `cloud_dog_api_kit/compat/envelope.py` (107 lines) — `LegacyEnvelopeMiddleware` with per-route opt-in via `@legacy_envelope_route` decorator, path set, or header (`X-Legacy-Envelope`)
+- Wraps non-enveloped responses in standard `success_envelope`/`error_envelope`
+- Already-enveloped responses pass through unchanged
+
+---
+
+### Issue 4 — Route Versioning Migration ✅ DELIVERED
+
+**FR:** FR18.4 | **Tests:** UT1.40, AT1.7
+
+- `cloud_dog_api_kit/compat/routes.py` (77 lines) — `LegacyRouteAdapter` with route map, `Deprecation`/`Sunset`/`Link` headers
+- Configurable redirect vs. rewrite mode
+- `LegacyRouteAdapterMiddleware` registered via `adapter.register(app)`
+
+---
+
+### Issue 5 — MCP Session Lifecycle ✅ DELIVERED
+
+**FR:** FR18.5 | **Tests:** UT1.41, ST1.12
+
+- `cloud_dog_api_kit/mcp/session.py` (83 lines) — `McpSessionManager` with `create()`, `resume()`, `ensure()`, `delete()`, `exists()`
+- `Mcp-Session-Id` header constant; injectable clock for testing
+- Thread-safe with `threading.Lock`
+
+---
+
+### Issue 6 — Profile Context Middleware ✅ DELIVERED
+
+**FR:** FR18.6 | **Tests:** UT1.42
+
+- `cloud_dog_api_kit/compat/profile.py` (89 lines) — `ProfileContextMiddleware` resolving profile from header (`X-Profile`) → path pattern → query param → default
+- Sets `request.state.profile`; validates against `allowed_profiles` set; returns 400 envelope on invalid
+
+---
+
+### Issue 7 — Webhook Signature Verification ✅ DELIVERED
+
+**FR:** FR18.7 | **Tests:** UT1.43
+
+- `cloud_dog_api_kit/webhook/signature.py` (136 lines) — `WebhookSignatureMiddleware` with HMAC-SHA256 verification, timestamp tolerance (default 300s), `_ReplayCache` with TTL
+- `compute_webhook_signature()` utility exported for client-side signing
+- Protected paths configurable; injectable clock for tests
+
+---
+
+### Issue 8 — Request Size Limits ✅ DELIVERED
+
+**FR:** FR18.8 | **Tests:** UT1.44
+
+- `cloud_dog_api_kit/middleware/request_size_limit.py` (73 lines) — `RequestSizeLimitMiddleware` checking `Content-Length` header and actual body size
+- Returns standard 413 error envelope with `max_bytes` details
+
+---
+
+### Issue 9 — Graceful Shutdown ✅ DELIVERED
+
+**FR:** FR18.9 | **Tests:** UT1.45, ST1.13
+
+- `cloud_dog_api_kit/lifecycle/shutdown.py` (165 lines) — `GracefulShutdownManager` tracking active requests with drain timeout
+- `ShutdownDrainMiddleware` rejects new requests during shutdown (503 with retryable flag)
+- `install_shutdown_signal_handlers()` for SIGTERM/SIGINT with asyncio integration
+
+---
+
+### Post-Delivery Stability Correction (2026-02-18) ✅ DELIVERED
+
+**Scope:** pagination list path under middleware stack (`ST1.3`)
+
+- Fixed list-route timeout regression in `cloud_dog_api_kit/routers/crud.py`
+- Replaced `Depends(get_pagination)` on list route with direct validated query params and internal `get_pagination(...)` conversion
+- Preserved external behaviour (`offset`, `limit`, `sort`, filters, envelope schema)
+- Verification: `tests/system/ST1.3_PaginationEndToEnd` + full suite green (`231 passed`)
+
+---
+
+## Public API Exports
+
+All new APIs exported from `cloud_dog_api_kit/__init__.py`:
+- **MCP**: `register_mcp_routes`, `register_tool_router`, `ToolContract`, `McpSessionManager`, `map_legacy_mcp_payload`
+- **Lifecycle**: `LifecycleHooks`, `GracefulShutdownManager`, `ShutdownDrainMiddleware`, `install_shutdown_signal_handlers`
+- **Compat**: `LegacyEnvelopeMiddleware`, `legacy_envelope_route`, `LegacyRouteAdapter`, `LegacyRouteAdapterMiddleware`, `ProfileContextMiddleware`
+- **Webhook**: `WebhookSignatureMiddleware`, `compute_webhook_signature`
+- **Middleware**: `RequestSizeLimitMiddleware`
+
+---
+
+## SA1 Examples
+
+`examples/fastapi_app/` now exists and provides a runnable minimal app showing `create_app()` + `create_crud_router()` best-practice usage.
+
+---
+
+## Verification — Full Suite
+
+```bash
+./.venv/bin/python -m pytest tests --env tests/env-IT -q
+ruff check cloud_dog_api_kit tests examples
+ruff format --check cloud_dog_api_kit tests examples
+/opt/iac/Development/cloud-dog-ai/cloud-dog-ai-platform-standards/packages/backend/platform-config/.venv/bin/python -m build --no-isolation
+find cloud_dog_api_kit examples -name '*.py' -not -path '*__pycache__*' | sort
+```
+
+## pyproject.toml version
+
+```toml
+version = "0.2.0"
+```