rxon 1.0.0__py3-none-any.whl

rxon/__init__.py

@@ -0,0 +1,202 @@
+# Copyright (c) 2025-2026 Dmitrii Gagarin aka madgagarin
+# This Source Code Form is subject to the terms of the Mozilla Public
+# License, v. 2.0. If a copy of the MPL was not distributed with this
+# file, You can obtain one at http://mozilla.org/MPL/2.0/.
+
+from rxon.blob import RXON_BLOB_SCHEME, calculate_config_hash, parse_uri
+from rxon.constants import (
+    AUTH_HEADER_CLIENT,
+    AUTH_HEADER_WORKER,
+    COMMAND_CANCEL_TASK,
+    ENDPOINT_TASK_NEXT,
+    ENDPOINT_TASK_RESULT,
+    ENDPOINT_WORKER_HEARTBEAT,
+    ENDPOINT_WORKER_REGISTER,
+    ERROR_CODE_CONTRACT_VIOLATION,
+    ERROR_CODE_DEPENDENCY,
+    ERROR_CODE_DEPENDENCY_MISSING,
+    ERROR_CODE_INTEGRITY_MISMATCH,
+    ERROR_CODE_INTERNAL,
+    ERROR_CODE_INVALID_INPUT,
+    ERROR_CODE_LIMIT_EXCEEDED,
+    ERROR_CODE_PERMANENT,
+    ERROR_CODE_RESOURCE_EXHAUSTED,
+    ERROR_CODE_SECURITY,
+    ERROR_CODE_TIMEOUT,
+    ERROR_CODE_TRANSIENT,
+    EVENT_TYPE_PROGRESS,
+    HB_RESP_CANCEL_TASKS,
+    HB_RESP_REQUIRE_FULL_SYNC,
+    JOB_STATUS_CANCELLED,
+    JOB_STATUS_ERROR,
+    JOB_STATUS_FAILED,
+    JOB_STATUS_FINISHED,
+    JOB_STATUS_PENDING,
+    JOB_STATUS_QUARANTINED,
+    JOB_STATUS_RUNNING,
+    JOB_STATUS_WAITING_FOR_HUMAN,
+    JOB_STATUS_WAITING_FOR_PARALLEL,
+    JOB_STATUS_WAITING_FOR_WORKER,
+    PROTOCOL_VERSION,
+    STS_TOKEN_ENDPOINT,
+    TASK_STATUS_CANCELLED,
+    TASK_STATUS_FAILURE,
+    TASK_STATUS_SUCCESS,
+    WORKER_API_PREFIX,
+    WS_ENDPOINT,
+)
+from rxon.exceptions import (
+    IntegrityError,
+    ParamValidationError,
+    RxonAuthError,
+    RxonError,
+    RxonNetworkError,
+    RxonProtocolError,
+    S3ConfigMismatchError,
+)
+from rxon.models import (
+    DeviceUsage,
+    ExecutionReceipt,
+    FileMetadata,
+    HardwareDevice,
+    Heartbeat,
+    InstalledArtifact,
+    Resources,
+    ResourcesUsage,
+    SecurityContext,
+    SkillInfo,
+    TaskError,
+    TaskPayload,
+    TaskResult,
+    TokenResponse,
+    WorkerCapabilities,
+    WorkerCommand,
+    WorkerEventPayload,
+    WorkerRegistration,
+)
+from rxon.schema import (
+    Header,
+    extract_input_schema_from_func,
+    extract_json_schema,
+    extract_output_schema_from_func,
+    extract_schema_from_func,
+    extract_skill_contract,
+    get_compiled_validator,
+    validate_data,
+)
+from rxon.security import (
+    create_client_ssl_context,
+    create_server_ssl_context,
+    extract_cert_identity,
+    sign_bubbling_chain,
+    sign_bubbling_chain_hmac,
+    sign_payload_ed25519,
+    verify_bubbling_chain_hmac,
+    verify_bubbling_chain_signature,
+    verify_signature_ed25519,
+)
+from rxon.transports.base import Listener, Transport
+from rxon.transports.factory import create_transport
+from rxon.transports.http import HttpTransport
+from rxon.transports.http_server import HttpListener
+from rxon.utils import from_dict, loads, to_dict
+from rxon.validators import is_valid_identifier, validate_identifier
+
+__version__ = PROTOCOL_VERSION
+
+__all__ = [
+    "RXON_BLOB_SCHEME",
+    "calculate_config_hash",
+    "parse_uri",
+    "AUTH_HEADER_CLIENT",
+    "AUTH_HEADER_WORKER",
+    "COMMAND_CANCEL_TASK",
+    "ENDPOINT_TASK_NEXT",
+    "ENDPOINT_TASK_RESULT",
+    "ENDPOINT_WORKER_HEARTBEAT",
+    "ENDPOINT_WORKER_REGISTER",
+    "ERROR_CODE_CONTRACT_VIOLATION",
+    "ERROR_CODE_DEPENDENCY",
+    "ERROR_CODE_DEPENDENCY_MISSING",
+    "ERROR_CODE_INTEGRITY_MISMATCH",
+    "ERROR_CODE_INTERNAL",
+    "ERROR_CODE_INVALID_INPUT",
+    "ERROR_CODE_LIMIT_EXCEEDED",
+    "ERROR_CODE_PERMANENT",
+    "ERROR_CODE_RESOURCE_EXHAUSTED",
+    "ERROR_CODE_SECURITY",
+    "ERROR_CODE_TIMEOUT",
+    "ERROR_CODE_TRANSIENT",
+    "HB_RESP_REQUIRE_FULL_SYNC",
+    "HB_RESP_CANCEL_TASKS",
+    "JOB_STATUS_CANCELLED",
+    "JOB_STATUS_ERROR",
+    "JOB_STATUS_FAILED",
+    "JOB_STATUS_FINISHED",
+    "JOB_STATUS_PENDING",
+    "JOB_STATUS_QUARANTINED",
+    "JOB_STATUS_RUNNING",
+    "JOB_STATUS_WAITING_FOR_HUMAN",
+    "JOB_STATUS_WAITING_FOR_PARALLEL",
+    "JOB_STATUS_WAITING_FOR_WORKER",
+    "EVENT_TYPE_PROGRESS",
+    "PROTOCOL_VERSION",
+    "STS_TOKEN_ENDPOINT",
+    "TASK_STATUS_CANCELLED",
+    "TASK_STATUS_FAILURE",
+    "TASK_STATUS_SUCCESS",
+    "WORKER_API_PREFIX",
+    "WS_ENDPOINT",
+    "RxonError",
+    "RxonNetworkError",
+    "RxonAuthError",
+    "RxonProtocolError",
+    "IntegrityError",
+    "ParamValidationError",
+    "S3ConfigMismatchError",
+    "DeviceUsage",
+    "ExecutionReceipt",
+    "FileMetadata",
+    "HardwareDevice",
+    "Heartbeat",
+    "InstalledArtifact",
+    "Resources",
+    "ResourcesUsage",
+    "SecurityContext",
+    "SkillInfo",
+    "TaskError",
+    "TaskPayload",
+    "TaskResult",
+    "TokenResponse",
+    "WorkerCapabilities",
+    "WorkerCommand",
+    "WorkerEventPayload",
+    "WorkerRegistration",
+    "create_client_ssl_context",
+    "create_server_ssl_context",
+    "extract_cert_identity",
+    "sign_payload_ed25519",
+    "verify_signature_ed25519",
+    "sign_bubbling_chain",
+    "verify_bubbling_chain_signature",
+    "sign_bubbling_chain_hmac",
+    "verify_bubbling_chain_hmac",
+    "Listener",
+    "Transport",
+    "create_transport",
+    "HttpTransport",
+    "HttpListener",
+    "from_dict",
+    "to_dict",
+    "loads",
+    "is_valid_identifier",
+    "validate_identifier",
+    "extract_input_schema_from_func",
+    "extract_output_schema_from_func",
+    "extract_schema_from_func",
+    "extract_skill_contract",
+    "extract_json_schema",
+    "get_compiled_validator",
+    "validate_data",
+    "Header",
+]

