Skip to content

fix(agent): match the Python reference on responses, wire shape, persistence and stats - #26

Merged
rennf93 merged 1 commit into
masterfrom
fix/parity-gaps
Oct 15, 2026
Merged

rennf93 merged 1 commit into
masterfrom
fix/parity-gaps

Conversation

@rennf93

@rennf93 rennf93 commented Oct 15, 2026

Copy link
Copy Markdown
Member

Closes #25

I matched guard-agent-jvm to the Python reference agent (master ab52909) on the gaps listed in the issue. The agent already carries the Go 3.2.3 and 3.2.4 changes, so nothing from those releases is missing.

What changed:

  • An encrypted 413 halves the batch and re-encrypts each half, like the plaintext path. No encrypted batch is dropped whole any more.
  • A 200 is a partial failure only on an explicit success: false or a truthy errors. An unparseable or empty-object 200 and any unlisted status (202, 204, 3xx, 405, 408) are retried at once without opening the breaker.
  • The rules GET no longer counts 400/404/413/422 as breaker failures, and an empty rules object returns no rules. A cancelled context is never a breaker failure.
  • The rules loop starts only with a project id, stop flushes under the backoff gates, and the failure rate counts events plus metrics.
  • A permanently rejected or oversized status push is a failed push.
  • The wire always carries ip_address, action_taken, reason, metadata, tags, events, metrics and errors. Optional string fields the reference sends as null are still omitted, which the API treats the same.
  • Redis persistence: the writes in flight are capped at bufferSize (the fixed 4 thread pool and 1024 queue are gone), one warning is logged per backlog episode, a write is skipped when the item already left the buffer, and keys carry the wall-clock epoch nanoseconds stamp (strictly increasing within the process) instead of System.nanoTime().
  • agentStats gains loop_failures, last_status_push_ok, buffer_stats.last_flush_time, buffer_stats.auto_flush_running, transport_stats.bytes_sent, transport_stats.failure_count and transport_stats.session_closed. rules_last_update is a float epoch (0.0 when none) and the breaker state is CLOSED, OPEN or HALF_OPEN. This changes the strings status().circuitState and stats().circuitState return.
  • Docs no longer say the Python agent signs gzipped bytes or that encrypted payloads cannot be split, and AGENTS.md and CLAUDE.md are added like the other agent repos.

Tests: src/test/resources/response_vectors.json and wire_shape.json are generated from the Python agent by the scripts next to them, and RefParityTest replays them. Against master the new tests fail (for example stamps [504995962182416, 504995964592500] outside the wall clock window and an item outside the buffer must never be written ==> expected: <0> but was: <2>) and they pass here. ./gradlew build --no-daemon (spotless, detekt, 220 tests) passes.

…istence and stats

An encrypted 413 now halves the batch and re-encrypts each half. Only an explicit success:false or a truthy errors value is a partial failure; an unparseable or empty-object 200 and any unlisted status are retried at once without opening the breaker. The rules GET no longer counts 400/404/413/422 as breaker failures, and a cancelled context is never a breaker failure. The rules loop needs a project id, stop flushes under the backoff gates, and the failure rate counts events plus metrics. A rejected status push is a failed push. The wire always carries ip_address, action_taken, reason, metadata, tags, events, metrics and errors. The Redis persist backlog is capped at bufferSize in flight, warns once per episode and skips the write for an item that already left the buffer, and keys carry the wall-clock stamp. agentStats gains the reference keys, float epoch timestamps and the CLOSED/OPEN/HALF_OPEN spelling. Docs no longer claim the Python agent signs gzipped bytes or that encrypted payloads cannot be split, and AGENTS.md and CLAUDE.md are added.

Closes #25
@github-actions github-actions Bot added the documentation Docs site, README, CHANGELOG, license files label Oct 15, 2026
@rennf93
rennf93 merged commit 58adbd0 into master Oct 15, 2026
8 checks passed
@rennf93
rennf93 deleted the fix/parity-gaps branch October 15, 2026 13:37
rennf93 added a commit that referenced this pull request Oct 15, 2026
…to 6cde4af (#28)

The 3.2.4 section now covers the Python reference parity work (#26), and CI, CodeQL and the release build check out guard-core-jvm at the 4.4.0 line.

Co-authored-by: Renn F <rennf93@users.noreply.github.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

documentation Docs site, README, CHANGELOG, license files

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Parity gaps against the Python reference agent

1 participant