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.

11.8 KB
Raw Blame
import { DateTime, DurationLike } from 'luxon'

import { HogFlowAction } from '~/cdp/schema/hogflow'
import { CyclotronJobInvocationHogFlow } from '~/cdp/types'
import { execHog } from '~/cdp/utils/hog-exec'

import { ParsedDuration, SECONDS_PER_DURATION_UNIT, parseDuration } from '../duration'
import { findContinueAction } from '../hogflow-utils'
import { ActionHandler, ActionHandlerOptions, ActionHandlerResult } from './action.interface'
import { resolveTimezone } from './timezone'

export class DelayHandler implements ActionHandler {
    async execute({
        invocation,
        action,
    }: ActionHandlerOptions<Extract<HogFlowAction, { type: 'delay' }>>): Promise<ActionHandlerResult> {
        const nextScheduledAt = action.config.delay_until
            ? await scheduledAtFromInstant(action, invocation)
            : calculatedScheduledAt(
                  action.config.delay_duration ?? '',
                  invocation.state.currentAction?.startedAtTimestamp,
                  undefined,
                  MAX_DELAY_VALUE_FOR_DURATION_UNIT
              )

        // While the delay is still pending, park WITHOUT advancing currentAction. Advancing eagerly
        // (returning nextAction alongside scheduledAt) made the job look like it was already at the
        // next step for the whole delay, so the subscription matcher could wake it — e.g. when the
        // next step is a wait_until_condition whose event fires — and collapse the delay. Advance only
        // once the delay has elapsed (calculatedScheduledAt returns null).
        if (nextScheduledAt) {
            return { scheduledAt: nextScheduledAt }
        }

        return { nextAction: findContinueAction(invocation) }
    }
}

const DEFAULT_MAX_DELAY_UNTIL = '30d'

// The last second luxon (and JS Date) can represent as a real date, end of year 9999. A numeric value larger
// than this is a millisecond timestamp mislabelled as seconds, not a plausible date to wait for.
const MAX_UNIX_SECONDS = 253402300799

/**
 * Seconds for a signed offset, at its full magnitude.
 *
 * Deliberately not held to the per-unit ceilings a fixed delay uses. Those exist to bound how long a run
 * waits, which `max_delay_duration` already does here, and applying them to an offset would shorten it
 * without saying so: "48 hours before" would become "24 hours before" and fire the message a day late.
 */
function offsetSeconds(value: string): number | null {
    const parsed = parseDuration(value)
    if (!parsed) {
        return null
    }
    return (parsed.negative ? -1 : 1) * parsed.amount * SECONDS_PER_DURATION_UNIT[parsed.unit]
}

/** Seconds for the wait's ceiling, using the same units and per-unit ceilings as a fixed delay. */
function maxDelaySeconds(value: string): number | null {
    const parsed = parseDuration(value)
    if (!parsed || parsed.negative) {
        return null
    }
    return clampedAmount(parsed, MAX_DELAY_VALUE_FOR_DURATION_UNIT) * SECONDS_PER_DURATION_UNIT[parsed.unit]
}

/** The amount a step is allowed to wait for, held to this unit's ceiling. */
function clampedAmount(parsed: ParsedDuration, ceilings: DurationCeilings): number {
    return Math.min(ceilings[parsed.unit], parsed.amount)
}

/**
 * The instant a `delay_until` expression evaluates to, or null when it yields nothing usable.
 *
 * `zone` only decides how a value that carries no offset of its own is read — a bare date or a local
 * datetime string. Luxon keeps the offset a value already states, and unix seconds and HogDateTime are
 * absolute, so those are unaffected by the zone.
 */
