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.

13.3 KB
Raw Blame
import { Dayjs, dayjs } from 'lib/dayjs'

import {
    FeatureFlagConfig,
    FeatureFlagGroupType,
    FeatureFlagType,
    RecurrenceInterval,
    ScheduledChangeOperationType,
    ScheduledChangeRequestState,
    ScheduledChangeType,
} from '~/types'

import { resolveAggregationGroupTypeIndex } from './aggregation'

/** Flag state as projected after a scheduled change occurrence has applied. */
export interface ScheduleProjectedState {
    active: boolean
    /** What the flag reaches on its own aggregation target. See maxUntargetedRolloutPercentage. */
    rolloutPercentage: number | null
    /** Null for flags with no variants. */
    variantCount: number | null
}

export interface ScheduleOccurrence {
    /** ISO timestamp of when this occurrence fires. */
    timestamp: string
    operation: ScheduledChangeOperationType
    schedule: ScheduledChangeType
    projected: ScheduleProjectedState
    /** Max rollout of the condition this occurrence adds; null for other operations. */
    addedRolloutPercentage: number | null
    /**
     * True when this occurrence adds a condition on the flag-level target at or below the projected
     * rollout on that target. The flag does not have to be active. Such a condition reaches nobody new,
     * so the projected rollout holds its level. False for every other operation.
     */
    rolloutUnchanged: boolean
    /** The occurrence will be skipped at fire time unless its approval request is approved first. */
    needsApproval: boolean
}

export const OCCURRENCE_CAP = 10
export const OCCURRENCE_HORIZON_DAYS = 90

const INTERVAL_UNIT: Record<RecurrenceInterval, 'day' | 'week' | 'month' | 'year'> = {
    [RecurrenceInterval.Daily]: 'day',
    [RecurrenceInterval.Weekly]: 'week',
    [RecurrenceInterval.Monthly]: 'month',
    [RecurrenceInterval.Yearly]: 'year',
}

/** Matches MAX_CATCHUP_ITERATIONS in posthog/tasks/process_scheduled_changes.py. */
const CATCHUP_CAP = 1000

/**
 * Advances a stalled recurring date to its first fire after `now`, as the sweep's catch-up loop
 * does. The sweep skips the missed fires instead of replaying them, so this projects one date.
 */
function catchUpToFuture(from: Dayjs, unit: 'day' | 'week' | 'month' | 'year', now: Dayjs): Dayjs {
    // Step from the previous date rather than add N intervals to the origin, because month-end
    // clamping is path dependent: a monthly schedule from Oct 31 gives Nov 30, then Dec 30.
    let next = from
    for (let step = 0; step < CATCHUP_CAP && !next.isAfter(now); step++) {
        next = next.add(1, unit)
    }
    // The sweep gives up the same way at its own cap and computes the next run from now.
    return next.isAfter(now) ? next : now.add(1, unit)
}

/** Null/undefined rollout means the condition set matches 100% of its targets. */
export function maxRolloutPercentage(groups: FeatureFlagGroupType[] | undefined): number | null {
    if (!groups?.length) {
        return null
    }
    return Math.max(...groups.map((group) => group.rollout_percentage ?? 100))
}

/**
 * The aggregation target every one of these condition sets buckets on, or undefined when they do
 * not share one.
 */
export function sharedAggregationTarget(
    groups: FeatureFlagGroupType[] | undefined,
    flagAggregationGroupTypeIndex: number | null | undefined
): number | null | undefined {
    const targets = new Set(
        (groups ?? []).map((group) =>
            resolveAggregationGroupTypeIndex(group.aggregation_group_type_index, flagAggregationGroupTypeIndex)
        )
    )
    return targets.size === 1 ? [...targets][0] : undefined
}

/**
 * Max rollout across the condition sets that no property filter narrows and that bucket on
 * `targetAggregationGroupTypeIndex`. The result is a share of everyone that a condition on that
 * target reaches, not a share of a segment.
 */
