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,227 @@
+//! [`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,
+    grpc::{job::JobOrchestrationClient, resource_group::ResourceGroupManagementClient},
+};
+
+/// User-facing client for the Spider storage gRPC services.
+#[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.
+    ///
+    /// # Returns
+    ///
+    /// A new [`SpiderClient`] connected to `endpoint` on success.
+    ///
+    /// # Errors
+    ///
+    /// Returns an error if:
+    ///
+    /// * [`ClientError::Transport`] if tonic cannot create or connect to the 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.
+    ///
+    /// # Returns
+    ///
+    /// The [`JobId`] the storage server assigned to the registered job on success.
+    ///
+    /// # Errors
+    ///
+    /// Returns an error if:
+    ///
+    /// * [`ClientError::Serialization`] if the task graph or inputs cannot be serialized or
+    ///   compressed.
+    /// * [`ClientError::InvalidArgument`] if the storage server rejects the task graph or inputs.
+    /// * [`ClientError::Unauthenticated`] if the resource group is unknown or unauthorized.
+    /// * [`ClientError::Transport`] if the gRPC transport fails or the connection is lost.
+    /// * [`ClientError::Server`] for any other server-reported error.
+    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.
+    ///
+    /// # Returns
+    ///
+    /// The job's [`JobState`] after the start request is accepted on success.
+    ///
+    /// # Errors
+    ///
+    /// Returns an error if:
+    ///
+    /// * [`ClientError::JobNotFound`] if no job with `job_id` exists.
+    /// * [`ClientError::InvalidJobState`] if the job is not in a state that allows starting.
+    /// * [`ClientError::UnspecifiedJobState`] if the server reports an unspecified job state.
+    /// * [`ClientError::Transport`] if the gRPC transport fails, the connection is lost, or the
+    ///   server reports an unrecognized job state.
+    /// * [`ClientError::Server`] for any other server-reported error.
+    pub async fn start_job(&self, job_id: JobId) -> Result<JobState, ClientError> {
+        self.job_orchestration.start_job(job_id).await
+    }
+
+    /// Cancels a job.
+    ///
+    /// # Returns
+    ///
+    /// The job's [`JobState`] after the cancellation request is accepted on success.
+    ///
+    /// # Errors
+    ///
+    /// Returns an error if:
+    ///
+    /// * [`ClientError::JobNotFound`] if no job with `job_id` exists.
+    /// * [`ClientError::InvalidJobState`] if the job is not in a state that allows cancellation.
+    /// * [`ClientError::UnspecifiedJobState`] if the server reports an unspecified job state.
+    /// * [`ClientError::Transport`] if the gRPC transport fails, the connection is lost, or the
+    ///   server reports an unrecognized job state.
+    /// * [`ClientError::Server`] for any other server-reported error.
+    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.
+    ///
+    /// # Returns
+    ///
+    /// The job's current [`JobState`] on success.
+    ///
+    /// # Errors
+    ///
+    /// Returns an error if:
+    ///
+    /// * [`ClientError::JobNotFound`] if no job with `job_id` exists.
+    /// * [`ClientError::UnspecifiedJobState`] if the server reports an unspecified job state.
+    /// * [`ClientError::Transport`] if the gRPC transport fails, the connection is lost, or the
+    ///   server reports an unrecognized job state.
+    /// * [`ClientError::Server`] for any other server-reported error.
+    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.
+    ///
+    /// # Returns
+    ///
+    /// The job's outputs, deserialized from the storage wire format into opaque msgpack payloads,
+    /// on success.
+    ///
+    /// # Errors
+    ///
+    /// Returns an error if:
+    ///
+    /// * [`ClientError::JobNotFound`] if no job with `job_id` exists.
+    /// * [`ClientError::InvalidJobState`] if the job has not yet succeeded.
+    /// * [`ClientError::Deserialization`] if the returned outputs cannot be decompressed or
+    ///   unframed.
+    /// * [`ClientError::Transport`] if the gRPC transport fails or the connection is lost.
+    /// * [`ClientError::Server`] for any other server-reported error.
+    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.
+    ///
+    /// # Returns
+    ///
+    /// The job's error message on success.
+    ///
+    /// # Errors
+    ///
+    /// Returns an error if:
+    ///
+    /// * [`ClientError::JobNotFound`] if no job with `job_id` exists.
+    /// * [`ClientError::InvalidJobState`] if the job has not yet failed.
+    /// * [`ClientError::Transport`] if the gRPC transport fails or the connection is lost.
+    /// * [`ClientError::Server`] for any other server-reported 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.
+    ///
+    /// # Returns
+    ///
+    /// The [`ResourceGroupId`] the storage server assigned to the registered resource group on
+    /// success.
+    ///
+    /// # Errors
+    ///
+    /// Returns an error if:
+    ///
+    /// * [`ClientError::InvalidArgument`] if the storage server rejects the request as invalid.
+    /// * [`ClientError::Unauthenticated`] if the resource group is unknown or the password is
+    ///   invalid.
+    /// * [`ClientError::Transport`] if the gRPC transport fails or the connection is lost.
+    /// * [`ClientError::Server`] for any other server-reported error.
+    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.
+    ///
+    /// # Returns
+    ///
+    /// `Ok(())` on success.
+    ///
+    /// # Errors
+    ///
+    /// Returns an error if:
+    ///
+    /// * [`ClientError::InvalidArgument`] if the storage server rejects the request as invalid.
+    /// * [`ClientError::Unauthenticated`] if the resource group is unknown or the password is
+    ///   invalid.
+    /// * [`ClientError::Transport`] if the gRPC transport fails or the connection is lost.
+    /// * [`ClientError::Server`] for any other server-reported error.
+    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,50 @@
+//! Client error type for the Spider storage gRPC services.
+
+/// 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")]
+    JobNotFound,
+
+    /// 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 unspecified")]
+    UnspecifiedJobState,
+}
+
+/// Converts a displayable transport-layer error into [`ClientError::Transport`].
+///
+/// # 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())
+}