function instantFromHogValue(value: unknown, zone: string): DateTime | null {
    if (value && typeof value === 'object' && '__hogDateTime__' in (value as Record<string, unknown>)) {
        const seconds = (value as { dt?: unknown }).dt
        if (typeof seconds !== 'number' || !Number.isFinite(seconds)) {
            // HogQL hands back a HogDateTime holding whatever it managed to parse, so toDateTime('not a date')
            // arrives here as NaN seconds. Left alone that becomes an instant the queue cannot schedule.
            return null
        }
        const asHogDateTime = DateTime.fromSeconds(seconds, { zone: 'UTC' })
        return asHogDateTime.isValid ? asHogDateTime : null
    }
    if (typeof value === 'number') {
        // Unix seconds, matching toUnixTimestamp(). A millisecond timestamp — what Date.now() and most SDKs
        // produce — is ~1000x too large and lands tens of thousands of years out, where the max-delay clamp
        // would swallow it silently. luxon still calls that instant valid, so reject anything past the last
        // representable second rather than guess the unit.
        if (value > MAX_UNIX_SECONDS) {
            return null
        }
        const asSeconds = DateTime.fromSeconds(value, { zone: 'UTC' })
        return asSeconds.isValid ? asSeconds : null
    }
    if (typeof value === 'string') {
        const parsed = DateTime.fromISO(value, { zone })
        return parsed.isValid ? parsed : null
    }
    return null
}

/**
 * When to continue for a `delay_until` step: the instant its expression evaluates to, plus any offset,
 * clamped to `max_delay_duration` past the step's start. Returns null once that instant has passed.
 *
 * Re-evaluated on every wake rather than only on entry, so a stored date that moves *later* while the run
 * is parked is honoured: the job wakes at the old, earlier instant and re-parks to the new one. A date
 * that moves *earlier* is only noticed once the old instant passes, because the only wake for a parked
 * delay is that stored instant — the subscription matcher never pulls a delay forward. Waking early is
 * free; the step simply re-parks to the new instant.
 */
async function scheduledAtFromInstant(
    action: Extract<HogFlowAction, { type: 'delay' }>,
    invocation: CyclotronJobInvocationHogFlow
): Promise<DateTime | null> {
    const config = action.config.delay_until!
    const startedAtTimestamp = invocation.state.currentAction?.startedAtTimestamp
    if (!startedAtTimestamp) {
        throw new Error("'startedAtTimestamp' is not set or is invalid")
    }

    if (!Array.isArray(config.bytecode) || config.bytecode.length === 0) {
        throw new Error(`Could not read the date to wait for: ${config.bytecode_error ?? 'no compiled expression'}`)
    }

    const globals = { ...invocation.filterGlobals, variables: invocation.state.variables }
    const { execResult, error } = await execHog(config.bytecode, { globals })
    const evaluationError = error ?? execResult?.error
    const zone = resolveTimezone(config, invocation.person)

    // A resumed invocation rebuilds its globals from stored state, which can arrive without the event or
    // person properties the expression reads — so evaluation can error (a missing global raises) or yield a
    // non-date on wake even though it resolved on entry. Re-evaluating is still worth attempting every wake,
    // because it is what lets a stored date that moved while parked be honoured — but it must not strand a
    // run that already resolved once, so an unusable evaluation falls back to the instant recorded on the
    // first park before giving up.
    const previous = invocation.state.currentAction?.delayUntilAt
    const instant =
        (evaluationError ? null : instantFromHogValue(execResult?.result, zone)) ??
        (previous ? DateTime.fromISO(previous, { zone: 'UTC' }) : null)
    if (!instant) {
        // Marked so the run aborts rather than falling through to the next step. on_error defaults to
        // 'continue', which for a "N days before X" message means sending it with nothing to be before.
        if (invocation.state.currentAction) {
            invocation.state.currentAction.delayUntilUnresolved = true
        }
        throw new Error(
            evaluationError
                ? `Could not read the date to wait for: ${String(evaluationError)}`
                : 'The date to wait for did not evaluate to a date'
        )
    }
    if (invocation.state.currentAction) {
        invocation.state.currentAction.delayUntilAt = instant.toISO() ?? undefined
        // The wait resolved, so a marker left by an earlier attempt must not outlive it and turn some later
        // failure of this step into an abort the author never asked for.
        delete invocation.state.currentAction.delayUntilUnresolved
    }

    const offset = config.offset ? offsetSeconds(config.offset) : 0
    if (offset === null) {
        throw new Error(`Invalid offset: ${config.offset}`)
    }

    const target = instant.plus({ seconds: offset })
    // A ceiling that cannot be read falls back to the default rather than to nothing: zero would put the cap
    // at the step's own start, which continues the run immediately - the outcome the wait exists to prevent.
    const maxSeconds =
        maxDelaySeconds(action.config.max_delay_duration ?? DEFAULT_MAX_DELAY_UNTIL) ??
        maxDelaySeconds(DEFAULT_MAX_DELAY_UNTIL)!
    const cap = DateTime.fromMillis(startedAtTimestamp).toUTC().plus({ seconds: maxSeconds })
    // An offset large enough to push the date past luxon's representable range makes the target invalid, and
    // an invalid DateTime compares false against everything — so it would slip past the cap below and hand the
    // queue an unschedulable instant. Treat it like any out-of-range target: a future overflow is bounded by
    // the cap, a past one has already elapsed.
    if (!target.isValid) {
        return offset > 0 && DateTime.utc() < cap ? cap : null
    }
    const scheduledAt = target > cap ? cap : target

    return DateTime.utc() >= scheduledAt ? null : scheduledAt
}

