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.

28.9 KB
Raw Blame
import { DateTime } from 'luxon'

import { FixtureHogFlowBuilder } from '~/cdp/_tests/builders/hogflow.builder'
import { HOG_FILTERS_EXAMPLES } from '~/cdp/_tests/examples'
import { createExampleHogFlowInvocation } from '~/cdp/_tests/fixtures-hogflows'
import { HogFlow, HogFlowAction } from '~/cdp/schema/hogflow'
import { CohortMembershipRepository, StoredCohortMembership } from '~/cdp/services/cohorts/cohort-membership-repository'
import { CyclotronJobInvocationHogFlow } from '~/cdp/types'
import { createInvocationResult } from '~/cdp/utils/invocation-utils'

import { findActionById, findActionByType } from '../hogflow-utils'
import {
    ConditionalBranchHandler,
    checkConditions,
    counterHogflowRekeyWake,
    counterHogflowWaitAdvancedAtMaxWait,
    counterHogflowWaitPersonRefreshFailed,
} from './conditional_branch'

const lateAdvanceCount = async (): Promise<number> =>
    (await counterHogflowWaitAdvancedAtMaxWait.get()).values[0]?.value ?? 0

const lateAdvanceLabels = async (): Promise<Record<string, string | number> | undefined> =>
    (await counterHogflowWaitAdvancedAtMaxWait.get()).values[0]?.labels

const personRefreshFailedCount = async (): Promise<number> =>
    (await counterHogflowWaitPersonRefreshFailed.get()).values[0]?.value ?? 0

const rekeyWakeCount = async (outcome: 'advanced' | 'reparked'): Promise<number> =>
    (await counterHogflowRekeyWake.get()).values.find((v) => v.labels.outcome === outcome)?.value ?? 0

