mirror of
https://github.com/tester-army/e2e.git
synced 2026-11-22 18:19:48 +08:00
* fix(engine): wait for a crashed server's exit before its connection closes spawnTransport handed the child's stdout to the connection directly. When a server exits mid-request, its stdout can end before Node delivers the exit and the rest of its stderr, and the connection reads both for its message the moment it closes. The request then failed with only "the peer closed the connection", which made the engine-protocol crash test flaky on CI (Node 22). The connection now reads stdout through a stream that ends once the child has closed, or 2 s after stdout ended, for a server that stays up or a grandchild that holds its stderr. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * test(engine): pin the wait on close, and time only the failing request A crashed server's child that shares its stderr now has a test, which fails when the transport waits for the exit instead of the close. The stdout-first test measures the request instead of a 1.5 s test timeout, which failed under load. The cap is a cleared timer, the changeset and docs name the signal case, and the fixture's modes are one option. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * fix(engine): end a server's stdout from a generator, and test the signal and the cap The input is now an async generator over the server's stdout that waits for the close or the 2 s cap, so a stdout error reaches the connection as an error event and the cap's timer is aborted, by construction. New tests pin the signal case the docs name and the cap's length, and the crash helper takes the fixture's mode type. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * docs(engine): say what a crash error holds after the cap, and what keeps a request open Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * fix(engine): cap the stdout wait with an unref'd delay, and pin the cap from both sides The aborted delay's .catch could never run and nothing tested the abort. An unref'd delay needs neither, the pattern step-control.ts uses. The stays-up test now fails a cap under 1.9 s or over 3 s. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
170 lines
5.8 KiB
Plaintext
170 lines
5.8 KiB
Plaintext
---
|
|
title: Engine servers
|
|
description: Run an engine in another process, on another machine, or in another language.
|
|
---
|
|
|
|
An engine server answers the [engine protocol](/reference/engine-protocol)
|
|
outside the runner's process: in a child process, on another machine, or on
|
|
a device, written in any language. `connectEngine` turns a server into an
|
|
engine handle, and the runner drives it like any other engine.
|
|
|
|
## Connect to a server
|
|
|
|
Set a `connectEngine` handle as the target's engine. The manifest says what
|
|
the server answers; the runner needs it at config load, before any server
|
|
starts.
|
|
|
|
```ts title="e2e.config.ts"
|
|
import type { E2EConfig } from 'e2e';
|
|
import { connectEngine, spawnTransport } from 'e2e/engine';
|
|
|
|
export default {
|
|
targets: [
|
|
{
|
|
name: 'kiosk',
|
|
engine: connectEngine({
|
|
manifest: {
|
|
name: 'kiosk',
|
|
version: '1.0.0',
|
|
spiVersion: 1,
|
|
platform: 'kiosk',
|
|
methods: ['engine/observe', 'engine/perform'],
|
|
actions: ['tap'],
|
|
},
|
|
transport: spawnTransport({ command: './kiosk-engine' }),
|
|
resolveLocators: true,
|
|
}),
|
|
},
|
|
],
|
|
} satisfies E2EConfig;
|
|
```
|
|
|
|
- The server's manifest from `initialize` must match the declared one. When
|
|
it differs, the first connection fails with `ENGINE_FAILURE` and names
|
|
each field.
|
|
- With `resolveLocators`, the client resolves locators over each
|
|
observation, so a server only has to produce a tree.
|
|
- `spawnTransport` starts a server per connection. `socketTransport`
|
|
reaches one that already listens on a port.
|
|
|
|
<Warning>
|
|
A server receives what an engine in the runner's process would: the run's
|
|
environment, model keys and `E2E_SECRET_*` values included, and secrets in
|
|
plaintext. Connect only to a server you trust, over a channel you trust.
|
|
`socketTransport` doesn't encrypt.
|
|
</Warning>
|
|
|
|
## Keep host work on the client
|
|
|
|
Some members hold functions, or need the machine the runner is on. Pass
|
|
them to `connectEngine`; they run in the runner's process:
|
|
|
|
| Option | Runs on the client |
|
|
| --- | --- |
|
|
| `fixtures` | Fixture factories, such as a `device` fixture. They reach the server through the engine's members. |
|
|
| `validateApp` | The app check at config load. |
|
|
| `secrets` | The `secrets.get()` handles the server may resolve. |
|
|
| `session` | Session hooks that replace the server's, such as relaunching an app with `simctl`. |
|
|
|
|
```ts
|
|
const engine = connectEngine({
|
|
manifest,
|
|
transport,
|
|
session: { restart: (operation) => relaunch(operation) },
|
|
fixtures: {
|
|
device: (context) => context.fixture('device', { back: () => engine.session!.back!(context.operation()) }, { back: { kind: 'resource' } }),
|
|
},
|
|
});
|
|
```
|
|
|
|
## Serve a TypeScript engine
|
|
|
|
`serveEngine` answers the protocol with a `defineEngine` engine, over stdin
|
|
and stdout by default. Run it as the command of a `spawnTransport`, and
|
|
declare its manifest with `describeEngine`.
|
|
|
|
```ts title="server.ts"
|
|
import { serveEngine } from 'e2e/engine';
|
|
import { kiosk } from './src/index.ts';
|
|
|
|
await serveEngine((options) => kiosk(options as { host: string }));
|
|
```
|
|
|
|
```ts title="e2e.config.ts"
|
|
import type { E2EConfig } from 'e2e';
|
|
import { connectEngine, describeEngine, spawnTransport } from 'e2e/engine';
|
|
import { kiosk } from './src/index.ts';
|
|
|
|
export default {
|
|
targets: [
|
|
{
|
|
name: 'kiosk',
|
|
engine: connectEngine({
|
|
manifest: describeEngine(kiosk({ host: 'localhost' })),
|
|
transport: spawnTransport({ command: 'node', args: ['server.ts'] }),
|
|
initializationOptions: { host: 'localhost' },
|
|
}),
|
|
},
|
|
],
|
|
} satisfies E2EConfig;
|
|
```
|
|
|
|
Keep the server's own logging on stderr: stdout carries the protocol.
|
|
When the server exits during a request, the request fails with
|
|
`ENGINE_FAILURE`, which names its exit code or the signal that stopped it,
|
|
and its last lines of stderr.
|
|
A process the server started that still holds its stdout keeps the request
|
|
open until that process exits too.
|
|
|
|
## Write a server in another language
|
|
|
|
A server reads and writes JSON-RPC 2.0 messages, each after a
|
|
`Content-Length` header, as a language server does. It answers:
|
|
|
|
1. `initialize`, with `{ protocolVersion: 1, manifest }`. Refuse any other
|
|
protocol version.
|
|
2. Each method its manifest lists, such as `engine/observe`. Its params are
|
|
the member's arguments by name.
|
|
3. `shutdown`, then the `exit` notification, after which the server stops.
|
|
|
|
Ignore notifications you don't know. Report a failure as error `-32000`
|
|
with the e2e error in `data`, so the runner classifies it as a local
|
|
engine's. The [messages reference](/reference/engine-protocol#messages)
|
|
lists every params and result shape. The manifest's JSON Schema ships as
|
|
`schema/engine-manifest-v1.schema.json` in the `e2e` package.
|
|
|
|
## Write a transport
|
|
|
|
Write a transport when a server needs setup first, such as an app installed
|
|
on a device and a port forwarded to it. `open` receives the target's app,
|
|
because a server elsewhere can't read the project's files. A `doctor`
|
|
connection, which `e2e doctor` opens, only checks: skip the install there.
|
|
|
|
```ts
|
|
import type { EngineTransport } from 'e2e/engine';
|
|
|
|
export function deviceTransport(serial: string): EngineTransport {
|
|
return {
|
|
label: `device ${serial}`,
|
|
async open(context) {
|
|
if (context.role !== 'doctor' && context.app?.appPath !== undefined) {
|
|
await install(serial, context.app.appPath);
|
|
}
|
|
const socket = await forward(serial, context.signal);
|
|
return { input: socket, output: socket, close: async () => void socket.destroy() };
|
|
},
|
|
};
|
|
}
|
|
```
|
|
|
|
## Next
|
|
|
|
<CardGroup cols={2}>
|
|
<Card title="Engine protocol" icon="book" href="/reference/engine-protocol">
|
|
Every function, message, and error code.
|
|
</Card>
|
|
<Card title="Writing an engine" icon="code" href="/writing-an-engine">
|
|
The members an engine implements, in TypeScript.
|
|
</Card>
|
|
</CardGroup>
|