HD SDK — Interface Binding Contract

This document defines the mandatory interface binding requirements for the HD SDK (hd_sdk). All consumers must supply explicit network interface names when initializing the SDK. The SDK itself never reads environment variables for interface names.

Background

HD separates network traffic across three dedicated planes:

Docker Compose Interface Order

In Docker Compose, multiple networks attached to a container are assigned kernel interface names in alphabetical order by network name:

hd_controlplane  → eth0
hd_dataplane     → eth1
hd_observability → eth2

Kubernetes Interface Order

In Kubernetes with Multus (or similar CNI), interfaces are assigned in the order the networks are listed in the pod annotation. Follow the same data/control/observability order as above to guarantee eth0 = control, eth1 = data, eth2 = observability.

C++ SDK Constructors

// Ingest client — binds the FHDWP data plane transport to data_plane_interface,
// and the control plane to control_plane_interface.
// Pass empty strings to bind to all interfaces (0.0.0.0).
explicit FermiHDIIngestClient(const std::string& data_plane_interface = "",
                               const std::string& control_plane_interface = "");

// Query client — same semantics as above.
explicit FermiHDIQueryClient(const std::string& proxy_url = "",
                              const std::string& data_plane_interface = "",
                              const std::string& control_plane_interface = "");

Example (C++, Docker Compose sandbox)

// Docker Compose: hd_controlplane=eth0, hd_dataplane=eth1
auto ingest_client = std::make_unique<fermihdi::sdk::FermiHDIIngestClient>("eth1", "eth0");
auto query_client  = std::make_unique<fermihdi::sdk::FermiHDIQueryClient>("", "eth1", "eth0");

Go SDK

The Go CGO wrapper exposes two constructors:

// Convenience wrapper that binds to all interfaces (0.0.0.0).
func NewQueryClient(proxyURL string) *QueryClient

// Full constructor with explicit interface names.
// dataPlaneIface: kernel interface name for FHDWP data receive port (e.g. "eth1").
// ctrlPlaneIface: kernel interface name for mTLS control plane (e.g. "eth0").
func NewQueryClientWithInterfaces(proxyURL, dataPlaneIface, ctrlPlaneIface string) *QueryClient

Example (Go, using env vars set by Docker Compose or K8s)

// The consumer service reads interface names from env vars (set by compose.yml / K8s manifests)
// and forwards them to the SDK. The SDK itself does not read env vars.
dataPlane := os.Getenv("FERMIHDI_DATA_PLANE_INTERFACE")    // e.g. "eth1"
ctrlPlane := os.Getenv("FERMIHDI_CONTROL_PLANE_INTERFACE") // e.g. "eth0"

client := fermihdi.NewQueryClientWithInterfaces(proxyURL, dataPlane, ctrlPlane)

Environment Variables (Consumer Services Only)

Consumer services (hd_graphql, hd_mcp, hd_data_explore, hd_ipflow_graphql) must set the following environment variables in their Docker Compose environment: blocks or Kubernetes manifests:

[!IMPORTANT] These env vars are consumed by the application layer (Go/Python wrappers), not by the C++ SDK directly. The application layer must read these values and pass them to the SDK constructor. Do not rely on the SDK to read env vars automatically.

[!WARNING] Failing to supply interface names results in the SDK binding to 0.0.0.0 (all interfaces). In a segmented network deployment, this causes the HD engine's reactor to receive its own internal SIGUSR1/SIGUSR2 signals on the HTTP library's thread pool, leading to SIGSEGV. Always provide explicit interface names in production.