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.

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

import { registerAsyncFunction } from '../async-function-registry'

/**
 * Example of a simple async function that writes arguments to the invocation logs. Once an async function has been registered, it can be called from a HogFunction.
 *
 * If you're trying to add a new realtime destination or workflow action that will use your async function, these are defined in nodejs/src/cdp/templates/_destinations.
 *
 * IMPORTANT: For your async function to become registered, it MUST be imported in the index.ts file in this directory (nodejs/src/cdp/async-functions/index.ts)
 *
 * RETURN-VALUE CONTRACT: when the VM hits an async function call it pops the args, advances the
 * instruction pointer, and pauses. By the time the VM resumes, `vmState.stack` MUST contain the
 * function's return value (so the bytecode compiler's trailing POP for expression statements has
 * something to consume). Handlers satisfy this in one of two ways:
 *
 * 1. Synchronous handlers (like this example, and `produceToWarehouseWebhooks`) finish their work
 *    inside `execute()` and push their return value directly onto `result.invocation.state.vmState.stack`.
 * 2. Queueing handlers (`fetch`, `sendEmail`, `postHogGetTicket`, `postHogUpdateTicket`) stage
 *    `result.invocation.queueParameters` and let the matching `executeFetch` / `executeSendEmail`
 *    worker push the response once the real I/O completes.
 *
 * Forgetting to push leaves the resumed VM with an empty stack and crashes with
 * "Invalid HogQL bytecode, stack is empty, can not pop".
 */
registerAsyncFunction('foobar', {
    /**
     *
     * @param args the arguments passed from the Hog code, for example `foobar('i am foo', {'key': 200}, 'i am baz')`
     * @param _context includes the invocation details, any global variables attached to the invocation, and a reference to
     *   the AsyncFunctionContext which provides access to other services and data (e.g. teamManager, siteUrl, etc.)
     * @param result the current state of the invocation result, which can be modified by the async function and serves as a place to store
     *   its return value and/or modify the invocation.
     *   For example, you can set a value for a key on result.invocation, and that value would then be accessible in subsequent async functions.
     *   You can stop execution after an error by setting result.finished = true + result.error, and you can log messages to the
     *   invocation logs by pushing to result.logs. See `CyclotronJobInvocationResult` for more details on the structure of the result object.
     */
    execute: async (args, _context, result) => {
        const [foo, bar, baz] = args as [string | undefined, Record<'key', number> | undefined, string | undefined]

        // Do something with the argument - this can be a fetch request, a database query, or any other asynchronous operation
        await new Promise((resolve) => setTimeout(resolve, bar?.['key'] || 100))

        result.logs.push({
            level: 'info',
            timestamp: DateTime.now(),
            message: `Executed async function 'foobar' with arguments: foo=${foo}, bar=${JSON.stringify(bar)}, baz=${baz}`,
        })

        // See the RETURN-VALUE CONTRACT comment above the registration. We finished our work
        // synchronously, so we push our return value onto the resumed VM stack right here.
        result.invocation.state.vmState?.stack.push(null)
    },
    /**
     * A mock implementation of the async function used in destinations and workflows Test tooling, when "Make real HTTP requests" is disabled.
     *
     * Important: this is NOT just for unit testing, and actually shows up in the product. Do your best to simulate the real implemenation and ensure the
     * results returned from the mock have the same structure as the real implementation, so that users can get a realistic experience when using the Test tool.
     */
    mock: (args, logs) => {
        logs.push({
            level: 'info',
            timestamp: DateTime.now(),
            message: `Async function 'foobar' was mocked with arguments:`,
        })
        logs.push({
            level: 'info',
            timestamp: DateTime.now(),
            message: `foobar('${args[0]}', ${JSON.stringify(args[1], null, 2)}, '${args[2]}')`,
        })

        return {
            status: 200,
            body: {},
        }
    },
})