feat: 30.2 — unified api surface

[vieiralucas]

Summary

• Update JS SDK for unified API from Story 30.1
• Replace batchEnqueue() with enqueueMany() (no "batch" prefix)
• enqueue(), ack(), nack() all use the unified repeated-message proto format
• consume() uses only the messages field (singular message field removed from proto)
• Batcher uses unified Enqueue RPC for all batch sizes (no more separate BatchEnqueue RPC)
• Fix batcher drain race condition: track in-flight RPCs to prevent premature channel close
• Regenerate proto types, remove stale BatchEnqueue* generated files

Test plan

• All 30 tests pass (7 unit, 23 integration)
• TypeScript typecheck clean
• ESLint clean
• enqueueMany() tests cover multi-message, partial errors, ordering
• Auto/linger/disabled batch modes all pass
• Drain-on-close test passes (was broken before in-flight tracking fix)
• TLS + API key auth tests pass

---

Summary by cubic

Unifies the JS SDK with the new API: single Enqueue with repeated messages and typed per-result errors across enqueue, ack, nack, and consume. Aligns with Linear Story 30.1 and fixes a batcher drain race.

• New Features

  • Unified Enqueue uses repeated messages with per-result outcomes; SDK maps typed errors to rich error classes.
  • ack()/nack() use repeated formats with per-item results; MESSAGE_NOT_FOUND maps to MessageNotFoundError.
  • consume() reads only messages[]; the batcher always calls the unified Enqueue.

• Migration

  • Replace batchEnqueue() with enqueueMany(). Update types from BatchEnqueueResult to EnqueueResult.
  • No changes needed for existing enqueue(), ack(), nack(), or consume() call sites.

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

[cubic-dev-ai]

1 issue found across 34 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="proto/fila/v1/service.proto">

<violation number="1" location="proto/fila/v1/service.proto:59">
P1: Reusing protobuf field numbers across this redesign risks silent data corruption during any mixed-version deployment. Every restructured message (EnqueueRequest, EnqueueResponse, ConsumeResponse, AckRequest, NackRequest) reuses field 1 with a different type.

Protobuf best practice is to `reserved` retired field numbers and start new fields at the next available number, or introduce a new package version (e.g., `fila.v2`). If this is a hard-cut with no rolling-deploy window, consider at minimum adding `reserved` declarations for the old field numbers as documentation to prevent future collisions.</violation>
</file>

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

[cubic-dev-ai]

P1: Reusing protobuf field numbers across this redesign risks silent data corruption during any mixed-version deployment. Every restructured message (EnqueueRequest, EnqueueResponse, ConsumeResponse, AckRequest, NackRequest) reuses field 1 with a different type.

Protobuf best practice is to reserved retired field numbers and start new fields at the next available number, or introduce a new package version (e.g., fila.v2). If this is a hard-cut with no rolling-deploy window, consider at minimum adding reserved declarations for the old field numbers as documentation to prevent future collisions.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At proto/fila/v1/service.proto, line 59:

<comment>Reusing protobuf field numbers across this redesign risks silent data corruption during any mixed-version deployment. Every restructured message (EnqueueRequest, EnqueueResponse, ConsumeResponse, AckRequest, NackRequest) reuses field 1 with a different type.

Protobuf best practice is to `reserved` retired field numbers and start new fields at the next available number, or introduce a new package version (e.g., `fila.v2`). If this is a hard-cut with no rolling-deploy window, consider at minimum adding `reserved` declarations for the old field numbers as documentation to prevent future collisions.</comment>

<file context>
@@ -6,57 +6,137 @@ import "fila/v1/messages.proto";
 message ConsumeResponse {
-  Message message = 1;           // Single message (backward compatible, used when batch size is 1)
-  repeated Message messages = 2; // Batched messages (populated when server sends multiple at once)
+  repeated Message messages = 1;
 }
 
</file context>

[vieiralucas]

Acknowledged — this is an intentional hard-cut redesign (Epic 30 API unification). Fila is pre-alpha with no rolling deployments or mixed-version scenarios. The server and all 6 SDKs are updated atomically in the same epic. Adding reserved declarations for retired field numbers is unnecessary here since there is no backward compatibility window to protect.

[cubic-dev-ai]

Thanks for the feedback! I've saved this as a new learning to improve future reviews.