Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
19 changes: 19 additions & 0 deletions DECISIONS.md
Original file line number Diff line number Diff line change
Expand Up @@ -603,3 +603,22 @@ published by hand by the owner.
status alerts and adds the tag `alert:pagerduty` for a Kibana rule to route on. Routing to PagerDuty is Kibana's job.
- **Schedule and locations are validated at export**, against `ALLOWED_SCHEDULES` and the public locations of
`@elastic/synthetics`, so a failure names the journey and does not arrive as a rejected push.

## `.http` monitors

- **A TypeScript subset of the parser, not the .NET tool at export time.** The plan allowed exporting JSON produced by
Nullean.HttpFileParser. That would make a Node package need a .NET tool to export, and the monitor would still need a
runner. Nullean.HttpFileParser is about 3,000 lines (environments, secrets, templates, files, scripts refusal); a
monitor needs requests, headers, bodies, variables, response references, `@readonly` and `@expect`. The subset is about
600 lines, refuses everything else with a reason and a line, and reuses the journey header grammar.
- **Messages and semantics are copied from Nullean.HttpFileParser**, so a file that passes `dotnet test` and a monitor
say the same things. The parsers are not tested against shared fixtures yet; the TS tests restate the .NET messages.
Known difference: JSON numbers compare as JavaScript reads them.
- **Header directives in comments before the first request.** Nullean.HttpFileParser treats unknown `@` comments as plain
comments, so a file with `# @monitor` still runs there. After the first request they are an error, as after the first
step of a journey: a directive that silently did nothing would be worse.
- **Step names are the request line as written.** Variables stay unresolved, so a header or URL secret never reaches a
step name in Kibana. Failure messages name `file:line` and what the response held, never a resolved request.
- **Read-only by default in exports.** The generated file sets `readOnly: true`; only GET, HEAD, OPTIONS and requests
marked `# @readonly` are sent. MCP `tools/list` and `search_docs` are POSTs that read, which is what `@readonly` is for.

48 changes: 47 additions & 1 deletion docs/journeys/playwright.md
Original file line number Diff line number Diff line change
Expand Up @@ -91,7 +91,7 @@ expect title "Elastic Docs"
| `--base-url <url>` | embed the base URL; without it a generated file reads `params.url`, from `--params` or the Synthetics config |
| `--root <folder>` | names are paths under this folder; by default the folder the arguments start in |

- **Which journeys export.** A journey needs `@monitor`; its `@requires` must hold for the flags, build type and
- **Which journeys export.** A journey (or `.http` file, see below) needs `@monitor`; its `@requires` must hold for the flags, build type and
environment you give; and it must not be `@mutates`, because a monitor runs against a live site. Every journey that
does not export is printed with the reason. A generated file also runs read-only (`readOnly: true`).
- **What the directives become.** `schedule` and `locations` go to `monitor.use` and are checked against what
Expand All @@ -106,6 +106,52 @@ expect title "Elastic Docs"
The files start with a generated-file header, and a later export removes generated files whose journey is no longer
exported, and only those. `push` replaces the project's monitors, so removing a journey removes its monitor.

## Monitor an API with `.http` files

