@kairos-es/feed 0.0.0-stage → 0.0.0

package/src/tuning.ts

@@ -0,0 +1,65 @@
+/**
+ * The driver's tuning: its defaults, and the checks that refuse a nonsensical
+ * value at construction rather than somewhere inside a running worker.
+ *
+ * The page size defaults to core's own catch-up page, and the supervision curve to
+ * the read side's — 100 ms doubling to 30 s — so a feed behaves like its
+ * neighbours unless told otherwise. The no-progress cap is the read side's too,
+ * and for the same reason: forty restarts on that curve is some twenty minutes of
+ * a sink refusing everything, which is long enough to ride out an outage and short
+ * enough that a broken wiring is reported the same day.
+ *
+ * Package-internal; the options a caller sets are `FeedSyncTuning`'s, on
+ * `runFeedSync`.
+ */
+import { DEFAULT_CATCH_UP_PAGE_SIZE, ReadLimit } from '@kairos-es/core'
+import { Duration } from 'effect'
+
+/** Rows read, and changes sent, per page. */
+export const DEFAULT_FEED_PAGE_SIZE: number = DEFAULT_CATCH_UP_PAGE_SIZE
+
+/** The upper bound on an idle worker's sleep: the poll that is the guarantee. */
+export const DEFAULT_FEED_POLL_INTERVAL: Duration.Duration = Duration.seconds(1)
+
+/** The first restart back-off. */
+export const DEFAULT_FEED_RESTART_MIN_DELAY: Duration.Duration =
+  Duration.millis(100)
+
+/** The restart back-off's cap, before jitter. */
+export const DEFAULT_FEED_RESTART_MAX_DELAY: Duration.Duration =
+  Duration.seconds(30)
+
+/** Consecutive restarts without a cursor advance before the worker gives up. */
+export const DEFAULT_FEED_MAX_NO_PROGRESS_RESTARTS = 40
+
+/**
+ * How many poll intervals a rebuild held on its readiness waits between two
+ * warnings that it is still held. Not a bound: the wait goes on, since publishing
+ * early is the failure the wait exists to prevent. Counted in polls, not time, so
+ * it scales with `pollInterval`: sixty polls is long past any replay that is
+ * merely busy at any sensible interval, and rare enough not to flood a log while
+ * a long one runs.
+ */
+export const HELD_WAIT_WARN_POLLS = 60
+
+/** The page size as a `ReadLimit`, refusing one that is not a positive integer. */
+export const readLimit = (pageSize: number): ReadLimit => {
+  if (!Number.isInteger(pageSize) || pageSize <= 0) {
+    throw new Error(
+      `feed: pageSize must be a positive integer (got ${pageSize})`,
+    )
+  }
+  return ReadLimit.make(pageSize)
+}
+
+/** A duration input decoded, refusing one that is not positive and finite. */
+export const positiveDuration = (
+  label: string,
+  input: Duration.Input,
+): Duration.Duration => {
+  const decoded = Duration.fromInputUnsafe(input)
+  if (!Duration.isFinite(decoded) || Duration.toMillis(decoded) <= 0) {
+    throw new Error(`feed: ${label} must be a positive, finite duration`)
+  }
+  return decoded
+}