RUSTLE/UCXL_CODES_README.md

UCXL Standard Response and Error Codes Library

This repository contains standardized UCXL error and response codes libraries for Rust, Go, and Python to ensure consistent cross-service communication and client handling across all UCXL implementations.

Overview

The UCXL codes standard provides:

• Unified error signaling across UCXL services (UCXI, Browser, BZZZ, etc.)
• Machine-readable error codes with structured payloads
• Client guidance for retry logic and error handling
• Cross-language compatibility with identical APIs

Standard Format

Error Codes

Format: UCXL-<HTTP-class>-<SHORT_NAME>

Examples:

• UCXL-400-INVALID_ADDRESS - Malformed UCXL URI
• UCXL-404-NOT_FOUND - Resource not found
• UCXL-503-SERVICE_UNAVAILABLE - Service temporarily unavailable

Response Codes

Format: UCXL-<HTTP-class>-<SHORT_NAME>

Examples:

• UCXL-200-OK - Successful request
• UCXL-201-CREATED - Resource created
• UCXL-202-ACCEPTED - Async operation accepted

Error Payload Schema

{
  "error": {
    "code": "UCXL-400-INVALID_ADDRESS",
    "message": "Invalid UCXL address format",
    "details": {
      "field": "address",
      "provided": "ucxl://invalid/address",
      "expected_format": "ucxl://<agent>:<role>@<project>:<task>[/<temporal>/<path>]"
    },
    "source": "ucxl-browser/v1",
    "path": "/resolve",
    "request_id": "req-12345",
    "timestamp": "2025-08-09T16:22:20Z",
    "cause": "parse_error"
  }
}

Success Payload Schema

{
  "response": {
    "code": "UCXL-200-OK",
    "message": "Request completed successfully",
    "data": {
      "items": [{"id": "item-1", "name": "Alpha"}]
    },
    "details": {
      "count": 1
    },
    "request_id": "req-12345",
    "timestamp": "2025-08-09T16:22:20Z"
  }
}

Language Implementations

Rust (ucxl_codes.rs)

use ucxl_core::*;

// Create error response
let error = UCXLErrorBuilder::new(UCXLErrorCode::InvalidAddress)
    .field("address", "ucxl://invalid".into())
    .expected_format("ucxl://<agent>:<role>@<project>:<task>")
    .source("my-service")
    .path("/resolve")
    .build();

// Create success response
let success = UCXLResponseBuilder::new(UCXLResponseCode::Ok)
    .data(serde_json::json!({"result": "success"}))
    .build();

// Check error properties
if error.error.code.should_retry() {
    // Implement retry logic
}

Go (ucxl_codes.go)

package main

import (
    "fmt"
    "your-module/ucxl_codes"
)

func main() {
    // Create error response
    error := ucxl_codes.NewErrorBuilder(ucxl_codes.ErrorInvalidAddress).
        Field("address", "ucxl://invalid").
        ExpectedFormat("ucxl://<agent>:<role>@<project>:<task>").
        Source("my-service").
        Path("/resolve").
        Build()

    // Create success response
    success := ucxl_codes.NewResponseBuilder(ucxl_codes.ResponseOK).
        Data(map[string]interface{}{"result": "success"}).
        Build()

    // Check error properties
    if error.Error.Code.ShouldRetry() {
        // Implement retry logic
    }
}

Python (ucxl_codes.py)

from ucxl_codes import UCXLErrorBuilder, UCXLErrorCode, UCXLResponseBuilder, UCXLResponseCode

# Create error response
error = UCXLErrorBuilder(UCXLErrorCode.INVALID_ADDRESS) \
    .field("address", "ucxl://invalid") \
    .expected_format("ucxl://<agent>:<role>@<project>:<task>") \
    .source("my-service") \
    .path("/resolve") \
    .build()

# Create success response
success = UCXLResponseBuilder(UCXLResponseCode.OK) \
    .data({"result": "success"}) \
    .build()

# Check error properties
if error.error.code.should_retry():
    # Implement retry logic
    pass

Complete Error Code Reference

