agentleFS
hoophqhoophq/hoop/sidecar/CLAUDE.md

hoop / sidecar

CLAUDE.md848 starsChanged 24 days agoMITView on GitHub

Wire-protocol inspection as a library. Relay codecs turn raw database and HTTP/1 bytes into structured statements; libhoop/v2/codec/grpc owns the gRPC HTTP/2 endpoint and reusable protocol mechanics, while daemon/ injects identity, statement, policy, audit, and masking behavior. Policy turns either form into allow/deny verdicts, masked responses and an audit trail. The root CLAUDE.md does not cover this directory. It describes the product modules under go.work; sidecar/ contributes nine more entries and follows different rules. This file governs everything under sidecar/. The…

  • Reads credentials

The file

We split this CLAUDE.md into the rules it gives an agent

2 rules. About 0 are common, 0 are distinctive, and 2 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈0

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 2

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    Every new field also gets cap:"<name>", unless it ships in the same release as a tagged block around it: omitting the zero value hides an …

    line 260
  2. Very specific:

    sidecar protocol-specific parsers: if the code must be added to libhoop, the sidecar parsers must live under libhoop/v2/*.

    line 363

≈ “Common” is an estimate: at least 1 in 5 of the 27,641 CLAUDE.md files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
CLAUDE.md

CLAUDE.md: sidecar

Wire-protocol inspection as a library. Relay codecs turn raw database and HTTP/1 bytes into structured statements; libhoop/v2/codec/grpc owns the gRPC HTTP/2 endpoint and reusable protocol mechanics, while daemon/ injects identity, statement, policy, audit, and masking behavior. Policy turns either form into allow/deny verdicts, masked responses and an audit trail.

The root CLAUDE.md does not cover this directory. It describes the product modules under go.work; sidecar/ contributes nine more entries and follows different rules. This file governs everything under sidecar/.

The directory was called hoopinspect/ until the CLI command became hoop start sidecar. Nothing about the module changed with the name, but two packages moved so the tree stops stuttering: the inspection core is sidecar/inspect (it was the root package) and the assembly that was hoopinspect/sidecar is sidecar/daemon. The binary, its config directory and HOOP_INSPECT_CONFIG all keep the hoop-inspect spelling, because renaming those breaks running deployments.

Full documentation is README.md here (86 KB, read the section you need, not the whole thing).

The invariant: exactly one dependency

github.com/hoophq/hoop/sidecar depends on github.com/hoophq/libhoop and nothing else. It used to depend on nothing at all, and that was the product pitch — vendorable without a supply-chain review, readable end to end in an afternoon, compilable to wasip1. The protocol codecs moving to libhoop ended it: this module cannot describe its own inputs without naming the types the decoders produce.

libhoop is PRIVATE, so building or testing here needs GOPRIVATE=github.com/hoophq/libhoop and credentials for that repository. cmd/ and the nested ica/ module also link the private Citrix ICA engine, so they need GOPRIVATE=github.com/hoophq/libhoop,github.com/hoophq/libhoop-ica and credentials for both.

The edge runs one way and must stay that way. libhoop imports nothing from this repository. Two mechanisms hold that:

  • Types are aliased, not copied. inspect/wiretypes.go declares type Statement = codectypes.Statement and so on. Same type, not a conversion — which is why a libhoop codec satisfies the Codec interface here structurally, without importing this package, and why there is one definition of the document a policy evaluates rather than two that drift.
  • Behaviour is injected, not imported. The SQL classifier (AnalyzeSQL) and the lexer stay here, because they are the most safety-critical code in the system and there must be one auditable copy. sidecar/codec/* hands them to each decoder through its Options.

Check it:

cd ../libhoop && grep -rn '"github.com/hoophq/hoop' --include='*.go' .   # must be empty

Each optional component is its own module, so it can be plugged in or dropped without touching anything else. SQLite is the clean case: removing it is removing a directory.

ModuleCarries
cmd/the hoop-inspect binary, where the optional plugins are linked
config/yaml/gopkg.in/yaml.v3
pii/alcatraz/github.com/hoophq/alcatraz and github.com/hoophq/alcatraz/ner, the ONNX NER model runtime: pure Go by default, ONNX Runtime under -tags ORT
store/sqlite/modernc.org/sqlite, pure Go because the sidecar is a static binary
analyzer/vertex/golang.org/x/oauth2, the only analyzer provider needing one. It wraps the anthropic, gemini and openai encoders from the root under a GCP bearer; the API-key providers stay in the root
descriptors/gcs/golang.org/x/oauth2, to read a grpc lane's descriptor set from a gs:// URL
mcp/github.com/modelcontextprotocol/go-sdk, for the review status MCP server an mcp: block turns on (ADR-0021)
ica/github.com/hoophq/libhoop-ica, the Citrix ICA engine a protocol: ica lane embeds; registers through daemon.RegisterICAEngine, linked into hoop-inspect only
mcpgateway/github.com/hoophq/mcpproxy, the engine a protocol: mcp lane embeds; registers through daemon.RegisterMCPGatewayEngine, linked into hoop-inspect and hoop start sidecar
codec/wasm/github.com/tetratelabs/wazero, the codec plug-in host; daemon only sees LoadCodecPlugin. sdk/ and examples/ hold the guest side: Rust, TinyGo and C
telemetry/otlp/the OpenTelemetry SDK and its OTLP exporters, behind the telemetry block; daemon sees only telemetry.Builder, injected by cmd like LoadCodecPlugin. The contract is the root package telemetry/
lexer/conformance/PostgreSQL's real parser, test-only

Adding a dependency to the root still needs a reason. Add a nested module, or do without.

Commands

make test-sidecar at the repo root runs every module below, and make test-oss depends on it, so CI runs them too. The commands are here because the target is a loop over them and you will want one at a time.

make test-sidecar-plugins covers what test-sidecar cannot reach: the guest SDKs and the examples under codec/wasm. It runs cargo test on the Rust crate and examples/resp, GOWORK=off go test on the TinyGo module and examples/memcache (neither is in go.work, so the walk above skips them), then hoop-inspect -codec-test over every checked-in .wasm. It needs Go and Rust only, which is why the artifacts are committed; the plug-in workflow installs TinyGo and lld, rebuilds them from source and proves the rebuilds with -codec-test (no byte compare: rustc differs across OSes). test-oss depends on it.

The SDKs under codec/wasm/sdk release from one file, sdk/VERSION, repeated in sdk/rust/Cargo.toml and recorded in sdk/rust/Cargo.lock (cargo update -w after the bump); sdk/version.sh refuses a PR where the three differ. Merging a bump to main tags hoop-codec-vX.Y.Z (sidecar-plugins-autotag.yml), and from that tag sidecar-plugins-release.yml publishes the crate, tags the Go module sidecar/codec/wasm/sdk/tinygo/vX.Y.Z at the same commit, and opens the hoophq/plugins mirror PR, which carries the C header as sdk/c/hoop_codec.h. It creates no GitHub release: that list is the product's and the deploy tooling reads it. Never push either tag by hand.

make test-sidecar-e2e is a separate path: it boots a real mysql:8 container and runs the hoop-inspect binary as a subprocess in front of it, so it needs a working Docker daemon. It is deliberately NOT a dependency of test-oss or test-sidecar — those run in the unit-test job, which has neither Docker nor the minutes for a container boot — and has its own CI job instead. e2e/ is outside go.work, so it only builds under GOWORK=off; the make target sets that for you. See the gotcha below.

SIDECAR_E2E_GOWORK overrides the workspace the harness builds hoop-inspect against. Unset — which is what CI does, and what you want — the binary resolves through the repository's own go.work and therefore the PUBLISHED libhoop pin, which is the thing under test. Point it at a workspace with a local use directive to run the suite against an unmerged codec before it lands:

SIDECAR_E2E_GOWORK=/path/to/dev/go.work make test-sidecar-e2e

It is not in .env.sample: that file configures the gateway at runtime, and this is a test-only override read by one harness.

# root module (inspect/, lexer/, codec/, policy/, gate/, proxy/, daemon/, ...)
go test ./...
go vet ./...

# nested modules are NOT reached by the line above
for m in cmd config/yaml pii/alcatraz store/sqlite analyzer/vertex descriptors/gcs mcp ica lexer/conformance codec/wasm telemetry/otlp; do
  (cd "$m" && CGO_ENABLED=0 go test ./...)
done

# pii/alcatraz under -tags ORT is cgo; the real-model test runs only with the env set
(cd pii/alcatraz && CGO_ENABLED=1 HOOP_ALCATRAZ_MODELS_DIR=/opt/alcatraz/models HOOP_ALCATRAZ_ORT_LIBRARY=/opt/alcatraz/ort/releases/1.28.0/lib/libonnxruntime.so go test -tags ORT -run TestNERRealModel ./...)

# the oracle: run this for ANY change under lexer/
(cd lexer/conformance && CGO_ENABLED=0 go test ./...)

# validate a sidecar config without starting anything
(cd cmd && go run . -validate -config /path/to/config.yaml)

# prove a codec plug-in against the ABI, then its own fixtures
(cd cmd && go run . -codec-test /path/to/plugin.wasm /path/to/fixtures.json)

# the guest SDKs and the three examples; also proves every checked-in .wasm
(cd ../.. && make test-sidecar-plugins)

# end to end against a real mysql:8, needs Docker. GOWORK=off is required:
# e2e/ is deliberately not a go.work member.
(cd e2e && GOWORK=off CGO_ENABLED=0 go test -tags integration -count=1 ./...)

Gotchas

  • go test ./... at the root reaches no nested module. Separate go.mod files are what keeps optional dependencies out of the root, and the cost is that every nested module needs its own invocation. See the loop above.
  • CI reaches this through two targets, not one. make test-oss runs go test github.com/hoophq/hoop/..., which does not match module github.com/hoophq/hoop/sidecar, so the Makefile carries test-sidecar, which walks every go.mod under sidecar/ and which test-oss depends on. Break that dependency and those tests stop running everywhere except on your machine.
  • sidecar/e2e is the exception, and it is not in go.work. Its testcontainers/docker dependency tree has no business in the workspace every other module resolves against. The cost is that go refuses to work there under the workspace at all — cd sidecar/e2e && go test fails with "directory prefix . does not contain modules listed in go.work" — so both the suite and anything building it need GOWORK=off. This is also why test-sidecar filters its discovered module list against go.work instead of running everything find turns up: unfiltered, the walk enters e2e, hits that error and aborts the loop under set -e, taking test-oss with it. The suite runs only under make test-sidecar-e2e, from its own CI job, and needs Docker. Adding it to test-oss to "fix" the asymmetry puts a multi-minute container boot on every unit run in a job with no Docker guarantee.
  • A lexer/ change is not verified until the conformance suite passes. lexer/conformance/ runs PostgreSQL's own parser and the scanner over the same statements and fails on disagreement. The scanner is hand-written and deliberately not a parser, so the oracle is the only thing standing between a plausible change and a wrong one. It runs under CGO_ENABLED=0 because the parser is a wasm build.
  • A false positive in the lexer is an outage, not a warning. A statement misread as a write is refused by a read-only lane. Reserved words are legal column aliases when AS is written, and BI tools emit them: Metabase's schema sync sends has_table_privilege(..., 'delete') AS delete. Widening the classifier costs an operator their tool. Add the case to lexer/conformance corpus in oracle_test.go and let the real parser judge.
  • Codecs register a factory, not an instance (inspect/registry.go). Codecs that reassemble messages across packets hold per-connection state, so a shared instance would let one connection's SQL surface in another's audit trail. Register panics on a duplicate protocol, because import order deciding a winner is worse than a build failure.
  • inspect imports no codec, and no longer ships one. The decoders live in github.com/hoophq/libhoop, a private module, under its v2/codec/* directory — v2 there is a folder name, not a major version. libhoop imports NOTHING from this repository; the types it returns are defined there and aliased here, so its codecs satisfy Codec structurally.
  • sidecar/codec/* is the registration seam, not a decoder. libhoop cannot call Register, so these packages do it, and they are also where AnalyzeSQL and the lexer get injected into a decoder. codec/http is not thin: its *Codec embeds libhoop's Inspector and adds the relay concerns libhoop has no reason to know (path cleaning, Connect Gateway resource normalization, credential lifting for per-request identity, the Via loop marker, and the refusal of a known credential outside its header, placement.go). Import codec/all for postgres, mysql, mssql and http, or one package for one protocol so a binary fronting Postgres never links the TDS, MySQL and HTTP machinery.
  • gRPC deliberately has no inspect.Codec. Its HTTP/2 endpoint and reusable protocol mechanics live in libhoop/v2/codec/grpc; daemon/ injects callbacks that enter gate.EvaluateStatement, policy, audit, and masking. Adding a registry decoder to codec/all would restore the connection-fatal denial and nested-length masking bugs ADR-0013 rejects.
  • Adding a protocol is not one package. The codec seam is the smallest part of it. A lane also needs a lexer Dialect (selected in inspect.AnalyzeSQL), a deny frame in proxy/deny.go, an analyzer content builder in analyzer/content.go, and the Protocol constant aliased in inspect/wiretypes.go. Every one of those fails QUIETLY when it is missing: the wrong dialect misreads a statement, a missing deny frame closes the socket with no message, a missing builder makes ai_analysis rules classify nothing. README.md's Protocols section carries the table. A new protocol also needs a label in daemon/schema.go protocolLabels.
  • ICA is an endpoint lane that embeds an engine and has no codec. A Citrix session carries pixels and no statements, so Validate refuses guardrail rules, mask rules, an analyzer and OPA on a protocol: ica lane. daemon/ica.go holds the whole contract (config blocks, ICALane/ICAServer, RegisterICAEngine, the audit bridge), and the engine (sidecar/ica, a nested module on github.com/hoophq/libhoop-ica) registers from init. Protocols() lists ica in every build, so the plane renders its form; the capabilities header lists protocol:ica only when an engine is registered, so the plane does not serve an ica lane to a build that checkICA would refuse. The engine's builder must not bind a socket or load a model: Validate constructs it on the plane and on macOS.
  • A new ListenerConfig field needs a UI tag. The control plane renders its listener form from daemon/schema.json. Tag the field label:"...", or ui:"-" to keep it out of the form, then regenerate: go test ./daemon -run TestListenerSchemaIsCurrent -update.
  • Every config field omits its zero value, and a field an older build must not receive carries cap:. The control plane serves its own copy of daemon.Config, and a build that predates a key refuses the whole document over it (ADR-0022). omitempty on scalars, pointers, slices and maps; omitzero on structs, and on rules, where [] is an opt-out. TestEveryConfigFieldOmitsItsZeroValue refuses a field with neither. Every new field also gets cap:"<name>", unless it ships in the same release as a tagged block around it: omitting the zero value hides an unset key, but an older build still refuses the key once an admin sets it. That missing tag let google_identity, trust, mcp, postgres and ssh.relay crash older sidecars (EVL-338). The header the sidecar sends on its handshake is generated from the tag, and the plane refuses to serve a document that sets it to a build without the entry. make test-sidecar-compat (CI job sidecar-compat) decodes a document with every field set using the previous release, and fails on a new field without the tag. A field that already shipped also carries since:"<release>", the release read from the git tags, so a build from before the header is refused it by its reported version; a new field leaves since off until its release exists. Rule types and protocols reach the header on their own, through policy.RuleTypes and daemon.Protocols. baselineCapabilities is frozen: it names what the builds before the header decode, each entry with the release it shipped in when that is later than 1.162.0, and nothing is ever added to it.
  • Construct codecs through the seam, never libhoop directly. A decoder built with the zero Options has no classifier: it reports statement text with OpUnknown. That fails closed, but it means a policy naming select matches nothing.
  • A plug-in protocol is config-level, never build-level. plugins: names the module and its x- protocol; Setup loads the module on the host, and Validate accepts the lane from the entry alone because the control plane never loads one. So an x- protocol is NOT in Protocols(), not in schema.json, not a protocol: header entry and never in baselineCapabilities: the plane grants it by the plugins capability. Adding it to any of those lists makes the build claim a protocol it does not link.
  • The license verifier exists twice, on purpose. sidecar/license reimplements common/license over the stdlib: same key, same RSA-PSS signature over the same bytes, same JSON. Importing the gateway's module would end the one-dependency invariant, so the copy is the price. Drift locks paying customers out of features they bought and neither module can see it, so client/licensecompat pins the two. Touch the key or the signing data on one side and you MUST touch the other.
  • The license verdict is a function of the clock. license.Status stores "the signature checked out" and derives everything else from the term, so a relay that has been up for months loses the caps the second its license lapses. Never cache State() in a field or a lane: that cache is the bug this design exists to prevent. Run watches the term and stops a process whose config the free tier would refuse, because re-applying the caps live would mean deleting guardrail and mask rules from a running proxy.
  • A verdict cannot be assembled, only earned. Status.verified is unexported and license.Load is the only thing that sets it, after checking the signature. Build a Status literal anywhere else and it reports invalid and grants nothing. Config.UseLicense therefore takes a license.Ref and never a Status: the control plane sends a document and the sidecar checks it, rather than believing whoever is on the connection. NEVER add a constructor that skips Verify, and NEVER export the trust root; a test that needs a licensed process uses license/licensetest, which signs for real under a key it installs for the duration of one *testing.T.

Layout

The module root holds no Go files: go.mod, this file and README.md only.

PathDoes
inspect/bytes to statements, plus the codec registry; the wire vocabulary every other package names
lexer/SQL text to an effect and a relation list, without a grammar
jsonsql/the SQL a JSON document carries (a field, a JSON-RPC tools/call), for any protocol; codec/http's http.sql is its first seam
codec/registration seam: wires libhoop's decoders to the classifier; codec/http also wraps the Inspector with the relay's HTTP additions
policy/statement to verdict; local rules, then OPA
license/verifies the signed license that lifts the rule caps; a stdlib twin of common/license. internal/trust owns the key, licensetest signs for tests
analyzer/the model-backed evaluator, third in the policy chain
gate/orders inspection, policy, audit and masking into one decision
proxy/TCP relay that pumps both directions through a Gate
daemon/assembles the relay from config — sinks, evaluators, listeners — and is the CLI entry point
session/one inspected connection and the identity behind it
identity/resolves a request credential to the identity behind it; google/ verifies a Google OAuth2 bearer with tokeninfo; token/ matches a caller token against a file it re-reads
audit/the write side of the trail
store/the read side
pii/detectors and maskers
descriptors/resolves grpc.descriptors entries and plugins[].module values that are URLs; fetchers register by scheme, https is in the root, gcs/ is nested
codec/wasm/nested module: the codec plug-in host (wazero) behind daemon.LoadCodecPlugin; abi/ABI.md is the contract, sdk/ the guest SDKs, examples/ one plug-in per guest language with its committed .wasm

Conventions

  • Comments say why, at length where the reasoning is not recoverable from the code. This module's comments carry design rationale on purpose; match that register rather than stripping it.
  • Tests use testing only. No assertion library, in any module that the root can reach.
  • A masking or policy change needs a test that would fail without it. gate/ and inspect/bypass_test.go are where behaviour that an operator sees is pinned.
  • inspect/bypass_test.go holds statements that evade classification. A new evasion belongs there, phrased as the verdict an operator would get.
  • Ask whether a piece is protocol-specific before you add it. Build pieces that combine, the way the http and WebSocket codecs do and a lane splits into more than one listener. The generic layers (gate/, proxy/, policy/, inspect/) name no protocol: protocol knowledge stays in the codec and reaches them through an optional interface the gate asserts, as it does Reframer, or a sentinel in libhoop/v2/codec/types. Logic that is not about the wire (JSON paths, SQL classification, guardrail matching) goes in a protocol-neutral package, with a thin seam per protocol. The design note and the PR say which pieces are reusable and which are protocol-bound.
  • sidecar protocol-specific parsers: if the code must be added to libhoop, the sidecar parsers must live under libhoop/v2/*.
  • When adding new sidecar capabilities like guardrails, data masking, AI analyzer, check if the codec WASM in sidecar plugins has these same capabilities; we must ensure new capabilities like that need to be added to plugins as well.

Running it

Two compose stacks exercise the relay end to end, both outside this directory:

  • deploy/docker-compose/envoy-stack/ : Envoy plus OPA plus the sidecar. It carries more than the Envoy demo, and the parts that do not need Envoy cannot be run on their own today. Splitting it is open work.
  • deploy/docker-compose/metabase-stack/ : Metabase against a masked warehouse, with an asserting ./demo.sh.

They share one image and one Dockerfile, so building hoop-inspect:local in either serves the other.

scripts/dev/ holds four ordered scripts for the Vertex analyzer, which spend real GCP calls. Read scripts/dev/README.md before running them.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.