feat: replace grpc with fibp binary protocol

[vieiralucas]

Summary

• Migrates the Java SDK from gRPC/protobuf to the Fila binary protocol (FIBP), matching the server's removal of gRPC in Epic 20
• Adds dev.faisca.fila.fibp codec package: Primitives (big-endian encoding), Opcodes, Codec (frame encoding for all 42 opcodes), FrameHeader, and Connection (TCP/TLS, handshake, multiplexed request/response, server-push delivery, ping/pong, continuation frame reassembly)
• Rewrites FilaClient to use FIBP for all operations, adds admin ops (createQueue, deleteQueue, setConfig, getConfig, redrive) and auth ops (createApiKey, revokeApiKey, setAcl)
• Removes all gRPC and protobuf dependencies — zero external runtime dependencies
• Updates RpcException to use FIBP error codes instead of gRPC status codes
• Version bump to 0.3.0
• 40 tests passing: 27 unit + 13 integration (including TLS + API key auth)

Test plan

• Unit tests: PrimitivesTest (11 round-trip tests for all encoding primitives)
• Unit tests: BatchModeTest, EnqueueResultTest, BuilderTest (configuration validation)
• Integration tests: FilaClientTest (enqueue/consume/ack lifecycle, nack redelivery, nonexistent queue error)
• Integration tests: BatchClientTest (explicit batch, auto batching, linger batching, disabled batching, cross-queue batch errors)
• Integration tests: TlsAuthClientTest (TLS + API key, rejection without API key)
• Code formatting: spotlessApply passes

---

Summary by cubic

Replaced gRPC/protobuf with the Fila binary protocol (FIBP) in the Java SDK to remove external deps and add admin/auth features. Adds smart enqueue batching and addresses review feedback with stricter TLS builder checks and safer stream cancellation.

• New Features

  • Added dev.faisca.fila.fibp codec: primitives, opcodes, frame encoding, and a TCP/TLS Connection with handshake, multiplexed req/resp, server-push delivery, ping/pong, and continuation reassembly.
  • Rewrote FilaClient to use FIBP for enqueue/consume/ack/nack; added admin ops (create/delete queue, set/get config, redrive) and auth ops (create/revoke API key, set ACL).
  • Added BatchMode, background Batcher, enqueueMany, per-item EnqueueResult; default opportunistic batching with linger and disabled options.
  • Updated RpcException to expose FIBP error codes; tightened builder validation (e.g., client cert/key require TLS) and improved consume cancellation handling.
  • 40 tests passing (27 unit, 13 integration incl. TLS + API key).

• Migration

  • Removed io.grpc and com.google.protobuf dependencies and the Gradle protobuf plugin; zero external runtime deps.
  • Version bump to 0.3.0.
  • Error handling now uses FIBP error codes; use RpcException.getErrorCode() instead of gRPC status codes.

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

[cubic-dev-ai]

11 issues found across 24 files

