feat(spider-client): Add user-facing client library for job orchestration and resource group management.

Cargo.toml

@@ -1,6 +1,7 @@
 [workspace]
 resolver = "3"
 members = [
+  "components/spider-client",
   "components/spider-core",
   "components/spider-derive",
   "components/spider-execution-manager",
@@ -20,6 +21,7 @@ members = [
   "tests/huntsman/test-utils",
 ]
 default-members = [
+  "components/spider-client",
   "components/spider-core",
   "components/spider-derive",
   "components/spider-execution-manager",

components/spider-client/Cargo.toml

@@ -0,0 +1,16 @@
+[package]
+name = "spider-client"
+version = "0.1.0"
+edition = "2024"
+
+[lib]
+name = "spider_client"
+path = "src/lib.rs"
+
+[dependencies]
+spider-core = { path = "../spider-core" }
+spider-proto-rust = { path = "../spider-proto-rust" }
+spider-utils = { path = "../spider-utils" }
+thiserror = "2.0.18"
+tokio = { version = "1.52.3", features = ["macros"] }
+tonic = "0.14.6"

components/spider-client/src/client.rs

@@ -0,0 +1,185 @@
+//! [`SpiderClient`] — the top-level handle holding the gRPC connection pools.
+
+use std::num::NonZeroUsize;
+
+use spider_core::{
+    job::JobState,
+    task::TaskGraph,
+    types::{
+        id::{JobId, ResourceGroupId},
+        io::{TaskInput, TaskOutput},
+    },
+};
+use tonic::transport::Endpoint;
+
+use crate::{
+    error::ClientError,
+    job::JobOrchestrationClient,
+    resource_group::ResourceGroupManagementClient,
+};
+
+/// User-facing client for the Spider storage gRPC services.
+///
+/// Wraps a [`JobOrchestrationClient`] and a [`ResourceGroupManagementClient`] against the same
+/// storage endpoint, so callers who need both job-lifecycle and resource-group operations get a
+/// single handle and one [`SpiderClient::connect`] call. Callers who need only one service may
+/// construct the inner client directly.
+#[derive(Debug, Clone)]
+pub struct SpiderClient {
+    job_orchestration: JobOrchestrationClient,
+    resource_group: ResourceGroupManagementClient,
+}
+
+impl SpiderClient {
+    /// Connects pools of `pool_size` connections to the storage gRPC endpoint.
+    ///
+    /// Both the job-orchestration and resource-group-management services are reached through the
+    /// same `endpoint`.
+    ///
+    /// # Returns
+    ///
+    /// A new [`SpiderClient`] connected to `endpoint` on success.
+    ///
+    /// # Errors
+    ///
+    /// Returns [`ClientError::Transport`] if tonic cannot establish a connection to `endpoint`.
+    pub async fn connect(endpoint: Endpoint, pool_size: NonZeroUsize) -> Result<Self, ClientError> {
+        let (job_orchestration, resource_group) = tokio::try_join!(
+            JobOrchestrationClient::connect(endpoint.clone(), pool_size),
+            ResourceGroupManagementClient::connect(endpoint, pool_size),
+        )?;
+
+        Ok(Self {
+            job_orchestration,
+            resource_group,
+        })
+    }
+
+    /// Serializes and zstd-compresses the task graph and inputs, registers the job, and returns
+    /// its assigned id. Delegates to [`JobOrchestrationClient::submit_job`].
+    ///
+    /// # Returns
+    ///
+    /// The [`JobId`] the storage server assigned to the registered job on success.
+    ///
+    /// # Errors
+    ///
+    /// See [`JobOrchestrationClient::submit_job`].
+    pub async fn submit_job(
+        &self,
+        resource_group_id: ResourceGroupId,
+        task_graph: &TaskGraph,
+        inputs: Vec<TaskInput>,
+    ) -> Result<JobId, ClientError> {
+        self.job_orchestration
+            .submit_job(resource_group_id, task_graph, inputs)
+            .await
+    }
+
+    /// Starts a registered job. Delegates to [`JobOrchestrationClient::start_job`].
+    ///
+    /// # Returns
+    ///
+    /// The job's [`JobState`] after the start request is accepted on success.
+    ///
+    /// # Errors
+    ///
+    /// See [`JobOrchestrationClient::start_job`].
+    pub async fn start_job(&self, job_id: JobId) -> Result<JobState, ClientError> {
+        self.job_orchestration.start_job(job_id).await
+    }
+
+    /// Cancels a job. Delegates to [`JobOrchestrationClient::cancel_job`].
+    ///
+    /// # Returns
+    ///
+    /// The job's [`JobState`] after the cancellation request is accepted on success.
+    ///
+    /// # Errors
+    ///
+    /// See [`JobOrchestrationClient::cancel_job`].
+    pub async fn cancel_job(&self, job_id: JobId) -> Result<JobState, ClientError> {
+        self.job_orchestration.cancel_job(job_id).await
+    }
+
+    /// Gets the current state of a job. Delegates to [`JobOrchestrationClient::get_job_state`].
+    ///
+    /// # Returns
+    ///
+    /// The job's current [`JobState`] on success.
+    ///
+    /// # Errors
+    ///
+    /// See [`JobOrchestrationClient::get_job_state`].
+    pub async fn get_job_state(&self, job_id: JobId) -> Result<JobState, ClientError> {
+        self.job_orchestration.get_job_state(job_id).await
+    }
+
+    /// Gets a job's task outputs. Delegates to [`JobOrchestrationClient::get_job_outputs`].
+    ///
+    /// # Returns
+    ///
+    /// The job's outputs, deserialized from the storage wire format into opaque msgpack payloads,
+    /// on success.
+    ///
+    /// # Errors
+    ///
+    /// See [`JobOrchestrationClient::get_job_outputs`].
+    pub async fn get_job_outputs(&self, job_id: JobId) -> Result<Vec<TaskOutput>, ClientError> {
+        self.job_orchestration.get_job_outputs(job_id).await
+    }
+
+    /// Gets a job's error message. Delegates to [`JobOrchestrationClient::get_job_error`].
+    ///
+    /// # Returns
+    ///
+    /// The job's error message on success.
+    ///
+    /// # Errors
+    ///
+    /// See [`JobOrchestrationClient::get_job_error`].
+    pub async fn get_job_error(&self, job_id: JobId) -> Result<String, ClientError> {
+        self.job_orchestration.get_job_error(job_id).await
+    }
+
+    /// Registers an external resource group and returns its server-assigned id. Delegates to
+    /// [`ResourceGroupManagementClient::add_resource_group`].
+    ///
+    /// # Returns
+    ///
+    /// The [`ResourceGroupId`] the storage server assigned to the registered resource group on
+    /// success.
+    ///
+    /// # Errors
+    ///
+    /// See [`ResourceGroupManagementClient::add_resource_group`].
+    pub async fn add_resource_group(
+        &self,
+        external_resource_group_id: String,
+        password: Vec<u8>,
+    ) -> Result<ResourceGroupId, ClientError> {
+        self.resource_group
+            .add_resource_group(external_resource_group_id, password)
+            .await
+    }
+
+    /// Verifies a resource group's password. Delegates to
+    /// [`ResourceGroupManagementClient::verify_resource_group`].
+    ///
+    /// # Returns
+    ///
+    /// `Ok(())` on success.
+    ///
+    /// # Errors
+    ///
+    /// See [`ResourceGroupManagementClient::verify_resource_group`].
+    pub async fn verify_resource_group(
+        &self,
+        resource_group_id: ResourceGroupId,
+        password: Vec<u8>,
+    ) -> Result<(), ClientError> {
+        self.resource_group
+            .verify_resource_group(resource_group_id, password)
+            .await
+    }
+}

components/spider-client/src/error.rs

@@ -0,0 +1,110 @@
+//! Client error type for the Spider storage gRPC services.
+//!
+//! [`ClientError`] is the single error type returned by [`crate::client::SpiderClient`] methods.
+//! It folds transport failures, tonic error status, and payload serialization and
+//! deserialization failures into one concrete enum. See [`ClientError`] for the variants and when
+//! each arises.
+
+use spider_core::types::id::JobId;
+use tonic::{Code, Status};
+
+/// Errors returned by [`crate::client::SpiderClient`] operations.
+#[derive(Debug, thiserror::Error)]
+pub enum ClientError {
+    /// The gRPC transport failed or the connection was lost or unestablished.
+    #[error("transport error: {0}")]
+    Transport(String),
+
+    /// The storage server returned an otherwise-uncategorized error.
+    #[error("storage server error: {0}")]
+    Server(String),
+
+    /// No job with the requested identifier exists.
+    #[error("job not found: {0:?}")]
+    JobNotFound(JobId),
+
+    /// The job is not in a state that allows the requested operation.
+    #[error("invalid job state: {0}")]
+    InvalidJobState(String),
+
+    /// The storage server rejected the request as invalid.
+    #[error("invalid argument: {0}")]
+    InvalidArgument(String),
+
+    /// The resource group or password was rejected.
+    #[error("unauthenticated: {0}")]
+    Unauthenticated(String),
+
+    /// A failure to serialize, compress, or wire-frame a request payload.
+    #[error("serialization error: {0}")]
+    Serialization(String),
+
+    /// A failure to deserialize, decompress, or wire-frame a response payload.
+    #[error("deserialization error: {0}")]
+    Deserialization(String),
+
+    /// The server returned an unspecified job state that has no core representation.
+    #[error("job state is unspecified")]
+    UnspecifiedJobState,
+}
+
+/// Maps a job-orchestration gRPC [`Status`] to a [`ClientError`].
+///
+/// `job_id` is the job the call targeted; it is attached to [`ClientError::JobNotFound`] when the
+/// server reports `NOT_FOUND`.
+///
+/// # Returns
+///
+/// The [`ClientError`] for `status`'s code:
+///
+/// * [`ClientError::JobNotFound`] for `NOT_FOUND`.
+/// * [`ClientError::InvalidJobState`] for `FAILED_PRECONDITION`.
+/// * [`ClientError::InvalidArgument`] for `INVALID_ARGUMENT`.
+/// * [`ClientError::Unauthenticated`] for `UNAUTHENTICATED`.
+/// * [`ClientError::Transport`] for `UNAVAILABLE` (a lost or unestablished connection).
+/// * [`ClientError::Server`] for any other code.
+pub(crate) fn job_status_to_error(status: &Status, job_id: JobId) -> ClientError {
+    match status.code() {
+        Code::NotFound => ClientError::JobNotFound(job_id),
+        Code::FailedPrecondition => ClientError::InvalidJobState(status.message().to_owned()),
+        Code::InvalidArgument => ClientError::InvalidArgument(status.message().to_owned()),
+        Code::Unauthenticated => ClientError::Unauthenticated(status.message().to_owned()),
+        Code::Unavailable => ClientError::Transport(status.message().to_owned()),
+        _ => ClientError::Server(status.message().to_owned()),
+    }
+}
+
+/// Maps a resource-group-management gRPC [`Status`] to a [`ClientError`].
+///
+/// # Returns
+///
+/// The [`ClientError`] for `status`'s code:
+///
+/// * [`ClientError::InvalidArgument`] for `INVALID_ARGUMENT`.
+/// * [`ClientError::Unauthenticated`] for `UNAUTHENTICATED` (an unknown or unauthorized resource
+///   group, or an invalid password).
+/// * [`ClientError::Transport`] for `UNAVAILABLE` (a lost or unestablished connection).
+/// * [`ClientError::Server`] for any other code (including `NOT_FOUND`, `FAILED_PRECONDITION`, and
+///   `INTERNAL`).
+pub(crate) fn resource_group_status_to_error(status: &Status) -> ClientError {
+    match status.code() {
+        Code::InvalidArgument => ClientError::InvalidArgument(status.message().to_owned()),
+        Code::Unauthenticated => ClientError::Unauthenticated(status.message().to_owned()),
+        Code::Unavailable => ClientError::Transport(status.message().to_owned()),
+        _ => ClientError::Server(status.message().to_owned()),
+    }
+}
+
+/// Converts a displayable transport-layer error into [`ClientError::Transport`].
+///
+/// Used by the `connect` methods of [`crate::client::SpiderClient`],
+/// [`crate::job::JobOrchestrationClient`],
+/// and [`crate::resource_group::ResourceGroupManagementClient`] to fold `spider_utils::grpc::Error`
+/// into [`ClientError`].
+///
+/// # Returns
+///
+/// A [`ClientError::Transport`] containing `error`'s display string.
+pub(crate) fn to_transport_error(error: impl std::fmt::Display) -> ClientError {
+    ClientError::Transport(error.to_string())
+}