Imported from yuuki/rpingmesh (
AGENTS.md). Install upstream withnpx skills add yuuki/rpingmesh. Copyright stays with the author.
Repository Guidelines
Project Structure
cmd/agentandcmd/controllercontain the active binary entry points.internal/contains the active Go implementation:agent/runs probing, responding, controller synchronization, and analysis reporting.config/loads YAML, environment, and CLI configuration.controller/implements the gRPC service, registry, pinglist generation, and Phase 1 analyzer.probe/defines probe results and timing calculations.rdmabridge/is the Go/Cgo boundary to the Zig RDMA library.telemetry/exports OpenTelemetry metrics.testutil/contains shared test helpers.
zig/contains the RDMA data-path library and its public C ABI inzig/include/rdma_bridge.h.proto/contains gRPC sources; generated*.pb.gofiles live beside them.configs/contains example agent and controller configuration.e2e/contains controller and RDMA end-to-end tests.packaging/contains nfpm definitions and systemd units.dashboards/anddeploy/contain the observability assets and local stack.docs/design/contains design documentation.legacy/archives the previous implementation as a separate Go module.
Build, Test, and Development Commands
Run active-development commands from the repository root.
make build: Build the Zig library, generate protobuf bindings, and build both binaries.make build-zig: Buildzig/zig-out/lib/librdmabridge.a.make generate-proto: Regenerate Go protobuf and gRPC bindings.make build-controller: Build the pure-Go controller.make build-agent: Build the Linux/Cgo agent linked to the Zig RDMA library.make test: Run the portable Go probe tests.make vet: Rungo vetfor all Go packages.make test-all: Run Zig tests and all non-e2e Go tests in a Linux RDMA build environment.make test-e2e-controller: Run the controller integration path in Docker.make test-e2e: Run the privileged soft-RoCE/RDMA end-to-end suite.make package: Build agent and controller.deband.rpmpackages.make obs-up,make obs-down,make obs-seed,make obs-logs, andmake obs-verify: Operate and verify the local observability stack.
Toolchain and Platform Constraints
- Use Go 1.27 or newer, Zig 0.15.2, protoc, protoc-gen-go, and protoc-gen-go-grpc.
- Agent builds require Linux, Cgo, libibverbs, and librdmacm. Agent runtime and RDMA e2e tests additionally require RDMA hardware or privileged soft-RoCE.
- The controller is pure Go (
CGO_ENABLED=0) and has no RDMA dependency.
Coding and Documentation
- Follow standard Go conventions and run
gofmton edited Go files. - Keep code comments and repository documentation in English.
- Do not edit generated
proto/controller_agent/*.pb.gofiles by hand. - After changing a
.protofile, runmake generate-proto. - Keep the Zig C ABI,
zig/include/rdma_bridge.h, andinternal/rdmabridge/bridge.gosynchronized. - Prefer simple, systematic solutions and update documentation with behavior or workflow changes.
Testing and Change Management
- Keep Go tests in
*_test.gofiles withTestXxxnames. - Use Conventional Commits (for example,
feat:,fix(agent):,docs:, orci:). - PRs must state their purpose, impact, and commands run.
- Explicitly document breaking changes, required privileges, kernel constraints, and RDMA dependencies in PRs.
- Do not modify
legacy/unless the task explicitly requests legacy maintenance.
