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.

11.4 KB
Raw Blame
import { Properties } from '~/plugin-scaffold'
import { OrganizationAvailableFeature, ProjectId, Team } from '~/types'

import { PostgresRouter, PostgresUse } from './db/postgres'
import { LazyLoader, LoadOptions, LoaderRetryOptions } from './lazy-loader'
import { logger } from './logger'
import { captureTeamEvent } from './posthog'

type RawTeam = Omit<Team, 'available_features'> & {
    available_product_feature_keys: unknown
}

// One team's row must not throw, because a throw fails the batched lookup for every team in it.
function availableFeatures(raw: unknown): OrganizationAvailableFeature[] {
    if (!Array.isArray(raw)) {
        return []
    }
    return raw.flatMap((key) => (typeof key === 'string' ? [key as OrganizationAvailableFeature] : []))
}

// Postgres stores team ids in int4 columns. A query that compares one of those columns to a
// non-integer, or to a number above 2_147_483_647, fails. Team ids start at 1. The check therefore
// also rejects 0 and negative numbers.
export function isValidTeamId(value: unknown): value is number {
    return Number.isInteger(value) && (value as number) > 0 && (value as number) <= 2_147_483_647
}

export function validTeamIds(keys: string[]): number[] {
    // parseInt would read "1.5" as team 1. Number keeps it 1.5, which isValidTeamId rejects.
    return keys.map(Number).filter(isValidTeamId)
}

// Ids and tokens share one cache, so each key carries its kind. A token that looks like a number
// must only ever match `api_token`, never `id`.
const ID_KEY_PREFIX = 'id:'
const TOKEN_KEY_PREFIX = 'token:'

const idKey = (teamId: number | string): string => `${ID_KEY_PREFIX}${teamId}`
const tokenKey = (token: string): string => `${TOKEN_KEY_PREFIX}${token}`

export interface TeamManagerOptions {
    /** Retry transient team-load failures (e.g. a Postgres pooler blip) instead of letting them propagate. */
    loaderRetry?: LoaderRetryOptions
}

/**
 * Looks up Teams by id or token, backed by a Postgres-loaded lazy cache.
 * Pure business surface — no `start` / `stop`. Callers that need to manage
 * its lifetime as part of a `Lifecycle` use `TeamManagerComponent`.
 */
export class TeamManager {
    private lazyLoader: LazyLoader<Team>

    constructor(
        private postgres: PostgresRouter,
        options?: TeamManagerOptions
    ) {
        this.lazyLoader = new LazyLoader({
            name: 'TeamManager',
            refreshAgeMs: 2 * 60 * 1000, // 2 minute
            refreshJitterMs: 30 * 1000, // 30 seconds
            loaderRetry: options?.loaderRetry,
            loader: async (keys: string[]) => {
                return await this.fetchTeams(keys)
            },
        })
    }

    public async getTeam(teamId: number): Promise<Team | null> {
        return this.lazyLoader.get(idKey(teamId))
    }

    public async getTeamByToken(token: string): Promise<Team | null> {
        return this.lazyLoader.get(tokenKey(token))
    }

    public async getTeams(teamIds: number[]): Promise<Record<string, Team | null>> {
        const loaded = await this.lazyLoader.getMany(teamIds.map(idKey))
        return Object.fromEntries(teamIds.map((teamId) => [String(teamId), loaded[idKey(teamId)] ?? null]))
    }

    public async getTeamsByTokens(tokens: string[], options?: LoadOptions): Promise<Record<string, Team | null>> {
        const loaded = await this.lazyLoader.getMany(tokens.map(tokenKey), options)
        return Object.fromEntries(tokens.map((token) => [token, loaded[tokenKey(token)] ?? null]))
    }

    public async hasAvailableFeature(teamId: number, feature: OrganizationAvailableFeature): Promise<boolean> {
        const team = await this.getTeam(teamId)
        return team?.available_features.includes(feature) || false
    }

    // `ingested_event` means "this project received data", so logs, traces and metrics set it too.
    public async setTeamsIngestedData(teamIds: Iterable<number>): Promise<void> {
        await Promise.all(
            [...new Set(teamIds)].map(async (teamId) => {
                try {
                    const team = await this.getTeam(teamId)
                    if (team) {
                        await this.setTeamIngestedEvent(team, {})
                    }
                } catch (error) {
                    logger.error('⚠️', 'Failed to set ingested_event', { teamId, error })
                }
            })
        )
    }

