Epic: Spec-Driven Client Generation (multi-language)

[robfrank]

Summary

ArcadeDB exposes two independent, complementary API surfaces — an HTTP/OpenAPI surface and a gRPC/proto surface — but has no official generated clients for either. Every language binding today is either hand-written (the Java grpc-client module) or nonexistent (there is no JS/TS, Python, Go, C#, or Rust client at all). This Epic replaces "hand-write a client per language" with "generate clients from the server's own specs," starting with the highest-leverage gap: a thin, fetch-native TypeScript client for browser/edge, where ArcadeDB currently has zero footprint.

Two specs, two personas — do not unify them

• OpenAPI / HTTP (server/src/main/java/com/arcadedb/server/http/handler/OpenApiSpecGenerator.java) — universal transport, works from any language with fetch/an HTTP client, no proxy needed in a browser. Covers the full breadth of the server: admin, auth, core query/command/transaction data plane, time-series, Grafana, Prometheus, PromQL, MCP, and AI endpoints. This is the "batteries included" surface.
• gRPC (grpc/src/main/proto/arcadedb-server.proto, 653 lines, 2 services, 23 RPCs) — data-plane and admin-plane only, optimized for throughput: streaming queries, CRUD, bulk/bidirectional ingest, transactions, and a small admin service. HTTP/2-only, browser-hostile without a gRPC-web/Connect layer. This is the "performance tier."

These serve different personas (a dashboard calling fetch vs. a high-throughput ingest pipeline) and should not be collapsed into one spec or one client family. Ship a decision guide instead (last child issue).

Governing principle: spec completeness is the gate

A generated client is only as complete and correct as the spec it's generated from. Today the OpenAPI spec covers 22 of 61 known operations (36%) and has at least one auth-scheme bug (bearerAuth declared but unused). No generated client ships against the current spec. Milestone 0 blocks every other milestone.

Generate in CI, never hand-maintain generated code

The server already serves its own OpenAPI spec at /api/v1/openapi.json at runtime. CI should stand up a live instance (reusing the e2e-* Testcontainers pattern already in the repo) and generate clients from that live spec, and run buf generate against the proto. Regeneration happens every release; generated code is never hand-edited.

Success criteria

• OpenAPI spec covers 100% of registered HTTP routes (all 61, including the 10 plugin-contributed ones), verified by a CI-enforced anti-drift test.
• bearerAuth is correctly attached to operations that support API-token auth.
• A thin, tree-shakeable, fetch-native TypeScript client ships for browser/edge/Node from the completed OpenAPI spec.
• Multi-language HTTP clients (Python, C#, Go, Rust) fan out from the same completed spec.
• A Connect-ES TypeScript gRPC client covers the streaming/ingest performance tier, usable in both browser and Node without a proxy.
• Per-language gRPC clients exist for Go, Python, and C#.
• All generated clients regenerate from the server's own live spec/proto in release CI and are versioned to the server release.
• A published "which client should I use?" guide plus a capability/version matrix exists in arcadedb-docs.

Checklist of child issues

• Clients: complete the OpenAPI spec to match the registered HTTP route surface #4895 — Complete the OpenAPI spec to match the registered HTTP route surface (M0)
• Clients: anti-drift contract test for the OpenAPI spec #4896 — Anti-drift contract test / structural derivation for the OpenAPI spec (M0)
• Clients: generate a thin fetch-native TS client from OpenAPI #4897 — Generate a thin fetch-native TS client from OpenAPI (M1)
• Clients: fan out multi-language REST clients via openapi-generator #4898 — Fan out multi-language REST clients via openapi-generator (M2)
• Clients: proto packaging + buf setup for multi-language gRPC codegen #4899 — Proto packaging + buf setup for multi-language gRPC codegen (M3)
• Clients: generate a Connect-ES TS gRPC client #4900 — Generate a Connect-ES TS gRPC client (M3)
• Clients: generate per-language gRPC clients (Go, Python, C#) #4901 — Generate per-language gRPC clients: Go, Python, C# (M3)
• Clients: release-time generation & publish automation #4902 — Release-time client generation & publish automation (M4)
• Clients: client-selection guide + capability/version matrix #4903 — Client-selection guide + capability/version matrix (M4)

Dependency-ordered implementation sequence

M0 (gate, sequential):        #4895 → #4896
M1 (priority, after M0):      #4897
M2 (parallel, after M0):      #4898  (Python + C# + Go + Rust sub-tracks parallelize internally)
M3 (parallel, own gate):      #4899 → { #4900, #4901 }  (#4900 and #4901 parallelize once #4899 lands)
M4 (final):                   #4902 (needs #4895-#4901) → #4903 (needs #4897,#4898,#4900,#4901; benefits from #4902)

• Clients: complete the OpenAPI spec to match the registered HTTP route surface #4895 and Clients: anti-drift contract test for the OpenAPI spec #4896 are strictly sequential and block everything else.
• Clients: generate a thin fetch-native TS client from OpenAPI #4897 (priority TS/HTTP client) and Clients: fan out multi-language REST clients via openapi-generator #4898 (breadth REST clients) parallelize with each other once Clients: complete the OpenAPI spec to match the registered HTTP route surface #4895 lands.
• Clients: proto packaging + buf setup for multi-language gRPC codegen #4899 is an independent second gate, parallel to the whole OpenAPI track (M0-M2) — can start on day one alongside Clients: complete the OpenAPI spec to match the registered HTTP route surface #4895.
• Clients: generate a Connect-ES TS gRPC client #4900 and Clients: generate per-language gRPC clients (Go, Python, C#) #4901 parallelize with each other once Clients: proto packaging + buf setup for multi-language gRPC codegen #4899 lands, and both are independent of the entire M1/M2 OpenAPI-client track.
• Clients: release-time generation & publish automation #4902 is the true convergence point — needs every client-producing issue (Clients: complete the OpenAPI spec to match the registered HTTP route surface #4895-Clients: generate per-language gRPC clients (Go, Python, C#) #4901) done.
• Clients: client-selection guide + capability/version matrix #4903 can start drafting early but can't finalize until Clients: generate a thin fetch-native TS client from OpenAPI #4897/Clients: fan out multi-language REST clients via openapi-generator #4898/Clients: generate a Connect-ES TS gRPC client #4900/Clients: generate per-language gRPC clients (Go, Python, C#) #4901 ship real packages.

Non-goals

• Hand-writing new per-language clients (the entire point is to stop doing this — the existing hand-written grpc-client Java module is grandfathered as a reference, not a template).
• Unifying the HTTP and gRPC specs into one schema/IDL. They stay two specs serving two personas.
• Exposing admin/observability (time-series, Grafana, Prometheus, PromQL, MCP, AI, Raft/HA cluster management) over gRPC. gRPC stays data-plane + a minimal admin service; the full admin/observability surface stays HTTP-only.
• Retrofitting the existing grpc-client Java module to be regenerated — out of scope for this Epic unless a follow-up issue is opened.

Notes on scope verification

This Epic and its child issues were drafted after auditing the actual source (HttpServer.java, OpenApiSpecGenerator.java, arcadedb-server.proto, grpc-client/, e2e-js/e2e-python/e2e-csharp) rather than assumption. Notably: the spec/route drift is larger than commonly assumed (61 total operations including 10 contributed by plugins the spec generator has no visibility into), the gRPC proto has a second, previously-unlisted admin service (9 RPCs), and the existing e2e-* modules currently test wire-protocol compatibility (Bolt, Postgres) only — none exercise HTTP or gRPC yet, so new e2e coverage is required rather than a retrofit.