refactor(api-server): Make CompressionUsage OpenAPI fields user-oriented.

- Change `status: i32` to `job_status: CompressionJobStatus` with typed enum
- Rename fields to include units: `_millisecs`, `_secs`, `_bytes`
- Rewrite docstrings to remove DB internals/Python file references
- Add `ToSchema` derive and user-facing docstrings to `CompressionJobStatus`
- Register `CompressionJobStatus` in OpenAPI schema components

Author: jackluo923

components/api-server/src/client.rs

@@ -133,36 +133,38 @@ impl TryFrom<CompressionUsageParams> for ValidatedCompressionUsageParams {
     }
 }
 
-/// A single row returned by the compression usage query (one row per job).
+/// Resource usage statistics for the compression job with the specified ID.
 #[derive(Serialize, sqlx::FromRow, ToSchema)]
 pub struct CompressionUsage {
     /// Compression job ID.
     pub id: i32,
-    /// Job status. See `CompressionJobStatus` in
-    /// `components/job-orchestration/job_orchestration/scheduler/constants.py`:
-    /// 0 = PENDING, 1 = RUNNING, 2 = SUCCEEDED, 3 = FAILED, 4 = KILLED.
-    pub status: i32,
+    /// Current status of the job.
+    #[sqlx(rename = "status", try_from = "i32")]
+    pub job_status: CompressionJobStatus,
     /// Time the job was created (epoch milliseconds).
     #[serde(with = "chrono::serde::ts_milliseconds")]
     #[schema(value_type = i64)]
-    pub creation_time: DateTime<Utc>,
-    /// Time the job started (epoch milliseconds). Always non-null in results
-    /// because the WHERE clause filters on `start_time`.
+    #[sqlx(rename = "creation_time")]
+    pub time_creation_millisecs: DateTime<Utc>,
+    /// Time the job started executing (epoch milliseconds).
     #[serde(with = "chrono::serde::ts_milliseconds")]
     #[schema(value_type = i64)]
-    pub start_time: DateTime<Utc>,
-    /// Wall-clock seconds the job ran for. `None` for non-succeeded jobs
-    /// (FAILED, KILLED, RUNNING) since `duration` is only set on completion.
-    pub duration: Option<f64>,
-    /// Total uncompressed size of input files (bytes).
-    pub uncompressed_size: i64,
-    /// Total compressed archive size (bytes).
-    pub compressed_size: i64,
+    #[sqlx(rename = "start_time")]
+    pub time_begin_millisecs: DateTime<Utc>,
+    /// Wall-clock duration the job ran, in seconds. Absent if the job did not complete.
+    #[sqlx(rename = "duration")]
+    pub duration_secs: Option<f64>,
+    /// Total uncompressed size of input files, in bytes.
+    #[sqlx(rename = "uncompressed_size")]
+    pub uncompressed_size_bytes: i64,
+    /// Total compressed archive size, in bytes.
+    #[sqlx(rename = "compressed_size")]
+    pub compressed_size_bytes: i64,
     /// Number of tasks the job was split into.
     pub num_tasks: i32,
-    /// Sum of all task durations (CPU-seconds across all parallel workers).
-    /// `None` if all task duration values are NULL in the database.
-    pub tasks_duration: Option<f64>,
+    /// Sum of all task durations, in seconds. Absent if no tasks reported a duration.
+    #[sqlx(rename = "tasks_duration")]
+    pub tasks_duration_secs: Option<f64>,
 }
 
 /// Defines the request configuration for submitting a search query.

components/api-server/src/routes.rs

@@ -73,6 +73,7 @@ mod api_doc {
         __path_query_results,
         CompressionUsage,
     };
+    use crate::client::CompressionJobStatus;
 
     #[derive(utoipa::OpenApi)]
     #[openapi(
@@ -82,7 +83,7 @@ mod api_doc {
             contact(name = "YScope")
         ),
         paths(health, query, query_results, cancel_query, compression_usage),
-        components(schemas(CompressionUsage))
+        components(schemas(CompressionUsage, CompressionJobStatus))
     )]
     pub struct ApiDoc;
 }

components/clp-rust-utils/src/job_config/compression.rs

@@ -1,10 +1,11 @@
 use num_enum::{IntoPrimitive, TryFromPrimitive};
 use serde::{Deserialize, Serialize};
 use strum::EnumString;
+use utoipa::ToSchema;
 
 pub type CompressionJobId = i32;
 