rxon/blob.py

@@ -0,0 +1,92 @@
+# Copyright (c) 2025-2026 Dmitrii Gagarin aka madgagarin
+# This Source Code Form is subject to the terms of the Mozilla Public
+# License, v. 2.0. If a copy of the MPL was not distributed with this
+# file, You can obtain one at http://mozilla.org/MPL/2.0/.
+
+from abc import ABC, abstractmethod
+from hashlib import sha256
+from typing import Any
+from urllib.parse import urlparse
+
+from rxon.models import FileMetadata
+
+__all__ = [
+    "RXON_BLOB_SCHEME",
+    "calculate_config_hash",
+    "parse_uri",
+    "BlobProvider",
+]
+
+RXON_BLOB_SCHEME = "s3"
+
+
+class BlobProvider(ABC):
+    """
+    Abstract interface for Blob Storage providers (S3, GCS, Local).
+    RXON uses URIs like s3://bucket/key to reference heavy data.
+    """
+
+    @abstractmethod
+    async def upload(self, local_path: str, uri: str) -> str | FileMetadata:
+        """Uploads a local file to the storage and returns etag or FileMetadata."""
+        pass
+
+    @abstractmethod
+    async def download(self, uri: str, local_path: str) -> bool:
+        """Downloads a file from storage to local path."""
+        pass
+
+    @abstractmethod
+    async def get_metadata(self, uri: str) -> dict[str, Any] | None:
+        """Returns metadata (size, etag, content-type) for a URI."""
+        pass
+
+    @abstractmethod
+    async def delete(self, uri: str) -> bool:
+        """Deletes a single object from storage."""
+        pass
+
+    @abstractmethod
+    async def delete_dir(self, uri: str) -> bool:
+        """Deletes all objects under a specific URI prefix."""
+        pass
+
+
+def calculate_config_hash(endpoint: str | None, access_key: str | None, bucket: str | None) -> str | None:
+    """
+    Calculates a consistent hash of the Blob/S3 configuration.
+    Used to ensure Workers and Orchestrators are talking to the same storage.
+    Uses '|' as separator.
+    """
+    if not endpoint or not access_key or not bucket:
+        return None
+
+    config_str = f"{endpoint}|{access_key}|{bucket}"
+    return sha256(config_str.encode()).hexdigest()[:16]
+
+
+def parse_uri(uri: str, default_bucket: str | None = None, prefix: str = "") -> tuple[str, str, bool]:
+    """
+    Parses a Blob/S3 URI or relative path into (bucket, key, is_directory).
+    Protocol: s3://bucket/key
+
+    :param uri: Full URI (s3://bucket/key) or relative path (key)
+    :param default_bucket: Bucket to use if URI is relative
+    :param prefix: Optional prefix to prepend to relative paths
+    :return: (bucket, key, is_directory)
+    :raises ValueError: If URI format is invalid or bucket is missing
+    """
+    is_dir = uri.endswith("/")
+
+    if uri.startswith(f"{RXON_BLOB_SCHEME}://"):
+        parsed = urlparse(uri)
+        bucket = parsed.netloc
+        key = parsed.path.lstrip("/")
+        return bucket, key, is_dir
+    else:
+        if not default_bucket:
+            raise ValueError(f"Cannot parse relative path '{uri}' without a default bucket.")
+
+        clean_path = uri.lstrip("/")
+        key = f"{prefix}{clean_path}" if prefix else clean_path
+        return default_bucket, key, is_dir

