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.

6.5 KB
Raw Blame
import { createHash } from 'crypto'
import { existsSync, readFileSync } from 'fs'
import path from 'path'

import { parseJSON } from '~/common/utils/json-parse'

export const MANIFEST_SCHEMA_VERSION = 1

// Resolves to /code/nodejs/schema-requirements.json in the Node image, next to nodejs/dist.
export const DEFAULT_MANIFEST_PATH = path.resolve(__dirname, '..', '..', 'schema-requirements.json')

// The names match the arguments of rust/bin/migrate-entry, which the sqlx-migrate deploy runs per database.
export const SQLX_DATABASES = ['persons', 'cyclotron-node', 'behavioral-cohorts'] as const
export type SqlxDatabase = (typeof SQLX_DATABASES)[number]

export interface DjangoRequirement {
    kind: 'django'
    database: 'default'
    app: string
    migration: string
    // Set when `migration` is a squash. Django can record either the squash or every migration it replaces.
    replaces?: string[]
}

export interface SqlxRequirement {
    kind: 'sqlx'
    database: SqlxDatabase
    // Every version in the migration directory, ascending. A version is the timestamp in the file name, so a
    // late merge can add a version below the highest one, and `sqlx migrate run` still applies it.
    versions: number[]
}

export type Requirement = DjangoRequirement | SqlxRequirement

export interface SchemaRequirementsManifest {
    schema_version: number
    source_commit: string | null
    // Identifies the requirement list in logs. Consumers do not recompute it, because JSON.stringify output is not canonical across languages.
    digest: string
    requirements: Requirement[]
}

export class ManifestError extends Error {}

export function computeRequirementsDigest(requirements: Requirement[]): string {
    return createHash('sha256').update(JSON.stringify(requirements)).digest('hex').slice(0, 12)
}

export function buildManifest(requirements: Requirement[], sourceCommit: string | null): SchemaRequirementsManifest {
    return {
        schema_version: MANIFEST_SCHEMA_VERSION,
        source_commit: sourceCommit,
        digest: computeRequirementsDigest(requirements),
        requirements,
    }
}

function isStringArray(value: unknown): value is string[] {
    return Array.isArray(value) && value.every((item) => typeof item === 'string' && item.length > 0)
}

function parseDjangoRequirement(item: Record<string, unknown>, index: number): DjangoRequirement {
    if (item.database !== 'default') {
        throw new ManifestError(`requirements[${index}].database must be "default"`)
    }
    if (typeof item.app !== 'string' || !item.app || typeof item.migration !== 'string' || !item.migration) {
        throw new ManifestError(`requirements[${index}] needs a non-empty app and migration`)
    }
    if (item.replaces !== undefined && !isStringArray(item.replaces)) {
        throw new ManifestError(`requirements[${index}].replaces must be a list of migration names`)
    }
    const requirement: DjangoRequirement = {
        kind: 'django',
        database: 'default',
        app: item.app,
        migration: item.migration,
    }
    if (item.replaces !== undefined) {
        requirement.replaces = item.replaces
    }
    return requirement
}

function parseSqlxRequirement(item: Record<string, unknown>, index: number): SqlxRequirement {
    const database = SQLX_DATABASES.find((name) => name === item.database)
    if (!database) {
        throw new ManifestError(`requirements[${index}].database must be one of ${SQLX_DATABASES.join(', ')}`)
    }
    const versions = item.versions
    if (
        !Array.isArray(versions) ||
        versions.length === 0 ||
        !versions.every((version) => typeof version === 'number' && Number.isSafeInteger(version) && version > 0)
    ) {
        throw new ManifestError(`requirements[${index}].versions must be a non-empty list of positive integers`)
    }
    return { kind: 'sqlx', database, versions: [...new Set<number>(versions)].sort((a, b) => a - b) }
}

// An unknown kind is an error. Skipping it would report a pass for a requirement that nothing checked.
function parseRequirement(value: unknown, index: number): Requirement {
    const item = value as Record<string, unknown> | null
    if (typeof item !== 'object' || item === null) {
        throw new ManifestError(`requirements[${index}] is not an object`)
    }
    if (item.kind === 'django') {
        return parseDjangoRequirement(item, index)
    }
    if (item.kind === 'sqlx') {
        return parseSqlxRequirement(item, index)
    }
    throw new ManifestError(`requirements[${index}].kind must be "django" or "sqlx", got ${JSON.stringify(item.kind)}`)
}

export function parseManifest(text: string): SchemaRequirementsManifest {
    let raw: unknown
    try {
        raw = parseJSON(text)
    } catch (error) {
        throw new ManifestError(`manifest is not valid JSON: ${error.message}`)
    }

    const data = raw as Record<string, unknown> | null
    if (typeof data !== 'object' || data === null) {
        throw new ManifestError('manifest is not a JSON object')
    }
    if (data.schema_version !== MANIFEST_SCHEMA_VERSION) {
        throw new ManifestError(
            `manifest schema_version is ${JSON.stringify(data.schema_version)}, expected ${MANIFEST_SCHEMA_VERSION}`
        )
    }
    if (!Array.isArray(data.requirements)) {
        throw new ManifestError('manifest has no requirements list')
    }
    const requirements = data.requirements.map(parseRequirement)
    // No Django entry means the generator found nothing, which is a broken build and not "no requirements".
    if (!requirements.some((requirement) => requirement.kind === 'django')) {
        throw new ManifestError('manifest has no Django requirements')
    }

    return {
        schema_version: MANIFEST_SCHEMA_VERSION,
        source_commit: typeof data.source_commit === 'string' ? data.source_commit : null,
        digest: typeof data.digest === 'string' ? data.digest : '',
        requirements,
    }
}

export function djangoRequirements(manifest: SchemaRequirementsManifest): DjangoRequirement[] {
    return manifest.requirements.filter(
        (requirement): requirement is DjangoRequirement => requirement.kind === 'django'
    )
}

export function sqlxRequirements(manifest: SchemaRequirementsManifest): SqlxRequirement[] {
    return manifest.requirements.filter((requirement): requirement is SqlxRequirement => requirement.kind === 'sqlx')
}

export function readManifest(manifestPath: string): SchemaRequirementsManifest {
    if (!existsSync(manifestPath)) {
        throw new ManifestError(`manifest not found at ${manifestPath}`)
    }
    return parseManifest(readFileSync(manifestPath, 'utf8'))
}