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.

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

import { HogFlow } from '~/cdp/schema/hogflow'
import { hasPushActions } from '~/cdp/services/hogflows/hogflow-utils'
import { instrumented } from '~/common/tracing/tracing-utils'
import { logger } from '~/common/utils/logger'
import { PluginsServerConfig } from '~/types'

import { isRowScopedTrigger } from '../schema/hogflow'
import { JobQueue } from '../services/job-queue/job-queue.interface'
import {
    CyclotronJobInvocation,
    CyclotronJobInvocationHogFlow,
    CyclotronJobInvocationResult,
    CyclotronPerson,
} from '../types'
import { convertToHogFunctionFilterGlobal } from '../utils/hog-function-filtering'
import { createInvocationResult } from '../utils/invocation-utils'
import { CdpConsumerBaseDeps } from './cdp-base.consumer'
import { CdpCyclotronWorker } from './cdp-cyclotron-worker.consumer'

type LoadHogFlowsResult = {
    loadedInvocations: CyclotronJobInvocationHogFlow[]
    canceledResults: CyclotronJobInvocationResult[]
}

// A transactional email's caller holds only a send key, which grants no access to person data, so its
// template never sees person properties, or the display name derived from them. The person stays attached
// so the send is recorded against them.
function personForFlow(
    hogFlow: HogFlow,
    person: CyclotronPerson | null | undefined
): CyclotronPerson | null | undefined {
    return person && hogFlow.trigger?.type === 'api' ? { ...person, properties: {}, name: '' } : person
}

export class CdpCyclotronWorkerHogFlow extends CdpCyclotronWorker {
    protected override name = 'CdpCyclotronWorkerHogFlow'

    constructor(config: PluginsServerConfig, deps: CdpConsumerBaseDeps, jobQueue: JobQueue) {
        super(config, deps, jobQueue, 'hogflow')
    }

    @instrumented('cdpConsumer.handleEachBatch.executeInvocations')
    public override async processInvocations(
        invocations: CyclotronJobInvocation[]
    ): Promise<CyclotronJobInvocationResult[]> {
        const { loadedInvocations, canceledResults } = await this.loadHogFlows(invocations)
        const executed = await Promise.all(loadedInvocations.map((item) => this.hogFlowExecutor.execute(item)))
        return [...canceledResults, ...executed]
    }

    protected override async queueInvocationResults(results: CyclotronJobInvocationResult[]): Promise<void> {
        await super.queueInvocationResults(results)
        await this.deleteAttachmentsOfFinishedSends(results)
    }

    private async deleteAttachmentsOfFinishedSends(results: CyclotronJobInvocationResult[]): Promise<void> {
        await Promise.all(
            results
                .filter(
                    (result) =>
                        result.finished &&
                        (result.invocation.state as CyclotronJobInvocationHogFlow['state'] | null)?.send?.attachments
                            ?.length
                )
                .map((result) => this.emailAttachmentsService.delete(result.invocation.id, result.invocation.teamId))
        )
    }

    /**
     * Terminate an invocation as canceled through the normal result pipeline, so the
     * terminal lifecycle row, app metric, and run log all land. A bare cyclotron
     * status flip would leave the run showing 'running' in the Invocations UI forever.
     */
    private buildCanceledResult(
        item: CyclotronJobInvocation,
        message: string,
        hogFlow?: HogFlow
    ): CyclotronJobInvocationResult {
        // The monitoring services identify a workflow result by the presence of `hogFlow`, and use
        // it to key the terminal lifecycle row as `hog_flow` and to fill the row's trigger fields.
        // Without it the row keys as `hog_function`; because `function_kind` is part of the
        // ReplacingMergeTree key, that row could never collapse the `running` row (written as
        // `hog_flow`), leaving the run stuck at 'running' in the Invocations tab. When the live flow
        // is gone (deleted, or its lookup failed) we still know its id, which is `item.functionId`,
        // so attach a minimal stub carrying just that so the row still keys as `hog_flow`. Only `id`
        // is read off this object on the cancellation path.
        const resolvedFlow = hogFlow ?? ({ id: item.functionId } as HogFlow)
        const invocation = { ...item, hogFlow: resolvedFlow }
        const result = createInvocationResult(invocation, {}, { finished: true })
        result.canceled = true
        result.logs.push({ level: 'info', timestamp: DateTime.now(), message })
        result.metrics.push({
            team_id: item.teamId,
            app_source_id: item.parentRunId ?? item.functionId,
            instance_id: (item.state as CyclotronJobInvocationHogFlow['state'] | null)?.currentAction?.id,
            metric_kind: 'other',
            metric_name: 'canceled',
            count: 1,
        })
        return result
    }

