Skip to content
1cedsodaPublic

About

Small pacing engine: can I do this now, and if not, when should I retry?

Resources

Stars

0 stars

Watchers

0 watching

Forks

Latest commit

 

History

1 Commit

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

@1cedsoda/pacer

Small pacing engine for one class of problem:

Can I do this now, and if not, when should I retry?

The package is intentionally minimal:

  • a Pacer<C> is a flat list of Rule<C>
  • each rule returns either ready, a concrete retryAt, or null (never retry)
  • the pacer runs all rules and takes the maximum blocking time

Everything interesting lives in your rules and your context, not in the pacer itself.

Mental Model

Think of the pacer as:

  1. run every rule
  2. collect every block
  3. if nothing blocks, return ready: true
  4. otherwise return the latest retryAt — or null if any rule is permanently blocked

That means you can model very different systems with the same primitive:

  • message pacing
  • per-IP scraping limits
  • business hours
  • cooldowns after failures
  • rolling quotas
  • deduplication / one-shot gates
  • reservation-backed slot allocation

Core Primitives

Rule<C>

One pacing rule for one context type.

export type RuleResult =
  | { readonly ready: true }
  | {
      readonly ready: false;
      /** Concrete time to retry. null means permanently blocked — never retry. */
      readonly retryAt: Date | null;
      readonly reason: string;
    };

export interface Rule<C> {
  readonly name: string;
  check(context: C, now: Date): RuleResult | Promise<RuleResult>;
}

Pacer<C>

The engine that aggregates rules.

export interface Pacer<C> {
  check(context: C, now: Date): Promise<Verdict>;
}

Verdict

The combined answer.

export interface Block {
  readonly rule: string;
  /** Concrete time to retry. null means permanently blocked — never retry. */
  readonly retryAt: Date | null;
  readonly reason: string;
}

export type Verdict =
  | { readonly ready: true }
  | {
      readonly ready: false;
      /** Latest retryAt across all blocks. null if any block is permanent. */
      readonly retryAt: Date | null;
      readonly blocks: readonly Block[];
    };

createPacer

Build a pacer from a flat list of rules.

import { createPacer } from "@1cedsoda/pacer";

const pacer = createPacer(rules);
const verdict = await pacer.check(context, new Date());

Quick Start

import {
  createPacer,
  minGap,
  fixedQuota,
  startOfDay,
  endOfDay,
} from "@1cedsoda/pacer";

type Context = {
  email: string;
  events: {
    getLastEventTime(scope: string): Promise<Date | null>;
    countSince(scope: string, since: Date): Promise<number>;
  };
};

const pacer = createPacer<Context>([
  minGap({
    name: "email-min-gap",
    scope: (context) => `email:${context.email}`,
    gapMs: 8 * 60_000,
    getLastEventTime: (context, scope) => context.events.getLastEventTime(scope),
  }),
  fixedQuota({
    name: "email-daily-cap",
    scope: (context) => `email:${context.email}`,
    limit: 30,
    window: (_context, now) => ({
      start: startOfDay(now),
      end: endOfDay(now),
    }),
    getCount: (context, scope, window) =>
      context.events.countSince(scope, window.start),
  }),
]);

const verdict = await pacer.check(
  {
    email: "alice@example.com",
    events,
  },
  new Date(),
);

if (!verdict.ready) {
  if (verdict.retryAt === null) {
    console.log("Permanently blocked:", verdict.blocks);
  } else {
    console.log("Retry at:", verdict.retryAt.toISOString());
    console.log("Blocked by:", verdict.blocks);
  }
}

Built-In Exports

Core:

  • createPacer
  • group
  • anyOf
  • allOf

Rule factories:

  • minGap
  • fixedWindow
  • notBefore
  • fixedQuota
  • slidingQuota
  • cooldown
  • concurrencyLimit
  • backoff
  • dedupe

Helpers:

  • startOfHour / endOfHour — UTC hour boundaries
  • startOfDay / endOfDay — UTC day boundaries
  • addMs
  • createWindow
  • ScopeKey

Built-In Rule Factories

The built-in factories use accessor callbacks instead of package-owned store interfaces. That keeps the package storage-agnostic.

