api: new endpoint that dynamically generate openapi from varlink IDL

This commit adds an endpoint for that generates openapi descriptions
from the varlink IDL for a given interface. It is located under
/openapi/{socket}/{interface} and is created dynamically.

This is useful to bridge the gap between varlink and the wide
openapi ecosytem. This allows to e.g. create fully typed interfaces
for tyescript/react/go etc.

This is using openapi 3.1 because it seems to be the most widely
used one currently.

Note that this seems to work well for most of the IDL and it maps
nicely. The thing that does not map well is errors. The varlink
IDL does only specify errors per interface but not per method. So
currently errors are added as `components` but not part of the
potential methods returns because we would have to add all errors
as potential returns to all methods which feels a bit too much.
Nullable is also added a bit simplistic.

The other gap is "more" support, currently this is not discoverable
from the IDL so we cannot make it part of the openapi output. We
may need to have a convention in the method description or something,
but that can be done in a followup. Only a small subset of calls uses
"more" currently.

E.g.
```json
$ curl -s http://localhost:1031/openapi/io.systemd.MuteConsole/io.systemd.MuteConsole|jq
{
  "info": {
    "description": "API for temporarily muting noisy output to the main kernel console",
    "title": "io.systemd.MuteConsole",
    "version": "0.0.0"
  },
  "openapi": "3.1.0",
  "paths": {
    "/call/io.systemd.MuteConsole/io.systemd.MuteConsole.Mute": {
      "post": {
        "description": "Mute kernel and PID 1 output to the main kernel console\n[Requires 'more' flag]",
        "operationId": "Mute",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "properties": {
                  "kernel": {
                    "description": "Whether to mute the kernel's output to the console (defaults to true).",
                    "type": "boolean"
                  },
                  "pid1": {
                    "description": "Whether to mute PID1's output to the console (defaults to true).",
                    "type": "boolean"
                  }
                },
                "type": "object"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {},
                  "type": "object"
                }
              }
            },
            "description": "Successful response"
          }
        }
      }
    }
  }
}
```

Author: mvo5

README.md

