ray-hive 1.0__py3-none-any.whl

ray_hive/__init__.py

@@ -0,0 +1,64 @@
+# Copyright 2026 ray-hive contributors
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Public API for the ray-hive HiveServer2 datasource."""
+
+from ray_hive._api import read_hive
+from ray_hive._credentials import CredentialProvider, SecretRef
+from ray_hive._errors import (
+    HiveAuthenticationError,
+    HiveCancellationError,
+    HiveCleanupError,
+    HiveCompatibilityError,
+    HiveConfigurationError,
+    HiveDependencyError,
+    HiveError,
+    HiveErrorCode,
+    HivePermissionError,
+    HivePlanningError,
+    HiveProtocolError,
+    HiveQueryError,
+    HiveSchemaError,
+    HiveTransportError,
+)
+from ray_hive._models import (
+    HiveConnectionOptions,
+    HiveReadOptions,
+    HiveTableIdentifier,
+    HiveTLSOptions,
+)
+
+__all__ = [
+    "CredentialProvider",
+    "HiveAuthenticationError",
+    "HiveCancellationError",
+    "HiveCleanupError",
+    "HiveCompatibilityError",
+    "HiveConfigurationError",
+    "HiveConnectionOptions",
+    "HiveDependencyError",
+    "HiveError",
+    "HiveErrorCode",
+    "HivePermissionError",
+    "HivePlanningError",
+    "HiveProtocolError",
+    "HiveQueryError",
+    "HiveReadOptions",
+    "HiveSchemaError",
+    "HiveTLSOptions",
+    "HiveTableIdentifier",
+    "HiveTransportError",
+    "SecretRef",
+    "read_hive",
+]

ray_hive/_api.py

@@ -0,0 +1,40 @@
+# Copyright 2026 ray-hive contributors
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Stable public read facade."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from typing import Any
+
+from ray_hive._compat import read_datasource_strict
+from ray_hive._models import HiveConnectionOptions, HiveReadOptions
+from ray_hive.datasource import HiveServer2Datasource
+
+
+def read_hive(
+    *,
+    connection: HiveConnectionOptions,
+    read: HiveReadOptions,
+    ray_remote_args: Mapping[str, Any] | None = None,
+) -> Any:
+    """Plan an HS2-only read and return a lazy Ray Dataset with task retries disabled."""
+
+    datasource = HiveServer2Datasource.from_options(connection, read)
+    return read_datasource_strict(
+        datasource,
+        num_tasks=len(datasource.task_specs),
+        ray_remote_args=ray_remote_args,
+    )

ray_hive/_capabilities.py

@@ -0,0 +1,70 @@
+# Copyright 2026 ray-hive contributors
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Fail-closed HiveServer2 capability negotiation."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from enum import StrEnum
+
+from ray_hive._errors import HiveCompatibilityError
+
+
+class CapabilityState(StrEnum):
+    """Tri-state support result; unknown is never treated as supported."""
+
+    SUPPORTED = "supported"
+    UNSUPPORTED = "unsupported"
+    UNKNOWN = "unknown"
+
+
+@dataclass(frozen=True, slots=True)
+class CapabilityEvidence:
+    """The origin of one capability conclusion."""
+
+    capability: str
+    state: CapabilityState
+    source: str
+
+
+@dataclass(frozen=True, slots=True)
+class HiveCapabilities:
+    """Immutable capabilities negotiated immediately after OpenSession."""
+
+    protocol_version: int
+    columnar_rowsets: CapabilityState
+    binary_columns: CapabilityState
+    cancel_operation: CapabilityState
+    operation_log: CapabilityState
+    evidence: tuple[CapabilityEvidence, ...] = ()
+
+    def require_core(self) -> None:
+        """Reject a connection that cannot satisfy the Core read profile."""
+
+        if self.protocol_version < 6:
+            raise HiveCompatibilityError("HS2 protocol V6 or newer is required")
+        if self.columnar_rowsets is not CapabilityState.SUPPORTED:
+            raise HiveCompatibilityError("Native V6 columnar result sets are required")
+        if self.cancel_operation is not CapabilityState.SUPPORTED:
+            raise HiveCompatibilityError("CancelOperation capability is required")
+
+    def require(self, capability: str, state: CapabilityState) -> None:
+        """Require an explicitly supported capability by attribute name."""
+
+        actual = getattr(self, capability, None)
+        if actual is not state:
+            raise HiveCompatibilityError(
+                f"Required capability {capability!r} is not explicitly {state.value}"
+            )

ray_hive/_compat.py

@@ -0,0 +1,120 @@
+# Copyright 2026 ray-hive contributors
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""The only module allowed to adapt Ray DeveloperAPI version differences."""
+
+from __future__ import annotations
+
+import inspect
+from collections.abc import Callable, Iterable, Mapping
+from importlib.metadata import version
+from typing import Any
+
+import pyarrow as pa
+
+from ray_hive._errors import HiveCompatibilityError
+
+SUPPORTED_RAY_VERSION = "2.55.1"
+SUPPORTED_PYARROW_VERSION = "19.0.1"
+_READ_TASK_PARAMETERS = ("self", "read_fn", "metadata", "schema", "per_task_row_limit")
+_GET_READ_TASKS_PARAMETERS = (
+    "self",
+    "parallelism",
+    "per_task_row_limit",
+    "data_context",
+)
+
+
+def validate_runtime() -> None:
+    """Fail closed unless the exact tested Ray/PyArrow contracts are installed."""
+
+    if version("ray") != SUPPORTED_RAY_VERSION:
+        raise HiveCompatibilityError(
+            f"ray-hive requires Ray {SUPPORTED_RAY_VERSION} in the initial release"
+        )
+    if pa.__version__ != SUPPORTED_PYARROW_VERSION:
+        raise HiveCompatibilityError(
+            f"ray-hive requires PyArrow {SUPPORTED_PYARROW_VERSION} in the initial release"
+        )
+
+    from ray.data import Datasource, ReadTask
+
+    read_task_parameters = tuple(inspect.signature(ReadTask.__init__).parameters)
+    if read_task_parameters != _READ_TASK_PARAMETERS:
+        raise HiveCompatibilityError("Unsupported Ray ReadTask constructor signature")
+    get_tasks_parameters = tuple(inspect.signature(Datasource.get_read_tasks).parameters)
+    if get_tasks_parameters != _GET_READ_TASKS_PARAMETERS:
+        raise HiveCompatibilityError("Unsupported Ray Datasource.get_read_tasks signature")
+
+
+def initialize_datasource(instance: Any) -> None:
+    """Invoke the exact pinned Ray Datasource initializer through the adapter boundary."""
+
+    from ray.data import Datasource
+
+    initializer: Any = Datasource.__init__
+    initializer(instance)
+
+
+def create_read_task(
+    read_fn: Callable[[], Iterable[pa.Table]],
+    schema: pa.Schema,
+    *,
+    per_task_row_limit: int | None,
+) -> Any:
+    """Construct the exact supported DeveloperAPI ReadTask shape."""
+
+    validate_runtime()
+    from ray.data import ReadTask
+    from ray.data.block import BlockMetadata
+
+    metadata = BlockMetadata(
+        num_rows=None,
+        size_bytes=None,
+        exec_stats=None,
+        input_files=None,
+    )
+    return ReadTask(
+        read_fn,
+        metadata,
+        schema=schema,
+        per_task_row_limit=per_task_row_limit,
+    )
+
+
+def read_datasource_strict(
+    datasource: Any,
+    *,
+    num_tasks: int,
+    ray_remote_args: Mapping[str, Any] | None,
+) -> Any:
+    """Call the public Ray facade with no retry or lineage replay of a query task."""
+
+    validate_runtime()
+    from ray.data import read_datasource
+
+    parameters = inspect.signature(read_datasource).parameters
+    required = {"datasource", "ray_remote_args", "concurrency", "override_num_blocks"}
+    if not required.issubset(parameters):
+        raise HiveCompatibilityError("Unsupported Ray read_datasource signature")
+    remote_args = dict(ray_remote_args or {})
+    if remote_args.get("max_retries", 0) != 0:
+        raise HiveCompatibilityError("Strict Hive reads require Ray max_retries=0")
+    remote_args["max_retries"] = 0
+    return read_datasource(
+        datasource,
+        ray_remote_args=remote_args,
+        concurrency=num_tasks,
+        override_num_blocks=num_tasks,
+    )