minGap

Use when one scope needs a minimum delay between actions.

You provide:

  • scope(context)
  • gapMs — number of milliseconds, or a function (context) => number
  • getLastEventTime(context, scope)

Use cases:

  • minimum delay between messages from one email
  • minimum delay between requests from one IP
  • minimum delay between retries for one account

fixedWindow

Use when actions are only allowed during a known time window.

You provide:

  • isOpen(context, now)
  • nextOpen(context, now)

Use cases:

  • business hours only
  • send only in evenings
  • API usage only during a maintenance-safe window

notBefore

Use when an action has a single scheduled start time.

You provide:

  • getTime(context) — returns the earliest allowed time

Use cases:

  • scheduled workflow step that must not start early
  • spawn staggering: each child gets a different runAt
  • embargo window: process after a fixed delay from creation

fixedQuota

Use when usage resets on a fixed boundary.

You provide:

  • scope(context)
  • limit
  • window(context, now) returning { start, end }
  • getCount(context, scope, window)

Use cases:

  • max 30 messages per day
  • max 100 requests per hour on the hour
  • max 5 actions per calendar minute

slidingQuota

Use when the window rolls continuously.

You provide:

  • scope(context)
  • limit
  • windowMs
  • getEventTimes(context, scope, since, until)

Use cases:

  • max 20 actions in any rolling 10 minutes
  • max 50 requests in any rolling hour
  • max 3 retries in any rolling 15 minutes

fixedQuota and slidingQuota are different:

  • fixed quota resets at known boundaries
  • sliding quota depends on when old events age out

cooldown

Use when a recent failure should pause a scope for some time.

You provide:

  • scope(context)
  • cooldownMs — number of milliseconds, or a function (context) => number (useful for exponential back-off based on attempt count)
  • getLastFailureTime(context, scope)

Use cases:

  • cooldown after login failure
  • cooldown after anti-bot detection
  • cooldown after a send error
  • exponential back-off: cooldownMs: (ctx) => 1_000 * 2 ** ctx.attempts

concurrencyLimit

Use when a scope can only have a limited number of inflight actions.

You provide:

  • scope(context)
  • max
  • getInflightCount(context, scope)
  • optional retryAfterMs — number or (context, now, scope, active) => number

Use cases:

  • only one message send per account at a time
  • max 3 concurrent workers per tenant
  • max 2 inflight page fetches per IP

backoff

Use when a series of attempts should wait progressively longer between retries.

You provide:

  • scope(context)
  • baseMs — delay for the first retry (attempt = 1)
  • getAttempts(context, scope) — number of attempts already made (0 → ready immediately)
  • getLastAttemptTime(context, scope)
  • optional multiplier — growth factor per attempt (default 2 for exponential; 1 for flat)
  • optional maxMs — cap on the computed delay

The delay formula is: min(baseMs × multiplier^(attempts − 1), maxMs)

attempts multiplier=2, baseMs=10s multiplier=1, baseMs=10s
1 10s 10s
2 20s 10s
3 40s 10s
4 80s 10s

Use cases:

  • retry a failing HTTP request with exponential back-off
  • re-queue a workflow step after each failed attempt
  • flatten retries to a fixed interval when exponential growth is undesirable

dedupe

Use when an item should only be processed once, ever.

You provide:

  • scope(context)
  • getCompletedAt(context, scope) — returns the completion timestamp, or null/undefined if not yet processed

When getCompletedAt returns a date the rule returns retryAt: null — permanently blocked. The pacer (and any combinator wrapping it) will propagate null upward.

Use cases:

  • skip a lead that has already been contacted
  • gate an idempotency check before expensive work
  • prevent a one-shot workflow from running twice

Combinators and Helpers

group(name, rules)

Pure naming helper.

It prefixes rule names:

  • email/min-gap
  • email/fixed-quota
  • ip/concurrency-limit

This is only for organization and debugging.

anyOf(name, rules)

Returns ready if any child rule is ready. All branches run in parallel.

retryAt semantics when all branches block:

  • returns the earliest concrete retryAt across branches — retry as soon as any branch might unblock
  • returns null only when every branch is permanently blocked