export function maxUntargetedRolloutPercentage(
    groups: FeatureFlagGroupType[] | undefined,
    flagAggregationGroupTypeIndex: number | null | undefined,
    targetAggregationGroupTypeIndex: number | null | undefined
): number | null {
    if (targetAggregationGroupTypeIndex === undefined) {
        return null
    }
    return maxRolloutPercentage(
        groups?.filter(
            (group) =>
                !group.properties?.length &&
                resolveAggregationGroupTypeIndex(group.aggregation_group_type_index, flagAggregationGroupTypeIndex) ===
                    targetAggregationGroupTypeIndex
        )
    )
}

/**
 * What the flag reaches on its own aggregation target.
 *
 * FeatureFlagSchedule passes this value to ScheduleTimeline as the step line's starting level.
 * expandScheduleOccurrences starts its projected steps from the same value. Both must call this
 * function. If one of them counted every condition set, a property-filtered set would lift only that
 * side. The chart would then draw a gain or a loss of reach that the flag never makes.
 */
export function projectedRolloutPercentage(
    filters: Pick<FeatureFlagConfig, 'groups' | 'aggregation_group_type_index'>
): number | null {
    return maxUntargetedRolloutPercentage(
        filters.groups,
        filters.aggregation_group_type_index,
        resolveAggregationGroupTypeIndex(undefined, filters.aggregation_group_type_index)
    )
}

/** A paused recurring schedule keeps its recurrence config but has is_recurring=false. */
export function isSchedulePaused(sc: ScheduledChangeType): boolean {
    return !sc.is_recurring && (!!sc.recurrence_interval || !!sc.cron_expression)
}

// A bound approval request that was rejected or expired means its current occurrence will not
// apply: apply_gated_scheduled_change skips it. A one-time change is then dropped entirely; a
// recurring one loses only this occurrence — the backend advances scheduled_at and re-gates the next.
export function hasDeniedApprovalRequest(sc: ScheduledChangeType): boolean {
    return (
        sc.change_request?.state === ScheduledChangeRequestState.Rejected ||
        sc.change_request?.state === ScheduledChangeRequestState.Expired
    )
}

/**
 * Expands active scheduled changes into the chronological list of upcoming occurrences, each with
 * the flag state projected after it applies (starting from the flag's current state).
 *
 * Every schedule contributes its `scheduled_at` occurrence. Cron schedules contribute only that one:
 * the backend keeps `scheduled_at` pointed at the next cron run, and further runs are deliberately
 * not expanded here (lib/cron could compute them; one next-run point is enough for this panel).
 * Fixed-interval recurring schedules expand further with date arithmetic, bounded by their end
 * date, the horizon, and the overall cap.
 */