ray_hive/_credentials.py

@@ -0,0 +1,140 @@
+# Copyright 2026 ray-hive contributors
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Serializable secret references resolved only by trusted HS2-connecting nodes."""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass, field, replace
+from typing import Protocol, runtime_checkable
+
+from ray_hive._errors import HiveAuthenticationError, HiveConfigurationError
+
+
+@dataclass(frozen=True, slots=True)
+class CredentialContext:
+    """Security boundary to which resolved credentials must be bound."""
+
+    endpoint: str
+    driver: str
+    auth: str
+    tls_server_name: str | None
+    audience: str | None = None
+
+
+@dataclass(frozen=True, slots=True)
+class HiveCredentials:
+    """Ephemeral authentication material that must never enter a task spec."""
+
+    username: str | None = None
+    password: str | None = field(default=None, repr=False)
+    token: str | None = field(default=None, repr=False)
+
+
+@runtime_checkable
+class CredentialProvider(Protocol):
+    """A serializable strategy resolved only by a trusted HS2-connecting node."""
+
+    def bind(self, context: CredentialContext) -> CredentialProvider:
+        """Return a provider restricted to the supplied connection context."""
+
+    def resolve(self, context: CredentialContext) -> HiveCredentials:
+        """Resolve ephemeral authentication material for the supplied context."""
+
+
+@dataclass(frozen=True, slots=True)
+class SecretRef:
+    """An immutable reference to one secret value, never the value itself."""
+
+    provider: str
+    key: str
+    allowed_context: CredentialContext | None = field(default=None, repr=False)
+
+    def __post_init__(self) -> None:
+        if self.provider != "env":
+            raise HiveConfigurationError(f"Unsupported secret provider: {self.provider!r}")
+        if not self.key or "\x00" in self.key:
+            raise HiveConfigurationError(
+                "Secret reference key must be non-empty and contain no NUL"
+            )
+
+    @classmethod
+    def env(cls, variable: str) -> SecretRef:
+        """Create a reference resolved from the local HS2 client's environment."""
+
+        return cls(provider="env", key=variable)
+
+    def bind(self, context: CredentialContext) -> SecretRef:
+        """Bind this reference to exactly one endpoint and authentication context."""
+
+        if self.allowed_context is not None and self.allowed_context != context:
+            raise HiveConfigurationError("Secret reference is already bound to another endpoint")
+        return replace(self, allowed_context=context)
+
+    def resolve_value(self, context: CredentialContext) -> str:
+        """Resolve the referenced value after validating its endpoint binding."""
+
+        if self.allowed_context is None or self.allowed_context != context:
+            raise HiveAuthenticationError("Secret reference is not bound to this endpoint")
+        try:
+            return os.environ[self.key]
+        except KeyError as exc:
+            raise HiveAuthenticationError(
+                f"Required environment credential {self.key!r} is unavailable"
+            ) from exc
+
+    def resolve(self, context: CredentialContext) -> HiveCredentials:
+        """Resolve a direct secret reference as a password credential."""
+
+        return HiveCredentials(password=self.resolve_value(context))
+
+    def __repr__(self) -> str:
+        return (
+            f"SecretRef(provider={self.provider!r}, key={self.key!r}, "
+            f"bound={self.allowed_context is not None})"
+        )
+
+
+@dataclass(frozen=True, slots=True)
+class EnvironmentCredentialProvider:
+    """Resolve optional username, password, and token environment references."""
+
+    username: str | None = None
+    password: SecretRef | None = None
+    token: SecretRef | None = None
+    allowed_context: CredentialContext | None = field(default=None, repr=False)
+
+    def bind(self, context: CredentialContext) -> EnvironmentCredentialProvider:
+        """Bind every contained reference to one connection context."""
+
+        if self.allowed_context is not None and self.allowed_context != context:
+            raise HiveConfigurationError("Credential provider is already bound to another endpoint")
+        return replace(
+            self,
+            password=self.password.bind(context) if self.password else None,
+            token=self.token.bind(context) if self.token else None,
+            allowed_context=context,
+        )
+
+    def resolve(self, context: CredentialContext) -> HiveCredentials:
+        """Resolve authentication material only when the binding is exact."""
+
+        if self.allowed_context != context:
+            raise HiveAuthenticationError("Credential provider is not bound to this endpoint")
+        return HiveCredentials(
+            username=self.username,
+            password=self.password.resolve_value(context) if self.password else None,
+            token=self.token.resolve_value(context) if self.token else None,
+        )

