feat(docker): add docker engine integration

Lazy Docker Engine client on the local socket listing running containers with a per-call timeout; unit tests and e2e tests against a fake Engine socket and real containers.

e2e/tests/host/containers-real.spec.ts

@@ -0,0 +1,124 @@
+// SPDX-License-Identifier: GPL-2.0-or-later
+// Copyright (C) 2026 Bryan Joshua Pedini
+
+/**
+ * PLAN §12 core items 6, 7, 12 against the real Docker Engine: uniquely named, labelled alpine
+ * containers are started, stopped, restarted and removed, and GET /api/v1/containers (Playwright
+ * request and real curl) must reflect `docker ps` for exactly those containers. Assertions only
+ * look at the suite's own names/labels — the host runs unrelated containers.
+ */
+import {
+  test,
+  expect,
+  assertDbInvariants,
+  expectContainersResponse,
+  readOperations,
+  type HttpClient,
+  type RealDocker,
+  type ServerHandle,
+  type TestContainer,
+} from '../../harness';
+
+interface ApiContainer {
+  Id: string;
+  Names: string[];
+  Image: string;
+  Command: string;
+  Labels: Record<string, string>;
+  State: string;
+  Status: string;
+}
+
+/** Our containers in the API response, via Playwright and via curl (both must agree). */
+async function ownViaApi(http: HttpClient, server: ServerHandle, token: string, docker: RealDocker): Promise<Map<string, ApiContainer>> {
+  const pw = expectContainersResponse<ApiContainer>(await http.get(server.url(), { token }));
+  const cu = await http.curl({ url: server.url(), token });
+  expect(cu.exitCode).toBe(0);
+  const viaCurl = expectContainersResponse<ApiContainer>(cu);
+  const own = (list: ApiContainer[]) => list.filter((c) => c.Labels?.['dpsapi.e2e.test'] === docker.testKey);
+  const a = own(pw).map((c) => c.Id).sort();
+  const b = own(viaCurl).map((c) => c.Id).sort();
+  expect(b, 'curl and Playwright see the same containers').toEqual(a);
+  // never stopped containers, for anyone
+  expect(pw.filter((c) => c.State !== 'running').map((c) => c.Names), 'only running containers are listed').toEqual([]);
+  return new Map(own(pw).map((c) => [c.Id, c]));
+}
+
+async function expectApiMatchesDocker(http: HttpClient, server: ServerHandle, token: string, docker: RealDocker, expected: TestContainer[]): Promise<Map<string, ApiContainer>> {
+  const api = await ownViaApi(http, server, token, docker);
+  const running = (await docker.runningIds()).sort();
+  expect([...api.keys()].sort(), 'API equals docker ps for our label').toEqual(running);
+  expect([...api.keys()].sort(), 'API equals the expected set').toEqual(expected.map((c) => c.id).sort());
+  return api;
+}
+
+test('started, stopped, restarted and removed containers are reflected (Playwright request and curl)', async ({ cli, startServer, http, docker }) => {
+  test.setTimeout(120_000);
+  const token = await cli.tokenNew('real docker');
+  const [sleeper, looper, tailer] = await Promise.all([
+    docker.run({ suffix: 'sleeper', command: ['sleep', '3600'], labels: { 'com.example.role': 'sleeper', 'unicode.label': 'naïve ☃' } }),
+    docker.run({ suffix: 'looper', command: ['sh', '-c', 'trap "exit 0" TERM; while :; do sleep 1; done'], labels: { 'com.example.role': 'looper' }, env: { FOO: 'bar' } }),
+    docker.run({ suffix: 'tail.er_2', command: ['tail', '-f', '/dev/null'], labels: { 'empty.value': '' } }),
+  ]);
+  const server = await startServer({ docker: 'real', logLevel: 'DEBUG' });
+
+  const api = await expectApiMatchesDocker(http, server, token, docker, [sleeper, looper, tailer]);
+  for (const c of [sleeper, looper, tailer]) {
+    const got = api.get(c.id)!;
+    expect(got.Names).toEqual([`/${c.name}`]);
+    expect(got.Image).toBe('alpine:3.22');
+    expect(got.State).toBe('running');
+    expect(got.Status).toMatch(/^Up /);
+    for (const [k, v] of Object.entries(c.labels)) expect(got.Labels[k]).toBe(v);
+  }
+  expect(api.get(sleeper.id)!.Command).toContain('sleep 3600');
+  expect(api.get(tailer.id)!.Command).toContain('tail -f /dev/null');
+
+  await docker.stop(sleeper);
+  await expectApiMatchesDocker(http, server, token, docker, [looper, tailer]);
+  expect((await docker.listOwn()).find((c) => c.name === sleeper.name)!.state, 'stopped container still exists').toBe('exited');
+
+  await docker.remove(looper);
+  await expectApiMatchesDocker(http, server, token, docker, [tailer]);
+
+  await docker.start(sleeper);
+  await expectApiMatchesDocker(http, server, token, docker, [sleeper, tailer]);
+
+  await docker.remove(sleeper);
+  await docker.remove(tailer);
+  await expectApiMatchesDocker(http, server, token, docker, []);
+  expect(await docker.listOwn()).toEqual([]);
+
+  expect((await server.stop()).exitCode).toBe(0);
+  // 5 checkpoints × 2 clients
+  expect(readOperations(server.dbPath)).toHaveLength(10);
+  expect(server.logs().filter({ msg: 'docker request finished' }).every((r) => r.attrs.ok === 'true')).toBe(true);
+  assertDbInvariants(server.dbPath, { operationCount: 10 });
+});
+
+test('moderate real set: 15 containers with varied names, labels and commands', async ({ cli, startServer, http, docker }) => {
+  test.setTimeout(150_000);
+  const token = await cli.tokenNew();
+  const commands = [['sleep', '3600'], ['tail', '-f', '/dev/null'], ['sh', '-c', 'while :; do sleep 2; done'], ['top', '-b', '-d', '5']];
+  const set = await docker.runMany(15, (i) => ({
+    suffix: `m${String(i).padStart(2, '0')}${i % 3 === 0 ? '.dot' : i % 3 === 1 ? '_under' : '-dash'}`,
+    command: commands[i % commands.length],
+    labels: { 'com.example.index': String(i), [`com.example.k${i}`]: `v${i}` },
+  }));
+  const server = await startServer({ docker: 'real' });
+  const api = await expectApiMatchesDocker(http, server, token, docker, set);
+  for (const [i, c] of set.entries()) {
+    const got = api.get(c.id)!;
+    expect(got.Names).toEqual([`/${c.name}`]);
+    expect(got.Labels['com.example.index']).toBe(String(i));
+  }
+  // stop a third of them
+  const stopped = set.filter((_, i) => i % 3 === 0);
+  await Promise.all(stopped.map((c) => docker.stop(c, 1)));
+  await expectApiMatchesDocker(http, server, token, docker, set.filter((c) => !stopped.includes(c)));
+  // remove everything
+  await Promise.all(set.map((c) => docker.remove(c)));
+  await expectApiMatchesDocker(http, server, token, docker, []);
+  expect((await server.stop()).exitCode).toBe(0);
+  expect(readOperations(server.dbPath)).toHaveLength(6);
+});