export function expandScheduleOccurrences(
    schedules: ScheduledChangeType[],
    flag: Pick<FeatureFlagType, 'active' | 'filters'>,
    now: Dayjs
): ScheduleOccurrence[] {
    const horizon = now.add(OCCURRENCE_HORIZON_DAYS, 'day')
    const raw: { at: Dayjs; schedule: ScheduledChangeType; isFirst: boolean }[] = []

    for (const schedule of schedules) {
        if (schedule.executed_at || isSchedulePaused(schedule)) {
            continue
        }
        // Parse in UTC so recurrence arithmetic below adds fixed 24h days/weeks, matching the
        // backend's relativedelta on the stored UTC instant. Browser-local .add() would preserve
        // wall-clock across a DST transition and drift the projected fire time by an hour.
        const parsed = dayjs.utc(schedule.scheduled_at)
        if (!parsed.isValid()) {
            continue
        }
        const end = schedule.end_date ? dayjs.utc(schedule.end_date) : null
        // The sweep closes out a recurring window whose end_date has passed, and it fires nothing
        // (process_scheduled_changes stamps executed_at when end_date <= now). Such a row can still
        // hold a future scheduled_at, because the sweep advances that date without reading end_date
        // and closes the row only once the date arrives.
        if (end && !end.isAfter(now) && (schedule.recurrence_interval || schedule.cron_expression)) {
            continue
        }
        // Only a fixed-interval recurrence expands here. A cron schedule contributes its stored
        // next run alone, because the client does not evaluate cron expressions.
        const unit =
            schedule.is_recurring && schedule.recurrence_interval && !schedule.cron_expression
                ? INTERVAL_UNIT[schedule.recurrence_interval]
                : null

        let first = parsed
        // isFirst distinguishes the occurrence the schedule's current change request covers from
        // the later ones the backend will re-gate. See needsApproval below.
        let isFirst = true
        if (!first.isAfter(now)) {
            // A stalled schedule keeps a past scheduled_at with executed_at still null: the sweep
            // defers on ApprovalRequired, and a recoverable failure retries in place. Projecting
            // that instant as upcoming clamps it to the axis origin and labels it "now".
            if (!unit) {
                continue
            }
            first = catchUpToFuture(first, unit, now)
            // The bound request covered the fire that never happened, so the sweep re-gates this
            // one and it must not read as certain.
            isFirst = false
        }
        if (end && first.isAfter(end)) {
            continue
        }
        // Skip a denied change's current occurrence; the backend re-gates the next, which the
        // recurrence expansion below still projects. A denied one-time schedule then ends up with
        // no occurrence at all, and so does a denied recurring cron schedule, because its next run
        // is not computed client-side.
        if (!(isFirst && hasDeniedApprovalRequest(schedule))) {
            raw.push({ at: first, schedule, isFirst })
        }

        if (unit) {
            // Derive each occurrence from the previous one, as the backend does when it advances
            // scheduled_at (process_scheduled_changes.compute_next_run). A month-end start then stays
            // clamped (Jan 31 -> Feb 28 -> Mar 28); adding from the origin each step would restore the
            // 31st and paint flip dates the flag never fires on.
            let next = first
            for (let step = 1; step < OCCURRENCE_CAP; step++) {
                next = next.add(1, unit)
                if (next.isAfter(horizon) || (end && next.isAfter(end))) {
                    break
                }
                raw.push({ at: next, schedule, isFirst: false })
            }
        }
    }

    raw.sort((a, b) => a.at.valueOf() - b.at.valueOf() || a.schedule.id - b.schedule.id)

    let active = flag.active
    const flagAggregation = flag.filters.aggregation_group_type_index
    const flagTarget = resolveAggregationGroupTypeIndex(undefined, flagAggregation)
    let rolloutPercentage = projectedRolloutPercentage(flag.filters)
    let variantCount = flag.filters.multivariate?.variants.length ?? null

    return raw.slice(0, OCCURRENCE_CAP).map(({ at, schedule, isFirst }) => {
        const { payload } = schedule
        let addedRolloutPercentage: number | null = null
        let rolloutUnchanged = false
        if (payload.operation === ScheduledChangeOperationType.UpdateStatus) {
            active = payload.value
        } else if (payload.operation === ScheduledChangeOperationType.AddReleaseCondition) {
            const addedGroups = payload.value.groups
            addedRolloutPercentage = maxRolloutPercentage(addedGroups)
            // Only sets on the added condition's own target can cover it. The backend appends only the
            // payload's groups. Each group keeps its own target. A payload-level target never applies.
            // The no-change copy quotes the projected level, which counts only sets on the flag-level
            // target. A condition on another target is therefore not judged here.
            rolloutUnchanged =
                addedRolloutPercentage !== null &&
                rolloutPercentage !== null &&
                sharedAggregationTarget(addedGroups, flagAggregation) === flagTarget &&
                addedRolloutPercentage <= rolloutPercentage
            const addedLevel = maxUntargetedRolloutPercentage(addedGroups, flagAggregation, flagTarget)
            if (addedLevel !== null) {
                rolloutPercentage = rolloutPercentage === null ? addedLevel : Math.max(rolloutPercentage, addedLevel)
            }
        } else if (payload.operation === ScheduledChangeOperationType.UpdateVariants) {
            variantCount = payload.value.variants.length
        }
        return {
            timestamp: at.toISOString(),
            operation: payload.operation,
            schedule,
            projected: { active, rolloutPercentage, variantCount },
            addedRolloutPercentage,
            rolloutUnchanged,
            // A bound change request covers one occurrence only. The first occurrence needs approval
            // when its own request is still pending. Every later occurrence of a gated schedule
            // needs one too: regate_recurring_scheduled_change binds a fresh pending request after
            // each fire, and apply_gated_scheduled_change skips an occurrence whose request is still
            // pending when the fire window closes.
            needsApproval: isFirst
                ? schedule.change_request?.state === ScheduledChangeRequestState.Pending
                : !!schedule.change_request,
        }
    })
}