feat: story 7.1 — rust client sdk

[vieiralucas]

Summary

• New fila-client crate: idiomatic Rust SDK wrapping tonic-generated FilaServiceClient<Channel>
• Four hot-path operations: enqueue, lease (streaming), ack, nack
• Context-aware error mapping: QueueNotFound vs MessageNotFound based on operation
• LeaseMessage flattens proto Message + MessageMetadata into ergonomic struct
• FilaClient is Clone + Send + Sync — safe to share across tokio tasks

Acceptance Criteria Covered

• AC feat: cargo workspace and protobuf api definitions (story 1.1) #1: fila-client crate in workspace as thin wrapper over fila-proto
• AC ci: add ci/cd pipeline and dockerfile (story 1.2) #2: FilaClient::connect(addr) returns connected client
• AC feat: core domain types and rocksdb storage layer #3: enqueue(queue, headers, payload) -> Result<String>
• AC feat: broker core with single-threaded scheduler loop #4: lease(queue) -> Result<impl Stream<Item = Result<LeaseMessage>>>
• AC feat: grpc server with queue management rpcs #5: ack(queue, msg_id) -> Result<()>
• AC feat: message enqueue rpc (story 1.6) #6: nack(queue, msg_id, error) -> Result<()>
• AC feat: consumer lease streaming & message delivery (story 1.7) #7: ConnectOptions with addr + timeout (TLS placeholder for future)
• AC feat: message ack with atomic cleanup (story 1.8) #8: All public types Send + Sync, async/await, Result<T, E>
• AC feat: crash recovery and graceful shutdown (story 1.9) #9: 3 integration tests against real fila-server subprocess

Test Summary

• 3 new integration tests (fila-client): lifecycle, nack/retry, error handling
• 267 existing tests pass (zero regressions)
• Clippy clean, fmt clean

New Files

• crates/fila-client/Cargo.toml
• crates/fila-client/src/lib.rs
• crates/fila-client/src/client.rs
• crates/fila-client/src/error.rs
• crates/fila-client/tests/integration.rs

---

Summary by cubic

Adds a new fila-sdk crate: an idiomatic Rust SDK wrapping the tonic FilaServiceClient with connect, enqueue, streaming lease, ack, and nack. Addresses Story 7.1 with per-operation error types, an ergonomic LeaseMessage, end-to-end tests, and CI that builds the workspace so tests can spawn fila-server.

• New Features

  • New fila-sdk crate with FilaClient::connect and ConnectOptions (addr, timeout).
  • enqueue returns message ID; lease streams LeaseMessage; ack/nack supported; LeaseMessage flattens proto types.
  • Client is Clone + Send + Sync; async API; 3 integration tests; CI builds workspace so fila-server is available.

• Refactors

  • Replaced single ClientError with per-operation errors (ConnectError, EnqueueError, LeaseError, AckError, NackError); lease stream items use StatusError only.
  • Renamed crate to fila-sdk; updated artifacts to mark Story 7.1 and Epic 7 done; integration tests fail fast and filter None keepalive frames.
  • Formatting fixes in fila-sdk to keep code style clean.

^{Written for commit d052e4f. Summary will update on new commits.}

[cubic-dev-ai]

2 issues found across 10 files

Prompt for AI agents (all issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="crates/fila-client/tests/integration.rs">

<violation number="1" location="crates/fila-client/tests/integration.rs:94">
P2: The startup poll never asserts that the server actually became reachable. If the timeout elapses, the test proceeds with an unusable client, leading to confusing downstream failures. Track whether a connection succeeded and assert after the loop.</violation>
</file>

<file name="crates/fila-client/src/client.rs">

<violation number="1" location="crates/fila-client/src/client.rs:118">
P2: Missing `message` fields in a lease response are silently dropped due to `?` inside `filter_map`. This hides protocol errors and can leave consumers unaware of a malformed response. Return an explicit error when `message` is `None` instead of filtering it out.</violation>
</file>

_{Reply with feedback, questions, or to request a fix. Tag @cubic-dev-ai to re-run a review.}

[cubic-dev-ai]

P2: Missing message fields in a lease response are silently dropped due to ? inside filter_map. This hides protocol errors and can leave consumers unaware of a malformed response. Return an explicit error when message is None instead of filtering it out.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At crates/fila-client/src/client.rs, line 118:

<comment>Missing `message` fields in a lease response are silently dropped due to `?` inside `filter_map`. This hides protocol errors and can leave consumers unaware of a malformed response. Return an explicit error when `message` is `None` instead of filtering it out.</comment>

<file context>
@@ -0,0 +1,173 @@
+
+        let stream = response.into_inner().filter_map(|result| match result {
+            Ok(lease_response) => {
+                let msg = lease_response.message?;
+                let metadata = msg.metadata.unwrap_or_default();
+                Some(Ok(LeaseMessage {
</file context>

[vieiralucas]

It annoys me that every method can return all the errors by the types. But that's not true. And for instance lease, the returned Result can have a QueueNotFound, but the inner one can never produce a QueueNotFound.