Use when you want branch-style logic:

  • any proxy may be available
  • any account in a pool may be available
  • any slot source may unblock the action

allOf(name, rules)

Returns blocked if any child rule blocks. All rules run in parallel.

retryAt semantics when rules block:

  • returns the latest concrete retryAt — all rules must be satisfied before retrying
  • returns null if any rule is permanently blocked

This is mostly useful for nesting inside anyOf.

Top-level pacer behavior is already effectively allOf.

ScopeKey<Family>

Optional branded string helper if you want stronger typing for scopes.

You do not need it to use the package.

null retryAt — Permanent Blocks

Some rules can signal that a scope will never be ready: retryAt: null.

Rules that can produce null:

  • dedupe — when the item has already been completed
  • any custom rule that returns retryAt: null

Propagation rules:

  • createPacer: null takes precedence over any concrete Date in the final Verdict
  • allOf: null in any child → null in the combined result
  • anyOf: null only in the combined result when all branches are permanently blocked; a mix of null and concrete retryAt values yields the earliest concrete date (the timed branch may still become ready)

Always check for null before calling .getTime() on verdict.retryAt:

if (!verdict.ready) {
  if (verdict.retryAt === null) {
    // Permanently blocked — do not schedule a retry
  } else {
    await sleepUntil(verdict.retryAt);
  }
}

Date Helpers

All date helpers operate in UTC. Do not rely on them for local-time boundaries.

Helper Returns
startOfHour(date) Start of the current UTC hour
endOfHour(date) Start of the next UTC hour
startOfDay(date) Midnight UTC of the current day
endOfDay(date) Midnight UTC of the next day
addMs(date, ms) New date offset by ms milliseconds
createWindow(start, end) TimeWindow object

For timezone-aware windows (e.g. "07:00 Europe/Berlin") use Intl or a timezone library in your fixedWindow.isOpen / fixedWindow.nextOpen callbacks.

Scenarios

Scenario 1: Outbound Messaging Per Email

Goal:

  • minimum delay between messages from one email
  • daily send cap per email
import {
  createPacer,
  minGap,
  fixedQuota,
  startOfDay,
  endOfDay,
} from "@1cedsoda/pacer";

type Context = {
  email: string;
  events: {
    getLastEventTime(scope: string): Promise<Date | null>;
    countSince(scope: string, since: Date): Promise<number>;
  };
};

const pacer = createPacer<Context>([
  minGap({
    name: "email-min-gap",
    scope: (context) => `email:${context.email}`,
    gapMs: 8 * 60_000,
    getLastEventTime: (context, scope) => context.events.getLastEventTime(scope),
  }),
  fixedQuota({
    name: "email-daily-cap",
    scope: (context) => `email:${context.email}`,
    limit: 30,
    window: (_context, now) => ({
      start: startOfDay(now),
      end: endOfDay(now),
    }),
    getCount: (context, scope, window) =>
      context.events.countSince(scope, window.start),
  }),
]);

Scenario 2: Scraping Per IP With Business Hours

Goal:

  • minimum delay per IP
  • scraping only allowed between 07:00 and 23:00 UTC
import { createPacer, fixedWindow, minGap } from "@1cedsoda/pacer";

type Context = {
  ip: string;
  events: {
    getLastEventTime(scope: string): Promise<Date | null>;
  };
};

const pacer = createPacer<Context>([
  minGap({
    name: "ip-min-gap",
    scope: (context) => `ip:${context.ip}`,
    gapMs: 3_000,
    getLastEventTime: (context, scope) => context.events.getLastEventTime(scope),
  }),
  fixedWindow({
    name: "wakeful-hours",
    isOpen: (_context, now) => {
      const hour = now.getUTCHours();
      return hour >= 7 && hour < 23;
    },
    nextOpen: (_context, now) => {
      const next = new Date(now);
      if (now.getUTCHours() < 7) {
        next.setUTCHours(7, 0, 0, 0);
      } else {
        next.setUTCDate(next.getUTCDate() + 1);
        next.setUTCHours(7, 0, 0, 0);
      }
      return next;
    },
  }),
]);

Scenario 3: Rolling Quota Per IP

Goal:

  • max 50 actions in any rolling hour
