Module api 

Unified API Types for Remote Compilation Helper

This module provides a consistent API interface for both CLI and daemon, enabling agents and tools to parse responses uniformly.

Design Principles

1. Unified Error Codes: All errors use the RCH-Exxx format from crate::ErrorCode.
2. Consistent Envelope: All responses wrapped in ApiResponse<T>.
3. Machine-Readable: Designed for programmatic parsing by AI agents.
4. Backward Compatible: Supports legacy error codes via mapping.

Example

use rch_common::api::{ApiResponse, ApiError};
use rch_common::ErrorCode;

// Success response
let response = ApiResponse::ok("workers list", vec!["worker1", "worker2"]);
println!("{}", serde_json::to_string_pretty(&response).unwrap());

// Error response
let response: ApiResponse<()> = ApiResponse::err(
    "workers probe",
    ApiError::from_code(ErrorCode::SshConnectionFailed)
        .with_message("Connection refused to worker-1")
        .with_context("worker_id", "worker-1"),
);
println!("{}", serde_json::to_string_pretty(&response).unwrap());

JSON Output Format

Success:

{
  "api_version": "1.0",
  "timestamp": 1705936800,
  "success": true,
  "data": { ... }
}

Error:

{
  "api_version": "1.0",
  "timestamp": 1705936800,
  "success": false,
  "error": {
    "code": "RCH-E100",
    "category": "network",
    "message": "SSH connection to worker failed",
    "details": "Connection refused to worker-1",
    "remediation": ["Check worker is running", "Verify SSH key"],
    "context": { "worker_id": "worker-1" }
  }
}

Re-exports

pub use schema::ErrorCatalog;

pub use schema::ErrorCategoryEntry;

pub use schema::ErrorCodeEntry;

pub use schema::SchemaExportResult;

pub use schema::export_schemas;

pub use schema::generate_api_error_schema;

pub use schema::generate_api_response_schema;

pub use schema::generate_error_catalog;

Modules

schema

JSON Schema Generation for RCH API Types

Structs

ApiError

Unified API error structure.

ApiResponse

Unified API response envelope.

ErrorContext

Context information for an API error.

Enums

LegacyErrorCode

Legacy error codes used in older CLI versions.

Constants

API_VERSION

Current API version.