Skip to main content
← Back to list
01Issue
FeatureClosedSwamp ClubPublic
AssigneesNone

Relationships

#2459 Docs: document --datastore-poll-interval and the timer duration maximum in serve-flags.md

Opened by stack72 · 9/23/2026

What changed

swamp-club#2446 adds a setting to swamp serve and a limit to every duration flag that drives a timer. The manual page content/manual/reference/swamp-serve/serve-flags.md documents every serve flag, serve.yaml key and env var, and needs both.

1. New setting: datastore poll interval

Surface Name
CLI flag --datastore-poll-interval <duration> (also on swamp serve daemon enable)
Env var SWAMP_DATASTORE_POLL_INTERVAL
serve.yaml key datastore-poll-interval (string)
  • What it does: how often serve pulls config, access data (grants and groups) and runtime data from a remote datastore. It sets all three pollers (ConfigPoller, AccessDataPoller, RuntimeDataPoller).
  • Default 30s (unchanged behaviour when unset). Minimum 1s. Accepts seconds (30), or units (30s, 1m, 1h); milliseconds are rejected.
  • Precedence: CLI flag, then env var, then serve.yaml.
  • No effect without a remote datastore; serve logs a warning if it is set with a filesystem datastore.
  • Operator guidance: this is how stale a peer instance can be. Lower values make instances converge faster at the cost of more list/get calls against the bucket. In a MinIO test with two instances, a model created on one appeared on the other in 1.1 to 2.6 s at 2s, against 29 s at the default.

Suggested places on the page:

  • The flag table (next to --heartbeat-interval and --hydration-timeout, around line 40).
  • The serve.yaml key table (around line 159) and the example serve.yaml (around line 322).
  • The env var table (around line 365).

2. Maximum on timer durations

Duration values above 2147483647 ms (about 24.8 days) are now rejected with <flag> (<value>) exceeds the maximum safe timer duration (~24.8 days). Previously Deno fired such a timer after 1 ms, so a timeout aborted at once and an interval loop ran continuously. Affected:

  • swamp serve: --heartbeat-interval, --reconciliation-interval, --group-refresh-interval, --hydration-timeout, --datastore-poll-interval, --max-run-duration (which already had this limit)
  • --timeout on swamp workflow run, swamp model method run, swamp workflow resume
  • swamp worker connect --idle-timeout

A one-line note under the serve flag table would cover the serve flags. The --timeout and --idle-timeout references, if the manual documents them, could carry the same note.

02Bog Flow
✓OPEN○TRIAGED○IN PROGRESS◉CLOSED

Closed

9/28/2026, 11:32:55 PM

No activity in this phase yet.

03Sludge Pulse
Editable. Press Enter to edit.

stack72 commented 9/28/2026, 11:32:55 PM

Documented in https://github.com/swamp-club/swamp-club/pull/1259. --datastore-poll-interval is now in the serve-flags.md flag, config key and env var tables and the example serve.yaml, with a new 'Datastore polling' section. A note under the flag table lists the duration flags capped at ~24.8 days, with the real error text. The same cap is noted on --timeout (workflows.md, model-definitions.md) and --idle-timeout (worker-commands.md).

Sign in to post a ripple.