import { createPacer, slidingQuota } from "@1cedsoda/pacer";

type Context = {
  ip: string;
  events: {
    getEventTimes(scope: string, since: Date, until: Date): Promise<readonly Date[]>;
  };
};

const pacer = createPacer<Context>([
  slidingQuota({
    scope: (context) => `ip:${context.ip}`,
    limit: 50,
    windowMs: 60 * 60_000,
    getEventTimes: (context, scope, since, until) =>
      context.events.getEventTimes(scope, since, until),
  }),
]);

Scenario 4: Cooldown After Failure

Goal:

  • stop attempting for 15 minutes after the most recent failure
import { createPacer, cooldown } from "@1cedsoda/pacer";

type Context = {
  email: string;
  failures: {
    getLastFailure(scope: string): Promise<Date | null>;
  };
};

const pacer = createPacer<Context>([
  cooldown({
    scope: (context) => `email:${context.email}`,
    cooldownMs: 15 * 60_000,
    getLastFailureTime: (context, scope) => context.failures.getLastFailure(scope),
  }),
]);

Scenario 5: Concurrency Ceiling

Goal:

  • only one inflight send per email
import { createPacer, concurrencyLimit } from "@1cedsoda/pacer";

type Context = {
  email: string;
  inflight: {
    count(scope: string): Promise<number>;
  };
};

const pacer = createPacer<Context>([
  concurrencyLimit({
    scope: (context) => `email:${context.email}`,
    max: 1,
    getInflightCount: (context, scope) => context.inflight.count(scope),
    retryAfterMs: 5_000,
  }),
]);

Scenario 6: Exponential Back-off After Failures

Goal:

  • wait progressively longer after each failed attempt (1s, 2s, 4s, 8s…), capped at 5 minutes
import { createPacer, backoff } from "@1cedsoda/pacer";

type Context = {
  jobId: string;
  jobs: {
    getAttemptCount(scope: string): Promise<number>;
    getLastAttemptTime(scope: string): Promise<Date | null>;
  };
};

const pacer = createPacer<Context>([
  backoff({
    scope: (context) => `job:${context.jobId}`,
    baseMs: 1_000,
    multiplier: 2,
    maxMs: 5 * 60_000,
    getAttempts: (context, scope) => context.jobs.getAttemptCount(scope),
    getLastAttemptTime: (context, scope) => context.jobs.getLastAttemptTime(scope),
  }),
]);

Scenario 7: One-Shot Deduplication Gate

Goal:

  • skip any lead that has already been contacted
import { createPacer, dedupe, minGap } from "@1cedsoda/pacer";

type Context = {
  leadId: number;
  email: string;
  db: {
    getContactedAt(scope: string): Promise<Date | null>;
    getLastSentAt(scope: string): Promise<Date | null>;
  };
};

const pacer = createPacer<Context>([
  dedupe({
    name: "already-contacted",
    scope: (context) => `lead:${context.leadId}`,
    getCompletedAt: (context, scope) => context.db.getContactedAt(scope),
  }),
  minGap({
    name: "send-gap",
    scope: (context) => `email:${context.email}`,
    gapMs: 10 * 60_000,
    getLastEventTime: (context, scope) => context.db.getLastSentAt(scope),
  }),
]);

const verdict = await pacer.check(context, new Date());
if (!verdict.ready) {
  if (verdict.retryAt === null) {
    // Lead already contacted — discard permanently, do not reschedule
  } else {
    await sleepUntil(verdict.retryAt);
  }
}

Scenario 8: Dynamic Budget Split Across Accounts

Goal:

  • total tenant budget is shared across active accounts
  • each account gets a dynamic daily share
import { createPacer, type Rule, startOfDay, endOfDay } from "@1cedsoda/pacer";

type Context = {
  email: string;
  tenantDailyBudget: number;
  activeAccountCount: number;
  events: {
    countSince(scope: string, since: Date): Promise<number>;
  };
};