    public async setTeamIngestedEvent(team: Team, properties: Properties): Promise<void> {
        if (!team.ingested_event) {
            // The cached team can be stale long after the first write, so this fires repeatedly for
            // a team that is already flagged. The guard makes those repeats match zero rows, which
            // writes nothing and leaves no dead tuple behind on a hot row.
            const updateResult = await this.postgres.query(
                PostgresUse.COMMON_WRITE,
                `UPDATE posthog_team SET ingested_event = $1 WHERE id = $2 AND NOT ingested_event`,
                [true, team.id],
                'setTeamIngestedEvent'
            )

            // Both keys, because a team is cached under its id and its token but ingestion only ever
            // looks it up by token - refreshing the id alone leaves the entry this worker reads stale.
            this.lazyLoader.markForRefresh([idKey(team.id), tokenKey(team.api_token)])

            if ((updateResult.rowCount ?? 0) === 0) {
                // Another worker (or an earlier event seen through a stale cache) already flipped
                // the flag - skip the first-event side effects so they fire exactly once per team.
                return
            }

            // The flag is already committed and no later event retries these, so a throw here loses
            // the team's first-event capture for good. Swallow it and leave a trail instead.
            try {
                const organizationMembers = await this.postgres.query(
                    PostgresUse.COMMON_WRITE,
                    'SELECT distinct_id FROM posthog_user JOIN posthog_organizationmembership ON posthog_user.id = posthog_organizationmembership.user_id WHERE organization_id = $1',
                    [team.organization_id],
                    'posthog_organizationmembership'
                )

                const distinctIds: { distinct_id: string }[] = organizationMembers.rows
                for (const { distinct_id } of distinctIds) {
                    captureTeamEvent(
                        team,
                        'first team event ingested',
                        {
                            sdk: properties.$lib,
                            realm: properties.realm,
                            host: properties.$host,
                        },
                        distinct_id
                    )
                }
            } catch (error) {
                logger.error('⚠️', 'Failed to capture first team event ingested', { teamId: team.id, error })
            }
        }
    }

    private async fetchTeams(keys: string[]): Promise<Record<string, Team | null>> {
        const teamIds: number[] = []
        const tokens: string[] = []
        for (const key of keys) {
            if (key.startsWith(ID_KEY_PREFIX)) {
                const rawId = key.slice(ID_KEY_PREFIX.length)
                if (/^\d{1,10}$/.test(rawId)) {
                    const parsed = parseInt(rawId)
                    if (isValidTeamId(parsed)) {
                        teamIds.push(parsed)
                    }
                }
            } else if (key.startsWith(TOKEN_KEY_PREFIX)) {
                tokens.push(key.slice(TOKEN_KEY_PREFIX.length))
            }
        }

        const result = await this.postgres.query<RawTeam>(
            PostgresUse.COMMON_READ,
            `SELECT
                t.id,
                t.project_id,
                t.uuid,
                t.organization_id,
                t.name,
                t.anonymize_ips,
                t.api_token,
                t.secret_api_token,
                t.session_recording_opt_in,
                t.person_processing_opt_out,
                t.heatmaps_opt_in,
                t.ingested_event,
                t.person_display_name_properties,
                t.cookieless_server_hash_mode,
                t.timezone,
                t.logs_settings,
                t.extra_settings,
                extract('epoch' from t.drop_events_older_than) as drop_events_older_than_seconds,
                COALESCE(cfg.minimal_flag_called_events, false) AS minimal_flag_called_events,
                COALESCE(ocfg.flag_evaluations_mode, 0) AS flag_evaluations_mode,
                -- The keys are the only part of available_product_features a caller reads. Picking
                -- them out here returns a text[], which the pg driver reads with its plain array
                -- parser. Selecting the jsonb[] column makes the driver JSON-parse every feature
                -- object of every row, and an organization holds about a hundred of them.
                ARRAY(
                    SELECT feature->>'key'
                    FROM unnest(o.available_product_features) AS feature
                    WHERE feature->>'key' IS NOT NULL
                ) AS available_product_feature_keys
            FROM posthog_team t
            JOIN posthog_organization o ON o.id = t.organization_id
            LEFT JOIN feature_flags_teamfeatureflagsconfig cfg ON cfg.team_id = t.id
            LEFT JOIN feature_flags_organizationfeatureflagsconfig ocfg ON ocfg.organization_id = t.organization_id
            WHERE t.id = ANY($1) OR t.api_token = ANY($2)
            `,
            [teamIds, tokens],
            'fetch-teams-with-features'
        )

        // Initialize result record with nulls for all requested keys
        const resultRecord: Record<string, Team | null> = {}
        for (const key of keys) {
            resultRecord[key] = null
        }

        // Fill in actual teams where they exist
        result.rows.forEach((row) => {
            const { available_product_feature_keys, ...teamPartial } = row
            const team: Team = {
                ...teamPartial,
                // NOTE: The postgres lib loads the bigint as a string, so we need to cast it to a ProjectId
                project_id: Number(teamPartial.project_id) as ProjectId,
                // NOTE: extract('epoch' from interval) returns a numeric which can be parsed as string by postgres driver
                drop_events_older_than_seconds:
                    teamPartial.drop_events_older_than_seconds !== null
                        ? Number(teamPartial.drop_events_older_than_seconds)
                        : null,
                available_features: availableFeatures(available_product_feature_keys),
            }
            resultRecord[idKey(row.id)] = team
            resultRecord[tokenKey(row.api_token)] = team
        })

        return resultRecord
    }
}

/**
 * Lifecycle owner for `TeamManager`. `start()` constructs a fresh
 * `TeamManager` and hands it back along with a no-op stop callback. The
 * resulting `TeamManager` has no `start`/`stop` of its own — its lifetime
 * is fully controlled through this Manager.
 */
export class TeamManagerComponent {
    constructor(
        private postgres: PostgresRouter,
        private options?: TeamManagerOptions
    ) {}

    start(): Promise<{ value: TeamManager; stop: () => Promise<void> }> {
        return Promise.resolve({
            value: new TeamManager(this.postgres, this.options),
            stop: () => Promise.resolve(),
        })
    }
}