improved gateway <-> agent updater communication

Author: pacmancoder

crates/devolutions-agent-shared/src/lib.rs

@@ -2,21 +2,20 @@
 pub mod windows;
 
 mod date_version;
-mod update_json;
+mod update_manifest;
+mod update_status;
 
 use std::env;
 
 use camino::Utf8PathBuf;
 use cfg_if::cfg_if;
-
-#[rustfmt::skip]
 pub use date_version::{DateVersion, DateVersionError};
-#[rustfmt::skip]
-pub use update_json::{
-    ProductUpdateInfo, UPDATE_MANIFEST_V2_MINOR_VERSION, UpdateJson, UpdateManifest,
-    UpdateManifestV2, UpdateProductKey, UpdateSchedule, VersionMajorV2, VersionSpecification,
+pub use update_manifest::{
+    ProductUpdateInfo, UPDATE_MANIFEST_V2_MINOR_VERSION, UpdateManifest, UpdateManifestV1, UpdateManifestV2,
+    UpdateProductKey, UpdateSchedule, VersionMajorV2, VersionSpecification, default_schedule_window_start,
     detect_update_manifest_major_version,
 };
+pub use update_status::UpdateStatus;
 
 cfg_if! {
     if #[cfg(target_os = "windows")] {
@@ -78,7 +77,12 @@ pub fn get_data_dir() -> Utf8PathBuf {
     }
 }
 
-/// Returns the path to the `update.json` file
+/// Returns the path to the `update.json` file.
 pub fn get_updater_file_path() -> Utf8PathBuf {
     get_data_dir().join("update.json")
 }
+
+/// Returns the path to the `agent_status.json` file.
+pub fn get_agent_status_file_path() -> Utf8PathBuf {
+    get_data_dir().join("agent_status.json")
+}

…olutions-agent-shared/src/update_json.rs …ions-agent-shared/src/update_manifest.rscrates/devolutions-agent-shared/src/update_json.rs renamed to crates/devolutions-agent-shared/src/update_manifest.rs crates/devolutions-agent-shared/src/update_json.rs renamed to crates/devolutions-agent-shared/src/update_manifest.rs

@@ -5,8 +5,8 @@ use serde::{Deserialize, Deserializer, Serialize, Serializer};
 
 use crate::DateVersion;
 
-// ── V1 ── (keep for backward-compat; written by gateways <= 2026.1.0) ───────
-
+/// Old gateway-written manifest format (v2026.1.0 and prior), supported for backward compatibility.
+///
 /// Example V1 JSON structure:
 ///
 /// ```json
@@ -17,7 +17,7 @@ use crate::DateVersion;
 /// ```
 #[derive(Debug, Default, Deserialize, Serialize)]
 #[serde(rename_all = "PascalCase")]
-pub struct UpdateJson {
+pub struct UpdateManifestV1 {
     #[serde(skip_serializing_if = "Option::is_none")]
     pub gateway: Option<ProductUpdateInfo>,
     #[serde(skip_serializing_if = "Option::is_none")]
@@ -62,25 +62,27 @@ pub struct ProductUpdateInfo {
     pub target_version: VersionSpecification,
 }
 
-// ── V2 ── (new agents init update.json with `{"VersionMajor": "2"}`) ─────────
-
-/// Minor version of the V2 manifest format written by this build of the agent.
+/// Minor version of the V2 manifest format written by current build of the agent.
 ///
-/// The minor version tracks feature-set additions within V2 (major version):
-/// a new updatable product or capability increments this value so the gateway
-/// can detect what the agent supports and reject requests for unsupported features.
+/// The minor version tracks backwards-compatible changes within V2 (major version) manifest.
+/// Increment this value when adding new fields to `UpdateManifestV2` or making other non-breaking
+/// changes that require gateway and agent to be updated in tandem to take advantage of the new
+/// features.
 pub const UPDATE_MANIFEST_V2_MINOR_VERSION: u32 = 1;
 
-fn default_schedule_window_start() -> u32 {
+pub fn default_schedule_window_start() -> u32 {
     7_200
 }
 
 /// Auto-update schedule for the Devolutions Agent, embedded in [`UpdateManifestV2`].
 ///
 /// Written by the gateway via `POST /jet/update/schedule` and consumed by the agent,
-/// which validates the values, applies them to the running poll loop, and persists them
-/// to `agent.json`.  Exposed to the gateway via `GET /jet/update/schedule` so that the
-/// current schedule is always readable without touching `agent.json`.
+/// which validates the values, applies them to the running scheduling loop, and persists them
+/// to `agent.json`.
+///
+/// Additionally, Agent writes the current scheduler recorded in `agent.json`
+/// so gateway can retrieve it back via `GET /jet/update/schedule` without needing to introduce
+/// knowledge of agent's configuration file format on the gateway side.
 #[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq, Default)]
 #[serde(rename_all = "PascalCase")]
 pub struct UpdateSchedule {
@@ -99,7 +101,7 @@ pub struct UpdateSchedule {
 
     /// End of the maintenance window as seconds past midnight, local time, exclusive.
     ///
-    /// `None` means no upper bound (only single update check at update_window_start).
+    /// `None` means no upper bound.
     /// When end < start the window crosses midnight.
     #[serde(default, skip_serializing_if = "Option::is_none")]
     pub update_window_end: Option<u32>,
@@ -109,13 +111,13 @@ pub struct UpdateSchedule {
     pub products: Vec<UpdateProductKey>,
 }
 
-/// Sentinel type that always serializes/deserializes as the number `2`.
+/// Marker type that always serializes/deserializes as the number `2`.
 ///
 /// Embedded as the `VersionMajor` field in [`UpdateManifestV2`] so that the
 /// untagged [`UpdateManifest`] enum can distinguish V2 from legacy V1 payloads:
 /// if `VersionMajor` is absent or not `"2"`, `ManifestV2` deserialization fails
 /// and the `Legacy` variant is tried next.  When a V3 format is introduced, a new
-/// sentinel and `ManifestV3` variant are added in the same way.
+/// marker type and `ManifestV3` variant are added in a similar way.
 #[derive(Debug, Default, Clone, Copy, PartialEq, Eq)]
 pub struct VersionMajorV2;
 
@@ -145,7 +147,9 @@ impl<'de> Deserialize<'de> for VersionMajorV2 {
     }
 }
 
-/// V2 manifest: major-version sentinel, minor feature version, product map, and schedule.
+/// Version 2 of the update manifest format, written by agent/gateway >=2026.2.0.
+/// Includes product update list and auto-update schedule. Adding a product name should always
+/// increase the minor version, to allow the gateway API caller to know supported products list.
 ///
 /// Example (full V2 file):
 /// ```json
@@ -163,10 +167,10 @@ impl<'de> Deserialize<'de> for VersionMajorV2 {
 #[serde(rename_all = "PascalCase")]
 pub struct UpdateManifestV2 {
     /// Always `2` — the presence and value of this field let the untagged
-    /// [`UpdateManifest`] distinguish V2 from legacy V1 payloads.
+    /// [`UpdateManifest`] distinguish V2 from legacy V1 payloads and prevent further parsing
+    /// attempt of V2 structure
     pub version_major: VersionMajorV2,
     /// Feature-set version within V2. Defaults to `0` when the field is absent in the file.
-    #[serde(default)]
     pub version_minor: u32,
     /// Auto-update schedule set by the gateway. Agent persists it to `agent.json`.
     #[serde(skip_serializing_if = "Option::is_none")]
@@ -187,8 +191,6 @@ impl Default for UpdateManifestV2 {
     }
 }
 
-// ── Unified manifest ─────────────────────────────────────────────────────────
-
 /// A parsed update manifest: either a V2 file or a legacy V1 file.
 ///
 /// New agents initialise `update.json` with `{"VersionMajor": "2", "VersionMinor": 0}`;
@@ -205,7 +207,7 @@ pub enum UpdateManifest {
     /// V2 format: contains `"VersionMajor": 2`.
     ManifestV2(UpdateManifestV2),
     /// Legacy V1 format: no `"VersionMajor"` field.
-    Legacy(UpdateJson),
+    Legacy(UpdateManifestV1),
 }
 
 fn strip_bom(data: &[u8]) -> &[u8] {

crates/devolutions-agent-shared/src/update_status.rs

@@ -0,0 +1,40 @@
+use std::collections::HashMap;
+
+use serde::{Deserialize, Serialize};
+
+use crate::{ProductUpdateInfo, UpdateProductKey, UpdateSchedule};
+
+/// Agent runtime status written to `agent_status.json` on agent start and refreshed
+/// after each updater run or auto-update schedule change.
+///
+/// The gateway reads this file for `GET /jet/update/schedule` so that it can surface
+/// current agent state without needing knowledge of the agent's internal `agent.json`
+/// configuration format.
+///
+/// Unlike [`crate::UpdateManifest`] (`update.json`), this file is **read-only** for
+/// the Gateway service: its DACL grants NETWORK SERVICE read access but **no write
+/// access**.  The agent is the sole writer.
+///
+/// Note: if the agent itself is being updated, `agent_status.json` will be
+/// automatically refreshed when the agent restarts after the update completes.
+#[derive(Debug, Clone, Serialize, Deserialize, Default)]
+#[serde(rename_all = "PascalCase")]
+pub struct UpdateStatus {
+    /// Current auto-update schedule configured for this agent.
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub schedule: Option<UpdateSchedule>,
+
+    /// Map of product name → currently **installed** version.
+    ///
+    /// Each entry's `TargetVersion` field holds the installed version of the product,
+    /// not a requested upgrade target.  Products that are not installed are omitted.
+    #[serde(default, skip_serializing_if = "HashMap::is_empty")]
+    pub products: HashMap<UpdateProductKey, ProductUpdateInfo>,
+}
+
+impl UpdateStatus {
+    /// Parse `agent_status.json` bytes.
+    pub fn parse(data: &[u8]) -> serde_json::Result<Self> {
+        serde_json::from_slice(data)
+    }
+}

devolutions-agent/src/config.rs

@@ -5,7 +5,7 @@ use std::sync::Arc;
 
 use anyhow::{Context, bail};
 use camino::{Utf8Path, Utf8PathBuf};
-use devolutions_agent_shared::get_data_dir;
+use devolutions_agent_shared::{default_schedule_window_start, get_data_dir};
 use serde::{Deserialize, Serialize};
 use tap::prelude::*;
 use url::Url;
@@ -220,7 +220,7 @@ pub mod dto {
         pub interval: u64,
 
         /// Start of the maintenance window as seconds past midnight, local time.
-        #[serde(default)]
+        #[serde(default = "default_schedule_window_start")]
         pub update_window_start: u32,
 
         /// End of the maintenance window as seconds past midnight, local time, exclusive.