M5: Patch Deployment & Job Management
Backend: - migrations/003_jobs_scheduling.sql: retry_next_at/last_error columns, pg_notify trigger for immediate job dispatch, retry index - pm-agent-client: ApplyPatchesRequest/Response, AgentJobStatus, RollbackResponse types; apply_patches/job_status/rollback_job client methods + generic POST helper - pm-core/models: JobStatus, JobKind, PatchJob, PatchJobHost, CreateJobRequest, PatchJobSummary - pm-web/routes/jobs.rs: POST/GET /api/v1/jobs, GET /jobs/:id, POST /jobs/:id/cancel, POST /jobs/:id/rollback - pm-worker/job_executor.rs: NOTIFY listener, periodic scanner, execute_host_job, poll_running_jobs, handle_host_failure (3-retry exponential backoff 1m/5m/30m), sync_job_status, retry_pending_jobs - pm-worker/main.rs: spawn job_executor Frontend: - types/index.ts: PatchInfo, PatchJobHost, PatchJob, PatchJobSummary, CreateJobRequest interfaces - api/client.ts: jobsApi (list/get/create/cancel/rollback), patchesApi (getHostPatches) - pages/PatchDeploymentPage.tsx: 3-step MUI Stepper (host select → configure → result) - pages/JobsPage.tsx: job list table, expandable per-host detail, cancel/rollback actions with confirm dialog, load-more pagination - App.tsx: /jobs and /deployment routes wired to real pages cargo check: 0 errors | vite build: 0 errors
This commit is contained in:
@ -1,10 +1,284 @@
|
||||
//! Agent HTTP client stub.
|
||||
//! Full mTLS Rustls-based implementation arrives in M4.
|
||||
//! mTLS HTTP client for communicating with Linux Patch API agents.
|
||||
//!
|
||||
//! # Example
|
||||
//!
|
||||
//! ```no_run
|
||||
//! use pm_agent_client::client::AgentClient;
|
||||
//!
|
||||
//! # async fn example() -> Result<(), pm_agent_client::error::AgentClientError> {
|
||||
//! let client = AgentClient::new(
|
||||
//! "192.168.1.10",
|
||||
//! 12443,
|
||||
//! include_bytes!("../certs/client.crt"),
|
||||
//! include_bytes!("../certs/client.key"),
|
||||
//! include_bytes!("../certs/ca.crt"),
|
||||
//! )?;
|
||||
//!
|
||||
//! let health = client.health().await?;
|
||||
//! println!("Agent status: {}", health.status);
|
||||
//! # Ok(())
|
||||
//! # }
|
||||
//! ```
|
||||
|
||||
use thiserror::Error;
|
||||
use std::time::Duration;
|
||||
|
||||
#[derive(Debug, Error)]
|
||||
pub enum AgentClientError {
|
||||
#[error("Not yet implemented")]
|
||||
NotImplemented,
|
||||
use reqwest::{
|
||||
tls::Version,
|
||||
Certificate, ClientBuilder, Identity,
|
||||
};
|
||||
use serde::{de::DeserializeOwned, Serialize};
|
||||
use tracing::{debug, instrument};
|
||||
|
||||
use crate::{
|
||||
error::AgentClientError,
|
||||
types::{
|
||||
AgentEnvelope, HealthData, PackagesData, PatchesData, SystemInfoData,
|
||||
ApplyPatchesRequest, ApplyPatchesResponse, AgentJobStatus, RollbackResponse,
|
||||
},
|
||||
};
|
||||
|
||||
/// Default TCP port that the Linux Patch API agent listens on.
|
||||
pub const DEFAULT_AGENT_PORT: u16 = 12443;
|
||||
|
||||
/// Request timeout applied to every agent API call.
|
||||
const REQUEST_TIMEOUT: Duration = Duration::from_secs(30);
|
||||
|
||||
// ============================================================
|
||||
// AgentClient
|
||||
// ============================================================
|
||||
|
||||
/// Async HTTP client that speaks mTLS to a single Linux Patch API agent.
|
||||
///
|
||||
/// Construct once via [`AgentClient::new`] and reuse across calls;
|
||||
/// the underlying [`reqwest::Client`] maintains a connection pool.
|
||||
#[derive(Debug, Clone)]
|
||||
pub struct AgentClient {
|
||||
/// Underlying HTTP client (configured for mTLS + TLS 1.3).
|
||||
inner: reqwest::Client,
|
||||
/// Base URL of the agent, e.g. `https://10.0.0.5:12443/api/v1`.
|
||||
base_url: String,
|
||||
}
|
||||
|
||||
impl AgentClient {
|
||||
/// Create a new [`AgentClient`] configured for mTLS.
|
||||
///
|
||||
/// # Arguments
|
||||
///
|
||||
/// * `host_ip` – IP address (or hostname) of the agent.
|
||||
/// * `port` – TCP port the agent listens on (default [`DEFAULT_AGENT_PORT`]).
|
||||
/// * `client_cert_pem` – PEM-encoded client certificate presented during the TLS handshake.
|
||||
/// * `client_key_pem` – PEM-encoded private key matching `client_cert_pem`.
|
||||
/// * `ca_cert_pem` – PEM-encoded CA certificate used to verify the agent's server cert.
|
||||
///
|
||||
/// # Errors
|
||||
///
|
||||
/// Returns [`AgentClientError::Tls`] when certificate parsing fails, or
|
||||
/// [`AgentClientError::Request`] when `reqwest` client construction fails.
|
||||
pub fn new(
|
||||
host_ip: &str,
|
||||
port: u16,
|
||||
client_cert_pem: &[u8],
|
||||
client_key_pem: &[u8],
|
||||
ca_cert_pem: &[u8],
|
||||
) -> Result<Self, AgentClientError> {
|
||||
// Build client identity: reqwest expects cert + key concatenated as PEM.
|
||||
let mut identity_pem = Vec::with_capacity(client_cert_pem.len() + client_key_pem.len());
|
||||
identity_pem.extend_from_slice(client_cert_pem);
|
||||
identity_pem.extend_from_slice(client_key_pem);
|
||||
|
||||
let identity = Identity::from_pem(&identity_pem)
|
||||
.map_err(|e| AgentClientError::Tls(format!("invalid client identity PEM: {e}")))?;
|
||||
|
||||
// Parse the CA certificate used to verify the agent's server certificate.
|
||||
let ca_cert = Certificate::from_pem(ca_cert_pem)
|
||||
.map_err(|e| AgentClientError::Tls(format!("invalid CA certificate PEM: {e}")))?;
|
||||
|
||||
// Build the reqwest client:
|
||||
// - force rustls TLS backend
|
||||
// - disable built-in OS/system trust roots (only trust our internal CA)
|
||||
// - enforce TLS 1.3 minimum
|
||||
// - attach client identity (mTLS)
|
||||
// - add our CA as a trusted root
|
||||
// - apply a global request timeout
|
||||
let inner = ClientBuilder::new()
|
||||
.use_rustls_tls()
|
||||
.tls_built_in_root_certs(false)
|
||||
.min_tls_version(Version::TLS_1_3)
|
||||
.identity(identity)
|
||||
.add_root_certificate(ca_cert)
|
||||
.timeout(REQUEST_TIMEOUT)
|
||||
.build()
|
||||
.map_err(|e| AgentClientError::Request(e))?;
|
||||
|
||||
let base_url = format!("https://{}:{}/api/v1", host_ip, port);
|
||||
tracing::debug!(base_url = %base_url, "AgentClient created");
|
||||
|
||||
Ok(Self { inner, base_url })
|
||||
}
|
||||
|
||||
// --------------------------------------------------------
|
||||
// Public API methods
|
||||
// --------------------------------------------------------
|
||||
|
||||
/// `GET /api/v1/health` — check agent liveness and retrieve uptime.
|
||||
#[instrument(skip(self), fields(base_url = %self.base_url))]
|
||||
pub async fn health(&self) -> Result<HealthData, AgentClientError> {
|
||||
self.get("health", &[]).await
|
||||
}
|
||||
|
||||
/// `GET /api/v1/system/info` — retrieve host system information.
|
||||
#[instrument(skip(self), fields(base_url = %self.base_url))]
|
||||
pub async fn system_info(&self) -> Result<SystemInfoData, AgentClientError> {
|
||||
self.get("system/info", &[]).await
|
||||
}
|
||||
|
||||
/// `GET /api/v1/packages?status=upgradable` — list packages with available upgrades.
|
||||
#[instrument(skip(self), fields(base_url = %self.base_url))]
|
||||
pub async fn packages_upgradable(&self) -> Result<PackagesData, AgentClientError> {
|
||||
self.get("packages", &[("status", "upgradable")]).await
|
||||
}
|
||||
|
||||
/// `GET /api/v1/patches` — list available patches with severity and CVE data.
|
||||
#[instrument(skip(self), fields(base_url = %self.base_url))]
|
||||
pub async fn patches(&self) -> Result<PatchesData, AgentClientError> {
|
||||
self.get("patches", &[]).await
|
||||
}
|
||||
|
||||
// --------------------------------------------------------
|
||||
// Private helpers
|
||||
// --------------------------------------------------------
|
||||
|
||||
/// Execute a GET request against `{base_url}/{path}` with optional query
|
||||
/// parameters, deserialize the [`AgentEnvelope`], and extract the `data`
|
||||
/// field — or propagate an [`AgentClientError::ApiError`].
|
||||
async fn get<T>(
|
||||
&self,
|
||||
path: &str,
|
||||
query: &[(&str, &str)],
|
||||
) -> Result<T, AgentClientError>
|
||||
where
|
||||
T: DeserializeOwned,
|
||||
{
|
||||
let url = format!("{}/{}", self.base_url, path);
|
||||
debug!(url = %url, ?query, "Sending GET request to agent");
|
||||
|
||||
let mut request = self.inner.get(&url);
|
||||
if !query.is_empty() {
|
||||
request = request.query(query);
|
||||
}
|
||||
|
||||
let response = request.send().await?;
|
||||
let status = response.status();
|
||||
debug!(url = %url, status = %status, "Received response from agent");
|
||||
|
||||
// Capture body text so we can attempt to deserialise the error envelope
|
||||
// even for non-2xx responses.
|
||||
let body = response.text().await?;
|
||||
|
||||
// Attempt to parse the standard agent envelope regardless of HTTP status.
|
||||
// The agent may embed a structured error body on 4xx/5xx responses.
|
||||
let envelope: AgentEnvelope<T> = serde_json::from_str(&body)?;
|
||||
|
||||
if !status.is_success() || !envelope.success {
|
||||
// Prefer the structured error from the envelope when present.
|
||||
if let Some(err) = envelope.error {
|
||||
return Err(AgentClientError::ApiError {
|
||||
code: err.code,
|
||||
message: err.message,
|
||||
});
|
||||
}
|
||||
// Fallback: use the HTTP status as the error indicator.
|
||||
return Err(AgentClientError::ApiError {
|
||||
code: status.as_str().to_string(),
|
||||
message: format!(
|
||||
"Agent returned HTTP {} for {}",
|
||||
status.as_u16(),
|
||||
url
|
||||
),
|
||||
});
|
||||
}
|
||||
|
||||
// On success the `data` field must be present.
|
||||
envelope.data.ok_or_else(|| AgentClientError::ApiError {
|
||||
code: "MISSING_DATA".to_string(),
|
||||
message: "Agent response success=true but data field is absent".to_string(),
|
||||
})
|
||||
}
|
||||
|
||||
// --------------------------------------------------------
|
||||
// Patch apply / job management methods
|
||||
// --------------------------------------------------------
|
||||
|
||||
/// `POST /api/v1/patches/apply` — trigger patch application on the agent.
|
||||
#[instrument(skip(self, req), fields(base_url = %self.base_url))]
|
||||
pub async fn apply_patches(
|
||||
&self,
|
||||
req: &ApplyPatchesRequest,
|
||||
) -> Result<ApplyPatchesResponse, AgentClientError> {
|
||||
self.post("patches/apply", req).await
|
||||
}
|
||||
|
||||
/// `GET /api/v1/jobs/{id}` — poll an async agent job for status.
|
||||
#[instrument(skip(self), fields(base_url = %self.base_url, job_id = %job_id))]
|
||||
pub async fn job_status(
|
||||
&self,
|
||||
job_id: &str,
|
||||
) -> Result<AgentJobStatus, AgentClientError> {
|
||||
self.get(&format!("jobs/{}", job_id), &[]).await
|
||||
}
|
||||
|
||||
/// `POST /api/v1/jobs/{id}/rollback` — trigger rollback on the agent.
|
||||
#[instrument(skip(self), fields(base_url = %self.base_url, job_id = %job_id))]
|
||||
pub async fn rollback_job(
|
||||
&self,
|
||||
job_id: &str,
|
||||
) -> Result<RollbackResponse, AgentClientError> {
|
||||
let empty: serde_json::Value = serde_json::json!({});
|
||||
self.post(&format!("jobs/{}/rollback", job_id), &empty).await
|
||||
}
|
||||
|
||||
// --------------------------------------------------------
|
||||
// Private POST helper
|
||||
// --------------------------------------------------------
|
||||
|
||||
/// Execute a POST request against `{base_url}/{path}`, serialize `body` as
|
||||
/// JSON, deserialize the [`AgentEnvelope`], and extract the `data` field —
|
||||
/// or propagate an [`AgentClientError::ApiError`].
|
||||
async fn post<Req, Resp>(
|
||||
&self,
|
||||
path: &str,
|
||||
body: &Req,
|
||||
) -> Result<Resp, AgentClientError>
|
||||
where
|
||||
Req: Serialize,
|
||||
Resp: DeserializeOwned,
|
||||
{
|
||||
let url = format!("{}/{}", self.base_url, path);
|
||||
debug!(url = %url, "Sending POST request to agent");
|
||||
|
||||
let response = self.inner.post(&url).json(body).send().await?;
|
||||
let status = response.status();
|
||||
debug!(url = %url, status = %status, "Received POST response from agent");
|
||||
|
||||
let body_text = response.text().await?;
|
||||
let envelope: AgentEnvelope<Resp> = serde_json::from_str(&body_text)?;
|
||||
|
||||
if !status.is_success() || !envelope.success {
|
||||
if let Some(err) = envelope.error {
|
||||
return Err(AgentClientError::ApiError {
|
||||
code: err.code,
|
||||
message: err.message,
|
||||
});
|
||||
}
|
||||
return Err(AgentClientError::ApiError {
|
||||
code: status.as_str().to_string(),
|
||||
message: format!("Agent returned HTTP {} for {}", status.as_u16(), url),
|
||||
});
|
||||
}
|
||||
|
||||
envelope.data.ok_or_else(|| AgentClientError::ApiError {
|
||||
code: "MISSING_DATA".to_string(),
|
||||
message: "Agent response success=true but data field is absent".to_string(),
|
||||
})
|
||||
}
|
||||
}
|
||||
|
||||
Reference in New Issue
Block a user