Jitter StatusPlugin report interval between min/max delay

[arimu1]

Problem

StatusPlugin.start() scheduled status reports via scheduleAtFixedRate(...) at a hardcoded 30s interval, with no way to configure it and no jitter. Every instance in a fleet therefore reports on the same cadence. This is the twin of #78 (DecisionLogPlugin), and this SDK's BundleDownloader already implements the chained random-delay pattern for bundle polling.

Approach

Mirrors BundleDownloader.scheduleNextPoll and this repo's own #78 fix for DecisionLogPlugin:

• Added min_delay_seconds/max_delay_seconds to Config.StatusConfig (previously it only had console and service), defaulting to 30/30 — see note below on why.
• Added matching minDelaySeconds/maxDelaySeconds fields + getters/setters to the inner StatusPlugin.Status class, and wired them through in initialize().
• Added a min_delay_seconds <= max_delay_seconds check to validate(), matching the existing pattern in DecisionLogPlugin.validate().
• Replaced scheduler.scheduleAtFixedRate(...) with a new private scheduleNextReport(minDelay, maxDelay) that re-schedules itself after each report with a uniformly random delay in [minDelay, maxDelay] (ThreadLocalRandom), swallowing Exception from reportStatus() (which already logs internally) so the chain keeps running, and stopping cleanly on RejectedExecutionException after shutdown — same structure as BundleDownloader.scheduleNextPoll and the DecisionLogPlugin.scheduleNextFlush added in Jittered upload interval #78.
• Preserved the previous immediate report on startup via a separate zero-delay scheduler.schedule(...) call before starting the chain, mirroring BundleDownloader.startPolling()'s "download immediately, then start the chained poll" structure — so there's no regression in time-to-first-report.
• If max_delay_seconds is unset, it now defaults to 2 * min_delay_seconds, consistent with the fallback added for DecisionLogPlugin in Jittered upload interval #78.
• Switched the plugin's scheduler construction to BundleDownloader.newPollScheduler("opa-status-scheduler"), matching BundlePlugin, DiscoveryPlugin, and the Jittered upload interval #78 DecisionLogPlugin change.

Note on defaults: I checked OPA Go's current v1/plugins/status/plugin.go and its Config struct has no min_delay_seconds/max_delay_seconds fields at all — status reports there are triggered by the bundle/discovery plugin's own polling (Trigger mode) rather than an independent timer, so there's no canonical upstream number to mirror for a standalone status interval default (this differs from decision logs, where OPA Go does have defaultMinDelaySeconds = 300 / defaultMaxDelaySeconds = 600 in v1/plugins/logs/plugin.go, matching what's already in this SDK's DecisionLogsConfig). Given that, I kept this SDK's existing 30s interval as the default when unconfigured (min = max = 30, deterministic, zero behavior change for existing users), while adding full jitter support once a wider [min, max] range is configured — which is the actual ask of this issue.

Tests

Added to StatusPluginTest:

• validate_delaySecondsInvalid_returnsError / validate_delaySecondsEqual_returnsNoErrors — validation edge cases for min <= max.
• configDefaults_delaySecondsAreCorrect — confirms the 30/30 default.
• configBuilder_setsAllFields — updated to also cover the new delay setters.
• start_periodicReport_usesJitteredChainedSchedule — sets min == max == 1s for a deterministic interval and verifies at least 3 "Status: %s" console logs (immediate + ~1s + ~2s), proving the schedule re-chains itself.
• start_onlyMinDelayConfigured_defaultsMaxToTwiceMin — sets only min_delay_seconds = 1 with max_delay_seconds explicitly null, and verifies at least 2 reports within 2.5s, proving the fallback is 2 * min rather than an unrelated default that wouldn't fire in the window.

Also added config_statusDefaults coverage in ConfigTest for the new fields.

Ran locally with JDK 17 / Gradle:

./gradlew :opa-services:test --tests "io.github.open_policy_agent.opa.plugins.StatusPluginTest" --tests "io.github.open_policy_agent.opa.config.ConfigTest"
./gradlew test

StatusPluginTest: 20/20 pass (14 pre-existing + 6 new/updated). ConfigTest: 14/14 pass. Full multi-module ./gradlew test and :opa-services:checkstyleMain also pass with zero violations in the changed files.

Fixes #80
Fixes #80

[sspaink]

Defaulting maxDelaySeconds to a non-null 30 makes the "unset max → 2 * min" fallback in StatusPlugin.start() unreachable through config, and turns a min-only configuration into a validation error.

Jackson only invokes a setter for keys physically present in the config, so an omitted max_delay_seconds retains this 30 default rather than becoming null. As a result:

• maxDelaySeconds = minDelaySeconds * 2 in start() can only fire if a caller explicitly passes null (as the test does) — never via normal YAML/JSON — contradicting the PR description's "if max_delay_seconds is unset, it now defaults to 2 * min_delay_seconds."
• A user who sets only min_delay_seconds: 60 (max omitted) keeps max = 30, so validate() fails with min_delay_seconds (60) cannot be greater than max_delay_seconds (30) at startup — even though they never configured a max.

DecisionLogsConfig sidesteps this with split defaults (300/600), and ReportingConfig uses null/null. Consider defaulting maxDelaySeconds (and probably minDelaySeconds) to null here and applying the 30 default in start(), so the documented min-only fallback actually works.

[arimu1]

Thanks @sspaink — good catch. StatusConfig.minDelaySeconds / maxDelaySeconds now default to null (same pattern as ReportingConfig), so an omitted max_delay_seconds in YAML stays unset and StatusPlugin.start() can apply the documented 2 * min fallback. The runtime default of 30 when both are unset is unchanged.

[sspaink]

When only max_delay_seconds is configured and it's below 30, min defaults to 30, so min > max and the report just fires every 30s — the configured max is silently ignored. validate() doesn't catch it either, since it only compares the two when both are non-null. Consider validating this case or defaulting min to max when only max is set.

[sspaink]

This only checks min > max, but doesn't reject negative values like BundleDownloader.validatePolling does (it guards min < 0 / max < 0). A negative min_delay_seconds passes validation and produces a negative delay, which the scheduler treats as 0 — so the chain busy-loops reporting status. Suggest adding the same >= 0 guards.

[arimu1]

Thanks @sspaink — addressed both points (and rebased onto main after #170/#171 merged):

1. Negative delays: validate() now rejects min_delay_seconds < 0 / max_delay_seconds < 0, same shape as BundleDownloader.validatePolling.
2. Max-only below 30: start() now resolves bounds as:
   • both set → use as-is
   • only min → max = 2 * min
   • only max → min = min(30, max) (so max: 10 becomes a 10–10 window instead of silently scheduling every 30s)
   • neither → 30 / 60

Tests: validate_negativeDelaySeconds_returnsError, validate_onlyMaxDelayNegative_returnsError, start_onlyMaxDelayBelowDefaultMin_defaultsMinToMax.

[sspaink]

Thanks!