An endpoint that has no page, such as an MCP server or a JSON API, is a `.http` file: the format of Visual Studio, the
VS Code REST Client and the JetBrains HTTP Client, which [nullean/snapshots](https://github.com/nullean/snapshots)
runs in `dotnet test`. `httpSteps` runs the same file as a Synthetics journey, one step per request:

```ts
import { journey, step } from '@elastic/synthetics';
import { httpSteps } from '@nullean/journeys/synthetics';

journey('mcp', ({ request, params }) =>
httpSteps({ request, step, params }, `
@host = ${params.url}
# @readonly
# @expect status 200
# @expect json $.result.tools[*].name contains "search_docs"
POST {{host}}/docs/_mcp
Content-Type: application/json

{"jsonrpc":"2.0","id":1,"method":"tools/list"}
`, { baseUrl: params.url }));
```

`journeys export-synthetics` exports a `.http` file with `@monitor` the same way as a journey, into
`*.http.journey.ts`. The header directives (`@tags`, `@requires`, `@monitor`, `@alert`, `@mutates`) go in the comments
before the first request, with the journey grammar; Nullean.HttpFileParser reads them as plain comments.

- **A step is a request.** Its name is the request line as written, with `{{variables}}` unresolved, so a secret never
reaches Kibana. A name from `# @name` leads it. Requests run in file order, and a failed one skips the rest.
- **A 404 or 500 is a response.** Only a request that cannot be resolved or sent, a read-only refusal, or an unmet
`# @expect` fails: `status 200` or `2xx`, `header content-type ~ json` (a case-insensitive substring), and
`json $.items[*].name equals|contains "lamp"` (`equals` needs every selected value, `contains` one). The messages are
Nullean.HttpFileParser's.
- **Read-only.** With `readOnly: true`, which every exported monitor sets, only GET, HEAD and OPTIONS are sent. A
request that reads although it is not a GET, such as an MCP `tools/list`, says so with `# @readonly`.
- **What is supported.** `METHOD URL`, headers, an inline body, `###` and `### name`, `# @name`, `# @no-redirect`,
`# @timeout`, file variables (`@host = ...`), and references: `{{host}}`, `{{login.response.body.$.token}}`,
`{{login.response.headers.Location}}`, `{{$guid}}`, `{{$uuid}}`, `{{$timestamp}}`, `{{$isoTimestamp}}`,
`{{$randomInt}}`, `{{$processEnv NAME}}`, `{{$env.NAME}}` and `{{$secret NAME}}` (from the journey's `params`, then the
environment).
- **What is refused, with its line.** File bodies (`< ./file`), `http-client.env.json` environments, `$datetime` and the
other dynamic variables, references to a request, JetBrains scripts, `>>` redirection, `@prompt`, cURL and GraphQL.
A URL that starts with `/` needs `baseUrl`, or an absolute `@host`.
- **A difference from the .NET runner.** A number a JSON expectation compares is JavaScript's reading of it, so `1.0`
is `1`. The two parsers are not run against shared fixtures yet.

## Assertions

`expect` lines (see the [command reference](commands.md#expect)) run on Playwright's own assertions when the adapter has
Expand Down
40 changes: 39 additions & 1 deletion js/journeys/src/adapters/synthetics.ts
Original file line number Diff line number Diff line change
Expand Up @@ -6,10 +6,14 @@
// import { journeySteps } from '@nullean/journeys/synthetics';
// journey('checkout', ({ page, params }) => journeySteps({ page, step, params, expect }, `open /\nclick #buy`, { baseUrl: params.url }));

import type { Page } from 'playwright-core';
import type { APIRequestContext, Page } from 'playwright-core';
import { joinLine } from '../commandline.ts';
import { parseJourney } from '../parse.ts';
import { JourneyRun } from '../run.ts';
import { parseHttpFile } from '../http.ts';
import { HttpRun } from '../http-run.ts';
import type { HttpRunOptions } from '../http-run.ts';
import { requirementMet } from '../parse.ts';
import type { PlaywrightExpect } from '../expect.ts';
import type { RunOptions } from '../run.ts';

Expand Down Expand Up @@ -39,3 +43,37 @@ export function journeySteps(context: SyntheticsContext, journeyText: string, op
});
}
}

export interface SyntheticsHttpContext {
/** The journey's `request` (Playwright's APIRequestContext). */
request: APIRequestContext;
step: (name: string, callback: () => void | Promise<void>) => void;
/** The journey's params: `{{$secret NAME}}` and `{{$processEnv NAME}}` resolve from here first, then the process environment. */
params?: Record<string, unknown>;
}

export interface SyntheticsHttpOptions extends HttpRunOptions {
source?: string;
}

/**
* Registers one Synthetics step per request of a `.http` file, in file order, so Kibana shows the file as it was written.
* A step is named by its request line as written (variables unresolved, so no secret reaches a step name). A file whose
* `@requires` does not hold, or that is `@mutates` in a read-only run, registers one step that says so.
*/
export function httpSteps(context: SyntheticsHttpContext, httpText: string, options: SyntheticsHttpOptions = {}): void {
const file = parseHttpFile(httpText, options.source);
const params = context.params ?? {};
const secrets = options.secrets ?? ((name: string) => (typeof params[name] === 'string' ? (params[name] as string) : undefined));
const unmet = file.metadata?.requires?.find((r) => !requirementMet(r, options));
if (unmet !== undefined || (options.readOnly === true && file.metadata?.mutates === true)) {
context.step(unmet !== undefined ? `skipped: @requires ${unmet} does not hold` : 'skipped: @mutates in a read-only run', () => {});
return;
}
const run = new HttpRun(context.request, file, { ...options, secrets });
for (const request of file.requests) {
context.step(request.name ? `${request.name}: ${request.requestLine}` : request.requestLine, async () => {
await run.send(request);
});
}
}
50 changes: 30 additions & 20 deletions js/journeys/src/export.ts
Original file line number Diff line number Diff line change
Expand Up @@ -3,8 +3,9 @@
// it with journeySteps from ./adapters/synthetics.ts. The output depends on nothing but the inputs: no timestamps, a
// stable order, so a second export changes nothing in git.

import { parseJourney, unmetRequirement } from './parse.ts';
import type { Journey } from './model.ts';
import { parseHttpFile } from './http.ts';
import { parseJourney, requirementMet } from './parse.ts';
import type { JourneyMetadata } from './model.ts';