const dynamicAccountQuota: Rule<Context> = {
  name: "dynamic-account-quota",
  async check(context, now) {
    const scope = `email:${context.email}`;
    const perAccountLimit = Math.max(
      1,
      Math.floor(context.tenantDailyBudget / context.activeAccountCount),
    );
    const count = await context.events.countSince(scope, startOfDay(now));

    if (count < perAccountLimit) return { ready: true };

    return {
      ready: false,
      retryAt: endOfDay(now),
      reason: `account share exhausted (${count}/${perAccountLimit})`,
    };
  },
};

const pacer = createPacer([dynamicAccountQuota]);

This is the point of the package: special business logic becomes a rule, not a pacer feature.

Scenario 9: Global Failure Breaker

Goal:

  • if global failure rate is too high, slow the whole system down
import { createPacer, addMs, type Rule } from "@1cedsoda/pacer";

type Context = {
  globalFailureRate: number;
};

const globalFailureBreaker: Rule<Context> = {
  name: "global-failure-breaker",
  check(context, now) {
    if (context.globalFailureRate < 0.2) return { ready: true };

    return {
      ready: false,
      retryAt: addMs(now, 5 * 60_000),
      reason: `global failure rate too high (${(context.globalFailureRate * 100).toFixed(1)}%)`,
    };
  },
};

const pacer = createPacer([globalFailureBreaker]);

Scenario 10: Reservation-Backed Slot Access

Goal:

  • use a reservation store to spread work into reserved future slots
import { createPacer, type Rule } from "@1cedsoda/pacer";

type Context = {
  email: string;
  reservations: {
    getActiveReservation(scope: string, now: Date): Promise<unknown | null>;
    tryReserve(scope: string, now: Date): Promise<{
      reserved: boolean;
      nextAvailable: Date;
    }>;
  };
};

const reservationRequired: Rule<Context> = {
  name: "reservation-required",
  async check(context, now) {
    const scope = `email:${context.email}`;
    const existing = await context.reservations.getActiveReservation(scope, now);
    if (existing) return { ready: true };

    const attempt = await context.reservations.tryReserve(scope, now);
    if (attempt.reserved) return { ready: true };

    return {
      ready: false,
      retryAt: attempt.nextAvailable,
      reason: "no reservation slot available",
    };
  },
};

const pacer = createPacer([reservationRequired]);

The pacer stays stateless. Restart safety lives in your reservation store and lease semantics.

Writing Custom Rules

If the built-ins do not fit, write a plain Rule<C>.

import { type Rule } from "@1cedsoda/pacer";

type Context = {
  tenantId: string;
  backlogSize: number;
};

const backlogShaper: Rule<Context> = {
  name: "backlog-shaper",
  check(context, now) {
    if (context.backlogSize < 100) return { ready: true };

    return {
      ready: false,
      retryAt: new Date(now.getTime() + 2 * 60_000),
      reason: "backlog is too large right now",
    };
  },
};

Return retryAt: null to signal a permanent block:

const permanentGate: Rule<Context> = {
  name: "permanent-gate",
  async check(context, _now) {
    const done = await db.isCompleted(context.id);
    if (!done) return { ready: true };
    return { ready: false, retryAt: null, reason: "already completed" };
  },
};

Error Behavior

If any rule throws, pacer.check() throws.

The pacer does not:

  • swallow errors
  • treat errors as ready
  • silently skip failing rules

Blocked pacing and execution failure are different outcomes.

Restart Safety

The pacer is stateless.

That means:

  • no pacing-critical state lives inside the pacer instance
  • all durable state lives in your stores
  • a fresh pacer with the same rules should produce the same verdicts given the same context-backed data

When possible:

  • derive quotas from durable events
  • derive cooldowns from durable failures
  • use lease semantics for reservations and inflight claims

Practical Guidance

  • Keep your rules small and focused.
  • Put storage access behind accessor callbacks.
  • Prefer plain rules before adding abstractions.
  • Use group(...) for readability, not for behavior.
  • Use anyOf(...) only when you actually need branch-style logic.
  • Keep retry reasons human-readable. They show up in verdict.blocks.
  • Always guard verdict.retryAt for null before calling .getTime() or sleepUntil.

Package Philosophy

The pacer is intentionally boring.

That is the point.

It should be easy to explain:

  • rules decide
  • pacer aggregates
  • context carries everything else

About

Small pacing engine: can I do this now, and if not, when should I retry?

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages