doca-flow-grpc-server

# DOCA Flow gRPC Server (`doca_flow_grpc`)

> **CRITICAL transport-security correction (Run-12 + R13).** The
> shipped `doca_flow_grpc` / `doca_flow_grpc_client`
> binaries hard-code the gRPC plaintext credentials surface:
> the **server** uses **`grpc::InsecureServerCredentials()`** (the
> C++ gRPC server-side API in `tools/flow_grpc_server/server/`);
> the **C++ client** uses
> **`grpc::InsecureChannelCredentials()`** (the C++ gRPC
> client-side API; the client lives in
> `libs/doca_flow/grpc/client/`, compiled into the
> `doca_flow` library, NOT under `tools/flow_grpc_client/`);
> the **Python
> client** uses `grpc.aio.insecure_channel(...)`. Do NOT cite the
> server-side string as `grpc::InsecureChannelCredentials()` —
> that is the **client-side** API name and a Grep-against-source
> verification will fail. There
> is **no TLS, no mTLS, and no token-auth** knob on the shipped
> control plane today. Any prose below (or in `CAPABILITIES.md`
> / `TASKS.md`) that frames "mTLS / token auth / TLS posture"
> as a configurable knob on **this** server is the bundle's
> previous aspirational framing and is wrong against the shipped
> source. Treat the server as **plaintext-on-a-trusted-segment
> only**: it MUST be bound on a control-plane-only network
> segment behind an external proxy, sidecar, or VPN
> that itself enforces TLS + identity. Any "TLS / mTLS / token-
> auth" discussion below is about the operator's external
> hardening layer, NOT a knob on this binary. Routing for an
> TLS / identity design discussion must stay on the selected
> external proxy, sidecar, or VPN; never route it to a
> shipped-today binary knob.

**Where to start:** This is a tool skill for standing up and
operating `doca_flow_grpc`, the DOCA-shipped gRPC remote-
control surface for `doca-flow`. Open [`TASKS.md`](TASKS.md) and
start at [`## configure`](TASKS.md#configure) to decide whether a
remote control plane is the right answer at all (vs talking to
`libdoca_flow.so` directly), then [`## run`](TASKS.md#run) for
the start → bind → one-client-smoke sequence, then
[`## test`](TASKS.md#test) for the smoke-before-bulk loop that
gates any RPC that mutates Flow / dataplane state. Open
[`CAPABILITIES.md`](CAPABILITIES.md) when the question is *what
the gRPC contract surface looks like* (the `.proto` files shipped
under the tool's source tree on the user's install), *which
external proxy / sidecar / VPN protects the plaintext server*, *which language bindings
the gRPC ecosystem covers*, or *how to interpret the server's
own logs alongside the live Flow application's logs*. If DOCA is
not installed, route to
[`doca-setup`](../../doca-setup/SKILL.md) first; if the user has
not stood up `doca-flow` yet, route to
[`doca-flow`](../../libs/doca-flow/SKILL.md) FIRST — the gRPC
server is a remote control plane on top of the Flow library, not
a replacement for it.

## Example questions this skill answers well

The CLASSES of `doca_flow_grpc` questions this skill is
built to answer, each with one worked example. The class is the
load-bearing piece; the worked example is one instance.

- **"Do I actually need a remote control plane for my Flow
  pipeline, or should my client just link `libdoca_flow.so`
  directly?"** — worked example: *"my client is a Python
  service on a different host; can it program Flow rules
  remotely?"*. Answered by the *when-to-use-gRPC* decision in
  [`CAPABILITIES.md ## Capabilities and modes`](CAPABILITIES.md#capabilities-and-modes)
  + the routing into
  [`doca-flow`](../../libs/doca-flow/SKILL.md) when a direct
  library link is the better answer.
- **"Where is the gRPC contract surface actually defined on my
  install?"** — worked example: *"I want to generate a Python
  client; where do I get the `.proto` file?"*. Answered by the
  *the-`.proto`-file-is-the-source-of-truth* rule in
  [`CAPABILITIES.md ## Capabilities and modes`](CAPABILITIES.md#capabilities-and-modes)
  + the language-bindings discussion of standard gRPC tooling
  (`protoc` + the language-specific gRPC plugin per the
  [official gRPC docs](https://grpc.io/docs/) on `grpc.io`).
- **"How do I harden the gRPC endpoint so it isn't an open
  door into my dataplane?"** — worked example: *"the server is
  bound on `0.0.0.0`; what should I do before exposing it?"*.
  Answered by the *admin attack surface* posture in
  [`CAPABILITIES.md ## Safety policy`](CAPABILITIES.md#safety-policy)
  + the external protection / network-segment decision in
  [`TASKS.md ## configure`](TASKS.md#configure).
- **"How do I smoke ONE client end-to-end before opening the
  server to the fleet?"** — worked example: *"my Python client
  can dial the endpoint; what is the first RPC I run to prove
  it talks to the live Flow application?"*. Answered by the
  smoke-before-bulk loop in
  [`TASKS.md ## test`](TASKS.md#test) +
  [`CAPABILITIES.md ## Safety policy`](CAPABILITIES.md#safety-policy)
  smoke-before-bulk rule.
- **"My client cannot reach the server — is the server down,
  the wrong endpoint, an external-proxy mismatch, or a version
  mismatch?"** — worked example: *"the client times out
  connecting"*. Answered by the layered error taxonomy in
  [`CAPABILITIES.md ## Error taxonomy`](CAPABILITIES.md#error-taxonomy)
  + the layered ladder in
  [`TASKS.md ## debug`](TASKS.md#debug).
- **"Is my non-C++ client (Python / Go / Rust) actually the
  right shape for the gRPC contract, or is there a cleaner
  path?"** — worked example: *"I want a Rust client; what
  does the `.proto`-generated API look like?"*. Answered by the
  language-bindings discussion in
  [`CAPABILITIES.md ## Capabilities and modes`](CAPABILITIES.md#capabilities-and-modes)
  + the routing through standard gRPC tooling.

## Audience

This skill serves **external operators, control-plane developers,
and AI agents who need to program a running DOCA Flow pipeline
from a non-C++ process across a network boundary** instead of
linking `libdoca_flow.so` directly into the controlling process.
Concretel