Updated OpenAPI

pacmancoder · pacmancoder · commit e004510b53b6 · 2026-03-31T02:03:12.000+03:00
diff --git a/devolutions-gateway/openapi/gateway-api.yaml b/devolutions-gateway/openapi/gateway-api.yaml
@@ -7,7 +7,7 @@ info:
     email: infos@devolutions.net
   license:
     name: MIT/Apache-2.0
-  version: 2025.3.2
+  version: 2026.1.0
 paths:
   /jet/config:
     patch:
@@ -598,22 +598,40 @@ paths:
     post:
       tags:
       - Update
-      summary: Triggers Devolutions Gateway update process.
+      summary: Trigger an update for one or more Devolutions products.
       description: |-
-        This is done via updating `Agent/update.json` file, which is then read by Devolutions Agent
-        when changes are detected. If the version written to `update.json` is indeed higher than the
-        currently installed version, Devolutions Agent will proceed with the update process.
+        Writes the requested version(s) into `Agent/update.json`, which is watched by Devolutions
+        Agent. When a requested version is higher than the installed version the agent proceeds
+        with the update.
+
+        **Body form** (preferred): pass a JSON body with a `Products` map.
+
+        **Query-param form** (legacy, gateway-only): `POST /jet/update?version=latest`.
+        This form updates only the Gateway product and is kept for backward compatibility.
+
+        Both forms cannot be used simultaneously; doing so returns HTTP 400.
       operationId: TriggerUpdate
       parameters:
       - name: version
         in: query
-        description: The version to install; use 'latest' for the latest version, or 'w.x.y.z' for a specific version
-        required: true
+        description: Gateway-only target version; use the request body for multi-product updates
+        required: false
+        deprecated: true
         schema:
           type: string
+          nullable: true
+      requestBody:
+        description: Products and target versions to update
+        content:
+          application/json:
+            schema:
+              allOf:
+              - $ref: '#/components/schemas/UpdateRequest'
+              nullable: true
+        required: false
       responses:
         '200':
-          description: Update request has been processed successfully
+          description: Update request accepted
           content:
             application/json:
               schema:
@@ -625,7 +643,72 @@ paths:
         '403':
           description: Insufficient permissions
         '500':
-          description: Agent updater service is malfunctioning
+          description: Failed to write update manifest
+        '503':
+          description: Agent updater service is unavailable
+      security:
+      - scope_token:
+        - gateway.update
+  /jet/update/schedule:
+    get:
+      tags:
+      - Update
+      summary: Retrieve the current Devolutions Agent auto-update schedule.
+      description: |-
+        Reads the `Schedule` field from `update.json`.  When the field is absent the response
+        contains zeroed defaults (`Enabled: false`, interval `0`, window start `0`, no products).
+      operationId: GetUpdateSchedule
+      responses:
+        '200':
+          description: Current auto-update schedule
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/GetUpdateScheduleResponse'
+        '401':
+          description: Invalid or missing authorization token
+        '403':
+          description: Insufficient permissions
+        '500':
+          description: Failed to read update manifest
+        '503':
+          description: Agent updater service is unavailable
+      security:
+      - scope_token:
+        - gateway.update
+    post:
+      tags:
+      - Update
+      summary: Set the Devolutions Agent auto-update schedule.
+      description: |-
+        Writes the `Schedule` field into `update.json`.  The agent watches this file and
+        applies the new schedule immediately, then persists it to `agent.json`.
+
+        All other fields in `update.json` are preserved; the `VersionMinor` field is reset to
+        the minor version this gateway build understands so the agent does not see an unknown
+        future version.
+      operationId: SetUpdateSchedule
+      requestBody:
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/SetUpdateScheduleRequest'
+        required: true
+      responses:
+        '200':
+          description: Auto-update schedule applied
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/SetUpdateScheduleResponse'
+        '400':
+          description: Bad request
+        '401':
+          description: Invalid or missing authorization token
+        '403':
+          description: Insufficient permissions
+        '500':
+          description: Failed to write update manifest
         '503':
           description: Agent updater service is unavailable
       security:
@@ -885,6 +968,43 @@ components:
       - connect_failure
       - normal_termination
       - abnormal_termination
+    GetUpdateScheduleResponse:
+      type: object
+      description: Current auto-update schedule for Devolutions Agent.
+      required:
+      - Enabled
+      - Interval
+      - UpdateWindowStart
+      properties:
+        Enabled:
+          type: boolean
+          description: Enable periodic Devolutions Agent self-update checks.
+        Interval:
+          type: integer
+          format: int64
+          description: |-
+            Minimum interval between auto-update checks, in seconds.
+
+            `0` means check once at `UpdateWindowStart`.
+          minimum: 0
+        Products:
+          type: array
+          items:
+            $ref: '#/components/schemas/UpdateProduct'
+          description: Products the agent autonomously polls for new versions.
+        UpdateWindowEnd:
+          type: integer
+          format: int32
+          description: |-
+            End of the maintenance window as seconds past midnight (local time, exclusive).
+            `None` means no upper bound (single check at `UpdateWindowStart`).
+          nullable: true
+          minimum: 0
+        UpdateWindowStart:
+          type: integer
+          format: int32
+          description: Start of the maintenance window as seconds past midnight (local time).
+          minimum: 0
     Heartbeat:
       type: object
       required:
@@ -1361,6 +1481,45 @@ components:
             $ref: '#/components/schemas/MonitorDefinitionProbeTypeError'
           description: An optional list of probes that this server could not parse.
           nullable: true
