diff --git a/.changeset/webhook-body-template-validation.md b/.changeset/webhook-body-template-validation.md new file mode 100644 index 0000000000..e541864458 --- /dev/null +++ b/.changeset/webhook-body-template-validation.md @@ -0,0 +1,8 @@ +--- +'@hyperdx/common-utils': patch +'@hyperdx/app': patch +--- + +fix: the webhook form now compiles the body template as you edit it and shows +the Handlebars error with its line and column. A broken template used to give +no feedback until an alert failed to deliver. diff --git a/docs/alert-webhook-template-variables.md b/docs/alert-webhook-template-variables.md index 22c8d84ee3..05d1a37539 100644 --- a/docs/alert-webhook-template-variables.md +++ b/docs/alert-webhook-template-variables.md @@ -67,6 +67,12 @@ number that may be absent. Compare against `undefined` rather than using Keep a newline or space between `{{/unless}}` and a closing `}` — Handlebars reads `}}}` as a triple-stache and fails to compile the template. +The template is Handlebars, not JSON: it only has to be JSON once rendered. +Write string arguments inside `{{ … }}` with plain or single quotes — +`{{#if (eq state "ALERT")}}` or `{{#if (eq state 'ALERT')}}` — never JSON-escaped +as `\"ALERT\"`, which Handlebars cannot parse. The webhook form shows where a +body fails to compile. + The **Send test** button on the webhook form fills every variable with a sample value, so a template that uses them can be checked before an alert fires. The sample is a `between` alert, so `{{thresholdMax}}` is populated there — a test @@ -93,13 +99,13 @@ instead if every group of a grouped alert should collapse into one incident. Routing by severity and deduping on the alert rather than the firing: -```json +``` { "alert_id": "{{alertId}}", "dedup_key": "{{alertId}}-{{groupKey}}", "status": "{{status}}", "summary": "{{title}}", - "urgency": "{{#if (eq alertType \"dashboard_chart\")}}low{{else}}high{{/if}}", + "urgency": "{{#if (eq alertType 'dashboard_chart')}}low{{else}}high{{/if}}", "value": {{value}}, "threshold": {{threshold}}, "window": { "start": "{{startTimeISO}}", "end": "{{endTimeISO}}" }, diff --git a/packages/app/src/components/TeamSettings/WebhookBodyValidation.tsx b/packages/app/src/components/TeamSettings/WebhookBodyValidation.tsx new file mode 100644 index 0000000000..335d4048ce --- /dev/null +++ b/packages/app/src/components/TeamSettings/WebhookBodyValidation.tsx @@ -0,0 +1,27 @@ +import { WebhookTemplateError } from '@hyperdx/common-utils/dist/core/handlebarsEnv'; +import { Alert, Code } from '@mantine/core'; +import { IconAlertTriangle } from '@tabler/icons-react'; + +const errorTitle = ({ line, column }: WebhookTemplateError) => { + if (line == null) return 'Template error'; + return column == null + ? `Template error on line ${line}` + : `Template error on line ${line}, column ${column}`; +}; + +export function WebhookBodyValidationAlert({ + error, +}: { + error: WebhookTemplateError; +}) { + return ( + } + title={errorTitle(error)} + data-testid="webhook-body-error" + > + {error.message} + + ); +} diff --git a/packages/app/src/components/TeamSettings/WebhookForm.tsx b/packages/app/src/components/TeamSettings/WebhookForm.tsx index 3fbc1d5c80..727083a051 100644 --- a/packages/app/src/components/TeamSettings/WebhookForm.tsx +++ b/packages/app/src/components/TeamSettings/WebhookForm.tsx @@ -1,9 +1,10 @@ -import { useEffect } from 'react'; +import { useEffect, useMemo } from 'react'; import { HTTPError } from 'ky'; import { Controller, SubmitHandler, useForm, useWatch } from 'react-hook-form'; import { ZodIssue } from 'zod'; import { json, jsonParseLinter } from '@codemirror/lang-json'; import { linter } from '@codemirror/lint'; +import { getWebhookTemplateError } from '@hyperdx/common-utils/dist/core/handlebarsEnv'; import { getDefaultWebhookBody, WEBHOOK_TEMPLATE_VARIABLES, @@ -23,6 +24,7 @@ import { Text, TextInput, } from '@mantine/core'; +import { useDebouncedValue } from '@mantine/hooks'; import { notifications } from '@mantine/notifications'; import { IconInfoCircleFilled } from '@tabler/icons-react'; import ReactCodeMirror, { @@ -31,6 +33,7 @@ import ReactCodeMirror, { } from '@uiw/react-codemirror'; import api from '@/api'; +import { WebhookBodyValidationAlert } from '@/components/TeamSettings/WebhookBodyValidation'; import { useBrandDisplayName } from '@/theme/ThemeProvider'; import { isValidUrl } from '@/utils'; @@ -133,6 +136,19 @@ export function WebhookForm({ } }, [webhook, form]); + const service = useWatch({ control: form.control, name: 'service' }); + const bodyText = useWatch({ control: form.control, name: 'body' }); + // Debounced so the error doesn't flash while a {{ … }} is half-typed. + const [debouncedBody] = useDebouncedValue(bodyText, 300); + const bodyError = useMemo( + // Slack sends a fixed payload and never renders the body. + () => + service === WebhookService.Slack + ? null + : getWebhookTemplateError(debouncedBody), + [service, debouncedBody], + ); + const handleTestWebhook = async (values: WebhookForm) => { const { service, url, body, headers } = values; @@ -288,7 +304,6 @@ export function WebhookForm({ } }; - const service = useWatch({ control: form.control, name: 'service' }); // A body left at the old service's default would still be sent verbatim, and // each service's default is invalid to the others' receivers. A hand-edited // body is the user's, so it survives the switch. @@ -418,6 +433,9 @@ export function WebhookForm({ )} /> , + bodyError && ( + + ), } key="5" diff --git a/packages/app/src/components/TeamSettings/__tests__/WebhookForm.test.tsx b/packages/app/src/components/TeamSettings/__tests__/WebhookForm.test.tsx index 87c1ed806a..2d9a22eef0 100644 --- a/packages/app/src/components/TeamSettings/__tests__/WebhookForm.test.tsx +++ b/packages/app/src/components/TeamSettings/__tests__/WebhookForm.test.tsx @@ -5,7 +5,12 @@ import { } from '@hyperdx/common-utils/dist/types'; import { MantineProvider } from '@mantine/core'; import { QueryClient, QueryClientProvider } from '@tanstack/react-query'; -import { render, screen } from '@testing-library/react'; +import { + act, + render, + screen, + waitForElementToBeRemoved, +} from '@testing-library/react'; import userEvent from '@testing-library/user-event'; import { @@ -132,4 +137,65 @@ describe('WebhookForm', () => { screen.queryByTestId('webhook-template-variables'), ).not.toBeInTheDocument(); }); + describe('body template validation', () => { + const VALID_BODY = + '{"status": "{{#if (eq state "ALERT")}}firing{{else}}resolved{{/if}}"}'; + const ESCAPED_QUOTES_BODY = + '{"status": "{{#if (eq state \\"ALERT\\")}}firing{{else}}resolved{{/if}}"}'; + + async function fillIncidentIoWebhook( + user: ReturnType, + body: string, + ) { + await user.click(screen.getByRole('radio', { name: 'incident.io' })); + await user.type(screen.getByTestId('webhook-name-input'), 'oncall'); + await user.type( + screen.getByTestId('webhook-url-input'), + 'https://api.incident.io/v2/alert_events/http/abc?token=xyz', + ); + // incident.io has no headers editor, so the only editor is the body. + await user.click(screen.getByTestId('codemirror')); + await user.paste(body); + } + + it('shows a compile error inline', async () => { + const user = userEvent.setup(); + renderForm(); + await fillIncidentIoWebhook(user, ESCAPED_QUOTES_BODY); + + const error = await screen.findByTestId('webhook-body-error'); + expect(error).toHaveTextContent('Template error on line 1, column 29'); + expect(error).toHaveTextContent('Parse error on line 1'); + }); + + it('clears the error once the template is fixed', async () => { + const user = userEvent.setup(); + renderForm(); + await fillIncidentIoWebhook(user, ESCAPED_QUOTES_BODY); + await screen.findByTestId('webhook-body-error'); + + await user.clear(screen.getByTestId('codemirror')); + await user.paste(VALID_BODY); + + await waitForElementToBeRemoved(() => + screen.queryByTestId('webhook-body-error'), + ); + }); + + it('saves a template that is only valid JSON once rendered', async () => { + const user = userEvent.setup(); + renderForm(); + await fillIncidentIoWebhook(user, VALID_BODY); + // Outlast the debounce so a false positive would have rendered. + await act(() => new Promise(resolve => setTimeout(resolve, 400))); + expect( + screen.queryByTestId('webhook-body-error'), + ).not.toBeInTheDocument(); + + await user.click(screen.getByTestId('add-webhook-button')); + expect(mockSaveWebhook).toHaveBeenCalledWith( + expect.objectContaining({ body: VALID_BODY }), + ); + }); + }); }); diff --git a/packages/common-utils/src/core/__tests__/handlebarsEnv.test.ts b/packages/common-utils/src/core/__tests__/handlebarsEnv.test.ts index c1bf2a4934..a798d38a22 100644 --- a/packages/common-utils/src/core/__tests__/handlebarsEnv.test.ts +++ b/packages/common-utils/src/core/__tests__/handlebarsEnv.test.ts @@ -2,9 +2,14 @@ import { clearTemplateCache, compileLenient, compileStrict, + getWebhookTemplateError, UnknownTemplateHelperError, validateTemplate, } from '@/core/handlebarsEnv'; +import { + DEFAULT_GENERIC_WEBHOOK_BODY, + DEFAULT_INCIDENT_IO_WEBHOOK_BODY, +} from '@/types'; describe.each([ ['compileStrict', compileStrict], @@ -128,3 +133,48 @@ describe('validateTemplate', () => { expect(() => validateTemplate('{{missing}}')).not.toThrow(); }); }); + +describe('getWebhookTemplateError', () => { + it('accepts a template that is invalid JSON before rendering', () => { + const body = + '{"status": "{{#if (eq state "ALERT")}}firing{{else}}resolved{{/if}}"}'; + expect(() => JSON.parse(body)).toThrow(); + expect(getWebhookTemplateError(body)).toBe(null); + }); + + it.each([DEFAULT_GENERIC_WEBHOOK_BODY, DEFAULT_INCIDENT_IO_WEBHOOK_BODY])( + 'accepts the default body %#', + body => { + expect(getWebhookTemplateError(body)).toBe(null); + }, + ); + + it('rejects JSON-escaped quotes inside a helper call', () => { + const body = + '{"status": "{{#if (eq state \\"ALERT\\")}}firing{{else}}resolved{{/if}}"}'; + expect(() => JSON.parse(body)).not.toThrow(); + expect(getWebhookTemplateError(body)).toEqual({ + message: expect.stringContaining('Parse error on line 1'), + line: 1, + column: 29, + }); + }); + + it('reports the line and column of a parse error on a later line', () => { + expect(getWebhookTemplateError('{\n "a": "{{title}"\n}')).toMatchObject({ + line: 2, + column: 16, + }); + }); + + it('reports the location of a mismatched block', () => { + expect(getWebhookTemplateError('{{#if x}}{{/each}}')).toMatchObject({ + message: expect.stringContaining("if doesn't match each"), + line: 1, + }); + }); + + it.each(['', ' \n', undefined])('accepts an empty body (%p)', body => { + expect(getWebhookTemplateError(body)).toBe(null); + }); +}); diff --git a/packages/common-utils/src/core/handlebarsEnv.ts b/packages/common-utils/src/core/handlebarsEnv.ts index 5bdd2c63fb..81076f3a35 100644 --- a/packages/common-utils/src/core/handlebarsEnv.ts +++ b/packages/common-utils/src/core/handlebarsEnv.ts @@ -134,3 +134,61 @@ export const clearTemplateCache = () => { strictCache.clear(); lenientCache.clear(); }; + +export type WebhookTemplateError = { + message: string; + line?: number; + column?: number; +}; + +const toFiniteNumber = (value: unknown): number | undefined => + typeof value === 'number' && Number.isFinite(value) ? value : undefined; + +// Reads a property off a value of unknown shape without a type assertion. +const read = (value: unknown, key: string): unknown => + value != null && typeof value === 'object' + ? Reflect.get(value, key) + : undefined; + +// Handlebars reports 0-based columns. +const toLocation = (line: unknown, column: unknown) => { + const col = toFiniteNumber(column); + return { + line: toFiniteNumber(line), + column: col == null ? undefined : col + 1, + }; +}; + +/** + * Compiles a webhook body template and returns the error, with its line and + * column where Handlebars knows them, or null when it compiles. Delivery + * renders with stock Handlebars plus an `eq` helper; helpers don't affect + * compilation, so stock Handlebars catches the same errors. An empty body + * compiles: it falls back to the default template. + */ +export function getWebhookTemplateError( + template: string | undefined, +): WebhookTemplateError | null { + if (!template?.trim()) return null; + try { + // compile() is lazy; precompile() parses and compiles up front. + Handlebars.precompile(template, { noEscape: true }); + return null; + } catch (e) { + const message = e instanceof Error ? e.message : String(e); + if (read(e, 'lineNumber') != null) { + return { + message, + ...toLocation(read(e, 'lineNumber'), read(e, 'column')), + }; + } + // Parse errors carry only the line, in the message. The lexer that just + // failed still holds the offending token's position. Parsing is + // synchronous, so nothing has run since. + const loc = read(read(read(Handlebars, 'Parser'), 'lexer'), 'yylloc'); + return { + message, + ...toLocation(read(loc, 'first_line'), read(loc, 'first_column')), + }; + } +}