Files
e2e/docs/engine-servers.mdx
Samanyu DasandClaude Opus 5.5 d960d2c448 fix(engine): wait for a crashed engine server's exit before its connection closes (#1863)
* 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>
2026-11-17 21:01:20 +00:00

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>