+    SetUpdateScheduleRequest:
+      type: object
+      description: Desired auto-update schedule to apply to Devolutions Agent.
+      required:
+      - Enabled
+      properties:
+        Enabled:
+          type: boolean
+          description: Enable periodic Devolutions Agent self-update checks.
+        Interval:
+          type: integer
+          format: int64
+          description: |-
+            Minimum interval between auto-update checks, in seconds.
+
+            `0` means check once at `UpdateWindowStart` (default).
+          minimum: 0
+        Products:
+          type: array
+          items:
+            $ref: '#/components/schemas/UpdateProduct'
+          description: 'Products the agent autonomously polls for new versions (default: empty).'
+        UpdateWindowEnd:
+          type: integer
+          format: int32
+          description: |-
+            End of the maintenance window as seconds past midnight in local time, exclusive.
+
+            `null` (default) means no upper bound -- a single check fires at `UpdateWindowStart`.
+            When end < start the window crosses midnight.
+          nullable: true
+          minimum: 0
+        UpdateWindowStart:
+          type: integer
+          format: int32
+          description: 'Start of the maintenance window as seconds past midnight in local time (default: `7200` = 02:00).'
+          minimum: 0
+    SetUpdateScheduleResponse:
+      type: object
     SubProvisionerKey:
       type: object
       required:
@@ -1455,8 +1614,54 @@ components:
       enum:
       - tcp
       - udp
+    UpdateProduct:
+      oneOf:
+      - type: string
+        enum:
+        - Gateway
+      - type: string
+        enum:
+        - HubService
+      - type: string
+        enum:
+        - Agent
+      - type: object
+        required:
+        - Other
+        properties:
+          Other:
+            type: string
+            description: A product name not recognised by this gateway version.
+      description: |-
+        Known product names accepted by the update endpoint.
+
+        `Other` captures any product name not yet known to this gateway version;
+        it is forwarded to the agent unchanged so future agents can act on it.
+    UpdateProductRequest:
+      type: object
+      description: Per-product version request.
+      required:
+      - Version
+      properties:
+        Version:
+          $ref: '#/components/schemas/VersionSpecification'
+    UpdateRequest:
+      type: object
+      description: |-
+        Request body for the unified update endpoint.
+
+        Every key in `Products` is a product name. Known products (`Gateway`, `Agent`,
+        `HubService`) are processed natively; any other name is forwarded as-is to the
+        agent so future product types are supported transparently.
+      properties:
+        Products:
+          type: object
+          description: Map of product name to version specification.
+          additionalProperties:
+            $ref: '#/components/schemas/UpdateProductRequest'
     UpdateResponse:
       type: object
+      description: Response returned by the update endpoint.
   securitySchemes:
     jrec_token:
       type: http
diff --git a/devolutions-gateway/src/api/update.rs b/devolutions-gateway/src/api/update.rs
@@ -81,7 +81,7 @@ async fn write_manifest(mut manifest: UpdateManifestV2) -> Result<(), HttpError>
 
 // ── OpenAPI request / response types ─────────────────────────────────────────
 
-/// Version specification string: `"latest"` or a specific version like `"2026.1.0"`.
+/// Per-product version request.
 #[cfg_attr(feature = "openapi", derive(utoipa::ToSchema))]
 #[derive(Debug, Deserialize)]
 #[serde(rename_all = "PascalCase")]
@@ -141,22 +141,11 @@ impl serde::Serialize for UpdateProduct {
 /// Every key in `Products` is a product name. Known products (`Gateway`, `Agent`,
 /// `HubService`) are processed natively; any other name is forwarded as-is to the
 /// agent so future product types are supported transparently.
-///
-/// # Example
-///
-/// ```json
-/// {
-///   "Products": {
-///     "Gateway": { "Version": "2026.1.0" },
-///     "Agent":   { "Version": "latest"   }
-///   }
-/// }
-/// ```
 #[cfg_attr(feature = "openapi", derive(utoipa::ToSchema))]
 #[derive(Debug, Default, Deserialize)]
 #[serde(rename_all = "PascalCase")]
 pub(crate) struct UpdateRequest {
-    /// Map of product name → version specification.
+    /// Map of product name to version specification.
     #[serde(default)]
     pub products: HashMap<UpdateProduct, UpdateProductRequest>,
 }
@@ -371,7 +360,7 @@ pub(crate) struct SetUpdateScheduleRequest {
     pub update_window_start: u32,
     /// End of the maintenance window as seconds past midnight in local time, exclusive.
     ///
-    /// `null` (default) means no upper bound — a single check fires at `UpdateWindowStart`.
+    /// `null` (default) means no upper bound - a single check fires at `UpdateWindowStart`.
     /// When end < start the window crosses midnight.
     #[serde(rename = "UpdateWindowEnd", default)]
     pub update_window_end: Option<u32>,
diff --git a/devolutions-gateway/src/openapi.rs b/devolutions-gateway/src/openapi.rs
@@ -26,6 +26,8 @@ use crate::config::dto::{DataEncoding, PubKeyFormat, Subscriber};
         crate::api::webapp::sign_app_token,
         crate::api::webapp::sign_session_token,
         crate::api::update::trigger_update_check,
+        crate::api::update::get_update_schedule,
+        crate::api::update::set_update_schedule,
         crate::api::preflight::post_preflight,
         crate::api::net::get_net_config,
         crate::api::monitoring::handle_set_monitoring_config,
@@ -55,6 +57,9 @@ use crate::config::dto::{DataEncoding, PubKeyFormat, Subscriber};
         crate::api::update::UpdateProduct,
         crate::api::update::UpdateProductRequest,
         crate::api::update::UpdateResponse,
+        crate::api::update::GetUpdateScheduleResponse,
+        crate::api::update::SetUpdateScheduleRequest,
+        crate::api::update::SetUpdateScheduleResponse,
         PreflightOperation,
         PreflightOperationKind,
         AppCredential,