Prompt for AI agents (unresolved 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="src/test/java/dev/faisca/fila/TlsAuthClientTest.java">

<violation number="1" location="src/test/java/dev/faisca/fila/TlsAuthClientTest.java:86">
P2: `assertNotNull(ex.getMessage())` is too weak here and can pass for unrelated connection failures, so the test no longer verifies API-key auth rejection specifically.</violation>
</file>

<file name="src/main/java/dev/faisca/fila/fibp/Codec.java">

<violation number="1" location="src/main/java/dev/faisca/fila/fibp/Codec.java:83">
P3: Javadoc opcode value is wrong: `ACK` is `0x16`, not `0x15` (0x15 is `CANCEL_CONSUME`).</violation>

<violation number="2" location="src/main/java/dev/faisca/fila/fibp/Codec.java:94">
P3: Javadoc opcode value is wrong: `NACK` is `0x18`, not `0x17` (0x17 is `ACK_RESULT`).</violation>
</file>

<file name="src/test/java/dev/faisca/fila/TestServer.java">

<violation number="1" location="src/test/java/dev/faisca/fila/TestServer.java:91">
P2: Restore the interrupt flag when handling `InterruptedException` instead of swallowing it in a combined catch block.</violation>
</file>

<file name="src/main/java/dev/faisca/fila/fibp/Primitives.java">

<violation number="1" location="src/main/java/dev/faisca/fila/fibp/Primitives.java:81">
P1: `writeString` can silently overflow its U16 length prefix, producing invalid frames for long strings.</violation>

<violation number="2" location="src/main/java/dev/faisca/fila/fibp/Primitives.java:93">
P1: `writeStringMap` can overflow the U16 element count and corrupt decoding for large maps.</violation>

<violation number="3" location="src/main/java/dev/faisca/fila/fibp/Primitives.java:184">
P1: `readBytes` should validate decoded length before allocating to avoid malformed-frame crashes or excessive allocation.</violation>
</file>

<file name="src/main/java/dev/faisca/fila/fibp/Connection.java">

<violation number="1" location="src/main/java/dev/faisca/fila/fibp/Connection.java:83">
P1: Socket and stream resources leak if `performHandshake()` throws. Wrap the handshake (and read-loop start) in a try-catch that closes the socket on failure.</violation>

<violation number="2" location="src/main/java/dev/faisca/fila/fibp/Connection.java:192">
P2: `readFrame()` returns `null` for continuation frames, but `performHandshake()` dereferences the result without a null check, risking an NPE. Loop until a non-null frame is received.</violation>
</file>

<file name="src/main/java/dev/faisca/fila/FilaClient.java">

<violation number="1" location="src/main/java/dev/faisca/fila/FilaClient.java:152">
P2: `InterruptedException` caught without restoring the interrupt flag. All `catch (IOException | InterruptedException e)` blocks in this class wrap the exception but never call `Thread.currentThread().interrupt()`, unlike the batched `enqueue()` path which handles it correctly. This drops the interrupt signal, breaking cooperative cancellation for callers.</violation>

<violation number="2" location="src/main/java/dev/faisca/fila/FilaClient.java:596">
P1: Connection and client leak in leader redirect. `leaderConn` is never closed — `AutoCloseable.close()` is not called by GC, and the `ConsumerHandle` returned by `leaderClient.consume()` is discarded, so the redirected consumer can never be cancelled or its connection released.</violation>
</file>

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

[cubic-dev-ai]

1 issue found across 7 files (changes from recent commits).

Prompt for AI agents (unresolved 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="src/main/java/dev/faisca/fila/FilaClient.java">

<violation number="1" location="src/main/java/dev/faisca/fila/FilaClient.java:643">
P1: Blocking on `handle.awaitDone()` in leader redirection can make redirected consumers non-cancellable and leave background consume threads running indefinitely.</violation>
</file>

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

[cubic-dev-ai]

P1: Blocking on handle.awaitDone() in leader redirection can make redirected consumers non-cancellable and leave background consume threads running indefinitely.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At src/main/java/dev/faisca/fila/FilaClient.java, line 643:

<comment>Blocking on `handle.awaitDone()` in leader redirection can make redirected consumers non-cancellable and leave background consume threads running indefinitely.</comment>

<file context>
@@ -598,11 +638,11 @@ private void retryConsumeOnLeader(
-        // This is called from within the consumer thread, so we just let it run
+        // Block until the consumer thread finishes. This method is called from
+        // within the original consumer thread, so blocking here is expected.
+        handle.awaitDone();
       } finally {
-        // Connection will be closed when the temporary client is GC'd or when
</file context>

[vieiralucas]

Closing unmerged. Fila is being rewritten from scratch and now ships a single client, in Rust.

Maintaining five thin SDK ports cost more than it returned — each one lagged the protocol, and this migration is the evidence: five parallel PRs, all green, all sitting unmerged for months because keeping them in step with a moving wire format was the bottleneck rather than the work itself.

The protocol has also moved past what this PR implements. Version 2 (faiscadev/fila@282984f) changes hot-path layouts: 16-byte message IDs instead of 36-char strings, u32 admin list counts, scheduling metadata on Enqueue, credit-based flow control, plus ExtendLease and delayed-Nack opcodes. Rebasing this onto v2 would be a rewrite, not a merge.

The work here was sound and the Cubic findings on it were addressed. It is preserved on the branch if anyone wants to build a Go/Python/JS/Ruby/Java client against v2 — docs/protocol.md is written to be implementable from the document alone.