ByteVeda / ByteVeda/flexiq

epic: a remote SDK tier, so someone else can add a language

Open
#835 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

area/wire epic P0
Dominant language
Rust
Stars
20
Forks
2
Avg merge
5h 10m
Merged PRs (30d)
127

Description

Why

Adding a language to FlexiQ currently means writing a native binding: a crate under crates/,
an FFI layer, a build matrix entry, and a permanent parity obligation against
crates/flexiq-core/BINDING_CONTRACT.md. Three languages have paid that price. Nobody outside
this repository can pay it.

2.0 changed the economics and the repository has not caught up. flexiq.v1.ProducerService
speaks gRPC and plain HTTP with JSON bodies, seeded from a committed descriptor at
contracts/descriptor.binpb so a client needs no .proto on hand. A client in any language is
now a normal client, not a build-system problem.

What is missing is everything that makes that fact usable: a written contract for the tier, one
reference implementation, a spec that generators can eat, and a way to talk to a server without
importing an SDK at all.

Shape

  • REMOTE_SDK_CONTRACT.md beside BINDING_CONTRACT.md — what a gRPC-only SDK must
    implement, what it is allowed to omit, and where the two tiers' compatibility obligations
    differ. #710 already established that the FFI contract and the network contract are separate
    documents with separate promises; this writes the second one down.
  • A Go client as the reference. Largest audience with no current option, and it proves the
    contract by being written against it.
  • A Rust client. Conspicuous absence for a Rust project — today a Rust user drops to
    flexiq-core raw.
  • An OpenAPI spec, generated from the proto, since the JSON transcoding already exists.
  • A standalone CLI over gRPC, so operating a server does not require installing an SDK.
  • The descriptor published as a release asset, with reflection-only clients documented.

What this is not

Not more FFI bindings. Every native SDK is a permanent build-matrix tax. The remote tier
exists so the next five languages do not pay it. A language arriving over gRPC is the intended
outcome, not a second-class one.

Not a promise that remote equals embedded. A remote client cannot run tasks in-process,
cannot use the attach path, and reaches admin operations only as far as the proto exposes them
(today: not far — see the wire epic). The contract must state the delta plainly.

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start by reading crates/flexiq-core/BINDING_CONTRACT.md, the referenced ProducerService contract, and contracts/descriptor.binpb. Map the separate remote-tier promises and their embedded-client differences before scoping the Go and Rust clients, OpenAPI output, standalone CLI, and descriptor release documentation. Done means the listed remote-tier artifacts and access paths are specified and delivered together.

Written by the indexing model from the issue text.

Assessment

Tech stack
go, grpc, openapi, rust
Domain
api, cli, distributed-systems, documentation
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Active
Clarity
Mostly clear
Newbie friendliness
25/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.