feat(axvisor): axum management HTTP control plane with VM lifecycle API

.github/workflows/ci.yml

@@ -464,6 +464,18 @@ jobs:
             container_image: base
             limit_to_owner: ""
             main_pr_only: false
+          - name: Test axvisor aarch64 qemu (http control-plane)
+            use_container: false
+            runs_on: '["self-hosted","linux","qcs"]'
+            self_hosted_owner: rcore-os
+            timeout_minutes: 30
+            command: |
+              cargo xtask image pull qemu-aarch64 --output-dir tmp/axbuild/images
+              cargo xtask axvisor test qemu --arch aarch64 --test-case http-control-plane
+            cache_key: ""
+            container_image: base
+            limit_to_owner: ""
+            main_pr_only: false
           - name: Test axvisor aarch64 qemu (panic modes)
             use_container: false
             runs_on: '["self-hosted","linux","qcs"]'

os/axvisor/Cargo.toml

@@ -47,6 +47,17 @@ stack-protector = ["ax-std/stack-protector"]
 backtrace = ["ax-std/backtrace", "dep:axbacktrace"]
 test-backtrace-panic = ["backtrace"]
 test-panic-no-backtrace = ["dep:axbacktrace"]
+# axum-based management HTTP server (see src/http/ for the Router).
+# Off by default. Replaces the hand-rolled pilot, which is intentionally not
+# carried forward.
+# axum-based management HTTP server. Pulls `ax-std/net` explicitly so the
+# ArceOS network stack (which probes the QEMU virtio-net NIC and backs the
+# tokio `TcpListener`) is enabled only when the control plane is built; a
+# non-HTTP build must not enable the network subsystem.
+http-axum = ["ax-std/net", "dep:axum", "dep:tokio", "dep:serde_json"]
+# Do not auto-boot the default VMs at startup; the HTTP control plane starts
+# and stops them on demand (VMs are created and stay in `Ready`).
+no-auto-start = []
 
 [dependencies]
 shlex.workspace = true
@@ -57,6 +68,12 @@ unexpected_cfgs = { level = "warn", check-cfg = ['cfg(axtest)', 'cfg(feature, va
 [target.'cfg(any(not(any(windows, unix)), target_env = "musl"))'.dependencies]
 anyhow.workspace = true
 log = "0.4"
+axum = { version = "0.8", optional = true }
+serde_json = { version = "1", optional = true }
+# The runtime only enables the IO driver (`enable_io()`), so no `time` driver
+# and thus no `timerfd` syscall is needed. `rt` + `net` cover the manually
+# built current-thread runtime and `TcpListener`.
+tokio = { version = "1", optional = true, features = ["rt", "net"] }
 
 # System dependent modules provided by ArceOS.
 ax-api.workspace = true

os/axvisor/src/guest_console/mod.rs

@@ -4,7 +4,15 @@ mod host;
 mod mux;
 
 pub(crate) use host::{configure_host_console_reader, read_host_byte, wait_for_host_input};
+#[cfg_attr(
+    feature = "no-auto-start",
+    expect(
+        unused_imports,
+        reason = "only the auto-start boot path attaches the console to a default running VM"
+    )
+)]
+pub(crate) use mux::attach_default;
 pub(crate) use mux::{
-    ConsoleInputEvent, activate, attach, attach_default, attached_vm, mark_running, mark_stopped,
+    ConsoleInputEvent, activate, attach, attached_vm, mark_running, mark_stopped,
     reconcile_vm_states, remove, route_host_byte, serial_backend_factory,
 };

os/axvisor/src/guest_console/mux/mod.rs

@@ -472,6 +472,13 @@ pub fn route_host_byte(byte: u8) -> ConsoleInputEvent {
 }
 
 /// Attach the lowest-ID member of the default running VM set.
+#[cfg_attr(
+    feature = "no-auto-start",
+    expect(
+        dead_code,
+        reason = "only the auto-start boot path attaches the console to a default running VM"
+    )
+)]
 pub fn attach_default(running: impl IntoIterator<Item = VMId>) -> Option<VMId> {
     GUEST_CONSOLE_MUX.attach_default(running)
 }

os/axvisor/src/http/auth.rs

@@ -0,0 +1,63 @@
+//! Bearer-token access control for the management HTTP control plane.
+//!
+//! Mutating routes (`create`/`delete`/`start`/`stop`) require an
+//! `Authorization: Bearer <token>` header matching the build-time token. The
+//! token is baked into the image at
+//! build time from the `[env] AXVM_HTTP_TOKEN` build-config variable — the same
+//! `option_env!` mechanism `crate::shell::command::base` uses for `AX_ARCH`.
+//!
+//! The control plane is **deny-by-default**: if `AXVM_HTTP_TOKEN` is unset,
+//! every protected route returns `401` and cannot be used. There is no
+//! "fall back to allowing writes without a token" path — a build that forgets
+//! the token fails its tests instead of silently exposing EL2 state changes.
+//! Read-only routes (`GET`) are intentionally left open; they expose no state
+//! mutation, and the default loopback bind (see [`crate::http::server`]) keeps
+//! them off the management network unless an operator explicitly opts in.
+
+use axum::{
+    extract::FromRequestParts,
+    http::{
+        StatusCode,
+        header::{AUTHORIZATION, HeaderValue},
+    },
+};
+
+/// A request that carries a matching `Authorization: Bearer <token>` header.
+///
+/// Attach as the first extractor on a mutating handler. Rejects the request
+/// with `401 Unauthorized` when no token was baked into the image
+/// (`AXVM_HTTP_TOKEN` unset) or the header is missing / does not match.
+pub struct ApiToken;
+
+impl ApiToken {
+    /// Whether the given header value carries the required bearer token.
+    fn header_matches(value: &HeaderValue) -> bool {
+        let Some(token) = option_env!("AXVM_HTTP_TOKEN") else {
+            return false;
+        };
+        value.to_str().ok().is_some_and(|value| {
+            value
+                .strip_prefix("Bearer ")
+                .is_some_and(|rest| rest == token)
+        })
+    }
+}
+
+impl<S: Sync> FromRequestParts<S> for ApiToken {
+    type Rejection = StatusCode;
+
+    async fn from_request_parts(
+        parts: &mut axum::http::request::Parts,
+        _state: &S,
+    ) -> Result<Self, Self::Rejection> {
+        let authorized = parts
+            .headers
+            .get(AUTHORIZATION)
+            .is_some_and(Self::header_matches);
+        if authorized {
+            Ok(ApiToken)
+        } else {
+            Err(StatusCode::UNAUTHORIZED)
+        }
+    }
+}

