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.

9.2 KB
Raw Blame
import '~/styles'
import '../shared/styles.scss'

import { KeaPlugin, resetContext } from 'kea'
import { disposablesPlugin } from 'kea-disposables'
import { formsPlugin } from 'kea-forms'
import { loadersPlugin } from 'kea-loaders'
import { localStoragePlugin } from 'kea-localstorage'
import { routerPlugin } from 'kea-router'
import { subscriptionsPlugin } from 'kea-subscriptions'
import { waitForPlugin } from 'kea-waitfor'
import { windowValuesPlugin } from 'kea-window-values'
import type { PostHog } from 'posthog-js'
import { createRoot } from 'react-dom/client'

import { ToolbarApp } from '~/toolbar/floating/components/ToolbarApp'
import { isToolbarMounted, posthogToolbarController, setToolbarRefs } from '~/toolbar/floating/toolbarController'
import { canonicalizeApiHost, identifiesToolbarUser } from '~/toolbar/shared/toolbarConfigLogic'
import { toolbarLogger } from '~/toolbar/shared/toolbarLogger'
import { captureToolbarException, toolbarPosthogJS } from '~/toolbar/shared/toolbarPosthogJS'
import { isToolbarRequestError } from '~/toolbar/shared/toolbarRequestError'
import { safeFetch, toError } from '~/toolbar/shared/utils'
import { ToolbarParams } from '~/types'

interface InitKeaProps {
    state?: Record<string, any>
    routerHistory?: any
    routerLocation?: any
    beforePlugins?: KeaPlugin[]
}

const initKeaInToolbar = ({ routerHistory, routerLocation, beforePlugins }: InitKeaProps = {}): void => {
    const plugins = [
        ...(beforePlugins || []),
        disposablesPlugin,
        localStoragePlugin(),
        windowValuesPlugin({ window: window }),
        routerPlugin({
            history: routerHistory,
            location: routerLocation,
            urlPatternOptions: {
                // :TRICKY: What chars to allow in named segment values i.e. ":key"
                // in "/url/:key". Default: "a-zA-Z0-9-_~ %".
                segmentValueCharset: "a-zA-Z0-9-_~ %.@()!'|",
            },
        }),
        formsPlugin,
        loadersPlugin({
            onFailure({ error, reducerKey, actionKey }: { error: any; reducerKey: string; actionKey: string }) {
                toolbarLogger.error('kea_loader', 'Toolbar fetch failed', {
                    reducer_key: reducerKey,
                    action_key: actionKey,
                })
                // Loaders throw ToolbarRequestError to drive their *Failure actions on
                // expected request failures (4xx/5xx/network) - those are logged above but
                // must not pollute error tracking. Anything else is a genuine toolbar bug.
                if (!isToolbarRequestError(error)) {
                    // A loader can reject with a non-Error value (e.g. html-to-image throws a raw
                    // DOM Event). Normalize first so no bare value reaches error tracking without a
                    // message or stack, whatever a loader throws.
                    captureToolbarException(toError(error), 'kea_loader', {
                        reducer_key: reducerKey,
                        action_key: actionKey,
                    })
                }
            },
        }),
        subscriptionsPlugin,
        waitForPlugin,
    ]

    resetContext({
        plugins: plugins,
        createStore: {
            compose: (...funcs: any[]) => {
                if (funcs.length === 0) {
                    return <T,>(arg: T) => arg
                }
                if (funcs.length === 1) {
                    return funcs[0]
                }
                return funcs.reduce(
                    (a, b) =>
                        (...args: any) =>
                            a(b(...args))
                )
            },
        },
    })
}

const win = window as any
win['posthogToolbarController'] = posthogToolbarController

// Re-exported for the loader script (loader.ts), which forwards its controller stub here.
export { posthogToolbarController }

// posthog-js's default refresh interval. The toolbar instance starts with refresh off, see toolbarPosthogJS.ts.
const TOOLBAR_FLAGS_REFRESH_INTERVAL_MS = 5 * 60 * 1000

function startToolbarFlags(toolbarParams: ToolbarParams): void {
    toolbarPosthogJS.set_config({ remote_config_refresh_interval_ms: TOOLBAR_FLAGS_REFRESH_INTERVAL_MS })
    // Otherwise identify() gives the instance a new distinct id, and posthog-js loads the flags for that user
    if (!identifiesToolbarUser(toolbarParams)) {
        toolbarPosthogJS.reloadFeatureFlags()
    }
}