@@ -16,6 +16,7 @@ POST /call/{method}                    → invoke method (c.f. varlink call, sup
 GET  /sockets                          → list available sockets (c.f. valinkctl list-registry)
 GET  /sockets/{socket}                 → socket info (c.f. varlinkctl info)
 GET  /sockets/{socket}/{interface}     → interface details, including method names (c.f. varlinkctl list-methods)
+GET  /openapi/{socket}/{interface}     → OpenAPI 3.1 description generated from varlink IDL
 
 GET  /health                           → health check
 ```

src/bin/varlink-httpd/main.rs

@@ -33,6 +33,7 @@ use zlink::varlink_service::Proxy;
 mod auth_ssh;
 #[cfg(feature = "sshauth")]
 mod import_ssh;
+mod openapi;
 
 #[cfg(feature = "sshauth")]
 use auth_ssh::{extract_nonce, maybe_create_ssh_authenticator};
@@ -540,6 +541,27 @@ struct AppState {
     authenticators: Arc<Vec<Box<dyn Authenticator>>>,
 }
 
+async fn route_openapi_get(
+    ConnectInfo(conn_cache): ConnectInfo<VarlinkConnCache>,
+    Path((socket, interface)): Path<(String, String)>,
+    State(state): State<AppState>,
+) -> Result<axum::Json<Value>, AppError> {
+    debug!("GET openapi for socket: {socket}, interface: {interface}");
+    let conn_arc = get_varlink_connection(&socket, &state, &conn_cache).await?;
+    let mut connection = conn_arc.lock().await;
+
+    let description = connection
+        .get_interface_description(&interface)
+        .await?
+        .map_err(|e| AppError::bad_gateway(format!("service error: {e}")))?;
+
+    let iface: zlink::idl::Interface = description
+        .parse()
+        .map_err(|e| AppError::bad_gateway(format!("upstream IDL parse error: {e}")))?;
+
+    Ok(axum::Json(openapi::idl_to_openapi(&socket, &iface)))
+}
+
 async fn route_sockets_get(State(state): State<AppState>) -> Result<axum::Json<Value>, AppError> {
     debug!("GET sockets");
     let all_sockets = state.varlink_sockets.list_sockets().await?;
@@ -830,6 +852,7 @@ fn create_router(
             "/sockets/{socket}/{interface}",
             get(route_socket_interface_get),
         )
+        .route("/openapi/{socket}/{interface}", get(route_openapi_get))
         .route("/call/{method}", post(route_call_post))
         .route("/ws/sockets/{socket}", get(route_ws))
         .layer(axum::middleware::from_fn_with_state(

src/bin/varlink-httpd/openapi.rs

@@ -0,0 +1,166 @@
+// SPDX-License-Identifier: LGPL-2.1-or-later
+
+use serde_json::{Value, json};
+use zlink::idl::{CustomType, Field, Interface, Type};
+
+fn type_to_schema(ty: &Type) -> Value {
+    match ty {
+        Type::Bool => json!({"type": "boolean"}),
+        Type::Int => json!({"type": "integer", "format": "int64"}),
+        Type::Float => json!({"type": "number"}),
+        Type::String => json!({"type": "string"}),
+        Type::ForeignObject | Type::Any => json!({"type": "object"}),
+        Type::Custom(name) => {
+            json!({"$ref": format!("#/components/schemas/{name}")})
+        }
+        Type::Optional(inner) => type_to_schema(inner.inner()),
+        Type::Array(inner) => {
+            json!({"type": "array", "items": type_to_schema(inner.inner())})
+        }
+        Type::Map(inner) => {
+            json!({"type": "object", "additionalProperties": type_to_schema(inner.inner())})
+        }
+        Type::Object(fields) => fields_to_schema(fields.iter()),
+        Type::Enum(variants) => {
+            let names: Vec<&str> = variants.iter().map(|v| v.name()).collect();
+            json!({"type": "string", "enum": names})
+        }
+    }
+}
+
+fn fields_to_schema<'a>(fields: impl Iterator<Item = &'a Field<'a>>) -> Value {
+    let mut properties = serde_json::Map::new();
+    let mut required = Vec::new();
+
+    for field in fields {
+        let mut schema = type_to_schema(field.ty());
+        if let Some(desc) = comments_to_string(field.comments()) {
+            if let Value::Object(ref mut map) = schema {
+                map.insert("description".to_string(), json!(desc));
+            }
+        }
+        properties.insert(field.name().to_string(), schema);
+        if !matches!(field.ty(), Type::Optional(_)) {
+            required.push(json!(field.name()));
+        }
+    }
+
+    let mut schema = serde_json::Map::new();
+    schema.insert("type".to_string(), json!("object"));
+    schema.insert("properties".to_string(), Value::Object(properties));
+    if !required.is_empty() {
+        schema.insert("required".to_string(), Value::Array(required));
+    }
+    Value::Object(schema)
+}
+
+fn comments_to_string<'a>(
+    comments: impl Iterator<Item = &'a zlink::idl::Comment<'a>>,
+) -> Option<String> {
+    let parts: Vec<&str> = comments.map(|c| c.content()).collect();
+    (!parts.is_empty()).then(|| parts.join("\n"))
+}
+
+pub fn idl_to_openapi(address: &str, iface: &Interface) -> Value {
+    let mut paths = serde_json::Map::new();
+
+    for method in iface.methods() {
+        let full_method = format!("{}.{}", iface.name(), method.name());
+        let path = format!("/call/{address}/{full_method}");
+
+        let mut operation = serde_json::Map::new();
+        operation.insert("operationId".to_string(), json!(method.name()));
+        if let Some(desc) = comments_to_string(method.comments()) {
+            operation.insert("description".to_string(), json!(desc));
+        }
+        operation.insert(
+            "requestBody".to_string(),
+            json!({
+                "required": true,
+                "content": {
+                    "application/json": {
+                        "schema": fields_to_schema(method.inputs())
+                    }
+                }
+            }),
+        );
+        let output_schema = fields_to_schema(method.outputs());
+        operation.insert(
+            "responses".to_string(),
+            json!({
+                "200": {
+                    "description": "Successful response",
+                    "content": {
+                        "application/json": {
+                            "schema": output_schema
+                        },
+                        "application/json-seq": {
+                            "description": "Streaming response using the varlink 'more' flag. Each reply is encoded as an RFC 7464 JSON text sequence (RS 0x1E + JSON + LF). Request this format via Accept: application/json-seq.",
+                            "schema": output_schema
+                        }
+                    }
+                }
+            }),
+        );
+
+        let path_item = json!({ "post": Value::Object(operation) });
+        paths.insert(path, path_item);
+    }
+
+    let mut schemas = serde_json::Map::new();
+
+    for custom_type in iface.custom_types() {
+        let (mut schema, desc) = match custom_type {
+            CustomType::Object(obj) => (
+                fields_to_schema(obj.fields()),
+                comments_to_string(obj.comments()),
+            ),
+            CustomType::Enum(e) => {
+                let names: Vec<&str> = e.variants().map(|v| v.name()).collect();
+                (
+                    json!({"type": "string", "enum": names}),
+                    comments_to_string(e.comments()),
+                )
+            }
+        };
+        if let Some(desc) = desc {
+            if let Value::Object(ref mut map) = schema {
+                map.insert("description".to_string(), json!(desc));
+            }
+        }
+        schemas.insert(custom_type.name().to_string(), schema);
+    }
+
+    for error in iface.errors() {
+        let mut schema = fields_to_schema(error.fields());
+        if let Some(desc) = comments_to_string(error.comments()) {
+            if let Value::Object(ref mut map) = schema {
+                map.insert("description".to_string(), json!(desc));
+            }
+        }
+        schemas.insert(error.name().to_string(), schema);
+    }
+
+    let mut doc = json!({
+        "openapi": "3.1.0",
+        "info": {
+            "title": iface.name(),
+            "version": "0.0.0",
+        },
+        "paths": paths,
+    });
+
+    if let Some(desc) = comments_to_string(iface.comments()) {
+        if let Value::Object(ref mut info_obj) = doc["info"] {
+            info_obj.insert("description".to_string(), json!(desc));
+        }
+    }
+
+    if !schemas.is_empty() {
+        if let Value::Object(ref mut doc_obj) = doc {
+            doc_obj.insert("components".to_string(), json!({ "schemas": schemas }));
+        }
+    }
+
+    doc
+}

src/bin/varlink-httpd/tests.rs

@@ -518,6 +518,31 @@ async fn test_varlink_unix_sockets_in_skips_dangling_symlinks() {
     assert_eq!(sockets, vec!["io.systemd.Hostname"]);
 }
 
+#[test_with::path(/run/systemd/io.systemd.Hostname)]
+#[tokio::test]
+async fn test_integration_real_systemd_openapi_get() {
+    let (server, local_addr) = run_test_server("/run/systemd").await;
+    defer! {
+        server.abort();
+    };
+
+    let client = Client::new();
+    let res = client
+        .get(format!(
+            "http://{}/openapi/io.systemd.Hostname/io.systemd.Hostname",
+            local_addr,
+        ))
+        .send()
+        .await
+        .expect("failed to get openapi from test server");
+    assert_eq!(res.status(), 200);
+    let body: Value = res.json().await.expect("openapi body invalid");
+    assert_eq!(body["openapi"], "3.1.0");
+    assert!(body.get("paths").is_some(), "missing 'paths' key");
+    assert!(body.get("info").is_some(), "missing 'info' key");
+    assert_eq!(body["info"]["title"], "io.systemd.Hostname");
+}
+
 #[test_with::path(/run/systemd/io.systemd.Hostname)]
 #[tokio::test]
 async fn test_ws_hostname_describe() {
@@ -1815,3 +1840,138 @@ mod sshauth_tests {
         assert_eq!(body["Hostname"], expected_hostname);
     }
 } // mod sshauth_tests
+
+// A varlink IDL that exercises all type features: methods with typed
+// input/output, a struct typedef, an enum typedef, an error with
+// parameters, arrays, dicts, optionals, and doc strings.
+const TEST_IDL: &str = "\
+# A test interface
+interface com.example.test
+
+# Status values
+type Status (enabled: bool, tag: ?string)
+
+# Priority levels
+type Priority (low, medium, high)
+
+# Item not found
+error ItemNotFound (id: int)
+
+# Get an item by id
+method GetItem(
+  # The item identifier
+  id: int,
+  options: ?object
+) -> (
+  name: string,
+  score: float,
+  status: Status,
+  tags: []string,
+  metadata: [string]int,
+  mode: (on, off, auto)
+)
+";
+
+#[test]
+fn test_idl_to_openapi() {
+    let iface: zlink::idl::Interface = TEST_IDL.try_into().expect("failed to parse test IDL");
+    let doc = openapi::idl_to_openapi("com.example.test", &iface);
+
+    // top-level structure
+    assert_eq!(doc["openapi"], "3.1.0");
+    assert_eq!(doc["info"]["title"], "com.example.test");
+    assert_eq!(doc["info"]["version"], "0.0.0");
+    assert_eq!(doc["info"]["description"], "A test interface");
+
+    // paths - one POST for GetItem
+    let path = &doc["paths"]["/call/com.example.test/com.example.test.GetItem"];
+    assert!(path.is_object(), "missing path for GetItem");
+    let post = &path["post"];
+    assert_eq!(post["operationId"], "GetItem");
+    assert_eq!(post["description"], "Get an item by id");
+
+    // request body schema
+    let req_schema = &post["requestBody"]["content"]["application/json"]["schema"];
+    assert_eq!(req_schema["type"], "object");
+    assert_eq!(req_schema["properties"]["id"]["type"], "integer");
+    assert_eq!(req_schema["properties"]["id"]["format"], "int64");
+    assert_eq!(
+        req_schema["properties"]["id"]["description"],
+        "The item identifier"
+    );
+    assert_eq!(req_schema["properties"]["options"]["type"], "object");
+    // "id" is required, "options" is optional
+    let required: Vec<&str> = req_schema["required"]
+        .as_array()
+        .unwrap()
+        .iter()
+        .map(|v| v.as_str().unwrap())
+        .collect();
+    assert!(required.contains(&"id"));
+    assert!(!required.contains(&"options"));
+
+    // response schema
+    let resp_content = &post["responses"]["200"]["content"];
+    assert!(
+        resp_content["application/json-seq"]["description"]
+            .as_str()
+            .unwrap()
+            .contains("RFC 7464"),
+        "json-seq response should document RFC 7464 streaming"
+    );
+    assert_eq!(
+        resp_content["application/json-seq"]["schema"], resp_content["application/json"]["schema"],
+        "json-seq and json schemas should match"
+    );
+    let resp_schema = &resp_content["application/json"]["schema"];
+    assert_eq!(resp_schema["properties"]["name"]["type"], "string");
+    assert_eq!(resp_schema["properties"]["score"]["type"], "number");
+    assert_eq!(
+        resp_schema["properties"]["status"]["$ref"],
+        "#/components/schemas/Status"
+    );
+    // array type
+    assert_eq!(resp_schema["properties"]["tags"]["type"], "array");
+    assert_eq!(resp_schema["properties"]["tags"]["items"]["type"], "string");
+    // dict type
+    assert_eq!(resp_schema["properties"]["metadata"]["type"], "object");
+    assert_eq!(
+        resp_schema["properties"]["metadata"]["additionalProperties"]["type"],
+        "integer"
+    );
+    // inline enum type
+    assert_eq!(resp_schema["properties"]["mode"]["type"], "string");
+    assert_eq!(
+        resp_schema["properties"]["mode"]["enum"],
+        json!(["on", "off", "auto"])
+    );
+
+    // components/schemas - struct typedef
+    let status_schema = &doc["components"]["schemas"]["Status"];
+    assert_eq!(status_schema["type"], "object");
+    assert_eq!(status_schema["description"], "Status values");
+    assert_eq!(status_schema["properties"]["enabled"]["type"], "boolean");
+    assert_eq!(status_schema["properties"]["tag"]["type"], "string");
+    // "enabled" required, "tag" optional
+    let status_required: Vec<&str> = status_schema["required"]
+        .as_array()
+        .unwrap()
+        .iter()
+        .map(|v| v.as_str().unwrap())
+        .collect();
+    assert!(status_required.contains(&"enabled"));
+    assert!(!status_required.contains(&"tag"));
+
+    // components/schemas - enum typedef
+    let priority_schema = &doc["components"]["schemas"]["Priority"];
+    assert_eq!(priority_schema["type"], "string");
+    assert_eq!(priority_schema["description"], "Priority levels");
+    assert_eq!(priority_schema["enum"], json!(["low", "medium", "high"]));
+
+    // components/schemas - error
+    let error_schema = &doc["components"]["schemas"]["ItemNotFound"];
+    assert_eq!(error_schema["type"], "object");
+    assert_eq!(error_schema["description"], "Item not found");
+    assert_eq!(error_schema["properties"]["id"]["type"], "integer");
+    assert_eq!(error_schema["properties"]["id"]["format"], "int64");
+}