const LUXON_UNIT = { d: 'days', h: 'hours', m: 'minutes', s: 'seconds' } as const

type DurationCeilings = Record<string, number>

// How long one step may wait, per unit. A delay parks once and wakes once, so it can run to a year.
// A wait stays registered with the subscription matcher while it parks, so it keeps the shorter cap.
// Mirrored in products/workflows/backend/utils/durations.py.
export const MAX_DELAY_VALUE_FOR_DURATION_UNIT: DurationCeilings = {
    d: 365,
    h: 24,
    m: 60,
    s: 60,
}

export const MAX_WAIT_VALUE_FOR_DURATION_UNIT: DurationCeilings = {
    d: 30,
    h: 24,
    m: 60,
    s: 60,
}

/**
 * Helper for the common case of delaying a hog flow action.
 * We calculate the delay value and return the scheduleAt based on the time the action started.
 * If an optional value is given of the max delay duration, we will use that instead of the default.
 */
export function calculatedScheduledAt(
    value: string,
    startedAtTimestamp?: number,
    maxDelaySeconds?: number,
    ceilings: DurationCeilings = MAX_WAIT_VALUE_FOR_DURATION_UNIT
): DateTime | null {
    const actionStartedAt = startedAtTimestamp ? DateTime.fromMillis(startedAtTimestamp).toUTC() : null

    if (!actionStartedAt || !actionStartedAt.isValid) {
        throw new Error("'startedAtTimestamp' is not set or is invalid")
    }

    const parsed = parseDuration(value)

    if (!parsed || parsed.negative) {
        throw new Error(`Invalid duration: ${value}`)
    }

    const duration: DurationLike = { [LUXON_UNIT[parsed.unit]]: clampedAmount(parsed, ceilings) }

    const waitUntilTime = actionStartedAt.plus(duration)

    if (DateTime.utc().diff(waitUntilTime).as('seconds') > 0) {
        // If the wait until time has already passed, we can just return to indicate no delay is needed
        return null
    }

    if (!maxDelaySeconds) {
        return waitUntilTime
    }

    // If a max delay seconds is provided, we will use that if smaller than the wait until time
    // NOTE: We use `utc` here as this is about clamping the total time for the new schedule, not about a relative time from when the action started
    let scheduledAt = DateTime.utc().plus({ seconds: maxDelaySeconds })

    if (waitUntilTime.diff(scheduledAt).as('seconds') < 0) {
        scheduledAt = waitUntilTime
    }

    return scheduledAt
}