/** What the exported monitors are for: judged against each journey's `@requires`, and embedded for its `feature` blocks. */
export interface ExportContext {
Expand Down Expand Up @@ -62,15 +63,11 @@ export class ExportError extends Error {
export function exportSynthetics(sources: ExportSource[], context: ExportContext = {}): { files: ExportedFile[]; skipped: ExportSkip[] } {
const files: ExportedFile[] = [];
const skipped: ExportSkip[] = [];
const ids = new Map<string, string>();
for (const source of [...sources].sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0))) {
const kind = source.kind ?? 'journey';
if (kind !== 'journey') {
skipped.push({ name: source.name, reason: `${kind} files are not exported by this version` });
continue;
}
const text = source.text.replace(/\r\n/g, '\n');
const journey = parseJourney(text, source.name);
const metadata = journey.metadata;
const metadata: JourneyMetadata | undefined = kind === 'http' ? parseHttpFile(text, source.name).metadata : parseJourney(text, source.name).metadata;
if (!metadata?.monitor) {
skipped.push({ name: source.name, reason: 'no @monitor' });
continue;
Expand All @@ -79,22 +76,32 @@ export function exportSynthetics(sources: ExportSource[], context: ExportContext
skipped.push({ name: source.name, reason: '@mutates: a monitor runs against a live site' });
continue;
}
const unmet = unmetRequirement(journey, context);
const unmet = metadata.requires?.find((r) => !requirementMet(r, context));
if (unmet !== undefined) {
skipped.push({ name: source.name, reason: `@requires ${unmet} does not hold` });
continue;
}
files.push({ name: source.name, fileName: `${source.name}.journey.ts`, content: render(source.name, text, journey, context) });
const id = monitorId(source.name);
const other = ids.get(id);
if (other !== undefined) throw new ExportError(source.name, `its monitor id '${id}' is already taken by ${other}: rename one of them`);
ids.set(id, source.name);
files.push({
name: source.name,
fileName: `${source.name}.${kind === 'http' ? 'http.' : ''}journey.ts`,
content: render(source.name, kind, text, metadata, context),
});
}
return { files, skipped };
}

function render(name: string, text: string, journey: Journey, context: ExportContext): string {
const monitor = journey.metadata!.monitor!;
const paging = context.paging === true && journey.metadata!.alert?.includes('pagerduty') === true;
const tags = [...(journey.metadata!.tags ?? [])];
const monitorId = (name: string) => name.replace(/[^A-Za-z0-9_-]+/g, '-');

function render(name: string, kind: 'journey' | 'http', text: string, metadata: JourneyMetadata, context: ExportContext): string {
const monitor = metadata.monitor!;
const paging = context.paging === true && metadata.alert?.includes('pagerduty') === true;
const tags = [...(metadata.tags ?? [])];
if (paging) tags.push('alert:pagerduty');
const id = name.replace(/[^A-Za-z0-9_-]+/g, '-');
const id = monitorId(name);

if (monitor.schedule !== undefined && !SCHEDULES.includes(monitor.schedule))
throw new ExportError(name, `@monitor schedule=${monitor.schedule} is not one Synthetics accepts: ${SCHEDULES.join(', ')}`);
Expand All @@ -114,14 +121,17 @@ function render(name: string, text: string, journey: Journey, context: ExportCon
if (context.env !== undefined) options.push(`env: ${literal(context.env)}`);
options.push('readOnly: true');

const http = kind === 'http';
return [
`${GENERATED_MARKER} from ${name}.journey. Do not edit: change the journey and export again.`,
`import { expect, journey, monitor, step } from '@elastic/synthetics';`,
`import { journeySteps } from '@nullean/journeys/synthetics';`,
`${GENERATED_MARKER} from ${name}.${http ? 'http' : 'journey'}. Do not edit: change the ${http ? 'file' : 'journey'} and export again.`,
`import { ${http ? '' : 'expect, '}journey, monitor, step } from '@elastic/synthetics';`,
`import { ${http ? 'httpSteps' : 'journeySteps'} } from '@nullean/journeys/synthetics';`,
'',
`journey({ id: ${literal(id)}, name: ${literal(name)} }, ({ page, params }) => {`,
`journey({ id: ${literal(id)}, name: ${literal(name)} }, ({ ${http ? 'request' : 'page'}, params }) => {`,
` monitor.use({ ${use.join(', ')} });`,
` journeySteps({ page, step, params, expect }, ${template(text)}, { ${options.join(', ')} });`,
http
? ` httpSteps({ request, step, params }, ${template(text)}, { ${options.join(', ')} });`
: ` journeySteps({ page, step, params, expect }, ${template(text)}, { ${options.join(', ')} });`,
'});',
'',
].join('\n');
Expand Down
Loading
Loading