Sergey Antropoff
777926487b
initial QEMU slice, backed by imported contracts for majors 6–9. - Implement durable handlers for access/auth, cluster, LXC, storage, HA, firewall, Ceph, SDN, ACME, notifications, pools, mapping, and node ops - Serve an interactive Web UI with catalog browsing, demo seed controls, and OpenAPI/help surfaces - Bundle PVE 6.4-15, 7.4-16, and 8.4.5 contract revisions alongside 9.2.3 - Support in-memory runtime contract Apply (POST /ui/api/contract/apply) so /version and /api2 routes follow the selected major until restart - Expand seed profiles (including demo-cluster), migrations 007–008, TLS gateway config, Compose/Makefile tooling, and compatibility evidence - Tighten .gitignore for macOS, hidden directories (.*/), and local secrets
78 lines
2.6 KiB
Markdown
78 lines
2.6 KiB
Markdown
# API versions (PVE 6–9)
|
||
|
||
The simulator ships authoritative imported contracts for four Proxmox VE majors.
|
||
Handler registry coverage is **100% verified** for each:
|
||
|
||
| Major | Source version | Declared methods | Handler coverage |
|
||
|---|---|---:|---:|
|
||
| 6 | 6.4-15 | 504 | 100% |
|
||
| 7 | 7.4-16 | 540 | 100% |
|
||
| 8 | 8.4.5 | 605 | 100% |
|
||
| 9 | 9.2.3 | 675 | 100% |
|
||
|
||
Older majors reuse the current semantic handlers plus path synonyms registered
|
||
in `app/handlers/legacy_aliases.py` (for example historical Ceph and backup path
|
||
spellings).
|
||
|
||
## Cold start
|
||
|
||
Set `CONTRACT_SNAPSHOT` to a normalized snapshot path. Docker Compose pins the
|
||
bundled PVE **9.2.3** revision by default.
|
||
|
||
`GET /api2/json/version` reports fields derived from the **active** snapshot’s
|
||
`source_version`.
|
||
|
||
## Hot-swap (runtime)
|
||
|
||
Browse any major in the Web UI catalog, then **Apply as runtime**, or call:
|
||
|
||
```http
|
||
POST /ui/api/contract/apply?major=7
|
||
```
|
||
|
||
Effects:
|
||
|
||
- In-memory `/api2/json` and `/api2/extjs` routes are replaced under an
|
||
application lock.
|
||
- `/version`, OpenAPI, implementation metadata, and compatibility state refresh
|
||
for the new major.
|
||
- The change is **process-local** and **not persisted**.
|
||
- Restart restores `CONTRACT_SNAPSHOT`.
|
||
|
||
Catalog browse (`GET /ui/api/catalog?major=N`) does **not** by itself change the
|
||
runtime; only apply does.
|
||
|
||
### Client guidance
|
||
|
||
- Pin the major explicitly in CI (cold-start env **or** apply + assert
|
||
`/version` before the suite).
|
||
- Mid-flight hot-swap can invalidate in-progress client assumptions about
|
||
schemas and paths — avoid during long Terraform/Ansible runs unless the run
|
||
owns the switch.
|
||
- After apply, re-check `/admin/compatibility` for the active runtime.
|
||
|
||
## Fallback modes
|
||
|
||
`CONTRACT_FALLBACK` controls undeclared-handler behaviour:
|
||
|
||
| Value | Behaviour |
|
||
|---|---|
|
||
| `error` (default) | HTTP 501 with an explicit pending-handler style message |
|
||
| `schema-default` | Synthesize a return value from the contract schema |
|
||
| `fixture` | Return only fixture data embedded in the method contract |
|
||
|
||
With full handler coverage on the active contract, declared methods should not
|
||
hit the fallback. Keep `error` so regressions remain visible.
|
||
|
||
## Evidence vs registry
|
||
|
||
**Registry coverage** means every declared method has a registered semantic
|
||
handler (no systematic 501 for that contract).
|
||
|
||
**Verified** in this project’s sense means the majors are exercised through the
|
||
compatibility and automated suites for handler presence across 6–9. Multi-
|
||
dimension evidence JSON can still expand over time for deeper edge-case claims;
|
||
prefer live `/admin/compatibility` when the process is running.
|
||
|
||
See [Compatibility](compatibility.md).
|