doc(msg-bus): add asyncapi doc generator
you can test generated doc resources/gen/asyncapi.json into https://studio.asyncapi.com/
This commit is contained in:
Edouard Vanbelle
@@ -0,0 +1,356 @@
|
|||||||
|
//! AsyncAPI 3.0 spec generator for the realtime message bus.
|
||||||
|
//!
|
||||||
|
//! Mirrors `generate-openapi.rs`: constructs the spec from the same
|
||||||
|
//! Rust enums the server uses (`Topic`, `RealtimeEvent`, JSON-RPC
|
||||||
|
//! error codes) and writes `resources/gen/asyncapi.json`.
|
||||||
|
//!
|
||||||
|
//! This is the first-PR MVP surface — the two topics and two events
|
||||||
|
//! that Phase A ships (see `docs/plan/message-bus.md § First PR`).
|
||||||
|
//! Adding a topic/event later is a match arm + a new schema block in
|
||||||
|
//! this file; the CI dirty-tree check (same as OpenAPI's) prevents
|
||||||
|
//! spec/code drift.
|
||||||
|
//!
|
||||||
|
//! Format: JSON, not YAML — matches `openapi.json`. AsyncAPI's own
|
||||||
|
//! tooling reads either; JSON also keeps us dep-free.
|
||||||
|
//!
|
||||||
|
//! Invocation:
|
||||||
|
//!
|
||||||
|
//! ```bash
|
||||||
|
//! cargo run --bin generate-asyncapi
|
||||||
|
//! # or
|
||||||
|
//! just asyncapi
|
||||||
|
//! ```
|
||||||
|
|
||||||
|
use std::fs;
|
||||||
|
use std::path::PathBuf;
|
||||||
|
|
||||||
|
use oxicloud::application::ports::realtime_ports::error_code;
|
||||||
|
use serde_json::{Value, json};
|
||||||
|
|
||||||
|
fn main() {
|
||||||
|
let doc = build_asyncapi();
|
||||||
|
let json =
|
||||||
|
serde_json::to_string_pretty(&doc).expect("Failed to serialize AsyncAPI spec to JSON");
|
||||||
|
|
||||||
|
let manifest_dir = PathBuf::from(env!("CARGO_MANIFEST_DIR"));
|
||||||
|
let resources_gen_dir = manifest_dir.join("resources").join("gen");
|
||||||
|
fs::create_dir_all(&resources_gen_dir).expect("Failed to create resources/gen directory");
|
||||||
|
let output_path = resources_gen_dir.join("asyncapi.json");
|
||||||
|
fs::write(&output_path, json).expect("Failed to write AsyncAPI spec to file");
|
||||||
|
|
||||||
|
println!(
|
||||||
|
"AsyncAPI spec generated successfully at: {}",
|
||||||
|
output_path.display()
|
||||||
|
);
|
||||||
|
}
|
||||||
|
|
||||||
|
fn build_asyncapi() -> Value {
|
||||||
|
json!({
|
||||||
|
"asyncapi": "3.0.0",
|
||||||
|
"info": {
|
||||||
|
"title": "OxiCloud realtime message bus",
|
||||||
|
"version": env!("CARGO_PKG_VERSION"),
|
||||||
|
"description": r#"
|
||||||
|
JSON-RPC 2.0 over WebSocket for control + events, Yjs sync protocol for
|
||||||
|
CRDT binary frames. The wire is described here for the first-PR MVP
|
||||||
|
surface (folder-live updates); Phase B (comments, presence) and
|
||||||
|
Phase C (sync-client push, album live) extend the same channels — see
|
||||||
|
`docs/plan/message-bus.md`.
|
||||||
|
"#.trim(),
|
||||||
|
"license": { "name": "AGPL-3.0-or-later" },
|
||||||
|
},
|
||||||
|
"servers": {
|
||||||
|
"default": {
|
||||||
|
"host": "{host}",
|
||||||
|
"pathname": "/api/rt/ws",
|
||||||
|
"protocol": "wss",
|
||||||
|
"description": "OxiCloud realtime bus WebSocket endpoint",
|
||||||
|
"variables": {
|
||||||
|
"host": {
|
||||||
|
"description": "Server host — replace with the deployment domain",
|
||||||
|
"default": "cloud.example.com",
|
||||||
|
},
|
||||||
|
},
|
||||||
|
"protocolVersion": "13",
|
||||||
|
// Subprotocol advertised in the WS handshake. Handler
|
||||||
|
// accepts `oxi.rt.v1` and the optional bearer element
|
||||||
|
// `authorization.bearer.<jwt>` alongside it.
|
||||||
|
"bindings": {
|
||||||
|
"ws": { "subProtocol": "oxi.rt.v1" }
|
||||||
|
},
|
||||||
|
}
|
||||||
|
},
|
||||||
|
"channels": channels(),
|
||||||
|
"operations": operations(),
|
||||||
|
"components": components(),
|
||||||
|
})
|
||||||
|
}
|
||||||
|
|
||||||
|
fn channels() -> Value {
|
||||||
|
json!({
|
||||||
|
"Folder": {
|
||||||
|
"address": "folder:{folderId}",
|
||||||
|
"description": "A folder's mutation stream — file/subfolder created events fire here. AuthZ: caller must hold `Read` on the folder.",
|
||||||
|
"parameters": {
|
||||||
|
"folderId": { "description": "Folder UUID" }
|
||||||
|
},
|
||||||
|
"messages": {
|
||||||
|
"SubscribeRequest": { "$ref": "#/components/messages/RtSubscribeRequest" },
|
||||||
|
"UnsubscribeRequest": { "$ref": "#/components/messages/RtUnsubscribeRequest" },
|
||||||
|
"PingRequest": { "$ref": "#/components/messages/RtPingRequest" },
|
||||||
|
"SubscribedResponse": { "$ref": "#/components/messages/RtSubscribedResponse" },
|
||||||
|
"ErrorResponse": { "$ref": "#/components/messages/RtErrorResponse" },
|
||||||
|
"FolderEvent": { "$ref": "#/components/messages/RtFolderEventNotification" },
|
||||||
|
}
|
||||||
|
},
|
||||||
|
"UserAuthz": {
|
||||||
|
"address": "user:{userId}:authz",
|
||||||
|
"description": "A user's private AuthZ-change channel. Identity-scoped: caller_id must equal userId (no admin bypass).",
|
||||||
|
"parameters": {
|
||||||
|
"userId": { "description": "User UUID — must match the authenticated caller" }
|
||||||
|
},
|
||||||
|
"messages": {
|
||||||
|
"SubscribeRequest": { "$ref": "#/components/messages/RtSubscribeRequest" },
|
||||||
|
"UnsubscribeRequest": { "$ref": "#/components/messages/RtUnsubscribeRequest" },
|
||||||
|
}
|
||||||
|
}
|
||||||
|
})
|
||||||
|
}
|
||||||
|
|
||||||
|
fn operations() -> Value {
|
||||||
|
json!({
|
||||||
|
"subscribeFolder": {
|
||||||
|
"action": "send",
|
||||||
|
"channel": { "$ref": "#/channels/Folder" },
|
||||||
|
"summary": "Subscribe to a folder's mutation stream",
|
||||||
|
"messages": [
|
||||||
|
{ "$ref": "#/channels/Folder/messages/SubscribeRequest" }
|
||||||
|
],
|
||||||
|
"reply": {
|
||||||
|
"channel": { "$ref": "#/channels/Folder" },
|
||||||
|
"messages": [
|
||||||
|
{ "$ref": "#/channels/Folder/messages/SubscribedResponse" },
|
||||||
|
{ "$ref": "#/channels/Folder/messages/ErrorResponse" },
|
||||||
|
]
|
||||||
|
}
|
||||||
|
},
|
||||||
|
"unsubscribeFolder": {
|
||||||
|
"action": "send",
|
||||||
|
"channel": { "$ref": "#/channels/Folder" },
|
||||||
|
"summary": "Unsubscribe from a folder's mutation stream",
|
||||||
|
"messages": [
|
||||||
|
{ "$ref": "#/channels/Folder/messages/UnsubscribeRequest" }
|
||||||
|
]
|
||||||
|
},
|
||||||
|
"receiveFolderEvent": {
|
||||||
|
"action": "receive",
|
||||||
|
"channel": { "$ref": "#/channels/Folder" },
|
||||||
|
"summary": "Server-pushed `rt.event` notification for a folder mutation",
|
||||||
|
"messages": [
|
||||||
|
{ "$ref": "#/channels/Folder/messages/FolderEvent" }
|
||||||
|
]
|
||||||
|
}
|
||||||
|
})
|
||||||
|
}
|
||||||
|
|
||||||
|
fn components() -> Value {
|
||||||
|
json!({
|
||||||
|
"messages": {
|
||||||
|
// ── Requests ────────────────────────────────────────────
|
||||||
|
"RtSubscribeRequest": {
|
||||||
|
"name": "rt.subscribe",
|
||||||
|
"title": "Subscribe to a topic",
|
||||||
|
"contentType": "application/json",
|
||||||
|
"payload": { "$ref": "#/components/schemas/RtSubscribeRequestBody" },
|
||||||
|
},
|
||||||
|
"RtUnsubscribeRequest": {
|
||||||
|
"name": "rt.unsubscribe",
|
||||||
|
"title": "Unsubscribe from a topic",
|
||||||
|
"contentType": "application/json",
|
||||||
|
"payload": { "$ref": "#/components/schemas/RtUnsubscribeRequestBody" },
|
||||||
|
},
|
||||||
|
"RtPingRequest": {
|
||||||
|
"name": "rt.ping",
|
||||||
|
"title": "Keepalive ping",
|
||||||
|
"contentType": "application/json",
|
||||||
|
"payload": { "$ref": "#/components/schemas/RtPingRequestBody" },
|
||||||
|
},
|
||||||
|
// ── Responses ───────────────────────────────────────────
|
||||||
|
"RtSubscribedResponse": {
|
||||||
|
"name": "rt.subscribed",
|
||||||
|
"title": "Subscribe / unsubscribe ack",
|
||||||
|
"contentType": "application/json",
|
||||||
|
"payload": { "$ref": "#/components/schemas/RtSuccessResponseBody" },
|
||||||
|
},
|
||||||
|
"RtErrorResponse": {
|
||||||
|
"name": "rt.error",
|
||||||
|
"title": "JSON-RPC error object",
|
||||||
|
"contentType": "application/json",
|
||||||
|
"payload": { "$ref": "#/components/schemas/RtErrorResponseBody" },
|
||||||
|
},
|
||||||
|
// ── Notifications (server → client) ─────────────────────
|
||||||
|
"RtFolderEventNotification": {
|
||||||
|
"name": "rt.event",
|
||||||
|
"title": "Folder mutation event",
|
||||||
|
"contentType": "application/json",
|
||||||
|
"payload": { "$ref": "#/components/schemas/RtFolderEventBody" },
|
||||||
|
}
|
||||||
|
},
|
||||||
|
"schemas": {
|
||||||
|
"RtSubscribeRequestBody": rpc_request_schema("rt.subscribe", topic_params_schema()),
|
||||||
|
"RtUnsubscribeRequestBody": rpc_request_schema("rt.unsubscribe", topic_params_schema()),
|
||||||
|
"RtPingRequestBody": rpc_request_schema("rt.ping", json!({ "type": "null" })),
|
||||||
|
"RtSuccessResponseBody": rpc_success_response_schema(),
|
||||||
|
"RtErrorResponseBody": rpc_error_response_schema(),
|
||||||
|
"RtFolderEventBody": folder_event_notification_schema(),
|
||||||
|
"FileCreatedData": file_created_schema(),
|
||||||
|
"FolderCreatedData": folder_created_schema(),
|
||||||
|
}
|
||||||
|
})
|
||||||
|
}
|
||||||
|
|
||||||
|
// ─── Schema builders ────────────────────────────────────────────────────────
|
||||||
|
|
||||||
|
fn rpc_request_schema(method: &str, params_schema: Value) -> Value {
|
||||||
|
json!({
|
||||||
|
"type": "object",
|
||||||
|
"required": ["jsonrpc", "id", "method"],
|
||||||
|
"properties": {
|
||||||
|
"jsonrpc": { "type": "string", "const": "2.0" },
|
||||||
|
"id": { "type": ["integer", "string", "null"] },
|
||||||
|
"method": { "type": "string", "const": method },
|
||||||
|
"params": params_schema,
|
||||||
|
}
|
||||||
|
})
|
||||||
|
}
|
||||||
|
|
||||||
|
fn topic_params_schema() -> Value {
|
||||||
|
json!({
|
||||||
|
"type": "object",
|
||||||
|
"required": ["topic"],
|
||||||
|
"properties": {
|
||||||
|
"topic": {
|
||||||
|
"type": "string",
|
||||||
|
"description": "Wire form: `folder:<uuid>` or `user:<uuid>:authz`",
|
||||||
|
"examples": ["folder:00000000-0000-0000-0000-000000000000"],
|
||||||
|
}
|
||||||
|
}
|
||||||
|
})
|
||||||
|
}
|
||||||
|
|
||||||
|
fn rpc_success_response_schema() -> Value {
|
||||||
|
json!({
|
||||||
|
"type": "object",
|
||||||
|
"required": ["jsonrpc", "id", "result"],
|
||||||
|
"properties": {
|
||||||
|
"jsonrpc": { "type": "string", "const": "2.0" },
|
||||||
|
"id": { "type": ["integer", "string", "null"] },
|
||||||
|
"result": { "type": "object" },
|
||||||
|
}
|
||||||
|
})
|
||||||
|
}
|
||||||
|
|
||||||
|
fn rpc_error_response_schema() -> Value {
|
||||||
|
// The `code`/`message` catalog is the stable public vocabulary —
|
||||||
|
// any change here IS a wire break. Every entry mirrors
|
||||||
|
// `application/ports/realtime_ports.rs::error_code`.
|
||||||
|
json!({
|
||||||
|
"type": "object",
|
||||||
|
"required": ["jsonrpc", "id", "error"],
|
||||||
|
"properties": {
|
||||||
|
"jsonrpc": { "type": "string", "const": "2.0" },
|
||||||
|
"id": { "type": ["integer", "string", "null"] },
|
||||||
|
"error": {
|
||||||
|
"type": "object",
|
||||||
|
"required": ["code", "message"],
|
||||||
|
"properties": {
|
||||||
|
"code": {
|
||||||
|
"type": "integer",
|
||||||
|
"enum": [
|
||||||
|
error_code::NO_READ,
|
||||||
|
error_code::NO_SHARE,
|
||||||
|
error_code::NO_COMMENT,
|
||||||
|
error_code::TOPIC_FORBIDDEN,
|
||||||
|
error_code::SUB_LIMIT,
|
||||||
|
error_code::RATE_LIMITED,
|
||||||
|
error_code::NO_EDIT,
|
||||||
|
error_code::INTERNAL_ERROR,
|
||||||
|
error_code::INVALID_REQUEST,
|
||||||
|
error_code::METHOD_NOT_FOUND,
|
||||||
|
error_code::INVALID_PARAMS,
|
||||||
|
],
|
||||||
|
},
|
||||||
|
"message": {
|
||||||
|
"type": "string",
|
||||||
|
"description": "Stable wire vocabulary; matches the `code`.",
|
||||||
|
"enum": [
|
||||||
|
"no_read", "no_share", "no_comment", "topic_forbidden",
|
||||||
|
"sub_limit", "rate_limited", "no_edit",
|
||||||
|
"internal_error", "invalid_request",
|
||||||
|
"method_not_found", "invalid_params",
|
||||||
|
],
|
||||||
|
},
|
||||||
|
"data": {
|
||||||
|
"type": "object",
|
||||||
|
"description": "Optional caller-facing context (e.g. offending topic).",
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
})
|
||||||
|
}
|
||||||
|
|
||||||
|
fn folder_event_notification_schema() -> Value {
|
||||||
|
json!({
|
||||||
|
"type": "object",
|
||||||
|
"description": "JSON-RPC notification (no `id`). `method = \"rt.event\"`.",
|
||||||
|
"required": ["jsonrpc", "method", "params"],
|
||||||
|
"properties": {
|
||||||
|
"jsonrpc": { "type": "string", "const": "2.0" },
|
||||||
|
"method": { "type": "string", "const": "rt.event" },
|
||||||
|
"params": {
|
||||||
|
"type": "object",
|
||||||
|
"required": ["topic", "event", "data"],
|
||||||
|
"properties": {
|
||||||
|
"topic": { "type": "string" },
|
||||||
|
"event": {
|
||||||
|
"type": "string",
|
||||||
|
"enum": ["file_created", "folder_created"],
|
||||||
|
},
|
||||||
|
"data": {
|
||||||
|
"oneOf": [
|
||||||
|
{ "$ref": "#/components/schemas/FileCreatedData" },
|
||||||
|
{ "$ref": "#/components/schemas/FolderCreatedData" },
|
||||||
|
]
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
})
|
||||||
|
}
|
||||||
|
|
||||||
|
fn file_created_schema() -> Value {
|
||||||
|
json!({
|
||||||
|
"type": "object",
|
||||||
|
"required": ["file_id", "name", "parent_id", "actor"],
|
||||||
|
"properties": {
|
||||||
|
"file_id": { "type": "string", "format": "uuid" },
|
||||||
|
"name": { "type": "string" },
|
||||||
|
"parent_id": { "type": "string", "format": "uuid" },
|
||||||
|
"actor": { "type": "string", "format": "uuid" },
|
||||||
|
}
|
||||||
|
})
|
||||||
|
}
|
||||||
|
|
||||||
|
fn folder_created_schema() -> Value {
|
||||||
|
json!({
|
||||||
|
"type": "object",
|
||||||
|
"required": ["folder_id", "name", "parent_id", "actor"],
|
||||||
|
"properties": {
|
||||||
|
"folder_id": { "type": "string", "format": "uuid" },
|
||||||
|
"name": { "type": "string" },
|
||||||
|
"parent_id": { "type": "string", "format": "uuid" },
|
||||||
|
"actor": { "type": "string", "format": "uuid" },
|
||||||
|
}
|
||||||
|
})
|
||||||
|
}
|
||||||
Reference in New Issue
Block a user