feat: add kvweb rest api

[allen3325]

Summary

kvctl and kvtop only work in terminal. this PR exposes the same /dev/shm KV cache stats over HTTP, plus the limit changes kvctl limit performs, so a
segment can be inspected or resized from HTTP. Start it with kvweb or kvctl web; FastAPI generates the docs at /docs.

GET /api/status, /api/ipcs, /api/ipcs/{name}, POST .../limit, POST .../limit-percent, DELETE .../{name}, and GET /api/stream (SSE).
Details in docs/WEB_API.md.

Notes for review

• Kept things secure by default. The endpoints can shrink or delete a running engine's KV cache, so the server binds to 127.0.0.1, sends no CORS headers, and takes an optional API key via KVCACHED_WEB_API_KEY. Binding elsewhere without a key prints a warning.
• Prevented ghost segments. RwLockedShm silently creates missing files when updating limits. We added an upfront existence check that throws a 404 so a typo doesn't spawn random dummy segments in kvtop. (kvctl limit has the same behaviour today; not touched here.)
• fastapi/uvicorn are an optional web extra, and kvctl imports kvweb lazily, so nothing changes for users who do not install it.
• _parse_size() in kvctl.py is renamed parse_size() and reused, rather than copied into the new module.
• Fixes a kvctl shell bug this touched: web was in COMMANDS and the help text but had no dispatch branch, so it fell through to the os.system() fallback.

I'll follow up with a web dashboard PR on top of this API.

Testing

tests/test_kvweb_api.py covers the endpoints, the 404 paths, and the API key.
Full CPU suite passes (176), as does pre-commit run --all-files.
Adds [fastapi, uvicorn, pydantic, httpx] to the CPU CI deps so the new tests actually run

[Copilot]

Pull request overview

Adds an HTTP control surface (kvweb) for inspecting /dev/shm KV-cache segments and applying the same limit operations that kvctl limit performs, with FastAPI-generated docs and an SSE status stream.

Changes:

• Introduces kvcached.cli.kvweb (FastAPI app) with status, IPC inspection, limit mutation, delete, and SSE streaming endpoints.
• Extends kvctl with a web subcommand and reuses the renamed parse_size() helper for size parsing.
• Adds endpoint-level tests + docs, and updates CI/test manifests to run the new API tests.

Reviewed changes

Copilot reviewed 7 out of 7 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
tests/test_kvweb_api.py	Adds end-to-end API tests (CRUD-ish flows, auth, SSE behavior).
tests/manifests/cpu.txt	Ensures the new API test is included in the CPU suite classification.
pyproject.toml	Registers kvweb script and adds web optional dependencies.
kvcached/cli/kvweb.py	Implements the FastAPI-based REST/SSE control API and server entrypoint.
kvcached/cli/kvctl.py	Adds kvctl web + interactive-shell dispatch; renames _parse_size to parse_size.
docs/WEB_API.md	Documents install/run, endpoints, and security model for the web API.
.github/workflows/cpu-tests.yml	Installs web-related deps in CPU CI so the new tests can run.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[RixinLiu]

Hi, thanks for the contribution, however, i dont think we need this in kvcached, it could be something in the production layer like discussed in #375