Skip to content

:hedgehog: PostHog is the leading platform for building self-driving products. Our developer tools – AI observability, analytics, session replay, flags, experiments, error tracking, logs, and more – capture all the context agents need to diagnose problems, uncover opportunities, and ship fixes. Steer it all from Slack, web, desktop, or the MCP.

feat(workflows): hold capped messages until a frequency cap slot frees (#127579)

Harley Alexander7a1cda6cde18
diff --git a/nodejs/src/cdp/services/hogflows/actions/hog_function.test.ts b/nodejs/src/cdp/services/hogflows/actions/hog_function.test.ts
index fe46d37dc7a5..bdb88d9c8caf 100644
--- a/nodejs/src/cdp/services/hogflows/actions/hog_function.test.ts
+++ b/nodejs/src/cdp/services/hogflows/actions/hog_function.test.ts
@@ -1,6 +1,6 @@
import { mockFetch } from '~/tests/helpers/mocks/request.mock'
-import { DateTime } from 'luxon'
+import { DateTime, Settings } from 'luxon'
import { register } from 'prom-client'
import { FixtureHogFlowBuilder } from '~/cdp/_tests/builders/hogflow.builder'
@@ -129,7 +129,7 @@ describe('HogFunctionHandler', () => {
)
mockRecipientPreferencesService = {
shouldSkipAction: jest.fn().mockResolvedValue(null),
- isFrequencyCapped: jest.fn().mockResolvedValue(false),
+ checkFrequencyCap: jest.fn().mockResolvedValue({ capped: false }),
} as any
mockEmailValidationService = {
getSkipReason: jest.fn().mockResolvedValue(null),
@@ -496,7 +496,11 @@ describe('HogFunctionHandler', () => {
])(
'should skip the send and emit message_frequency_capped when the recipient reached the frequency cap for %s',
async (_label, parentRunId) => {
- ;(mockRecipientPreferencesService.isFrequencyCapped as jest.Mock).mockResolvedValueOnce(true)
+ ;(mockRecipientPreferencesService.checkFrequencyCap as jest.Mock).mockResolvedValueOnce({
+ capped: true,
+ nextSlotAt: Date.now() + 60 * 60 * 1000,
+ holdHours: null,
+ })
invocation.parentRunId = parentRunId
const invocationResult = createInvocationResult<CyclotronJobInvocationHogFlow>(invocation, {
@@ -524,6 +528,102 @@ describe('HogFunctionHandler', () => {
}
)
+ const hour = 60 * 60 * 1000
+
+ it.each([
+ ['another send took the freed slot', 1 * hour, { capped: true, nextSlotAt: 1_800_000_000_000 + 3 * hour }, 1],
+ // A worker backlog can wake the send after the hold ended. It must not claim a slot that freed late.
+ ['the send wakes after the hold ended', 3 * hour, { capped: false }, 0],
+ ])(
+ 'should hold a capped send until the next slot, then skip it when %s',
+ async (_label, wakeAfter, wakeCheck, checks) => {
+ const start = 1_800_000_000_000
+ const originalNow = Settings.now
+ jest.spyOn(Math, 'random').mockReturnValue(0)
+ const checkFrequencyCap = mockRecipientPreferencesService.checkFrequencyCap as jest.Mock
+ try {
+ Settings.now = () => start
+ checkFrequencyCap.mockResolvedValueOnce({ capped: true, nextSlotAt: start + hour, holdHours: 2 })
+ const held = createInvocationResult<CyclotronJobInvocationHogFlow>(invocation, {
+ queue: 'hog',
+ queuePriority: 0,
+ })
+
+ const heldResult = await hogFunctionHandler.execute({ invocation, action, result: held })
+
+ expect(heldResult).toEqual({ scheduledAt: DateTime.fromMillis(start + hour) })
+ expect(held.invocation.state.currentAction?.frequencyCapHoldDeadlineAt).toBe(
+ DateTime.fromMillis(start + 2 * hour).toISO()
+ )
+ expect(held.logs[0].message).toContain('Holding send until')
+ expect(held.metrics).toMatchObject([{ metric_name: 'message_frequency_cap_held', count: 1 }])
+
+ Settings.now = () => start + wakeAfter
+ checkFrequencyCap.mockClear()
+ checkFrequencyCap.mockResolvedValueOnce({ ...wakeCheck, holdHours: 2 })
+ const woken = createInvocationResult<CyclotronJobInvocationHogFlow>(held.invocation, {
+ queue: 'hog',
+ queuePriority: 0,
+ })
+
+ const wokenResult = await hogFunctionHandler.execute({
+ invocation: held.invocation,
+ action,
+ result: woken,
+ })
+
+ expect(wokenResult.nextAction?.id).toBe('exit')
+ expect(woken.logs[0].message).toContain('no slot opened before the hold ended')
+ expect(woken.metrics).toMatchObject([{ metric_name: 'message_frequency_capped', count: 1 }])
+ expect(checkFrequencyCap).toHaveBeenCalledTimes(checks)
+ expect(mockFetch).not.toHaveBeenCalled()
+ } finally {
+ Settings.now = originalNow
+ }
+ }
+ )
+
+ it('should skip at once when the next slot frees after the hold would end', async () => {
+ ;(mockRecipientPreferencesService.checkFrequencyCap as jest.Mock).mockResolvedValueOnce({
+ capped: true,
+ nextSlotAt: Date.now() + 3 * hour,
+ holdHours: 2,
+ })
+ const invocationResult = createInvocationResult<CyclotronJobInvocationHogFlow>(invocation, {
+ queue: 'hog',
+ queuePriority: 0,
+ })
+
+ const handlerResult = await hogFunctionHandler.execute({ invocation, action, result: invocationResult })
+
+ expect(handlerResult.nextAction?.id).toBe('exit')
+ expect(invocationResult.metrics).toMatchObject([{ metric_name: 'message_frequency_capped', count: 1 }])
+ })
+
+ it('should skip, not hold, a capped send that resumes on the email queue', async () => {
+ // A hold here would drop the pending send that the email queue continuation carries.
+ ;(mockRecipientPreferencesService.checkFrequencyCap as jest.Mock).mockResolvedValueOnce({
+ capped: true,
+ nextSlotAt: Date.now() + hour,
+ holdHours: 2,
+ })
+ invocation.state.currentAction!.hogFunctionState = {
+ globals: { ...createExampleHogFlowInvocation(invocation.hogFlow).state.event, inputs: {} } as any,
+ timings: [],
+ attempts: 0,
+ } as any
+ const invocationResult = createInvocationResult<CyclotronJobInvocationHogFlow>(invocation, {
+ queue: 'email',
+ queuePriority: 0,
+ })
+
+ const handlerResult = await hogFunctionHandler.execute({ invocation, action, result: invocationResult })
+
+ expect(handlerResult.nextAction?.id).toBe('exit')
+ expect(invocationResult.metrics).toMatchObject([{ metric_name: 'message_frequency_capped', count: 1 }])
+ expect(invocationResult.invocation.state.currentAction?.frequencyCapHoldDeadlineAt).toBeUndefined()
+ })
+
it.each([
['a workflow run', undefined],
['a broadcast run', 'broadcast-run-id'],
@@ -576,7 +676,11 @@ describe('HogFunctionHandler', () => {
)
}
const skipFrequencyCapped = (): void => {
- ;(mockRecipientPreferencesService.isFrequencyCapped as jest.Mock).mockResolvedValueOnce(true)
+ ;(mockRecipientPreferencesService.checkFrequencyCap as jest.Mock).mockResolvedValueOnce({
+ capped: true,
+ nextSlotAt: Date.now() + 60 * 60 * 1000,
+ holdHours: null,
+ })
}
it.each([
diff --git a/nodejs/src/cdp/services/hogflows/actions/hog_function.ts b/nodejs/src/cdp/services/hogflows/actions/hog_function.ts
index 4386e42b93c0..7aa0700925e2 100644
--- a/nodejs/src/cdp/services/hogflows/actions/hog_function.ts
+++ b/nodejs/src/cdp/services/hogflows/actions/hog_function.ts
@@ -20,7 +20,7 @@ import {
import { HogExecutorExecuteAsyncOptions } from '../../hog-executor-async.service'
import { EmailSkipReason, EmailStatusService } from '../../messaging/email-status.service'
import { EmailValidationService } from '../../messaging/email-validation.service'
-import { RecipientPreferencesService } from '../../messaging/recipient-preferences.service'
+import { FrequencyCapCheck, RecipientPreferencesService } from '../../messaging/recipient-preferences.service'
import { CdpUsageReporterService } from '../../usage/cdp-usage-reporter.service'
import { trackHogFlowBillableInvocation } from '../billing-utils'
import { HogFlowFunctionsService } from '../hogflow-functions.service'
@@ -185,7 +185,10 @@ export class HogFunctionHandler implements ActionHandler {
// Inputs are rendered once, on fresh entry into the action (continuations reuse the
// rendered state in hogFunctionState) - so this also fires at most once per step per run
- if (!invocation.state.currentAction?.hogFunctionState) {
+ if (
+ !invocation.state.currentAction?.hogFunctionState &&
+ !invocation.state.currentAction?.frequencyCapHoldDeadlineAt
+ ) {
observeMissingVariableReferences(invocation, action, result)
}
@@ -214,6 +217,12 @@ export class HogFunctionHandler implements ActionHandler {
result.metrics = [...result.metrics, ...functionResult.metrics]
result.messageAssets = [...result.messageAssets, ...functionResult.messageAssets]
+ if (functionResult.frequencyCapHold) {
+ result.invocation.state.currentAction!.frequencyCapHoldDeadlineAt =
+ functionResult.frequencyCapHold.deadlineAt
+ return { scheduledAt: functionResult.frequencyCapHold.until }
+ }
+
if (!functionResult.finished) {
// Set the state of the function result on the substate of the flow for the next execution
result.invocation.state.currentAction!.hogFunctionState = {
@@ -431,7 +440,12 @@ export class HogFunctionHandler implements ActionHandler {
invocation: CyclotronJobInvocationHogFlow,
action: Action,
hogExecutorOptions?: HogExecutorExecuteAsyncOptions
- ): Promise<CyclotronJobInvocationResult<CyclotronJobInvocationHogFunction> & { skipped?: boolean }> {
+ ): Promise<
+ CyclotronJobInvocationResult<CyclotronJobInvocationHogFunction> & {
+ skipped?: boolean
+ frequencyCapHold?: FrequencyCapHold
+ }
+ > {
const hogFunction = await instrumentFn(
{ key: 'hogFlow.action.hogFunction.buildHogFunction', sendException: false },
() => this.hogFlowFunctionsService.buildHogFunction(invocation.hogFlow, action.config, action.name)
@@ -537,10 +551,46 @@ export class HogFunctionHandler implements ActionHandler {
// This check runs last because it also records the send against the cap. If it ran before the
// opt-out, suppression or bounce checks, a send that one of them skips would still use a slot.
- if (
- !hogExecutorOptions?.isTest &&
- (await this.recipientPreferencesService.isFrequencyCapped(hogFunctionInvocation, action))
- ) {
+ // A held send that wakes after its hold ended is skipped before the check, so it never claims a slot late.
+ const holdExpired = frequencyCapHoldExpired(invocation)
+ const frequencyCap =
+ hogExecutorOptions?.isTest || holdExpired
+ ? ({ capped: false } as const)
+ : await this.recipientPreferencesService.checkFrequencyCap(hogFunctionInvocation, action)
+ if (holdExpired || frequencyCap.capped) {
+ const hold = frequencyCap.capped ? frequencyCapHold(invocation, frequencyCap) : null
+ if (hold) {
+ return {
+ finished: false,
+ invocation: hogFunctionInvocation,
+ frequencyCapHold: hold,
+ logs: [
+ {
+ level: 'info',
+ timestamp: DateTime.now(),
+ // Worded apart from the skip line, which the metrics drill-down finds by 'reached the frequency cap'.
+ message: `Holding send until ${hold.until.toUTC().toISO()}: the recipient is at the frequency cap.`,
+ },
+ ],
+ // Counted once per held send, not on every wake that finds the cap still full.
+ metrics: hold.firstHold
+ ? [
+ {
+ team_id: hogFunctionInvocation.teamId,
+ app_source_id: hogFunctionInvocation.parentRunId ?? hogFunctionInvocation.functionId,
+ instance_id: action.id,
+ metric_kind: 'other',
+ metric_name: 'message_frequency_cap_held',
+ count: 1,
+ },
+ ]
+ : [],
+ capturedPostHogEvents: [],
+ warehouseWebhookPayloads: [],
+ messageAssets: [],
+ conversionWatchers: [],
+ }
+ }
this.recordSkippedEmail(hogFunctionInvocation, action, 'frequency_capped', hogExecutorOptions)
return {
finished: true,
@@ -550,7 +600,9 @@ export class HogFunctionHandler implements ActionHandler {
{
level: 'info',
timestamp: DateTime.now(),
- message: 'Skipping send: recipient reached the frequency cap.',
+ message: invocation.state.currentAction?.frequencyCapHoldDeadlineAt
+ ? 'Skipping send: recipient reached the frequency cap, and no slot opened before the hold ended.'
+ : 'Skipping send: recipient reached the frequency cap.',
},
],
metrics: [
@@ -575,3 +627,37 @@ export class HogFunctionHandler implements ActionHandler {
)
}
}
+
+type FrequencyCapHold = { until: DateTime; deadlineAt: string; firstHold: boolean }
+
+// Up to a minute of spread, so held sends for one person that wait on the same slot don't all wake at once.
+const FREQUENCY_CAP_HOLD_JITTER_MS = 60_000
+function frequencyCapHoldExpired(invocation: CyclotronJobInvocationHogFlow): boolean {
+ const deadlineAt = invocation.state.currentAction?.frequencyCapHoldDeadlineAt
+ return !!deadlineAt && DateTime.now() >= DateTime.fromISO(deadlineAt)
+}
+
+/** When the team holds capped messages and the hold has not ended, returns when to check the cap again. */
+function frequencyCapHold(
+ invocation: CyclotronJobInvocationHogFlow,
+ cap: Extract<FrequencyCapCheck, { capped: true }>
+): FrequencyCapHold | null {
+ // A continuation on the email queue carries a pending send that a hold would drop, so it skips as before.
+ if (!cap.holdHours || invocation.state.currentAction?.hogFunctionState) {
+ return null
+ }
+ const now = DateTime.now()
+ const startedDeadline = invocation.state.currentAction?.frequencyCapHoldDeadlineAt
+ const deadline = startedDeadline ? DateTime.fromISO(startedDeadline) : now.plus({ hours: cap.holdHours })
+ // No slot frees before the hold ends, so waiting cannot help.
+ if (cap.nextSlotAt >= deadline.toMillis()) {
+ return null
+ }
+ // Wake after the slot frees but before the deadline, which the next wake enforces strictly.
+ const jitterMs = Math.min(
+ Math.floor(Math.random() * FREQUENCY_CAP_HOLD_JITTER_MS),
+ Math.floor((deadline.toMillis() - cap.nextSlotAt) / 2)
+ )
+ const until = DateTime.max(now, DateTime.fromMillis(cap.nextSlotAt + jitterMs))
+ return { until, deadlineAt: deadline.toISO()!, firstHold: !startedDeadline }
+}
diff --git a/nodejs/src/cdp/services/managers/team-workflows-config.service.ts b/nodejs/src/cdp/services/managers/team-workflows-config.service.ts
index c32434562bde..59e5ddb039ba 100644
--- a/nodejs/src/cdp/services/managers/team-workflows-config.service.ts
+++ b/nodejs/src/cdp/services/managers/team-workflows-config.service.ts
@@ -23,9 +23,11 @@ export type TeamWorkflowsConfig = {
/** Max marketing messages one person gets per window. Null on either field means no cap. */
marketing_frequency_cap_max_messages: number | null
marketing_frequency_cap_window_days: number | null
+ /** Hours a capped marketing message waits for a free slot. Null skips it at once. */
+ marketing_frequency_cap_hold_hours: number | null
}
-export type FrequencyCap = { max_messages: number | null; window_days: number | null }
+export type FrequencyCap = { max_messages: number | null; window_days: number | null; hold_hours: number | null }
const DEFAULT_CONFIG: TeamWorkflowsConfig = {
capture_workflows_engagement_events: false,
@@ -35,6 +37,7 @@ const DEFAULT_CONFIG: TeamWorkflowsConfig = {
email_sending_tier: 0,
marketing_frequency_cap_max_messages: null,
marketing_frequency_cap_window_days: null,
+ marketing_frequency_cap_hold_hours: null,
}
/**
@@ -119,6 +122,7 @@ export class TeamWorkflowsConfigService {
return {
max_messages: config.marketing_frequency_cap_max_messages,
window_days: config.marketing_frequency_cap_window_days,
+ hold_hours: config.marketing_frequency_cap_hold_hours,
}
}
@@ -132,6 +136,7 @@ export class TeamWorkflowsConfigService {
email_sending_tier: number
marketing_frequency_cap_max_messages: number | null
marketing_frequency_cap_window_days: number | null
+ marketing_frequency_cap_hold_hours: number | null
}>(
PostgresUse.COMMON_READ,
// Only DISABLED blocks: ENABLED and REINSTATED both permit sending, and '' means the
@@ -139,7 +144,8 @@ export class TeamWorkflowsConfigService {
`SELECT team_id, capture_workflows_engagement_events, email_tracking_consent_mode,
email_sending_suspended_at IS NOT NULL AS email_sending_suspended,
ses_tenant_sending_status = 'DISABLED' AS ses_tenant_provider_suspended,
- email_sending_tier, marketing_frequency_cap_max_messages, marketing_frequency_cap_window_days
+ email_sending_tier, marketing_frequency_cap_max_messages, marketing_frequency_cap_window_days,
+ marketing_frequency_cap_hold_hours
FROM workflows_teamworkflowsconfig
WHERE team_id = ANY($1)`,
[validTeamIds(teamIds)],
@@ -159,6 +165,7 @@ export class TeamWorkflowsConfigService {
email_sending_tier: row.email_sending_tier ?? 0,
marketing_frequency_cap_max_messages: row.marketing_frequency_cap_max_messages,
marketing_frequency_cap_window_days: row.marketing_frequency_cap_window_days,
+ marketing_frequency_cap_hold_hours: row.marketing_frequency_cap_hold_hours,
}
}
return configs
diff --git a/nodejs/src/cdp/services/messaging/recipient-preferences.service.test.ts b/nodejs/src/cdp/services/messaging/recipient-preferences.service.test.ts
index 84217d319ede..ac4a0ca18511 100644
--- a/nodejs/src/cdp/services/messaging/recipient-preferences.service.test.ts
+++ b/nodejs/src/cdp/services/messaging/recipient-preferences.service.test.ts
@@ -13,10 +13,10 @@ import { createTestTeamFixture } from '~/tests/helpers/sql'
import { Hub, Team } from '~/types'
import { RecipientsManagerService } from '../managers/recipients-manager.service'
-import { TeamWorkflowsConfigService } from '../managers/team-workflows-config.service'
+import { FrequencyCap, TeamWorkflowsConfigService } from '../managers/team-workflows-config.service'
import { EmailSuppressionService, emailSuppressionConfigFromEnv } from './email-suppression.service'
import { createFrequencyCapValkeyPool } from './frequency-cap-valkey-pool'
-import { RecipientPreferencesService } from './recipient-preferences.service'
+import { FrequencyCapCheck, RecipientPreferencesService } from './recipient-preferences.service'
import { RecipientTokensService } from './recipient-tokens.service'
const escapeRegExp = (value: string): string => value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
@@ -658,9 +658,9 @@ describe('RecipientPreferencesService', () => {
})
})
- describe('isFrequencyCapped', () => {
+ describe('checkFrequencyCap', () => {
let valkey: RedisV2
- let frequencyCap: { max_messages: number | null; window_days: number | null }
+ let frequencyCap: FrequencyCap
let teamWorkflowsConfig: TeamWorkflowsConfigService
let cappedService: RecipientPreferencesService
let persons: { getCyclotronPerson: jest.Mock }
@@ -691,7 +691,7 @@ describe('RecipientPreferencesService', () => {
beforeEach(async () => {
await deleteKeysWithPrefix(valkey, `@posthog/workflows-frequency-cap/${team.id}/`)
- frequencyCap = { max_messages: 2, window_days: 7 }
+ frequencyCap = { max_messages: 2, window_days: 7, hold_hours: null }
teamWorkflowsConfig = new TeamWorkflowsConfigService(hub.postgres, hub.pubSub)
jest.spyOn(teamWorkflowsConfig, 'getFrequencyCap').mockImplementation(() => Promise.resolve(frequencyCap))
persons = { getCyclotronPerson: jest.fn().mockResolvedValue(null) }
@@ -702,10 +702,11 @@ describe('RecipientPreferencesService', () => {
})
})
- const sendAt = async (action: HogFlowAction, at: number): Promise<boolean> => {
+ const checkAt = async (action: HogFlowAction, at: number): Promise<FrequencyCapCheck> => {
jest.spyOn(Date, 'now').mockReturnValue(at)
- return cappedService.isFrequencyCapped(createFunctionStepInvocation(action as any), action)
+ return cappedService.checkFrequencyCap(createFunctionStepInvocation(action as any), action)
}
+ const sendAt = async (action: HogFlowAction, at: number): Promise<boolean> => (await checkAt(action, at)).capped
it('caps marketing sends past the limit until the window moves past the oldest send', async () => {
const day = 24 * 60 * 60 * 1000
@@ -713,33 +714,42 @@ describe('RecipientPreferencesService', () => {
expect(await sendAt(emailAction(), start)).toBe(false)
expect(await sendAt(emailAction(), start + day)).toBe(false)
- expect(await sendAt(emailAction(), start + 2 * day)).toBe(true)
+ expect(await checkAt(emailAction(), start + 2 * day)).toEqual({
+ capped: true,
+ nextSlotAt: start + 7 * day,
+ holdHours: null,
+ })
expect(await sendAt(emailAction(), start + 7 * day + 1)).toBe(false)
})
it('lets a re-entered step visit keep its slot from the send time and counts a later visit', async () => {
- frequencyCap = { max_messages: 1, window_days: 1 }
+ frequencyCap = { max_messages: 1, window_days: 1, hold_hours: 12 }
const hour = 60 * 60 * 1000
const start = 1_800_000_000_000
const action = emailAction()
const invocation = createFunctionStepInvocation(action)
invocation.state.actionId = action.id
invocation.state.actionStepCount = 1
- const checkAt = async (at: number): Promise<boolean> => {
+ const visitAt = async (at: number): Promise<FrequencyCapCheck> => {
jest.spyOn(Date, 'now').mockReturnValue(at)
- return cappedService.isFrequencyCapped(invocation, action)
+ return cappedService.checkFrequencyCap(invocation, action)
}
// The email queue runs the step a second time after the hog queue routed it there and paced it.
- expect(await checkAt(start)).toBe(false)
- expect(await checkAt(start + 23 * hour)).toBe(false)
+ expect(await visitAt(start)).toEqual({ capped: false })
+ expect(await visitAt(start + 23 * hour)).toEqual({ capped: false })
+ // The slot frees a day after the second run moved it, not a day after the first check.
invocation.state.actionStepCount = 3
- expect(await checkAt(start + 25 * hour)).toBe(true)
+ expect(await visitAt(start + 25 * hour)).toEqual({
+ capped: true,
+ nextSlotAt: start + 47 * hour,
+ holdHours: 12,
+ })
})
it('counts a push to a named person against that person, not the run person', async () => {
- frequencyCap = { max_messages: 1, window_days: 7 }
+ frequencyCap = { max_messages: 1, window_days: 7, hold_hours: null }
persons.getCyclotronPerson.mockResolvedValue({ id: 'named-person-id' })
const pushToNamed: Extract<HogFlowAction, { type: 'function_push' }> = {
id: 'push',
@@ -770,9 +780,17 @@ describe('RecipientPreferencesService', () => {
})
it.each([
- ['transactional sends', emailAction('transactional'), { max_messages: 0, window_days: 7 }],
- ['marketing sends that skip the cap', emailAction('marketing', true), { max_messages: 1, window_days: 7 }],
- ['teams with no cap', emailAction(), { max_messages: null, window_days: null }],
+ [
+ 'transactional sends',
+ emailAction('transactional'),
+ { max_messages: 0, window_days: 7, hold_hours: null },
+ ],
+ [
+ 'marketing sends that skip the cap',
+ emailAction('marketing', true),
+ { max_messages: 1, window_days: 7, hold_hours: null },
+ ],
+ ['teams with no cap', emailAction(), { max_messages: null, window_days: null, hold_hours: null }],
])('never caps %s', async (_, action, cap) => {
frequencyCap = cap
for (let i = 0; i < 3; i++) {
diff --git a/nodejs/src/cdp/services/messaging/recipient-preferences.service.ts b/nodejs/src/cdp/services/messaging/recipient-preferences.service.ts
index b9963c487801..6bf19cb6b079 100644
--- a/nodejs/src/cdp/services/messaging/recipient-preferences.service.ts
+++ b/nodejs/src/cdp/services/messaging/recipient-preferences.service.ts
@@ -23,14 +23,28 @@ export type RecipientSkipReason = 'suppressed' | 'opted_out'
// is keyed on the step visit. The email queue and send retries run the same step visit again, so a
// visit that already holds a slot passes. That run also moves the slot score to now, because the email
// queue can delay the actual send by hours and the window must start when the email goes out.
+// A capped call returns the time in ms when the next slot frees up: the oldest slot that must leave
+// the window before the count drops below the cap. An allowed call returns 0.
const FREQUENCY_CAP_SCRIPT = `
redis.call('ZREMRANGEBYSCORE', KEYS[1], '-inf', tonumber(ARGV[1]) - tonumber(ARGV[2]))
-if not redis.call('ZSCORE', KEYS[1], ARGV[4]) and redis.call('ZCARD', KEYS[1]) >= tonumber(ARGV[3]) then return 1 end
+if not redis.call('ZSCORE', KEYS[1], ARGV[4]) then
+ local count = redis.call('ZCARD', KEYS[1])
+ if count >= tonumber(ARGV[3]) then
+ local freeing = redis.call('ZRANGE', KEYS[1], count - tonumber(ARGV[3]), count - tonumber(ARGV[3]), 'WITHSCORES')
+ return tonumber(freeing[2]) + tonumber(ARGV[2])
+ end
+end
redis.call('ZADD', KEYS[1], ARGV[1], ARGV[4])
redis.call('PEXPIRE', KEYS[1], ARGV[2])
return 0
`
+export type FrequencyCapCheck =
+ | { capped: false }
+ // nextSlotAt is when the person can get a marketing message again, in ms. holdHours is how long the
+ // team lets a capped message wait for that slot; null means skip it.
+ | { capped: true; nextSlotAt: number; holdHours: number | null }
+
export class RecipientPreferencesService {
constructor(
private recipientsManager: RecipientsManagerService,
@@ -42,11 +56,11 @@ export class RecipientPreferencesService {
}
) {}
- /** Returns true when the person is at the cap. Otherwise records this send against the cap and returns false. */
- public async isFrequencyCapped(
+ /** Reports whether the person is at the cap. When they are not, records this send against the cap. */
+ public async checkFrequencyCap(
invocation: CyclotronJobInvocationHogFunction,
action: HogFlowAction
- ): Promise<boolean> {
+ ): Promise<FrequencyCapCheck> {
const messageAction = this.asMessageAction(action)
if (
!this.frequencyCap ||
@@ -54,20 +68,19 @@ export class RecipientPreferencesService {
messageAction.config.message_category_type === 'transactional' ||
(messageAction.type === 'function_email' && messageAction.config.skip_frequency_cap === true)
) {
- return false
+ return { capped: false }
}
try {
- const { max_messages, window_days } = await this.frequencyCap.teamWorkflowsConfig.getFrequencyCap(
- invocation.teamId
- )
+ const { max_messages, window_days, hold_hours } =
+ await this.frequencyCap.teamWorkflowsConfig.getFrequencyCap(invocation.teamId)
if (!max_messages || !window_days) {
- return false
+ return { capped: false }
}
const personId = await this.cappedPersonId(invocation, messageAction, this.frequencyCap.persons)
if (!personId) {
- return false
+ return { capped: false }
}
- const capped = await this.frequencyCap.valkey.useClient(
+ const nextSlotAt = await this.frequencyCap.valkey.useClient(
{ name: 'workflows-frequency-cap', failOpen: true },
(client) =>
client.eval(
@@ -80,12 +93,12 @@ export class RecipientPreferencesService {
workflowStepDispatchKeyFromInvocation(invocation) ?? `${invocation.id}:${action.id}`
) as Promise<number>
)
- return capped === 1
+ return nextSlotAt ? { capped: true, nextSlotAt, holdHours: hold_hours } : { capped: false }
} catch (error) {
// Fail open: a config or Valkey pool error must never block a send. failOpen above only
// covers errors inside the Valkey callback.
logger.error(`Failed to check the frequency cap for team ${invocation.teamId}:`, error)
- return false
+ return { capped: false }
}
}
diff --git a/nodejs/src/cdp/types.ts b/nodejs/src/cdp/types.ts
index ef962fa084c5..2bb28279f5e4 100644
--- a/nodejs/src/cdp/types.ts
+++ b/nodejs/src/cdp/types.ts
@@ -262,6 +262,7 @@ export type MinimalAppMetric = {
| 'email_bounced_undetermined'
| 'email_bounce_prevented'
| 'message_frequency_capped'
+ | 'message_frequency_cap_held'
| 'email_suppressed'
| 'email_missing_recipient'
| 'email_suspended'
@@ -560,6 +561,9 @@ export type HogFlowInvocationContext = {
parkedAt?: string
}
resumeResult?: { key: string; status: WorkflowStepResumeStatus; result?: Record<string, unknown> }
+ // Set when a message step first finds the person at the frequency cap and the team holds capped
+ // messages. The step re-checks the cap on each wake and skips the send once this ISO time passes.
+ frequencyCapHoldDeadlineAt?: string
}
// Set by the subscription matcher consumer when an incoming event matched the
// workflow's event-based conversion goals. shouldExitEarly reads and clears it.