-/// Mirror of `job_orchestration.scheduler.constants.CompressionJobStatus`. Must be kept in sync.
+// Mirror of `job_orchestration.scheduler.constants.CompressionJobStatus`. Must be kept in sync.
 #[derive(
     Clone,
     Copy,
@@ -15,14 +16,20 @@ pub type CompressionJobId = i32;
     IntoPrimitive,
     PartialEq,
     Serialize,
+    ToSchema,
     TryFromPrimitive,
 )]
 #[repr(i32)]
 #[strum(ascii_case_insensitive)]
 pub enum CompressionJobStatus {
+    /// Job is waiting to be scheduled.
     Pending = 0,
+    /// Job is currently executing.
     Running = 1,
+    /// Job completed successfully.
     Succeeded = 2,
+    /// Job failed.
     Failed = 3,
+    /// Job was killed by a user.
     Killed = 4,
 }

docs/src/_static/generated/api-server-openapi.json

@@ -213,69 +213,78 @@
   },
   "components": {
     "schemas": {
+      "CompressionJobStatus": {
+        "type": "string",
+        "enum": [
+          "Pending",
+          "Running",
+          "Succeeded",
+          "Failed",
+          "Killed"
+        ]
+      },
       "CompressionUsage": {
         "type": "object",
-        "description": "A single row returned by the compression usage query (one row per job).",
+        "description": "Resource usage statistics for the compression job with the specified ID.",
         "required": [
           "id",
-          "status",
-          "creation_time",
-          "start_time",
-          "uncompressed_size",
-          "compressed_size",
+          "job_status",
+          "time_creation_millisecs",
+          "time_begin_millisecs",
+          "uncompressed_size_bytes",
+          "compressed_size_bytes",
           "num_tasks"
         ],
         "properties": {
-          "compressed_size": {
+          "compressed_size_bytes": {
             "type": "integer",
             "format": "int64",
-            "description": "Total compressed archive size (bytes)."
-          },
-          "creation_time": {
-            "type": "integer",
-            "format": "int64",
-            "description": "Time the job was created (epoch milliseconds)."
+            "description": "Total compressed archive size, in bytes."
           },
-          "duration": {
+          "duration_secs": {
             "type": [
               "number",
               "null"
             ],
             "format": "double",
-            "description": "Wall-clock seconds the job ran for. `None` for non-succeeded jobs\n(FAILED, KILLED, RUNNING) since `duration` is only set on completion."
+            "description": "Wall-clock duration the job ran, in seconds. Absent if the job did not complete."
           },
           "id": {
             "type": "integer",
             "format": "int32",
             "description": "Compression job ID."
           },
+          "job_status": {
+            "$ref": "#/components/schemas/CompressionJobStatus",
+            "description": "Current status of the job."
+          },
           "num_tasks": {
             "type": "integer",
             "format": "int32",
             "description": "Number of tasks the job was split into."
           },
-          "start_time": {
-            "type": "integer",
-            "format": "int64",
-            "description": "Time the job started (epoch milliseconds). Always non-null in results\nbecause the WHERE clause filters on `start_time`."
-          },
-          "status": {
-            "type": "integer",
-            "format": "int32",
-            "description": "Job status. See `CompressionJobStatus` in\n`components/job-orchestration/job_orchestration/scheduler/constants.py`:\n0 = PENDING, 1 = RUNNING, 2 = SUCCEEDED, 3 = FAILED, 4 = KILLED."
-          },
-          "tasks_duration": {
+          "tasks_duration_secs": {
             "type": [
               "number",
               "null"
             ],
             "format": "double",
-            "description": "Sum of all task durations (CPU-seconds across all parallel workers).\n`None` if all task duration values are NULL in the database."
+            "description": "Sum of all task durations, in seconds. Absent if no tasks reported a duration."
+          },
+          "time_begin_millisecs": {
+            "type": "integer",
+            "format": "int64",
+            "description": "Time the job started executing (epoch milliseconds)."
+          },
+          "time_creation_millisecs": {
+            "type": "integer",
+            "format": "int64",
+            "description": "Time the job was created (epoch milliseconds)."
           },
-          "uncompressed_size": {
+          "uncompressed_size_bytes": {
             "type": "integer",
             "format": "int64",
-            "description": "Total uncompressed size of input files (bytes)."
+            "description": "Total uncompressed size of input files, in bytes."
           }
         }
       },