describe('action.conditional_branch', () => {
    let invocation: CyclotronJobInvocationHogFlow
    let action: Extract<HogFlowAction, { type: 'conditional_branch' }>
    let hogFlow: HogFlow

    beforeEach(() => {
        const fixedTime = DateTime.fromObject({ year: 2025, month: 1, day: 1 }, { zone: 'UTC' })
        jest.spyOn(Date, 'now').mockReturnValue(fixedTime.toMillis())

        hogFlow = new FixtureHogFlowBuilder()
            .withWorkflow({
                actions: {
                    conditional_branch: {
                        type: 'conditional_branch',
                        config: {
                            conditions: [
                                {
                                    filters: HOG_FILTERS_EXAMPLES.pageview_or_autocapture_filter.filters, // Match for pageviews
                                },
                            ], // Filled by tests
                        },
                    },
                    condition_1: {
                        type: 'delay',
                        config: {
                            delay_duration: '2h',
                        },
                    },
                    condition_2: {
                        type: 'delay',
                        config: {
                            delay_duration: '2h',
                        },
                    },
                },
                edges: [
                    {
                        from: 'conditional_branch',
                        to: 'condition_2',
                        type: 'branch',
                        index: 1,
                    },
                    {
                        from: 'conditional_branch',
                        to: 'condition_1',
                        type: 'branch',
                        index: 0,
                    },
                ],
            })
            .build()

        action = findActionByType(hogFlow, 'conditional_branch')!
        invocation = createExampleHogFlowInvocation(hogFlow)

        invocation.state.currentAction = {
            id: action.id,
            startedAtTimestamp: DateTime.utc().toMillis(),
        }
    })

    describe('no matching events', () => {
        it('should return finished if no matches', async () => {
            invocation.state.event!.event = 'no-match'
            const result = await checkConditions(invocation, action)
            expect(result).toEqual({})
        })

        // A wait arrives here already normalised into a conditional_branch, so its ceiling comes in
        // as `repark` rather than off the action. A branch without one never parks.
        describe('wait logic', () => {
            const repark = (maxWaitDuration: string) => ({ maxWaitDuration })

            it('should park for the whole ceiling', async () => {
                const result = await checkConditions(invocation, action, undefined, repark('2h'))
                expect(result).toEqual({ scheduledAt: DateTime.utc().plus({ hours: 2 }) })
            })

            it('should park a short ceiling for its own duration', async () => {
                const result = await checkConditions(invocation, action, undefined, repark('5m'))
                expect(result).toEqual({ scheduledAt: DateTime.utc().plus({ minutes: 5 }) })
            })

            it('should not schedule at all without a ceiling', async () => {
                const result = await checkConditions(invocation, action)
                expect(result).toEqual({})
            })

            it('should throw error if action started at timestamp is invalid', async () => {
                invocation.state.currentAction = undefined
                await expect(async () =>
                    checkConditions(invocation, action, undefined, repark('300s'))
                ).rejects.toThrow("'startedAtTimestamp' is not set or is invalid")
            })
        })
    })

    describe('matching events', () => {
        beforeEach(() => {
            invocation = createExampleHogFlowInvocation(hogFlow, {
                // These values match the pageview_or_autocapture_filter
                event: {
                    event: '$pageview',
                    properties: {
                        $current_url: 'https://posthog.com',
                    },
                } as any,
            })
        })

        it('should match condition and go to action', async () => {
            const result = await checkConditions(invocation, action)
            expect(result).toEqual({
                nextAction: findActionById(invocation.hogFlow, 'condition_1'),
            })
        })

        it('should ignore conditions that do not match', async () => {
            action.config.conditions = [
                {
                    filters: HOG_FILTERS_EXAMPLES.elements_text_filter.filters, // No match
                },
                {
                    filters: HOG_FILTERS_EXAMPLES.pageview_or_autocapture_filter.filters, // No match
                },
            ]

            const result = await checkConditions(invocation, action)
            expect(result).toEqual({
                nextAction: findActionById(invocation.hogFlow, 'condition_2'),
            })
        })

        it('should execute the first matching branch when multiple conditions match', async () => {
            action.config.conditions = [
                {
                    filters: HOG_FILTERS_EXAMPLES.pageview_or_autocapture_filter.filters, // Match
                },
                {
                    filters: HOG_FILTERS_EXAMPLES.no_filters.filters, // Also matches (always true)
                },
            ]

            const result = await checkConditions(invocation, action)
            expect(result).toEqual({
                nextAction: findActionById(invocation.hogFlow, 'condition_1'),
            })
        })
    })

    describe('cohort membership conditions', () => {
        const COHORT_ID = 42

        class FakeCohortMembershipRepository implements CohortMembershipRepository {
            public calls: { teamId: number; personUuid: string }[] = []

            constructor(
                private memberCohortIds: number[],
                private error?: Error
            ) {}

            getMemberCohortIds(teamId: number, personUuid: string): Promise<number[]> {
                this.calls.push({ teamId, personUuid })
                if (this.error) {
                    return Promise.reject(this.error)
                }
                return Promise.resolve(this.memberCohortIds)
            }

            getCohortMembership(): Promise<StoredCohortMembership | null> {
                return Promise.reject(new Error('not used by branches'))
            }
        }

        // Same shape the Python serializer emits: the authored properties plus compiled bytecode.
        // Keeping the properties key matters: filters holding ONLY bytecode short-circuit to an
        // unconditional match in filterFunctionInstrumented and never execute the VM.
        const cohortConditionFilters = (fn: 'inCohort' | 'notInCohort'): Record<string, any> => ({
            bytecode: ['_H', 1, 33, COHORT_ID, 32, 'cohort_ids', 1, 1, 2, fn, 2],
            properties: [{ key: 'id', type: 'cohort', value: COHORT_ID }],
        })

        const executeWithRepository = async (
            repository: CohortMembershipRepository,
            fn: 'inCohort' | 'notInCohort'
        ): Promise<HogFlowAction | undefined> => {
            action.config.conditions = [
                { filters: cohortConditionFilters(fn) },
                { filters: HOG_FILTERS_EXAMPLES.no_filters.filters }, // always-true fallthrough
            ]
            const handler = new ConditionalBranchHandler(repository)
            const result = await handler.execute({
                invocation,
                action,
                result: createInvocationResult(invocation),
            })
            return result.nextAction
        }

        it.each([
            ['inCohort', true, 'condition_1'],
            ['inCohort', false, 'condition_2'],
            ['notInCohort', false, 'condition_1'],
            ['notInCohort', true, 'condition_2'],
        ] as const)('routes %s with membership=%s to %s', async (fn, isMember, expectedActionId) => {
            const repository = new FakeCohortMembershipRepository(isMember ? [7, COHORT_ID] : [7])

            const nextAction = await executeWithRepository(repository, fn)

            expect(nextAction).toEqual(findActionById(invocation.hogFlow, expectedActionId))
            expect(repository.calls).toEqual([
                { teamId: invocation.hogFlow.team_id, personUuid: invocation.person!.id },
            ])
        })

        it('does not query membership when an earlier non-cohort condition matches', async () => {
            // The lookup is lazy: a run that never reaches the cohort condition must not depend on
            // the behavioral cohorts DB, even when that DB is down.
            const repository = new FakeCohortMembershipRepository([], new Error('cohorts DB down'))
            action.config.conditions = [
                { filters: HOG_FILTERS_EXAMPLES.no_filters.filters }, // matches first
                { filters: cohortConditionFilters('inCohort') },
            ]
            const handler = new ConditionalBranchHandler(repository)

            const result = await handler.execute({
                invocation,
                action,
                result: createInvocationResult(invocation),
            })

            expect(result.nextAction).toEqual(findActionById(invocation.hogFlow, 'condition_1'))
            expect(repository.calls).toEqual([])
        })

        it('does not query membership for a condition that merely mentions "inCohort" as a string', async () => {
            const repository = new FakeCohortMembershipRepository([COHORT_ID])
            action.config.conditions = [
                {
                    // properties.foo == 'inCohort' — the name appears as a string constant, not a call
                    filters: {
                        bytecode: ['_H', 1, 32, 'inCohort', 32, 'foo', 32, 'properties', 1, 2, 11],
                        properties: [{ key: 'foo', type: 'event', value: 'inCohort', operator: 'exact' }],
                    },
                },
                { filters: HOG_FILTERS_EXAMPLES.no_filters.filters },
            ]
            const handler = new ConditionalBranchHandler(repository)

            const result = await handler.execute({
                invocation,
                action,
                result: createInvocationResult(invocation),
            })

            expect(result.nextAction).toEqual(findActionById(invocation.hogFlow, 'condition_2'))
            expect(repository.calls).toEqual([])
        })

        it('treats a person-less invocation as a non-member without querying', async () => {
            const repository = new FakeCohortMembershipRepository([COHORT_ID])
            invocation.person = undefined
            invocation.state.personId = undefined

            const nextAction = await executeWithRepository(repository, 'inCohort')

            expect(nextAction).toEqual(findActionById(invocation.hogFlow, 'condition_2'))
            expect(repository.calls).toEqual([])
        })

        it.each([
            [0, 10],
            [1, 60],
        ])('retries a failed lookup after %s earlier failures in %ss instead of routing', async (earlier, delay) => {
            const repository = new FakeCohortMembershipRepository([], new Error('lookup timed out'))
            invocation.state.currentAction!.cohortLookupAttempts = earlier || undefined
            action.config.conditions = [{ filters: cohortConditionFilters('inCohort') }]

            const result = await new ConditionalBranchHandler(repository).execute({
                invocation,
                action,
                result: createInvocationResult(invocation),
            })

            expect(result.nextAction).toBeUndefined()
            expect(result.scheduledAt).toEqual(DateTime.now().plus({ seconds: delay }))
            expect(invocation.state.currentAction!.cohortLookupAttempts).toBe(earlier + 1)
            expect(invocation.state.currentAction!.cohortLookupFailed).toBeUndefined()
        })

        it('marks the step failed and throws once every lookup attempt failed', async () => {
            const repository = new FakeCohortMembershipRepository([], new Error('lookup timed out'))
            invocation.state.currentAction!.cohortLookupAttempts = 2

            await expect(executeWithRepository(repository, 'inCohort')).rejects.toThrow('lookup timed out')
            expect(invocation.state.currentAction!.cohortLookupFailed).toBe(true)
        })
    })

    describe('wait_until_condition eventMatched short-circuit', () => {
        let waitInvocation: CyclotronJobInvocationHogFlow
        let waitAction: Extract<HogFlowAction, { type: 'wait_until_condition' }>
        let handler: ConditionalBranchHandler

        beforeEach(() => {
            const waitFlow = new FixtureHogFlowBuilder()
                .withWorkflow({
                    actions: {
                        wait_until_condition: {
                            type: 'wait_until_condition',
                            config: {
                                condition: {
                                    filters: HOG_FILTERS_EXAMPLES.elements_text_filter.filters, // no match
                                },
                                max_wait_duration: '10m',
                            },
                        },
                        matched_target: {
                            type: 'delay',
                            config: { delay_duration: '2h' },
                        },
                    },
                    edges: [
                        {
                            from: 'wait_until_condition',
                            to: 'matched_target',
                            type: 'branch',
                            index: 0,
                        },
                        // The timeout edge, so a wait that reaches its ceiling unmatched has somewhere to go.
                        {
                            from: 'wait_until_condition',
                            to: 'matched_target',
                            type: 'continue',
                        },
                    ],
                })
                .build()

            waitAction = findActionByType(waitFlow, 'wait_until_condition')!
            waitInvocation = createExampleHogFlowInvocation(waitFlow)
            waitInvocation.state.currentAction = {
                id: waitAction.id,
                startedAtTimestamp: DateTime.utc().toMillis(),
            }
            const stubCohortMembershipRepository: CohortMembershipRepository = {
                getMemberCohortIds: () => Promise.resolve([]),
                getCohortMembership: () => Promise.resolve(null),
            }
            handler = new ConditionalBranchHandler(stubCohortMembershipRepository)
            counterHogflowWaitAdvancedAtMaxWait.reset()
            counterHogflowRekeyWake.reset()
            counterHogflowWaitPersonRefreshFailed.reset()
        })

        it('evaluates a first wait against the refreshed person, on the invocation and the result alike', async () => {
            // The result carries a shallow clone, so both have to land on the fresh person: whichever
            // one a later reader picks up must not still hold the person the dequeue cached.
            const freshPerson = { id: 'p1', properties: { email: '[email protected]' } }
            waitInvocation.refreshPerson = jest.fn().mockResolvedValue({
                person: freshPerson,
                filterGlobals: { ...waitInvocation.filterGlobals, person: freshPerson },
            })
            const result = createInvocationResult<CyclotronJobInvocationHogFlow>(waitInvocation)

            await handler.execute({ invocation: waitInvocation, action: waitAction, result })

            expect(waitInvocation.refreshPerson).toHaveBeenCalledTimes(1)
            expect(waitInvocation.filterGlobals.person?.properties).toEqual(freshPerson.properties)
            expect(result.invocation.filterGlobals.person?.properties).toEqual(freshPerson.properties)
            expect(result.invocation.person).toEqual(freshPerson)
        })

        it('keeps the person it already had when the refresh comes back empty', async () => {
            // The refresh adds freshness; it must not drop a person because one lookup found nothing.
            const before = waitInvocation.person
            waitInvocation.refreshPerson = jest
                .fn()
                .mockResolvedValue({ person: undefined, filterGlobals: { person: null } as any })
            const result = createInvocationResult<CyclotronJobInvocationHogFlow>(waitInvocation)

            await handler.execute({ invocation: waitInvocation, action: waitAction, result })

            expect(waitInvocation.person).toEqual(before)
            expect(waitInvocation.filterGlobals.person).not.toBeNull()
        })

        it('keeps the person it already had when the refresh fails, and stays parked', async () => {
            // A failed read must not reach the executor's error handling: that follows the continue
            // edge, which for a wait is the timeout edge, so the run would leave the wait early.
            const before = waitInvocation.person
            waitInvocation.refreshPerson = jest.fn().mockRejectedValue(new Error('person read failed'))
            const result = createInvocationResult<CyclotronJobInvocationHogFlow>(waitInvocation)

            const handlerResult = await handler.execute({
                invocation: waitInvocation,
                action: waitAction,
                result,
            })

            expect(handlerResult.scheduledAt).toEqual(DateTime.utc().plus({ minutes: 10 }))
            expect(handlerResult.nextAction).toBeUndefined()
            expect(waitInvocation.person).toEqual(before)
            expect(await personRefreshFailedCount()).toBe(1)
        })

        it('advances to the matched branch and clears eventMatched', async () => {
            waitInvocation.state.currentAction!.eventMatched = true
            waitInvocation.state.currentAction!.eventMatchedEvent = 'subscription created'
            waitInvocation.state.currentAction!.eventMatchedEventUuid = 'evt-uuid'

            const result = await handler.execute({
                invocation: waitInvocation,
                action: waitAction,
                result: createInvocationResult(waitInvocation),
            })

            expect(result.nextAction).toEqual(findActionById(waitInvocation.hogFlow, 'matched_target'))
            expect(result.result).toEqual({ eventMatched: true })
            // All wake markers are cleared so a later timeout fire isn't misread as an event wake.
            expect(waitInvocation.state.currentAction!.eventMatched).toBe(false)
            expect(waitInvocation.state.currentAction!.eventMatchedEvent).toBeUndefined()
            expect(waitInvocation.state.currentAction!.eventMatchedEventUuid).toBeUndefined()
        })

        it('falls through to condition evaluation when eventMatched is not set', async () => {
            const result = await handler.execute({
                invocation: waitInvocation,
                action: waitAction,
                result: createInvocationResult(waitInvocation),
            })

            // Condition does not match, so the step reschedules itself rather than advancing.
            expect(result.scheduledAt).toBeDefined()
            expect(result.nextAction).toBeUndefined()
        })

        it('does not fire immediately when the condition has no properties (always-true bytecode)', async () => {
            // An empty property condition compiles to always-true bytecode. It must not match on
            // entry and advance the wait; the step should park until an event wakes it or it times out.
            waitAction.config.condition = { filters: HOG_FILTERS_EXAMPLES.no_filters.filters }

            const result = await handler.execute({
                invocation: waitInvocation,
                action: waitAction,
                result: createInvocationResult(waitInvocation),
            })

            expect(result.scheduledAt).toBeDefined()
            expect(result.nextAction).toBeUndefined()
        })

        it('parks a wait for its whole max_wait_duration, with no periodic re-check', async () => {
            // The matcher is the only thing that wakes a wait, so it parks once rather than on a timer.
            waitAction.config.max_wait_duration = '4h'

            const result = await handler.execute({
                invocation: waitInvocation,
                action: waitAction,
                result: createInvocationResult(waitInvocation),
            })

            expect(result.scheduledAt).toEqual(DateTime.utc().plus({ hours: 4 }))
        })

        it('parks a short wait for its own duration too', async () => {
            waitAction.config.max_wait_duration = '30m'

            const result = await handler.execute({
                invocation: waitInvocation,
                action: waitAction,
                result: createInvocationResult(waitInvocation),
            })

            expect(result.scheduledAt).toEqual(DateTime.utc().plus({ minutes: 30 }))
        })

        it('counts a wait whose condition only matched once max_wait_duration elapsed', async () => {
            // Nothing re-checks a wait any more, so a match at the ceiling means the condition became
            // true earlier and no stream woke the run. That is the signal that replaces the poll.
            waitAction.config.condition = {
                filters: {
                    bytecode: ['_H', 1, 32, 'test', 32, 'event', 1, 1, 11],
                    events: [{ id: 'test', name: 'test', type: 'events', order: 0 }],
                },
            }
            waitInvocation.state.currentAction!.startedAtTimestamp = DateTime.utc().minus({ hours: 5 }).toMillis()
            waitInvocation.state.currentAction!.parkedMaxWaitDuration = '4h'
            waitAction.config.max_wait_duration = '4h'

            const result = await handler.execute({
                invocation: waitInvocation,
                action: waitAction,
                result: createInvocationResult(waitInvocation),
            })

            expect(result.nextAction).toEqual(findActionById(waitInvocation.hogFlow, 'matched_target'))
            expect(await lateAdvanceCount()).toBe(1)
            // Must name the flow, not the run: attributing the residual is the counter's whole job.
            expect(await lateAdvanceLabels()).toEqual({
                team_id: waitInvocation.hogFlow.team_id,
                hog_flow_id: waitInvocation.hogFlow.id,
            })
        })

        it('does not count a wait that matched before its ceiling', async () => {
            // The ordinary case: a stream woke the run, or it matched on entry, well inside max_wait.
            waitAction.config.condition = {
                filters: {
                    bytecode: ['_H', 1, 32, 'test', 32, 'event', 1, 1, 11],
                    events: [{ id: 'test', name: 'test', type: 'events', order: 0 }],
                },
            }
            waitInvocation.state.currentAction!.startedAtTimestamp = DateTime.utc().minus({ minutes: 5 }).toMillis()
            waitAction.config.max_wait_duration = '4h'

            const result = await handler.execute({
                invocation: waitInvocation,
                action: waitAction,
                result: createInvocationResult(waitInvocation),
            })

            expect(result.nextAction).toEqual(findActionById(waitInvocation.hogFlow, 'matched_target'))
            expect(await lateAdvanceCount()).toBe(0)
        })

        it('does not count a match woken by a sweep after the ceiling was shortened', async () => {
            // The timing sweep moves `scheduled` with a bulk UPDATE and stamps no marker, so a run
            // parked against a ceiling the author later cut wakes past the new one. That is an edit
            // landing, not a wake the streams missed.
            waitAction.config.condition = {
                filters: {
                    bytecode: ['_H', 1, 32, 'test', 32, 'event', 1, 1, 11],
                    events: [{ id: 'test', name: 'test', type: 'events', order: 0 }],
                },
            }
            waitInvocation.state.currentAction!.startedAtTimestamp = DateTime.utc().minus({ hours: 5 }).toMillis()
            waitInvocation.state.currentAction!.parkedMaxWaitDuration = '7d'
            waitAction.config.max_wait_duration = '4h'

            const result = await handler.execute({
                invocation: waitInvocation,
                action: waitAction,
                result: createInvocationResult(waitInvocation),
            })

            expect(result.nextAction).toEqual(findActionById(waitInvocation.hogFlow, 'matched_target'))
            expect(await lateAdvanceCount()).toBe(0)
        })

        it('does not count a timeout, which takes the continue edge rather than matching', async () => {
            // The default condition never matches, so reaching the ceiling is an ordinary timeout.
            waitInvocation.state.currentAction!.startedAtTimestamp = DateTime.utc().minus({ hours: 5 }).toMillis()
            waitAction.config.max_wait_duration = '4h'

            await handler.execute({
                invocation: waitInvocation,
                action: waitAction,
                result: createInvocationResult(waitInvocation),
            })

            expect(await lateAdvanceCount()).toBe(0)
        })

        it('records a rekey wake as advanced and consumes the one-shot flag when the merge makes the condition match', async () => {
            // A merge re-keyed this parked wait onto the survivor and woke it (rekeyWake). The re-check
            // now finds the condition true. Consuming the flag is what keeps the next re-check from
            // re-emitting the outcome — without it a re-parked wake would inflate the churn metric.
            waitAction.config.condition = {
                filters: {
                    bytecode: ['_H', 1, 32, 'test', 32, 'event', 1, 1, 11],
                    events: [{ id: 'test', name: 'test', type: 'events', order: 0 }],
                },
            }
            waitInvocation.state.currentAction!.rekeyWake = true

            const result = await handler.execute({
                invocation: waitInvocation,
                action: waitAction,
                result: createInvocationResult(waitInvocation),
            })

            expect(result.nextAction).toEqual(findActionById(waitInvocation.hogFlow, 'matched_target'))
            expect(await rekeyWakeCount('advanced')).toBe(1)
            expect(await rekeyWakeCount('reparked')).toBe(0)
            expect(waitInvocation.state.currentAction!.rekeyWake).toBe(false)
        })

        it('records a rekey wake as reparked and consumes the one-shot flag when the merge does not satisfy the wait', async () => {
            // The default condition still does not match after the re-key, so waking was wasted churn.
            waitInvocation.state.currentAction!.rekeyWake = true

            const result = await handler.execute({
                invocation: waitInvocation,
                action: waitAction,
                result: createInvocationResult(waitInvocation),
            })

            expect(result.scheduledAt).toBeDefined()
            expect(await rekeyWakeCount('reparked')).toBe(1)
            expect(await rekeyWakeCount('advanced')).toBe(0)
            expect(waitInvocation.state.currentAction!.rekeyWake).toBe(false)
        })
    })
})