e2e/tests/host/docker-backend.spec.ts

@@ -0,0 +1,177 @@
+// SPDX-License-Identifier: GPL-2.0-or-later
+// Copyright (C) 2026 Bryan Joshua Pedini
+
+/**
+ * PLAN §12 core item 12 and the Docker-socket matrix: empty / one / large container sets
+ * (FakeDocker), inaccessible / missing / failing / hanging Engine → 500 with a generic body and no
+ * internal details, recovery once the Engine recovers, and running-only (`docker ps`) semantics.
+ */
+import {
+  test,
+  expect,
+  assertDbInvariants,
+  expectContainersResponse,
+  expectErrorResponse,
+  expectNoInternalDetails,
+  makeContainerSummary,
+  pollUntil,
+  readOperations,
+  type ContainerSummary,
+} from '../../harness';
+
+test('no running containers → 200 with exactly []', async ({ cli, startServer, http }) => {
+  const tok = await cli.tokenNew();
+  const server = await startServer();
+  server.fakeDocker!.empty();
+  const pw = await http.get(server.url(), { token: tok });
+  expect(expectContainersResponse(pw)).toEqual([]);
+  expect(pw.body).toBe('[]');
+  expect(pw.headers['content-length']).toBe('2');
+  const c = await http.curl({ url: server.url(), token: tok });
+  expect(c.body).toBe('[]');
+  expect((await server.stop()).exitCode).toBe(0);
+  expect(readOperations(server.dbPath)).toHaveLength(2);
+});
+
+test('the Engine is asked for running containers only (GET /containers/json without all)', async ({ cli, startServer, http }) => {
+  const tok = await cli.tokenNew();
+  const server = await startServer();
+  expectContainersResponse(await http.get(server.url('/api/v1/containers?all=true'), { token: tok }));
+  expect((await server.stop()).exitCode).toBe(0);
+  const lists = server.fakeDocker!.requests.filter((r) => r.path === '/containers/json');
+  expect(lists).toHaveLength(1);
+  expect(lists[0].method).toBe('GET');
+  expect(new URLSearchParams(lists[0].query).get('all') ?? '0').toMatch(/^(0|false)$/);
+  expect(server.fakeDocker!.stats.other, 'no other Engine endpoints are called').toBe(0);
+});
+
+test('one container: Engine summary fields are passed through', async ({ cli, startServer, http }) => {
+  const tok = await cli.tokenNew();
+  const server = await startServer();
+  const c: ContainerSummary = makeContainerSummary(0, undefined, {
+    Names: ['/web-1'],
+    Image: 'nginx:1.29',
+    Command: 'nginx -g "daemon off;"',
+    Labels: { 'com.example.role': 'web', 'unicode.label': 'naïve ☃' },
+    Ports: [{ IP: '127.0.0.1', PrivatePort: 80, PublicPort: 8080, Type: 'tcp' }],
+    Status: 'Up 5 minutes',
+  });
+  server.fakeDocker!.setContainers([c]);
+  const [got] = expectContainersResponse(await http.get(server.url(), { token: tok }));
+  expect(got).toMatchObject({ Id: c.Id, Names: c.Names, Image: c.Image, ImageID: c.ImageID, Command: c.Command, Created: c.Created, Labels: c.Labels, State: 'running', Status: c.Status });
+  expect(got.Ports).toEqual([{ IP: '127.0.0.1', PrivatePort: 80, PublicPort: 8080, Type: 'tcp' }]);
+  expect((await server.stop()).exitCode).toBe(0);
+});
+
+test('large container set: 2000 summaries, complete and in order (Playwright and curl)', async ({ cli, startServer, http }) => {
+  const tok = await cli.tokenNew();
+  const server = await startServer();
+  server.fakeDocker!.many(2000);
+  const ids = server.fakeDocker!.containers.map((c) => c.Id);
+  const pw = expectContainersResponse<ContainerSummary>(await http.get(server.url(), { token: tok }));
+  expect(pw.map((c) => c.Id)).toEqual(ids);
+  expect(pw.every((c) => c.State === 'running')).toBe(true);
+  const cu = await http.curl({ url: server.url(), token: tok });
+  expect(expectContainersResponse<ContainerSummary>(cu).map((c) => c.Names[0])).toEqual(ids.map((_, i) => `/fake-${i}`));
+  expect(cu.bodyBuffer.length).toBeGreaterThan(500_000);
+  expect((await server.stop()).exitCode).toBe(0);
+  expect(readOperations(server.dbPath)).toHaveLength(2);
+});
+
+test('Engine failures → 500 with the generic body only; details stay in the ERROR log', async ({ cli, startServer, http }) => {
+  const tok = await cli.tokenNew();
+  const server = await startServer({ logLevel: 'INFO' });
+  const f = server.fakeDocker!;
+  const modes: Array<[string, () => void]> = [
+    ['500 with internal message', () => f.error500('boom: /var/lib/docker/overlay2 sqlite secret path')],
+    ['404 (API mismatch)', () => f.error(404, 'page not found')],
+    ['503', () => f.error(503, 'engine starting')],
+    ['connection dropped mid-request', () => f.destroy()],
+    ['malformed JSON', () => f.badJson('{"not":"an array"')],
+    ['JSON of the wrong shape', () => f.badJson('{"Id":"x"}')],
+    ['HTML instead of JSON', () => f.badJson('<html>proxy error</html>')],
+  ];
+  for (const [name, apply] of modes) {
+    await test.step(name, async () => {
+      apply();
+      const r = await http.get(server.url(), { token: tok });
+      expectErrorResponse(r, 500);
+      expectNoInternalDetails(r.body);
+      expect(Object.keys(r.headers).filter((h) => /^(api-version|docker|ostype|server)/i.test(h)), 'no Engine headers forwarded').toEqual([]);
+    });
+  }
+  f.many(3);
+  expect(expectContainersResponse(await http.get(server.url(), { token: tok }))).toHaveLength(3);
+  expect((await server.stop()).exitCode).toBe(0);
+  const errors = server.logs().filter({ level: 'ERROR' });
+  expect(errors.map((e) => e.msg)).toEqual(modes.map(() => 'docker request failed'));
+  expect(errors[0].attrs.error).toContain('boom');
+  expect(server.logs().requests().map((r) => r.attrs.status)).toEqual([...modes.map(() => '500'), '200']);
+  expect(readOperations(server.dbPath)).toHaveLength(modes.length + 1);
+  assertDbInvariants(server.dbPath);
+});
+
+test('socket inaccessible (EACCES) and missing (ENOENT): server starts, requests → 500, no details', async ({ cli, startServer, http }) => {
+  const tok = await cli.tokenNew();
+  for (const docker of ['inaccessible', 'missing'] as const) {
+    await test.step(docker, async () => {
+      const server = await startServer({ docker });
+      const r = await http.get(server.url(), { token: tok });
+      expectErrorResponse(r, 500);
+      expectNoInternalDetails(r.body);
+      const c = await http.curl({ url: server.url(), token: tok });
+      expectErrorResponse(c, 500);
+      expectErrorResponse(await http.get(server.url()), 401);
+      expect((await server.stop()).exitCode).toBe(0);
+      const err = server.logs().filter({ level: 'ERROR', msg: 'docker request failed' });
+      expect(err).toHaveLength(2);
+      expect(err[0].attrs.error).toMatch(docker === 'inaccessible' ? /permission denied/ : /no such file or directory/);
+    });
+  }
+});
+
+test('temporarily failing Engine: errors while failing, recovery afterwards', async ({ cli, startServer, http }) => {
+  const tok = await cli.tokenNew();
+  const server = await startServer();
+  const f = server.fakeDocker!.many(2).flaky(3);
+  const statuses: number[] = [];
+  for (let i = 0; i < 5; i++) statuses.push((await http.get(server.url(), { token: tok })).status);
+  expect(statuses).toEqual([500, 500, 500, 200, 200]);
+  // full outage then recovery
+  f.destroy();
+  expectErrorResponse(await http.get(server.url(), { token: tok }), 500);
+  f.many(1);
+  expect(expectContainersResponse(await http.get(server.url(), { token: tok }))).toHaveLength(1);
+  expect((await server.stop()).exitCode).toBe(0);
+  expect(readOperations(server.dbPath)).toHaveLength(7);
+});
+
+test('hung Engine: request bounded by the 10 s Docker timeout, server stays responsive, graceful shutdown waits for it', async ({ cli, startServer, http }) => {
+  test.setTimeout(90_000);
+  const tok = await cli.tokenNew();
+  const server = await startServer({ logLevel: 'DEBUG' });
+  const f = server.fakeDocker!.hang();
+  const t0 = performance.now();
+  const hung = http.get(server.url(), { token: tok, timeoutMs: 30_000 });
+  await pollUntil('the hung list call to reach the fake', () => (f.listCalls() >= 1 ? true : undefined));
+  // other requests are served meanwhile
+  const quick = await http.get(server.url('/elsewhere'));
+  expectErrorResponse(quick, 404);
+  expect(quick.durationMs).toBeLessThan(2000);
+  const r = await hung;
+  const elapsed = performance.now() - t0;
+  expectErrorResponse(r, 500);
+  expect(elapsed, 'bounded by the 10 s Engine timeout').toBeGreaterThan(9_500);
+  expect(elapsed).toBeLessThan(15_000);
+  expect(server.logs().find({ level: 'ERROR', msg: 'docker request failed' })!.attrs.error).toMatch(/context deadline exceeded|timeout/i);
+
+  // second hung request in flight while SIGTERM arrives: shutdown drains it and exits 0
+  const hung2 = http.get(server.url(), { token: tok, timeoutMs: 30_000 });
+  await pollUntil('second hung call', () => (f.listCalls() >= 2 ? true : undefined));
+  const stopping = server.stop('SIGTERM', { timeoutMs: 25_000 });
+  expectErrorResponse(await hung2, 500);
+  const exit = await stopping;
+  expect(exit.exitCode).toBe(0);
+  expect(server.logs().has({ msg: 'server stopped' })).toBe(true);
+  expect(readOperations(server.dbPath)).toHaveLength(2);
+});