Code	HTTP	Description	Retry?
UCXL-400-INVALID_ADDRESS	400	Malformed UCXL URI	No
UCXL-400-MISSING_FIELD	400	Required field missing	No
UCXL-400-INVALID_FORMAT	400	Input format invalid	No
UCXL-401-UNAUTHORIZED	401	Authentication required	No
UCXL-403-FORBIDDEN	403	Insufficient permissions	No
UCXL-404-NOT_FOUND	404	Resource not found	No
UCXL-409-CONFLICT	409	State conflict	No
UCXL-422-UNPROCESSABLE_ENTITY	422	Business rule violation	No
UCXL-429-RATE_LIMIT	429	Rate limiting active	Yes
UCXL-500-INTERNAL_ERROR	500	Unhandled server error	Yes
UCXL-503-SERVICE_UNAVAILABLE	503	Service down/maintenance	Yes
UCXL-504-GATEWAY_TIMEOUT	504	Downstream timeout	Yes

Complete Response Code Reference

Code	HTTP	Description	Use Case
UCXL-200-OK	200	Successful request	Standard operations
UCXL-201-CREATED	201	Resource created	POST/PUT create
UCXL-202-ACCEPTED	202	Async operation accepted	Long-running tasks
UCXL-204-NO_CONTENT	204	Success, no content	DELETE operations
UCXL-206-PARTIAL_CONTENT	206	Partial results	Paginated responses
UCXL-304-NOT_MODIFIED	304	Not changed since last fetch	Caching

Client Implementation Guidance

Retry Logic

fn should_retry_request(error_code: UCXLErrorCode, attempt: u32) -> bool {
    error_code.should_retry() && attempt < MAX_RETRIES
}

async fn execute_with_retry<T>(operation: impl Fn() -> Result<T, UCXLErrorCode>) -> Result<T, UCXLErrorCode> {
    let mut attempt = 0;
    loop {
        match operation() {
            Ok(result) => return Ok(result),
            Err(error) if should_retry_request(error, attempt) => {
                let backoff = Duration::from_millis(100 * 2_u64.pow(attempt));
                tokio::time::sleep(backoff).await;
                attempt += 1;
            },
            Err(error) => return Err(error),
        }
    }
}

Error Classification

fn classify_error(error: &UCXLErrorCode) -> ErrorCategory {
    if error.is_client_error() {
        ErrorCategory::ClientError // Fix input, don't retry
    } else if error.should_retry() {
        ErrorCategory::RetryableServerError // Retry with backoff
    } else {
        ErrorCategory::PermanentServerError // Don't retry
    }
}

Response Handling

fn handle_response(response: UCXLResponseCode) -> ActionRequired {
    if response.is_async() {
        ActionRequired::Poll // Poll for completion
    } else if response.is_partial() {
        ActionRequired::Paginate // Fetch remaining data
    } else {
        ActionRequired::None // Complete response
    }
}

Integration with BZZZ

The BZZZ Gateway has been updated to use standardized UCXL codes:

// BZZZ now returns standardized errors
let error_response = create_error_response(
    UCXLErrorCode::ServiceUnavailable,
    "/bzzz/store",
    Some(&request_id)
);

// DHT operations use standard codes
let not_found = create_envelope_error(
    UCXLErrorCode::NotFound,
    &envelope_id,
    "/dht/retrieve"
);

Testing

Each implementation includes comprehensive tests:

Rust:

cargo test --lib ucxl_codes

Go:

go test ./ucxl_codes

Python:

python -m pytest ucxl_codes.py -v
# Or run inline tests:
python ucxl_codes.py

Governance and Versioning

• Version: 1.0 (following UCXL-ERROR-CODES.md specification)
• Registry: Machine-readable definitions in error-codes.yaml (future)
• Deprecation Policy: New codes added in minor versions, deprecated codes marked but maintained for compatibility
• Updates: Changes published with changelog and migration guidance

Future Enhancements

1. Machine-readable registry (error-codes.yaml) for code generation
2. OpenAPI integration for automatic client generation
3. Observability integration with tracing and metrics
4. Additional language support (JavaScript/TypeScript, C#, etc.)

Contributing

When adding new error codes:

1. Follow the UCXL-<HTTP-class>-<SHORT_NAME> format
2. Add to all three language implementations
3. Update this documentation
4. Include appropriate tests
5. Ensure retry logic is correctly classified

License

This UCXL codes library follows the same license as the UCXL project.