// Tracks an in-flight mount. The mounted-state flag isn't set until the very end of the async
// mount, so without this two overlapping ph_load_toolbar calls would both pass the guard below
// and mount twice. Concurrent calls dedupe onto this promise instead.
let loadPromise: Promise<void> | null = null

export async function loadToolbar(toolbarParams: ToolbarParams, posthog?: PostHog): Promise<void> {
    // ph_load_toolbar is not called once per page — posthog-js re-invokes it during a page's
    // lifetime, most notably on SPA client-side route changes. Mounting is destructive
    // (initKeaInToolbar() calls resetContext()), so a naive re-run tears the Kea logics out from
    // under the already-mounted React tree: the toolbar the user is interacting with vanishes and
    // a duplicate shadow root is appended. Keep a healthy live instance instead of remounting.
    if (isToolbarMounted()) {
        return
    }
    // A mount is already in flight. Calls can overlap before the first finishes its async setup
    // and records itself as mounted, so join the existing mount rather than starting a second.
    if (loadPromise) {
        return loadPromise
    }
    // Flagged as loaded but the container was detached (the host page removed our node): tear the
    // stale React root / Kea context down before mounting a fresh one so we don't leak or stack.
    if (posthogToolbarController.isLoaded) {
        posthogToolbarController.destroy()
    }

    loadPromise = mountToolbar(toolbarParams, posthog).finally(() => {
        loadPromise = null
    })
    return loadPromise
}

async function mountToolbar(toolbarParams: ToolbarParams, posthog?: PostHog): Promise<void> {
    // Store the start time so we can measure total load duration in initInstrumentation.
    // The loader script already stamps this before fetching the app module, so the measured
    // duration includes the chunk fetch — keep the earliest timestamp.
    ;(window as any).__posthog_toolbar_load_start ??= performance.now()

    startToolbarFlags(toolbarParams)

    // If posthog and toolbarFlagsKey is present, fetch the feature flags from the backend
    if (posthog && toolbarParams.toolbarFlagsKey) {
        // Validate with canonicalizeApiHost so an attacker-controlled apiURL in
        // the hash can't receive the credentialed request (the flags key is
        // low-impact on its own, but `credentials: 'include'` would send any
        // cookies for the attacker's origin alongside it).
        const trimmedHost =
            canonicalizeApiHost(posthog.config?.api_host) ||
            canonicalizeApiHost(toolbarParams.apiURL) ||
            window.location.origin
        const flagsUrl = `${trimmedHost}/api/user/get_toolbar_preloaded_flags?key=${toolbarParams.toolbarFlagsKey}`

        // The flags preload is best-effort and the toolbar degrades cleanly without it.
        // Every failure mode here is request-shaped (transient network failure, ad blocker,
        // CORS, a proxy returning a non-JSON error page, an invalid/stale flags key), so
        // nothing in this block is reported to error tracking - only logged.
        let response: Response | undefined
        try {
            response = await safeFetch(flagsUrl, { credentials: 'include' })
        } catch (error) {
            toolbarLogger.warn('flags', 'Error fetching toolbar feature flags', {
                error: error instanceof Error ? error.message : String(error),
            })
        }

        if (response) {
            try {
                const data = await response.json()
                if (data.featureFlags) {
                    posthog.featureFlags.overrideFeatureFlags({ flags: data.featureFlags })
                } else {
                    toolbarLogger.error('flags', 'Feature flags not found', { response: data })
                }
            } catch (error) {
                toolbarLogger.error('flags', 'Error processing toolbar feature flags', {
                    error: error instanceof Error ? error.message : String(error),
                })
            }
        }
    }

    initKeaInToolbar()
    const container = document.createElement('div')
    const root = createRoot(container)

    document.body.appendChild(container)

    if (!posthog) {
        toolbarLogger.warn('init', 'Loaded toolbar via old version of posthog-js that does not support feature flags')
    }

    root.render(
        <ToolbarApp
            {...toolbarParams}
            actionId={parseInt(String(toolbarParams.actionId))}
            experimentId={parseInt(String(toolbarParams.experimentId))}
            posthog={posthog}
        />
    )

    setToolbarRefs(root, container)
}

// Kept for direct consumers and back-compat: once this module evaluates, calls skip the loader.
win['ph_load_toolbar'] = loadToolbar

/** @deprecated, use "ph_load_toolbar" instead */
win['ph_load_editor'] = loadToolbar