ray_hive/_errors.py

@@ -0,0 +1,157 @@
+# Copyright 2026 ray-hive contributors
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Public, stable error contracts for ray-hive."""
+
+from __future__ import annotations
+
+from enum import StrEnum
+
+
+class HiveErrorCode(StrEnum):
+    """Stable conformance error codes."""
+
+    CONFIG = "CONFIG"
+    AUTH = "AUTH"
+    PERMISSION = "PERMISSION"
+    QUERY_COMPILE = "QUERY_COMPILE"
+    QUERY_EXECUTION = "QUERY_EXECUTION"
+    SCHEMA = "SCHEMA"
+    PROTOCOL = "PROTOCOL"
+    TRANSPORT_BEFORE_OUTPUT = "TRANSPORT_BEFORE_OUTPUT"
+    TRANSPORT_AFTER_OUTPUT = "TRANSPORT_AFTER_OUTPUT"
+    CANCELLED = "CANCELLED"
+    CLEANUP = "CLEANUP"
+
+
+class HiveError(Exception):
+    """Base exception with stable, sanitized machine-readable attributes."""
+
+    default_error_code = HiveErrorCode.CONFIG
+    default_retryable = False
+    default_partial_output = False
+
+    def __init__(
+        self,
+        safe_message: str,
+        *,
+        error_code: HiveErrorCode | None = None,
+        retryable: bool | None = None,
+        partial_output: bool | None = None,
+        operation_state: str | None = None,
+    ) -> None:
+        super().__init__(safe_message)
+        self.error_code = error_code or self.default_error_code
+        self.retryable = self.default_retryable if retryable is None else retryable
+        self.partial_output = (
+            self.default_partial_output if partial_output is None else partial_output
+        )
+        self.operation_state = operation_state
+
+    def __repr__(self) -> str:
+        return (
+            f"{type(self).__name__}(error_code={self.error_code.value!r}, "
+            f"retryable={self.retryable!r}, partial_output={self.partial_output!r}, "
+            f"operation_state={self.operation_state!r})"
+        )
+
+    def mark_partial_output(self) -> HiveError:
+        """Preserve the concrete error while recording that output was published."""
+
+        self.partial_output = True
+        self.retryable = False
+        if self.error_code is HiveErrorCode.TRANSPORT_BEFORE_OUTPUT:
+            self.error_code = HiveErrorCode.TRANSPORT_AFTER_OUTPUT
+        return self
+
+
+class HiveConfigurationError(HiveError):
+    """Raised for invalid or insecure configuration."""
+
+
+class HiveDependencyError(HiveConfigurationError):
+    """Raised when an explicitly selected optional dependency is unavailable."""
+
+
+class HiveAuthenticationError(HiveError):
+    """Raised when HiveServer2 authentication fails."""
+
+    default_error_code = HiveErrorCode.AUTH
+
+
+class HivePermissionError(HiveError):
+    """Raised when HiveServer2 rejects an authorized operation."""
+
+    default_error_code = HiveErrorCode.PERMISSION
+
+
+class HivePlanningError(HiveError):
+    """Raised when a logical read cannot be compiled safely."""
+
+    default_error_code = HiveErrorCode.QUERY_COMPILE
+
+
+class HiveSchemaError(HiveError):
+    """Raised for unsupported types or schema drift."""
+
+    default_error_code = HiveErrorCode.SCHEMA
+
+
+class HiveQueryError(HiveError):
+    """Raised when an accepted Hive query fails during execution."""
+
+    default_error_code = HiveErrorCode.QUERY_EXECUTION
+
+
+class HiveProtocolError(HiveError):
+    """Raised when the server violates the negotiated HS2 protocol."""
+
+    default_error_code = HiveErrorCode.PROTOCOL
+
+
+class HiveCompatibilityError(HiveProtocolError):
+    """Raised when a runtime version or capability is unsupported."""
+
+
+class HiveTransportError(HiveError):
+    """Raised when the HS2 transport fails."""
+
+    default_error_code = HiveErrorCode.TRANSPORT_BEFORE_OUTPUT
+    default_retryable = True
+
+    @classmethod
+    def after_output(
+        cls, safe_message: str, *, operation_state: str | None = None
+    ) -> HiveTransportError:
+        """Construct a non-retryable transport error after a block was published."""
+
+        return cls(
+            safe_message,
+            error_code=HiveErrorCode.TRANSPORT_AFTER_OUTPUT,
+            retryable=False,
+            partial_output=True,
+            operation_state=operation_state,
+        )
+
+
+class HiveCancellationError(HiveError):
+    """Raised when a read is cancelled."""
+
+    default_error_code = HiveErrorCode.CANCELLED
+
+
+class HiveCleanupError(HiveError):
+    """Raised when required resource cleanup fails."""
+
+    default_error_code = HiveErrorCode.CLEANUP

ray_hive/_hs2/__init__.py

@@ -0,0 +1,15 @@
+# Copyright 2026 ray-hive contributors
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Internal HiveServer2 protocol implementation."""