    @instrumented('cdpConsumer.handleEachBatch.loadHogFlows')
    protected async loadHogFlows(invocations: CyclotronJobInvocation[]): Promise<LoadHogFlowsResult> {
        const loadedInvocations: CyclotronJobInvocationHogFlow[] = []
        const failedInvocations: CyclotronJobInvocation[] = []
        const canceledResults: CyclotronJobInvocationResult[] = []
        const hogFlows = await this.hogFlowManager.getHogFlowsCheckingPrimaryOnMiss(
            invocations.filter((item) => !item.cancelRequestedAt).map((item) => item.functionId)
        )

        await Promise.all(
            invocations.map(async (item) => {
                // Checked before the team/flow lookups so a cancel-requested run terminates even
                // when its flow or team has since been deleted. The flow lookup here is
                // best-effort and only sets the terminal row's function_kind: a null flow
                // (deleted) or a lookup error still cancels.
                if (item.cancelRequestedAt) {
                    const hogFlow = await this.hogFlowManager.getHogFlow(item.functionId).catch(() => null)
                    canceledResults.push(this.buildCanceledResult(item, 'Run canceled', hogFlow ?? undefined))
                    return
                }

                const team = await this.deps.teamManager.getTeam(item.teamId)
                const hogFlow = hogFlows[item.functionId]
                if (!hogFlow || !team) {
                    logger.error('⚠️', 'Error finding hog flow', {
                        id: item.functionId,
                    })

                    failedInvocations.push(item)
                    this.invocationResultsService.emailStatusService.queueUnavailableRun(item)

                    return
                }

                // A run waking while its workflow is disabled/archived is canceled rather
                // than executed. Runs that wake while the workflow is active proceed
                // normally, so re-enabling before a parked run's wake time releases it.
                if (hogFlow.status !== 'active') {
                    logger.info('⏭️', 'Cancelling hog flow invocation - workflow is no longer active', {
                        id: item.functionId,
                        status: hogFlow.status,
                    })

                    canceledResults.push(
                        this.buildCanceledResult(item, 'Run canceled: the workflow is no longer active', hogFlow)
                    )

                    return
                }

                const hogFlowInvocationState = item.state as CyclotronJobInvocationHogFlow['state']

                // Row-scoped invocations (a warehouse row, a Slack message, a GitHub event) don't have
                // a real person — the delivery is the unit of work and person-dependent steps no-op for
                // these flows. Explicitly skip the person lookup rather than relying on
                // event.distinct_id being empty so future changes to the synthetic event shape don't
                // accidentally re-enable the lookup.
                const isRowScoped = isRowScopedTrigger(hogFlow.trigger)
                // Account-audience batch invocations carry the account's group key as
                // event.distinct_id; resolving it as a person distinct_id would attach an
                // unrelated person to the run. Accounts have no person — skip the lookup.
                // The state stamp wins over the live trigger, which may have been edited to a
                // person audience while these children were queued; the trigger check remains
                // as a fallback for jobs enqueued before the stamp existed.
                const isAccountAudience =
                    hogFlowInvocationState.accountAudience === true ||
                    (hogFlow.trigger?.type === 'batch' && hogFlow.trigger.filters?.audience_type === 'accounts')
                // The matcher wrote this job's personId anchor: a merge repointed the distinct_id onto a
                // survivor, or the distinct_id acquired its first person. Resolve by that personId so the step
                // reads the right person — resolving by the distinct_id would hit its stale ~1min cache entry
                // (the pre-merge person, or none at all) and e.g. drop an email.
                const resolveByRepointedPerson =
                    hogFlowInvocationState.personIdRepointed === true && !!hogFlowInvocationState.personId
                // One-shot: consume the flag on this wake-resolution only. Later steps fall back to normal
                // distinct_id-first resolution, which self-heals to the latest survivor if the distinct_id is
                // repointed again (a second merge onto a non-wait step is out of processMoveBatch's scope).
                if (resolveByRepointedPerson) {
                    delete hogFlowInvocationState.personIdRepointed
                }
                const personIdOrDistinctId =
                    isRowScoped || isAccountAudience
                        ? undefined
                        : resolveByRepointedPerson
                          ? hogFlowInvocationState.personId
                          : hogFlowInvocationState.event.distinct_id || hogFlowInvocationState.personId
                const kind =
                    resolveByRepointedPerson || !hogFlowInvocationState.event.distinct_id ? 'person_id' : 'distinct_id'

                // A push cannot be recalled, and the cached person can predate a device that
                // unregistered since the last read, so a flow that sends push bypasses the cache here.
                // A wait woken by a match advances without re-evaluating, so the steps after it would
                // otherwise read the person cached when the wait parked, without the write that woke it.
                const forceFreshPerson =
                    hasPushActions(hogFlow.actions) || hogFlowInvocationState.currentAction?.eventMatched === true
                const [resolvedPerson, groups] = await Promise.all([
                    personIdOrDistinctId
                        ? this.personsManager.getCyclotronPerson(hogFlow.team_id, personIdOrDistinctId, kind, {
                              forceFresh: forceFreshPerson,
                          })
                        : undefined,
                    this.groupsManager.getGroupsForEvent(
                        hogFlow.team_id,
                        hogFlowInvocationState.event.properties,
                        `${this.config.SITE_URL}/project/${hogFlow.team_id}`
                    ),
                ])

                const person = personForFlow(hogFlow, resolvedPerson)

                if (!person && hogFlow.trigger?.type === 'event') {
                    logger.warn('⚠️', 'Person not found for hog flow invocation', {
                        hogFlowId: hogFlow.id,
                        distinctId: hogFlowInvocationState.event?.distinct_id || hogFlowInvocationState.personId,
                        invocationId: item.id,
                    })
                }

                // Batch-triggered invocations arrive with an empty event.distinct_id because the
                // blast-radius query returns UUIDs only. The person lookup above resolves one
                // distinct_id for us (when the person has any), so backfill it here so templates
                // defaulting to `{event.distinct_id}` resolve at hog runtime.
                if (!hogFlowInvocationState.event.distinct_id && person?.distinct_id) {
                    hogFlowInvocationState.event.distinct_id = person.distinct_id
                }

                // Persist the resolved person UUID into state so a re-parked wait keeps its person_id
                // even when a later re-resolution transiently misses. clickhouse_person wakes match on
                // person_id only, so a wait parked with person_id = null could never be woken by a
                // person-property change — it would depend entirely on the polling backstop.
                if (person?.id && !hogFlowInvocationState.personId) {
                    hogFlowInvocationState.personId = person.id
                }

                const filterGlobals = convertToHogFunctionFilterGlobal({
                    event: hogFlowInvocationState.event,
                    person: person ?? undefined,
                    groups,
                    variables: hogFlowInvocationState.variables || {},
                })

                const loaded: CyclotronJobInvocationHogFlow = {
                    ...item,
                    state: hogFlowInvocationState,
                    hogFlow,
                    person: person ?? undefined,
                    groups,
                    filterGlobals,
                }

                if (personIdOrDistinctId) {
                    loaded.refreshPerson = async () => {
                        const fresh = personForFlow(
                            hogFlow,
                            await this.personsManager.getCyclotronPerson(hogFlow.team_id, personIdOrDistinctId, kind, {
                                forceFresh: true,
                            })
                        )
                        return {
                            person: fresh ?? undefined,
                            filterGlobals: convertToHogFunctionFilterGlobal({
                                event: hogFlowInvocationState.event,
                                person: fresh ?? undefined,
                                groups,
                                variables: hogFlowInvocationState.variables || {},
                            }),
                        }
                    }
                }

                loadedInvocations.push(loaded)
            })
        )

        await this.cyclotronJobQueue.dequeueInvocations(failedInvocations)

        return { loadedInvocations, canceledResults }
    }
}