rxon/constants.py

@@ -0,0 +1,136 @@
+# Copyright (c) 2025-2026 Dmitrii Gagarin aka madgagarin
+# This Source Code Form is subject to the terms of the Mozilla Public
+# License, v. 2.0. If a copy of the MPL was not distributed with this
+# file, You can obtain one at http://mozilla.org/MPL/2.0/.
+
+"""
+Centralized constants for the RXON protocol.
+Shared between Orchestrator and Worker SDK.
+"""
+
+__all__ = [
+    "AUTH_HEADER_CLIENT",
+    "AUTH_HEADER_WORKER",
+    "ERROR_CODE_TRANSIENT",
+    "ERROR_CODE_PERMANENT",
+    "ERROR_CODE_INVALID_INPUT",
+    "ERROR_CODE_INTEGRITY_MISMATCH",
+    "ERROR_CODE_TIMEOUT",
+    "ERROR_CODE_LATE_RESULT",
+    "ERROR_CODE_RESOURCE_EXHAUSTED",
+    "ERROR_CODE_LIMIT_EXCEEDED",
+    "ERROR_CODE_DEPENDENCY_MISSING",
+    "ERROR_CODE_CONTRACT_VIOLATION",
+    "ERROR_CODE_DEPENDENCY",
+    "ERROR_CODE_SECURITY",
+    "ERROR_CODE_INTERNAL",
+    "TASK_STATUS_SUCCESS",
+    "TASK_STATUS_FAILURE",
+    "TASK_STATUS_CANCELLED",
+    "COMMAND_CANCEL_TASK",
+    "EVENT_TYPE_PROGRESS",
+    "STS_TOKEN_ENDPOINT",
+    "WS_ENDPOINT",
+    "ENDPOINT_WORKER_REGISTER",
+    "ENDPOINT_TASK_NEXT",
+    "ENDPOINT_TASK_RESULT",
+    "ENDPOINT_WORKER_HEARTBEAT",
+    "ENDPOINT_WORKER_EVENTS",
+    "JOB_STATUS_PENDING",
+    "JOB_STATUS_WAITING_FOR_WORKER",
+    "JOB_STATUS_RUNNING",
+    "JOB_STATUS_FINISHED",
+    "JOB_STATUS_FAILED",
+    "JOB_STATUS_ERROR",
+    "JOB_STATUS_QUARANTINED",
+    "JOB_STATUS_CANCELLED",
+    "JOB_STATUS_WAITING_FOR_HUMAN",
+    "JOB_STATUS_WAITING_FOR_PARALLEL",
+    "WORKER_API_PREFIX",
+    "PROTOCOL_VERSION",
+    "PROTOCOL_VERSION_HEADER",
+    "IGNORED_REASON_LATE",
+    "IGNORED_REASON_CANCELLED",
+    "IGNORED_REASON_NOT_FOUND",
+    "IGNORED_REASON_MISMATCH",
+    "IGNORED_REASON_STALE",
+    "HB_RESP_REQUIRE_FULL_SYNC",
+    "HB_RESP_CANCEL_TASKS",
+    "AUTH_HEADER_WORKER_ID",
+    "STS_REFRESH_ENDPOINT",
+    "TERMINAL_STATES",
+    "WORKER_STATUS_ACTIVE",
+    "WORKER_STATUS_DRAINING",
+]
+
+PROTOCOL_VERSION = "1.0.0"
+PROTOCOL_VERSION_HEADER = "X-RXON-Version"
+
+AUTH_HEADER_CLIENT = "X-Client-Token"
+AUTH_HEADER_WORKER = "X-Worker-Token"
+AUTH_HEADER_WORKER_ID = "X-Worker-ID"
+
+ERROR_CODE_TRANSIENT = "TRANSIENT_ERROR"
+ERROR_CODE_PERMANENT = "PERMANENT_ERROR"
+ERROR_CODE_INVALID_INPUT = "INVALID_INPUT_ERROR"
+ERROR_CODE_INTEGRITY_MISMATCH = "INTEGRITY_MISMATCH_ERROR"
+ERROR_CODE_TIMEOUT = "TIMEOUT_ERROR"
+ERROR_CODE_LATE_RESULT = "LATE_RESULT"
+ERROR_CODE_RESOURCE_EXHAUSTED = "RESOURCE_EXHAUSTED_ERROR"
+ERROR_CODE_LIMIT_EXCEEDED = "LIMIT_EXCEEDED_ERROR"
+ERROR_CODE_CONTRACT_VIOLATION = "CONTRACT_VIOLATION_ERROR"
+ERROR_CODE_DEPENDENCY_MISSING = "DEPENDENCY_MISSING_ERROR"
+
+IGNORED_REASON_LATE = "deadline_exceeded"
+IGNORED_REASON_CANCELLED = "job_cancelled"
+IGNORED_REASON_NOT_FOUND = "job_not_found"
+IGNORED_REASON_MISMATCH = "worker_mismatch"
+IGNORED_REASON_STALE = "stale_task"
+
+HB_RESP_REQUIRE_FULL_SYNC = "require_full_sync"
+HB_RESP_CANCEL_TASKS = "cancel_task_ids"
+
+ERROR_CODE_DEPENDENCY = "DEPENDENCY_ERROR"
+ERROR_CODE_SECURITY = "SECURITY_ERROR"
+ERROR_CODE_INTERNAL = "INTERNAL_ERROR"
+
+TASK_STATUS_SUCCESS = "success"
+TASK_STATUS_FAILURE = "failure"
+TASK_STATUS_CANCELLED = "cancelled"
+
+COMMAND_CANCEL_TASK = "cancel_task"
+EVENT_TYPE_PROGRESS = "progress"
+
+WORKER_API_PREFIX = "/_worker"
+
+STS_TOKEN_ENDPOINT = f"{WORKER_API_PREFIX}/auth/token"
+STS_REFRESH_ENDPOINT = f"{WORKER_API_PREFIX}/auth/token/refresh"
+WS_ENDPOINT = f"{WORKER_API_PREFIX}/ws"
+
+ENDPOINT_WORKER_REGISTER = f"{WORKER_API_PREFIX}/workers/register"
+ENDPOINT_TASK_NEXT = f"{WORKER_API_PREFIX}/workers/{{worker_id}}/tasks/next"
+ENDPOINT_TASK_RESULT = f"{WORKER_API_PREFIX}/tasks/result"
+ENDPOINT_WORKER_HEARTBEAT = f"{WORKER_API_PREFIX}/workers/{{worker_id}}"
+ENDPOINT_WORKER_EVENTS = f"{WORKER_API_PREFIX}/events"
+
+JOB_STATUS_PENDING = "pending"
+JOB_STATUS_WAITING_FOR_WORKER = "waiting_for_worker"
+JOB_STATUS_RUNNING = "running"
+JOB_STATUS_FINISHED = "finished"
+JOB_STATUS_FAILED = "failed"
+JOB_STATUS_ERROR = "error"
+JOB_STATUS_QUARANTINED = "quarantined"
+JOB_STATUS_CANCELLED = "cancelled"
+JOB_STATUS_WAITING_FOR_HUMAN = "waiting_for_human"
+JOB_STATUS_WAITING_FOR_PARALLEL = "waiting_for_parallel_tasks"
+
+TERMINAL_STATES = {
+    JOB_STATUS_FINISHED,
+    JOB_STATUS_FAILED,
+    JOB_STATUS_ERROR,
+    JOB_STATUS_QUARANTINED,
+    JOB_STATUS_CANCELLED,
+}
+
+WORKER_STATUS_ACTIVE = "active"
+WORKER_STATUS_DRAINING = "draining"