os/axvisor/src/http/mod.rs

@@ -0,0 +1,25 @@
+//! Management HTTP control plane.
+//!
+//! Served by an axum `Router` running on a tokio current-thread runtime
+//! (see [`server`]). The VM list/detail and start/stop lifecycle routes live
+//! in [`vm`]. JSON is built with `serde_json`.
+//!
+//! Security boundary: mutating routes require a build-time bearer token
+//! ([`auth`]); the server binds `127.0.0.1:8080` by default and only binds
+//! wider when `[env] AXVM_HTTP_BIND` opts in. See the per-module docs.
+//!
+//! This whole module is only compiled under the `http-axum` feature, which is
+//! off by default. The hand-rolled HTTP/1.0 pilot was intentionally not
+//! carried forward.
+
+pub mod auth;
+pub mod server;
+pub mod vm;
+
+/// Blocking entry point for the management HTTP server.
+///
+/// Spawned on its own task (see `crate::main`); builds the tokio runtime and
+/// serves until the hypervisor shuts down.
+pub fn serve() {
+    server::serve();
+}

os/axvisor/src/http/server.rs

@@ -0,0 +1,67 @@
+//! axum-based management HTTP server (`http-axum` feature).
+//!
+//! Runs an axum `Router` on a tokio current-thread runtime and serves the
+//! management API. Routes and JSON fields mirror the hand-rolled pilot's API,
+//! but dispatch and JSON construction are delegated to axum + serde_json.
+//!
+//! ```text
+//! GET    /api/vms            → 200, JSON array (summary form)
+//! GET    /api/vms/{id}       → 200, JSON detail (with vcpu_states) | 404
+//! POST   /api/vms/create     → 200 {"id":N} | 400 | 409 | 500 (body {"toml": "..."})
+//! DELETE /api/vms/{id}       → 204 | 404 | 500
+//! POST   /api/vms/{id}/start → 200 {"ok":true,"status":...} | 404 | 409 | 503
+//! POST   /api/vms/{id}/stop  → 200 {"ok":true,"status":...} | 404 | 409 | 503
+//! ```
+//!
+//! Mutating routes (`create`/`delete`/`start`/`stop`) require
+//! `Authorization: Bearer <token>` with the build-time `[env] AXVM_HTTP_TOKEN`;
+//! see [`crate::http::auth`]. GET routes are open. The listener binds
+//! [`bind_addr`], loopback by default.
+//!
+//! The tokio reactor is initialized with `enable_io()` only (no time driver),
+//! which needs only epoll, so no `timerfd` syscall is required.
+
+use axum::{Router, routing::get, routing::post};
+
+use crate::http::vm;
+
+/// Assemble the management routes.
+pub fn router() -> Router {
+    Router::new()
+        .route("/api/vms", get(vm::list_vms))
+        .route("/api/vms/{id}", get(vm::vm_detail).delete(vm::vm_delete))
+        .route("/api/vms/create", post(vm::vm_create))
+        .route("/api/vms/{id}/start", post(vm::vm_start))
+        .route("/api/vms/{id}/stop", post(vm::vm_stop))
+}
+
+/// Bind address for the management HTTP server.
+///
+/// Defaults to loopback (`127.0.0.1:8080`) so a stock `http-axum` build is not
+/// reachable from the management network. Test/dev flows that need QEMU
+/// hostfwd to reach the in-guest listener must opt in to all interfaces by
+/// setting `[env] AXVM_HTTP_BIND = "0.0.0.0:8080"` in their build config; the
+/// mutating routes still require the bearer token regardless of the bind.
+fn bind_addr() -> &'static str {
+    option_env!("AXVM_HTTP_BIND").unwrap_or("127.0.0.1:8080")
+}
+
+/// Blocking serve: build a tokio current-thread runtime and hand it to axum.
+///
+/// `main` spawns this on its own task via `std::thread::spawn(|| http::serve())`;
+/// the runtime is built here. Only the IO driver is enabled — the epoll
+/// reactor suffices for `axum::serve`; a time driver would need `timerfd`.
+pub fn serve() {
+    let rt = tokio::runtime::Builder::new_current_thread()
+        .enable_io()
+        .build()
+        .expect("failed to build tokio runtime");
+    rt.block_on(async {
+        let bind = bind_addr();
+        let listener = tokio::net::TcpListener::bind(bind)
+            .await
+            .expect("failed to bind management HTTP server");
+        info!("management HTTP server (axum) listening on {bind}");
+        axum::serve(listener, router()).await.expect("server error");
+    });
+}