: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.
Python ab-testingai-analyticsanalyticscdpdata-warehouseexperimentsfeature-flagsjavascriptproduct-analyticspythonreactsession-replaysurveystypescriptweb-analytics
import { tryJsonParse } from 'lib/utils/json'
import { LiquidRenderer } from 'lib/utils/liquid'
import { type EmailTemplate, MAX_WORKFLOW_EMAIL_SENDERS } from 'scenes/hog-functions/email-templater/types'
import { CyclotronJobInputSchemaType, CyclotronJobInputType } from '~/types'
export type CyclotronJobInputsValidationResult = {
valid: boolean
errors: Record<string, string>
warnings: Record<string, string>
}
// Roots of the templating globals available to hog functions. Anchoring the
// mismatch heuristics on these keeps false positives down — literal braces in
// JSON/text bodies won't trip them unless they look like a global reference.
const GLOBAL_ROOTS = 'event|person|groups|inputs|source|project'
// A global root immediately followed by property access (`.field` or `[…]`). Requiring the
// access form is what distinguishes a real expression (`person.properties.email`) from a
// literal JSON key that happens to be named after a global (`{"event": "pageview"}`).
const GLOBAL_REFERENCE = `\\b(${GLOBAL_ROOTS})\\s*[.\\[]`
export const TEMPLATING_MISMATCH_WARNINGS = {
// Hog single-brace expression authored in a Liquid field — rendered literally.
hogSyntaxInLiquidField:
'This looks like Hog syntax ({…}), but the field uses Liquid templating which expects {{ … }}. It will be sent as literal text — switch the templating engine to Hog, or use {{ … }}.',
// Liquid double-brace expression authored in a Hog field.
liquidSyntaxInHogField:
'This looks like Liquid syntax ({{ … }}), but the field uses Hog templating which expects { … }. Switch the templating engine to Liquid, or use single braces.',
// Bare global path with no braces at all — sent literally by either engine. The
// suggested fix differs: Hog wraps in { … }, Liquid in {{ … }}.
unbracedExpressionInHogField: (expression: string): string =>
`This will be sent as literal text. Did you mean {${expression}}? Wrap it in braces to use the value.`,
unbracedExpressionInLiquidField: (expression: string): string =>
`This will be sent as literal text. Did you mean {{ ${expression} }}? Wrap it in braces to use the value.`,
} as const
/**
* Detect when a value is authored in the wrong templating syntax for its engine.
* These are non-blocking warnings: the value still saves, but it would be sent
* literally rather than evaluated (e.g. `person.properties.email` with no braces,
* or `{ … }` hog syntax in a Liquid field).
*/
const detectTemplatingMismatch = (value: unknown, language: 'hog' | 'liquid'): string | undefined => {
if (typeof value !== 'string' || !value) {
return
}
// A bare global path with no braces at all is literal in BOTH engines, so check it
// regardless of language — only the suggested brace style differs.
if (!value.includes('{') && new RegExp(`^(${GLOBAL_ROOTS})(\\.[\\w$]+|\\[[^\\]]+\\])+$`).test(value.trim())) {
return language === 'liquid'
? TEMPLATING_MISMATCH_WARNINGS.unbracedExpressionInLiquidField(value.trim())
: TEMPLATING_MISMATCH_WARNINGS.unbracedExpressionInHogField(value.trim())
}
if (language === 'liquid') {
// Strip valid Liquid ({{ }} / {% %}) first, then look for leftover hog-style
// single-brace expressions referencing a global — those render literally.
const withoutLiquid = value.replace(/\{\{[\s\S]*?\}\}/g, '').replace(/\{%[\s\S]*?%\}/g, '')
if (new RegExp(`\\{[^{}]*${GLOBAL_REFERENCE}[^{}]*\\}`).test(withoutLiquid)) {
return TEMPLATING_MISMATCH_WARNINGS.hogSyntaxInLiquidField
}
return
}
// Hog field. Beyond `{{ global.… }}`, a pipe filter inside double braces (`{{ x | upcase }}`)
// or a `{% … %}` tag is unambiguously Liquid regardless of what it references — Hog has no
// single-pipe operator and no percent tags, so these fail Hog compilation at activation.
if (
new RegExp(`\\{\\{[^}]*${GLOBAL_REFERENCE}[^}]*\\}\\}`).test(value) ||
/\{\{[^{}]*\|[^{}]*\}\}/.test(value) ||
/\{%[\s\S]*?%\}/.test(value)
) {
return TEMPLATING_MISMATCH_WARNINGS.liquidSyntaxInHogField
}
}
const detectInputWarning = (
input: CyclotronJobInputType,
inputSchema: CyclotronJobInputSchemaType
): string | undefined => {
if (!input || input.secret) {
return
}
if (inputSchema.templating === false) {
return
}
const language = input.templating ?? 'hog'
if (['string', 'json'].includes(inputSchema.type)) {
return detectTemplatingMismatch(input.value, language)
}
if (inputSchema.type === 'dictionary' && input.value && typeof input.value === 'object') {
for (const val of Object.values(input.value)) {
const warning = detectTemplatingMismatch(val, language)
if (warning) {
return warning
}
}
}
}
const validateInput = (input: CyclotronJobInputType, inputSchema: CyclotronJobInputSchemaType): string | undefined => {
const language = input?.templating ?? 'hog'
const value = input?.value
if (input?.secret) {
// We leave unmodified secret values alone
return
}
const getTemplatingError = (value: string): string | undefined => {
if (language === 'liquid' && typeof value === 'string') {
try {
LiquidRenderer.parse(value)
} catch (e: any) {
return `Liquid template error: ${e.message}`
}
}
}
const missing = value === undefined || value === null || value === ''
if (missing) {
if (inputSchema.required) {
return 'This field is required'
}
return undefined
}
if (inputSchema.type === 'string' && typeof value !== 'string') {
return 'Value must be a string'
} else if (inputSchema.type === 'number' && typeof value !== 'number') {
return 'Value must be a number'
} else if (inputSchema.type === 'boolean' && typeof value !== 'boolean') {
// When templating is enabled (default), boolean fields can be template strings
if (inputSchema.templating === false || typeof value !== 'string') {
return 'Value must be a boolean'
}
} else if (inputSchema.type === 'dictionary' && typeof value !== 'object') {
return 'Value must be a dictionary'
} else if (inputSchema.type === 'integration' && typeof value !== 'number') {
return 'Value must be an Integration ID'
} else if (inputSchema.type === 'json') {
if (!['string', 'object'].includes(typeof value)) {
return 'Value must be valid json'
}
if (typeof value === 'string' && !tryJsonParse(value)) {
return 'Invalid JSON'
}
}
if (['email', 'native_email'].includes(inputSchema.type) && value) {
// `native_email` stores `to` as { name, email }; the legacy `email` type stores a bare address string.
// Pull out the address so it gets the same required + templating validation as every other field —
// otherwise a malformed Liquid template in the To field (or an empty address) saves with no error.
const toEmail = value.to && typeof value.to === 'object' ? value.to.email : value.to
const senderLimitError =
inputSchema.type === 'native_email' &&
typeof value.from === 'object' &&
Array.isArray(value.from?.integrationIds) &&
value.from.integrationIds.length > MAX_WORKFLOW_EMAIL_SENDERS
? `Choose no more than ${MAX_WORKFLOW_EMAIL_SENDERS} email senders`
: undefined
const emailTemplateErrors: Partial<EmailTemplate> = {
html:
!value.html && !value.text
? 'HTML or plain text is required'
: value.html
? getTemplatingError(value.html)
: undefined,
text: value.text ? getTemplatingError(value.text) : undefined,
subject: !value.subject ? 'Subject is required' : getTemplatingError(value.subject),
// `native_email` stores `from` as { integrationId, email?, name? } where the optional
// keys are templated sender overrides; the legacy `email` type stores a template string.
from: !value.from
? 'From is required'
: (senderLimitError ??
(typeof value.from === 'string'
? getTemplatingError(value.from)
: (getTemplatingError(value.from.email) ?? getTemplatingError(value.from.name)))),
to: !toEmail ? 'To is required' : getTemplatingError(toEmail),
}
const combinedErrors = Object.values(emailTemplateErrors)
.filter((v) => !!v)
.join(', ')
if (combinedErrors) {
return combinedErrors
}
}
if (['string', 'json'].includes(inputSchema.type)) {
const templatingError = getTemplatingError(value)
if (templatingError) {
return templatingError
}
}
if (inputSchema.type === 'dictionary') {
for (const val of Object.values(value ?? {})) {
if (typeof val === 'string') {
const templatingError = getTemplatingError(val)
if (templatingError) {
return templatingError
}
}
}
}
}
export const MISSING_INTEGRATION_ERROR =
'This integration no longer exists. It may have been deleted. Select a connected integration.'
export class CyclotronJobInputsValidation {
static validate(
inputs: Record<string, CyclotronJobInputType>,
inputsSchema: CyclotronJobInputSchemaType[],
integrations?: { id: number }[] | null
): CyclotronJobInputsValidationResult {
const inputErrors: Record<string, string> = {}
const inputWarnings: Record<string, string> = {}
inputsSchema?.forEach((inputSchema) => {
const input = inputs[inputSchema.key]
const error =
validateInput(input, inputSchema) ??
(inputSchema.type === 'integration' &&
integrations &&
typeof input?.value === 'number' &&
!integrations.some((integration) => integration.id === input.value)
? MISSING_INTEGRATION_ERROR
: undefined)
if (error) {
inputErrors[inputSchema.key] = error
}
const warning = detectInputWarning(input, inputSchema)
if (warning) {
inputWarnings[inputSchema.key] = warning
}
})
return {
// Warnings are intentionally excluded from `valid` — they never block save.
valid: Object.keys(inputErrors).length === 0,
errors: inputErrors,
warnings: inputWarnings,
}
}
}