rxon/exceptions.py

@@ -0,0 +1,74 @@
+# Copyright (c) 2025-2026 Dmitrii Gagarin aka madgagarin
+# This Source Code Form is subject to the terms of the Mozilla Public
+# License, v. 2.0. If a copy of the MPL was not distributed with this
+# file, You can obtain one at http://mozilla.org/MPL/2.0/.
+
+from typing import Any
+
+from rxon.constants import ERROR_CODE_LIMIT_EXCEEDED
+
+__all__ = [
+    "RxonError",
+    "RxonNetworkError",
+    "RxonAuthError",
+    "RxonProtocolError",
+    "RxonRateLimitError",
+    "S3ConfigMismatchError",
+    "IntegrityError",
+    "ParamValidationError",
+]
+
+
+class RxonError(Exception):
+    """Base exception for all RXON library errors."""
+
+    def __init__(self, message: str, details: dict[str, Any] | None = None):
+        super().__init__(message)
+        self.message = message
+        self.details = details or {}
+
+
+class RxonNetworkError(RxonError):
+    """Raised when a network operation fails (connection refused, timeout, etc.)."""
+
+    pass
+
+
+class RxonAuthError(RxonError):
+    """Raised when authentication fails (401/403) and cannot be recovered."""
+
+    pass
+
+
+class RxonProtocolError(RxonError):
+    """Raised when the server response violates the protocol (unexpected status, bad JSON)."""
+
+    pass
+
+
+class RxonRateLimitError(RxonProtocolError):
+    """Raised when the orchestrator rate limits the worker (HTTP 429)."""
+
+    def __init__(self, message: str, details: dict[str, Any] | None = None):
+        details = details or {}
+        if "code" not in details:
+            details["code"] = ERROR_CODE_LIMIT_EXCEEDED
+        super().__init__(message, details)
+
+
+class S3ConfigMismatchError(RxonProtocolError):
+    """Raised when Worker and Orchestrator S3 configurations do not match."""
+
+    pass
+
+
+class IntegrityError(RxonProtocolError):
+    """Raised when file integrity check (size/hash) fails."""
+
+    pass
+
+
+class ParamValidationError(RxonProtocolError):
+    """Raised when task parameters fail validation."""
+
+    pass