Files

T

Sergey Antropoff 777926487b Add a stateful Proxmox API console and broad handler coverage beyond the

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

2026-07-16 01:08:01 +03:00

2.6 KiB

Raw Blame History

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:

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.

2.6 KiB Raw Blame History Unescape Escape