Compare commits

..

72 Commits

Author SHA1 Message Date
Nathanaël HANNEBERT
1a6563decf fix(web): trust the new host key when reconfiguring a Docker engine
Changing the address (or port) of an engine to a host which presents another
SSH key gave a HOST_KEY_MISMATCH with both fingerprints and no way forward but
emptying the fingerprint field by hand. While editing an engine, the mismatch
alert now offers "I trust the new host key": it pins the presented key and
submits the current form again (the server still verifies that key on
connection). Not offered when creating an engine: a mismatch there is with the
fingerprint the user pasted on purpose.
2026-11-11 13:17:05 -07:00
Nathanaël HANNEBERT
cf6f18b433 fix(web): highlight only the selected row of the Containers tree
On a container host's Containers tab, the VM row of the site tree (an
ancestor route) and the host row (exact-active whatever the `?id=`) were
highlighted along with the selected row. Now:

- the host row is highlighted on its Containers tab, unless the selected
  container has its own row (host expanded and container listed)
- the VM row is not highlighted there when the VM has a container host row;
  it still is for a VM without an engine
- the sidebar reveals the selected container's row, else the host's, rather
  than the VM in the site tree

`useDockerHostRoute()` tells which host and container the page shows;
`isDockerHostRowActive()` is unit-tested.
2026-11-11 13:02:14 -07:00
Nathanaël HANNEBERT
4baccb916a feat(web): Containers in the tree view
A Containers branch after the site: the VMs running a Docker or Podman engine,
then their containers, listed (without stats) only for the expanded hosts, by
requests of at most 10 engines, as listing connects to the engines. The hosts
start collapsed the first time they appear. Hidden without engine, or when the
XOA plan does not include Docker.

The root leads to a new /containers page listing the container hosts (no SSH),
a host to the Containers tab of its VM, a container to its side panel there
(UiTreeItemLabel's active prop now decides alone when set: RouterLink ignores
the query).
2026-11-11 09:41:03 -07:00
Nathanaël HANNEBERT
910e9a520b refactor(web): split the navigation tree from the site tree definitions
useXoSiteTreeDefinitions() only defines the site tree, useNavigationTree()
owns the filter, the collapse state and the tree, so that other trees can be
added next to it. No change of behaviour.
2026-11-11 09:28:26 -07:00
Nathanaël HANNEBERT
9e23b86361 feat(docker): tell Podman engines from Docker
getEngineKind() reads the components and the platform of GET /version, the
connection records it at negotiation, the engine info and the engine record
expose it (the last known kind is saved, without bumping the revision, so that
it is shown while idle).
2026-11-11 09:22:52 -07:00
Nathanaël HANNEBERT
3afb4d7db6 fix(web): Docker module on top of the redesigned side panels
- VtsCopyButton: back to upstream's, which already sets `:aria-label="label"`
  (ours duplicated the attribute, breaking the SFC and many test files)
- DockerContainerSidePanel: UiPanelCardTitle (id, label, icon, size) instead
  of the removed VtsCardObjectTitle and of UiCardTitle, VtsCardRowList instead
  of the `.content` wrappers, `values` for the ports and volumes (per-value
  copy buttons, copy all, `-` when empty), small side panel link
- DockerContainerLogsCard: UiPanelCardTitle
- dates with `formatDateTime` (upstream dropped the vue-i18n datetime formats,
  `d(…, 'datetime_short')` rendered nothing)
- DockerContainerLogsCard test: no `d` from the test i18n helper, expected
  dates with `formatDateTime`, only the open button's accessible name asserted
  (the copy button's comes from its optional `label` upstream)
2026-11-11 08:47:32 -07:00
Nathanaël HANNEBERT
e06e88dc42 refactor(xo-server/docker): getDockerContainerScope() for the ACLs, without SSH
Returns { id, $engine, $VM, $pool } of a container from its engine record
only (noSuchObject on a malformed id or an unknown engine), typed in XoApp:
what a future ACL v2 getObject must use instead of getDockerContainer(), which
may connect. No change for ACL v1.
2026-10-09 12:01:10 +02:00
Nathanaël HANNEBERT
bb8d061f8a refactor(xo-server/docker): the model is the single source of the one-engine-per-VM rule
DockerEngines#assertNoEngineForVm(vm, ignored?) is the only implementation:
enforced by _beforeAdd()/_beforeUpdate() on every write, and called by the
mixin as a fast pre-check before connecting (create, update) and before
writing a config import, instead of its own copies.
2026-10-09 11:58:17 +02:00
Nathanaël HANNEBERT
b828ac2cc7 refactor(xo-server/docker): engine record logic as pure functions
Field lists, validateRecord(), applyProperties(), setHostKey(), newRevision()
and the validation of a config import (parseImportedEngines()) move from the
mixin to models/docker-engine-record.mjs, tested without app, redis or SSH.
2026-10-09 11:55:25 +02:00
Nathanaël HANNEBERT
a6d1e1f146 refactor(docker): stats samplers hold their pooled connection with pool.hold()
DockerConnectionPool#hold() returns the connection and an idempotent
release(error?) (use() is built on it): the stats sampler of the mixin keeps
one reference on its pooled connection until it stops, without hand-written
deferreds. An engine failure given to release() evicts the connection and is
negatively cached, as before.
2026-10-09 11:52:57 +02:00
Nathanaël HANNEBERT
28a61fa77e refactor(docker-ssh): container logs and raw passthrough requests
readContainerLogs() (logs request, TTY detection before API 1.42, demux,
size/entries caps, overall and idle timeouts) and rawRequest() (request and
response size limiters, whole-request timer, body cleanup on failure) move
from the xo-server mixin to docker-ssh, with unit tests. The mixin keeps the
parameter validation, the records, the 404 mapping and the pooled connection.
2026-10-09 11:50:30 +02:00
Nathanaël HANNEBERT
5300ad1e94 refactor(docker-ssh): one DockerConnection = one SSH session
A DockerConnection no longer reconnects underneath the pool when its SSH
session ends: it becomes closed (queued and in-flight requests fail with
CONNECTION_CLOSED, later ones are refused), notifies onClose(), and the pool
removes it. Only pool.use() opens a new connection, through the connection
factory (SSH cooldown) and the negative cache.

Removes the reconnection machinery (generation counter, closed clients set,
host key pinning across reconnections).
2026-10-09 11:46:03 +02:00
Nathanaël HANNEBERT
522f84381a fix(xo-server/docker): stale records, unknown VM, logs cap, daemon answers, samplers cap, host key
- a record read before an update or a delete never connects (old credentials)
  nor starts a stats sampler (deleted engine): the current revision of the
  engines written by this process is kept, a stale one is refused with
  CONNECTION_CLOSED
- create/update with a $VM which does not exist: noSuchObject, before
  connecting
- logs: at most `maxLogsTail` entries (lines over 64 KiB are split), the
  response is then cut (`truncated`)
- one failed inspection keeps the list entry instead of failing the list
- a malformed answer of the daemon (non-array container list, non-string
  Names…) is a DOCKER_API_ERROR, not a TypeError
- at most `docker.maxStatsEngines` (10, never more than half of
  `maxConnections`) live stats samplers, the containers of the other engines
  are listed without stats
- a whole `ssh-keygen -l` line is accepted as hostKeyFingerprint (its key type
  is used), the import normalizes it before validating and allow-lists
  hostKeyAlgorithm
- the host key is not in the key of the pooled connection: pinning an accepted
  unknown key no longer opens a second connection (other changes of the host
  key bump the revision)
- integration tests: API version is MAX_API_VERSION (1.44)
2026-10-09 11:39:00 +02:00
Nathanaël HANNEBERT
5085390086 feat(web-core): French translations of the Docker integration 2026-10-09 11:34:51 +02:00
Nathanaël HANNEBERT
93e4af1459 feat(web): Docker tab tells when the XOA plan does not include Docker
useDockerCapability is the single capability source of the module: a 403
featureUnauthorized when reading the engines shows a dedicated state instead
of the generic error. The tab stays visible for discovery.
2026-10-09 11:33:49 +02:00
Nathanaël HANNEBERT
f871c574a0 feat(web-core): remote resource HTTP errors carry the status and the body
`lastError.cause` is `{ status, body }`: e.g. a 403 featureUnauthorized can
be told apart from a generic failure.
2026-10-09 11:33:49 +02:00
Nathanaël HANNEBERT
1746ac3ea3 fix(web): accessible names and state of the Docker icon buttons and toggle
- aria-expanded on the "Advanced settings" toggle of the connection form
- the icon-only copy (VtsCopyButton) and open-in-new-tab (UiLogEntryViewer)
  buttons get an aria-label, without API change
2026-10-09 11:32:28 +02:00
Nathanaël HANNEBERT
881cabf0ac fix(web): Docker logs in local time without ANSI sequences, validated open-port URL
- log timestamps are formatted in local time with i18n, like the other dates
  (they were raw UTC)
- ANSI escape sequences (colors…) are stripped from the log messages
- the open-port URL is built with the URL setters: an invalid host offers no
  link instead of a broken one
2026-10-09 11:31:18 +02:00
Nathanaël HANNEBERT
f75996f8bc test(rest-api): Docker engine create/update with an unknown VM is a 404 2026-10-09 11:29:25 +02:00
Nathanaël HANNEBERT
e3bb023ffd fix(web-core): UiLogEntryViewer auto-scroll follows only from the bottom
The user scrolling up to read the logs is no longer brought back to the
bottom on each update: whether to follow is decided before the content
changes.
2026-10-09 11:29:18 +02:00
Nathanaël HANNEBERT
1a63541fd2 fix(rest-api): Docker raw route OpenAPI entry in tsoa.json, more tests
- the hand-written /docker-engines/{id}/_raw/{path} operations (x-mcp-exposure
  deny) are in the static spec (tsoa.json, like /docs/swagger.json): only the
  auto-inserted wildcard path is removed at runtime
- description: admin-only, ACL v2 will add an acl check in addition to the
  admin check (it said "no ACL, even in v2")
- tests through the real external router (non-admin: 403 even with
  allowRawApi on, the static spec entry), the upstream signal aborted when
  the client disconnects mid-stream, 415 when the body was already consumed
2026-10-09 11:29:07 +02:00
Nathanaël HANNEBERT
30bf6d8fc0 fix(docker-ssh): exec timeout, HTTP-level errors, response cap, ssh-keygen lines
- exec(): the channel opening is abortable too (a server never answering it
  hung forever), a channel opened after the abort is destroyed, stdin is ended
- dockerd closing a channel or answering garbage (ECONNRESET, EPIPE, socket
  hang up, HPE_*) is a DOCKER_API_ERROR, not an SSH failure evicting the
  pooled connection (HPE_* errors have a string `reason`, they were taken for
  channel open failures)
- request(): responses are capped at 8 MiB by default, `maxSize` allows more
- parseFingerprint(): accepts a whole `ssh-keygen -l` line and takes the host
  key type from it, HOST_KEY_TYPES lists the expectable ones
- HOST_KEY_MISMATCH mentions the presented algorithm
2026-10-09 11:27:59 +02:00
Nathanaël HANNEBERT
522001551d refactor(rest-api): DOCKER feature check as a class-level middleware
Replaces the per-route assertDockerFeature() calls: it runs before every
handler of the Docker controllers and before their route middlewares (body
parsing, the future acl ones), so a new route cannot forget it. The raw
route keeps its own order (501, admin, feature, engine).
2026-10-09 11:27:49 +02:00
Nathanaël HANNEBERT
49c0a8afe8 fix(web): Docker engine card shows every connection failure
- the engine record's connectionStatus/error are read again: a pooled
  connection in error (e.g. the container list failed) shows the danger alert
  and the table error state instead of "No container detected"
- a failing /info no longer hides the engine card (Configure, Forget): inline
  error alert instead of a page-level error
- a failure to forget the engine is shown instead of only logged
2026-10-09 11:27:35 +02:00
Nathanaël HANNEBERT
462b06c225 fix(rest-api): Docker container scope with complex-matcher's semantics
The engine scope compared exact values while the filter itself matches
case-insensitive substrings: `filter=$VM:c7b3b4bc` silently returned [].
The scoping term is now evaluated by complex-matcher on the scope properties
of each engine ($engine, $VM, $pool), still restricted to values and
disjunctions of values, and still capped by docker.maxListedEngines.
2026-10-09 11:26:31 +02:00
Nathanaël HANNEBERT
9098a9c183 fix(rest-api): Docker container actions 404 before creating a task
Only the id and the engine were checked: an unknown container of a known
engine created a task which failed. The container is now resolved first
(getObject, served from the listing cache when possible).
2026-10-09 11:26:01 +02:00
Nathanaël HANNEBERT
b83569a6d2 fix(web): Docker connection form secrets and host key handling
- passphrase: autocomplete=new-password and not trimmed, username with a
  distinct name: the browser no longer autofills the XO login password
- trusting the host key rebuilds the request from the current form
- the request (with the secrets) is dropped once the save settles, the
  secrets are cleared on unmount
- an emptied fingerprint sends hostKeyFingerprint: null to unpin the host key
2026-10-09 11:25:54 +02:00
Nathanaël HANNEBERT
e447ffa725 fix(rest-api): no Docker connection context in failed task records
The ApiError mapped from a DockerError kept the raw error as `cause`, which
`@vates/task` serializes (with host/port/socketPath) into the record readable
with task:read, while its status and data are private fields. It now has no
cause and a toJSON() giving what the client gets: { code, message, … }.

The controller tests now record failures like the real Tasks mixin
(serializeError() unless toJSON()) and check the serialized records: the
previous assertions checked an unused `task.error`.
2026-10-09 11:25:42 +02:00
Nathanaël HANNEBERT
c037b9a2ec fix(rest-api): Docker engine create/update/delete and container removal without tasks
Their task records (engine connection parameters, the raw DockerError with
host/port/socketPath on failure) were readable by any user with task:read,
which the built-in Read only role grants, bypassing the v1 admin-only rule.

Plain synchronous calls like servers/: 201 { id } / 204, the errors (e.g.
the TOFU 409) are the HTTP answer, mapped by the generic error handler.
obfuscateDockerEngineParams() is no longer used.
2026-10-09 11:24:37 +02:00
Nathanaël HANNEBERT
a6288fef97 fix(web-core): remote resource leaves the error state after a successful fetch
lastError was never cleared: hasError stuck until the cache entry died, e.g.
the Docker tab stayed on its full-page error.
2026-10-09 11:23:41 +02:00
Nathanaël HANNEBERT
eb302273e5 fix(docker-ssh): API 1.44 and negotiate the daemon's MinAPIVersion
Docker 29 refuses API versions older than 1.44 by default: 1.44 (Docker 25)
becomes the max version, and a daemon whose oldest supported version is newer
than it is used with that version (with a warning) instead of failing.
2026-10-09 11:23:31 +02:00
Nathanaël HANNEBERT
6c40bd0f71 refactor(rest-api): simplify Docker controllers
- map DockerErrors centrally in generic-error-handler (toDockerApiError at
  the top), per docs/guidelines.md; drop the per-call mapping of the
  non-task routes (info, container get/stats/logs, scoped listing) and the
  mapping-only try/catch of the raw passthrough (its cleanup is kept)
- keep withDockerErrors only inside createAction callbacks: task records
  store the error as thrown, before the generic handler, so they keep the
  scrubbed ApiError (no connection context)
- remove the pass-through DockerEngineService and its ioc binding:
  controllers call restApi.xoApp directly; the DOCKER feature check is the
  shared assertDockerFeature() helper
- DockerContainerService: inline the pass-throughs (getContainer, getStats,
  runAction, delete), keep the scoped listing, id check and logs dates
- docker-container.controller: 503 declared once at class level (also
  documents it on DELETE, which uses the same connection pool)
- inline #withEngine (single caller)
- getClientData: Object.fromEntries/filter
- delete DockerContainerList, DockerEngineId, POOL_EXHAUSTED_RETRY_AFTER,
  the undefined guard of obfuscateDockerEngineParams; unexport file-local
  symbols (INBOUND_HEADERS, OUTBOUND_HEADERS, dockerRawRoutes,
  DockerErrorLike, isDockerError, DOCKER_ERRORS_HEADER)
- tests: controllers built without the removed service; the POOL_EXHAUSTED
  test passes the raw DockerError to the generic handler
2026-09-29 12:39:57 +02:00
Nathanaël HANNEBERT
9d3bd23296 refactor(docker-ssh): simplify
No behaviour change:
- connection: one capped body reader (`readBody(response, maxSize)`
  returning `{ buffer, truncated }`) for both success and error bodies,
  the request throws the same "too large" error when truncated
- connection: drop the dead success-path reset of the pending negotiation
  (`#apiVersion` is set on success and checked first)
- connection: drop a redundant `clearTimeout()` (the `finally` clears it)
- ssh-http-agent: `connectTimeout` is required, its only caller always
  passes it
- pool: `clearFailure()` and the stale failures pruning share one
  `#deleteFailures()` helper
- normalize: drop the test-only `CONTAINER_STATES` export
- stats-sampler: drop the test-only `has()`, tests use `get()`
- ttl-cache: drop the test-only `delete()`, tests use `deleteByPrefix()`
- xo-server/docker: `IDENTITY_FIELDS` derived from `CONNECTION_FIELDS`,
  `setHostKey()` and `#setVmAndPool()` helpers replace duplicated
  blocks, `#newConnection()` inlined into its single caller
2026-09-29 12:38:59 +02:00
Nathanaël HANNEBERT
588ee7c9b5 refactor(web): simplify the Docker module 2026-09-29 12:38:44 +02:00
Nathanaël HANNEBERT
32b0dd8eba refactor(web-core): code column without maxWidth option 2026-09-29 12:38:44 +02:00
Nathanaël HANNEBERT
640b82b14e docs(docker-ssh): why AsyncTtlCache is not lru-cache
lru-cache's fetch() matches the rest of the semantics (shared pending fetch,
rejections not cached, nothing cached after a delete with ignoreFetchAbort),
but its keys() skips pending fetches: deleteByPrefix() could not drop them, and
a container list fetched with an engine's previous credentials would be cached
after the change (the race fixed in review 2). Checked with lru-cache 11.5.
2026-09-28 14:07:33 +02:00
Nathanaël HANNEBERT
8e29220966 refactor(docker-ssh): Docker wire types from the official OpenAPI specs
The wire types were hand-copied subsets of the Docker Engine API. They are now
picked from types generated from Docker's published specifications
(`src/docker-api.gen.mts`, `yarn generate-api-types`): API 1.43
(MAX_API_VERSION), and API 1.48 for the stats, the first spec documenting
them (as a plain `object` before, same field names).

- `wire.mts` picks the fields read and keeps their required-ness; the
  departures from the spec are commented (`null` sent by the daemon for
  empty lists and unpublished ports, the container list `State` narrowed to
  the spec's state enum, `os_type` in the stats)
- the stats keep `unknown` values (hostile daemon), their keys now come from
  the spec with no index signature: reading an undocumented key fails to
  compile
- `WithRequired` is an intersection: `Omit` loses the properties of types
  with an index signature
- the generated file is marked `linguist-generated`; no runtime change, the
  208 tests pass
2026-09-28 14:05:59 +02:00
Nathanaël HANNEBERT
2bbca2e868 docs(docker-ssh): README, and drop unrelated yarn.lock churn
The README is generated from .USAGE.md (scripts/usage-to-readme.js), its
example was run against a real sshd + dockerd.

yarn.lock: only the @types/ssh2 entries remain; yarn had also re-split the
string-width/strip-ansi/wrap-ansi aliases, which is unrelated (the lockfile
without it passes `yarn install --frozen-lockfile`).
2026-09-28 12:22:20 +02:00
Nathanaël HANNEBERT
d130c8b88a chore(xo-server/docker): type-check the Docker mixin and model
`// @ts-check` on `xo-mixins/docker.mjs` and `models/docker-engine.mjs`
(which stay `.mjs`, built by Babel), like `xo-mixins/acls-v2/index.mjs`:

- typedefs of the `@vates/types` DTOs and of the `@xen-orchestra/docker-ssh`
  types, and `DockerEngineRecord` (the stored engine) in the model
- the public methods return the `@vates/types` types, and the class
  `@implements` their signatures in `XoApp` (`@vates/types/src/xo-app.mts`),
  so the mixin can no longer drift from them
- narrow JSDoc casts where the values come from untyped code: the Docker API
  bodies (`unknown`), `Collection#get()`, the TTL cache
- no runtime change (a few intermediate variables for the casts)

Check, from packages/xo-server, once the declarations of `@vates/types` and
`@xen-orchestra/docker-ssh` are built (0 errors):

node -e "const ts=require('typescript'),f=['src/xo-mixins/docker.mjs','src/models/docker-engine.mjs'],p=ts.createProgram(f,{noEmit:true,allowJs:true,checkJs:true,skipLibCheck:true,target:ts.ScriptTarget.ES2022,module:ts.ModuleKind.NodeNext,moduleResolution:ts.ModuleResolutionKind.NodeNext,types:['node'],experimentalDecorators:true}),d=f.flatMap(n=>{const s=p.getSourceFile(n);return[...p.getSyntacticDiagnostics(s),...p.getSemanticDiagnostics(s)]});console.log(ts.formatDiagnostics(d,{getCanonicalFileName:n=>n,getCurrentDirectory:ts.sys.getCurrentDirectory,getNewLine:()=>'\\n'})+d.length+' errors');process.exitCode=d.length?1:0"

Plain `tsc --allowJs --checkJs` on these files cannot be used: the untyped
legacy modules they import (`collection/redis.mjs`, `utils.mjs`) use Babel's
`::` operator, tsc reports these syntax errors and then skips the type
checking. The command above reports the diagnostics of the two files only, like
an editor does.
2026-09-28 12:19:55 +02:00
Nathanaël HANNEBERT
b1cf44e109 refactor(docker-ssh): move the Docker transport into a TypeScript package
`packages/xo-server/src/_docker/` has no XO concepts: it becomes
`@xen-orchestra/docker-ssh`, a strict TypeScript package built like
`@xen-orchestra/disk-transform` and `@vates/iscsi` (`tsc` to `dist/*.mjs`,
`node --test "dist/**/*.test.mjs"`). This is a port, not a rewrite: the
runtime code is the same (compared after compilation), the comments, test
names and assertions are kept.

- every module, test, integration test and fixture is now `.mts`, and
  `src/index.mts` exports what xo-server uses
- `src/wire.mts`: Docker Engine API wire shapes (version, info, container
  list entry, inspect, stats sample), internal to the package; the stats
  values are `unknown` (hostile daemon), the fixtures are checked against
  these types
- the normalizers return the `@vates/types` DTOs (`XoDockerContainer` without
  its XO fields, `XoDockerContainerStats`, `XoDockerEngineInfoConnected`
  without its XO fields, `XoDockerLogEntry`); `@vates/types` is unchanged
- zero `any`; Node/ssh2 internals go through minimal typed shims (`SshClient`
  with ssh2's private `_sock`, `DecoratedStream`), plus one
  `@ts-expect-error` for `http.Agent#removeSocket()` (internal to Node,
  missing from @types/node) and one in the stdcopy tests (no `pipeline()`
  overload for a rest argument)
- tests: only syntax and types changed; the fakes of the pool and connection
  tests get stubs of the members they do not implement (`exec`,
  `requestStream`…) to satisfy the connection interfaces
- `ssh2` stays in xo-server (used by `ssh-cli.mjs`), and is added to the
  package with `@types/ssh2`

xo-server imports the transport from `@xen-orchestra/docker-ssh`.
2026-09-28 12:13:26 +02:00
Nathanaël HANNEBERT
8d7c41b0ab refactor(web): Docker module reuses existing helpers
- errors: read ApiError instead of guessing the error shape; the host key
  mismatch data needs both expected and actual fingerprints
- SSH addresses: validated IPv4 only, with isIpv6 from web-core
- monospace: rely on base.pcss for <code>, VtsCodeSnippet for the socket
  path and the host key fingerprint of the engine card
- VmOfflineHero: the halted VM hero shared by the VM dashboard and the
  Containers tab (same rendering and i18n keys)
- connection form: two-column grid instead of empty spacers
- dead code: getDockerStatus, DOCKER_STATUS.NOT_CONFIGURED, unused returns
  of the delete composable
- casts: the save request and the job identity narrow the discriminated
  union; the stop modal policy is 'always' | 'unless-stopped'
- i18n: capitalized health statuses, modal:confirm-docker-container-stop?
2026-09-28 11:58:06 +02:00
Nathanaël HANNEBERT
abfa163afb refactor(web-core): drop the unused copy option of the code column 2026-09-28 11:58:06 +02:00
Nathanaël HANNEBERT
8914dd96d3 fix(web): Docker tab no longer relies on web-core internals
- the logs card follows the tail with UiLogEntryViewer's autoScroll instead
  of querying its inner <code>
- the private key textarea drops its :deep(.textarea) override: UiTextarea
  forwards class to the native <textarea>, so the rule never matched
- the summary card keeps its :deep(.values) recolor until UiCardNumbers gets
  an accent, marked TODO(design-system)
2026-09-28 11:50:35 +02:00
Nathanaël HANNEBERT
3c2ddd1755 feat(web-core): UiLogEntryViewer can keep the latest lines in view
Add an optional `autoScroll` prop: when set, the code block scrolls to its
bottom each time the content changes, like `tail -f`. Behaviour only, no
style variant, so existing usages are unchanged.
2026-09-28 11:50:35 +02:00
Nathanaël HANNEBERT
145533b850 test(xo-server/docker): rootless assertion follows XO_DOCKER_TEST_ROOTLESS
The mixin suite asserted a rootless daemon, so it failed against a regular
dockerd. XO_DOCKER_TEST_ROOTLESS=0 now expects a rootful one.
2026-09-28 11:43:35 +02:00
Nathanaël Hannebert
a912f52803 docs(docker): Docker containers page and changelog 2026-09-25 02:41:17 +00:00
Nathanaël Hannebert
7d30f5b75f fix(rest-api): Docker error data, status allowlist, raw hijack and compression
- DOCKER_API_ERROR: only code, statusCode and a truncated message are sent,
  the connection context (host, port, socketPath, path) is only logged
- only 400, 404 and 409 from dockerd are passed through, other 4xx are 502
  (never a 401/407/403 from the daemon), also for the raw passthrough's 401/407
- raw: attach/exec start refused for names containing /
- raw: Cache-Control: no-transform so that compression does not buffer streams
2026-09-25 02:35:20 +00:00
Nathanaël Hannebert
f6685ad05c fix(xo-server/docker): bound hostile daemon input, raw request lifetime
- stats sampler: only the latest complete line of a chunk is parsed, at most
  once per second per stream, the buffer is checked against the cap before
  scanning
- stats: only finite numbers are accepted (no string concatenation, NaN,
  Infinity or overflow)
- error bodies: read at most 4 KiB, message truncated
- raw requests: body piped only once connected (unpiped on failure),
  docker.rawRequestTimeout (default 5 min) for the whole response
2026-09-25 02:35:01 +00:00
Nathanaël Hannebert
f6f0820853 fix(web): Docker side panel command row, logs follow the tail 2026-09-25 02:34:34 +00:00
Nathanaël Hannebert
a2c9daeb10 feat(web): Docker containers table, side panel, logs and actions
Column set with the new stacked-text and code columns, stats (stats=true),
side panel with the details and the logs, lifecycle and delete jobs (sync),
stop confirmation for restart policies, SSH cooldown messages, engine test.
2026-09-25 02:23:16 +00:00
Nathanaël Hannebert
158975ed99 docs(rest-api): real Docker container stats example 2026-09-25 01:27:40 +00:00
Nathanaël Hannebert
a6344a4c3e feat(rest-api): Docker container stats and raw passthrough 2026-09-25 01:25:02 +00:00
Nathanaël Hannebert
1ef7d651e0 feat(xo-server/docker): stats sampler and raw requests (steps 8 and 10) 2026-09-25 01:24:46 +00:00
Nathanaël Hannebert
191dc72d18 feat(@vates/types): Docker container stats and raw passthrough 2026-09-25 01:24:33 +00:00
Nathanaël Hannebert
dc2232d590 fix(web): Docker connection form polish 2026-09-25 01:12:18 +00:00
Nathanaël Hannebert
77ecba566e docs(rest-api): Docker OpenAPI examples after the review fixes
Regenerated from a new end-to-end run: plain arrays for GET
/docker-containers, logs with timedOut. The xo-nginx logs integration test
tolerates a restarted container.
2026-09-24 21:31:17 +00:00
Nathanaël Hannebert
e3eed972a2 fix(web): Docker job args types 2026-09-24 21:30:38 +00:00
Nathanaël Hannebert
0d70b3ed07 test(web): DockerTab status branches 2026-09-24 21:27:38 +00:00
Nathanaël Hannebert
915568bd9a test(web): Docker connection form 2026-09-24 21:08:45 +00:00
Nathanaël Hannebert
0bdd147b86 fix(rest-api): Docker containers as a plain array, SSH cooldown
- GET /docker-containers returns a plain array through sendObjects, like
  every collection (fields, limit, ndjson and markdown behave as usual); the
  engines which failed are reported in the x-docker-errors header (JSON array
  of { engine, code }, only when non-empty); asOf dropped; ?force_refresh
- SSH_COOLDOWN → 429 with Retry-After from data.retryAfter,
  SSH_REFUSED_PENALTY → 502
- PATCH /docker-engines/{id} documents that an identity change connects first
  and saves nothing on failure, with the errors of the creation
- XoDockerLogs.timedOut
2026-09-24 21:08:18 +00:00
Nathanaël Hannebert
12f68ef7f8 feat(web): VM Containers tab (WIP) 2026-09-24 21:08:11 +00:00
Nathanaël Hannebert
620fb0890d fix(xo-server/docker): serialize engine mutations, bound logs, SSH cooldown
- per-engine and per-VM in-process mutexes (decorator-synchronized) around
  create, update, delete, host key pinning and config import; the model
  serializes its writes and an update never re-creates a removed engine
- unique random revisions; pooled connections and caches are keyed on an HMAC
  of the connection parameters, so a stale record never reuses a connection
- an update changing the connection parameters connects first (with the new
  or stored pin) and is only saved on success
- logs: overall deadline (logsTimeout) and idle timer (logsIdleTimeout),
  partial result with truncated and timedOut, pool slot released
- authFailureCooldown against OpenSSH PerSourcePenalties (SSH_COOLDOWN), and
  SSH_REFUSED_PENALTY for a handshake lost soon after failures
- config import validated before writing, under the locks
- systemErr payload capped at 64 KiB, clearing the private key clears the
  passphrase, stale pool failures pruned, socket probe without `!`
2026-09-24 20:19:38 +00:00
Nathanaël Hannebert
ab38e9ff9b feat(rest-api): Docker containers
`/rest/v0/docker-containers`:

- scoped listing: `filter` must contain an equality term on `$engine`,
  `$VM` or `$pool` designating at most `docker.maxListedEngines`
  engines (422 otherwise, before any SSH connection), then the whole filter
  is applied. The JSON response is `{ containers, errors, asOf }`: an engine
  which fails is reported in `errors` instead of failing the request
- `GET {id}`, `GET {id}/logs` (bounded, not exposed to MCP)
- `POST {id}/actions/{start,stop,restart,pause,unpause}` and `DELETE {id}`
  (`force`, `removeVolumes`), as tasks
- `stats=true` is refused (422) until the stats sampler exists
2026-09-24 19:13:44 +00:00
Nathanaël Hannebert
548ede5afa feat(rest-api): Docker engines
`/rest/v0/docker-engines`: list, get (never connect, never any secret),
create (connects first, TOFU: 409 HOST_KEY_UNKNOWN with the observed
fingerprint, to send back as `hostKeyFingerprint`), PATCH, DELETE,
`GET {id}/info` (always 200 with a `status` discriminator) and
`POST {id}/actions/test`.

- administrators only for now (no ACL middleware), `// ACLs v2:` comments
  give the middlewares of the `docker-engine` resource
- every route checks the `DOCKER` feature first
- the DockerErrors of xo-server are mapped to HTTP statuses: 409 for the
  host key, 502 for SSH/socket failures (never 401), 504 for timeouts, 503
  + Retry-After when the connection pool is exhausted, Docker API client
  errors passed through
- the mutations are tasks, with the secrets obfuscated in their params
- `ApiError` can carry response headers
2026-09-24 19:13:17 +00:00
Nathanaël Hannebert
b4c95eaf18 feat(xo-server/docker): container actions and removal
`runDockerContainerAction(id, action)` (start, stop, restart, pause,
unpause) and `deleteDockerContainer(id, { force, removeVolumes })`, for
the REST API. Both evict the cached container lists of the engine.

Starting a running container or stopping a stopped one is a no-op (Docker
answers 304), other invalid transitions are Docker API errors (e.g. 409).
2026-09-24 19:12:42 +00:00
Nathanaël Hannebert
c96dd62e01 feat(@vates/types): Docker engines and containers
- `XoDockerEngine` and `XoDockerContainer` records, in `NonXapiXoRecord`
- their DTOs in `lib/xen-orchestra-docker.mts` (ports, compose, info, logs,
  stats, test result…)
- the `XoApp` methods of xo-server's Docker mixin
- `XoVm['docker']` (legacy xscontainer) is deprecated
2026-09-24 19:12:27 +00:00
Nathanaël Hannebert
22448c94af feat(@vates/obfuscate): obfuscate private keys
`privateKey`, `private_key`, `sshPrivateKey`… params are now considered
sensitive, like passwords.
2026-09-24 19:01:31 +00:00
Nathanaël Hannebert
a3a9cf898a feat(xo-server/docker): engines collection and mixin (steps 3 and 5)
- `models/docker-engine.mjs`: redis collection `dockerEngine`, random uuid
  ids, `indexes: ['vm']`, whole-record encryption via `cryptoCredentials`,
  one engine per VM (`objectAlreadyExists` → 409) on add and on update.
- `xo-mixins/docker.mjs`:
  - engines CRUD: `getAllDockerEngines`, `getDockerEngine`,
    `createDockerEngine` (connects first, TOFU: `HOST_KEY_UNKNOWN` with the
    observed fingerprint and nothing saved, or `acceptUnknownHostKey` pins
    it), `updateDockerEngine` (PATCH: omitted secrets kept, `null`/`''`
    clear, connection changes bump the revision), `deleteDockerEngine`,
    `testDockerEngine` (with a socket probe telling apart a missing socket,
    a permission problem and disabled forwarding)
  - records are sanitized from an allowlist: no secrets, `hasPassword`,
    `hasPrivateKey`, `$VM`, `$pool` (when the VM is known), `resolvedHost`
    and the passive `connectionStatus`/`error` of the pool
  - read-only methods through the pool: `getDockerEngineInfo` (status
    discriminator, never throws for connection problems),
    `getDockerContainers` (list + bounded inspection of running containers,
    composite ids `<engineId>_<dockerId>`, per-engine TTL cache, partial
    results), `getDockerContainer`, `getDockerContainerLogs` (bounded tail
    and size, demuxed)
- `config.toml`: `[docker]` block.
- `authorization.mjs`: `DOCKER` feature code is also for the new REST
  services.

The secrets are stored in plain text unless
`redis.encryptCredentialDatabase` is enabled, like XenServer credentials.
2026-09-24 18:46:21 +00:00
Nathanaël Hannebert
4310594842 feat(xo-server/docker): connection pool (step 4)
- `_docker/pool.mjs`: `DockerConnectionPool`, keyed by engine id + revision,
  one shared handshake for concurrent first uses, idle GC by one shared
  unref'd sweeper, `maxConnections` cap with LRU eviction of idle connections
  (`POOL_EXHAUSTED` when all are busy), negative cache (fail fast for
  `failureTtl`, last error exposed passively by `getState()`), invalidation
  and `destroy()`. Pooled connections are handed out through a facade which
  refuses requests once the pool closed them, so no untracked reconnection
  can happen.
- `_docker/ttl-cache.mjs`: small async TTL cache (in-flight dedupe, no
  caching of rejections, prefix eviction, sweep).
- `DockerConnection#exec()`: run a command in an SSH session channel, used
  by the Docker socket probe.
2026-09-24 18:46:04 +00:00
Nathanaël Hannebert
c2ca305fc5 feat(xo-server/docker): logs demuxing and DTO normalization (step 2)
- `stdcopy.mjs`: `createStdcopyDemuxer()` (8-byte frames split across any
  chunk boundary, raw/TTY mode, truncated trailing frame, systemErr frames),
  `createLogLineParser()` (per-stream line splitting, leading RFC3339Nano
  timestamp, UTF-8 safe, bounded line length) and `isMultiplexedStream()`
  (Content-Type, falling back to `Config.Tty` before API 1.42)
- `normalize.mjs`: container list entries and inspect data (ports with the
  0.0.0.0/:: dedupe, Compose labels, exit code and health from `Status`,
  restart policy, mounts, networks; never the environment), stats (CPU% like
  `docker stats`, `null` instead of Infinity/NaN, memory without inactive
  file pages on cgroup v1 and v2) and engine info
- `fixtures/`: real payloads from Docker 29.8.1 at API 1.43, scrubbed

Integration tests read real logs (non-TTY and TTY) and stats (`stream=false`
and `stream=true`) through `DockerConnection.requestStream()`.
2026-09-24 17:08:05 +00:00
Nathanaël Hannebert
d1091b5df1 fix(xo-server/docker): harden transport after review
- never reuse keep-alive channels closed by an SSH connection loss: ssh2
  leaves them writable, so `http.Agent` kept them in its free list and
  requests sent on them never completed
- make the agent forget destroyed channels (ssh2 emits no `close` once the
  connection is lost) and settle/release requests on abort even when the
  channel never emits anything, so limiter slots cannot leak
- close(): destroy the TCP socket when the server does not close the
  connection in time, reject queued requests and report the interrupted
  ones with the new CONNECTION_CLOSED code, never reconnect for them
- pin the host key (and its type) accepted on the first connection for the
  lifetime of the instance, including with `acceptUnknownHostKey`
- new `hostKeyAlgorithm` option restricting `serverHostKey`
- the caller signal interrupts a pending API version negotiation
- abort while reading an error body is reported as TIMEOUT
- `hostKeyFingerprint: null` is treated as missing (HOST_KEY_UNKNOWN)
2026-09-24 16:24:59 +00:00
Nathanaël Hannebert
8e16763df4 feat(xo-server/docker): SSH → docker.sock transport (phase 0)
Internal building blocks to talk to a Docker Engine through SSH, using
`direct-streamlocal@openssh.com` channels multiplexed on a single ssh2
connection:

- `errors.mjs`: `DockerError` with stable codes, mapping of ssh2 errors,
  credentials scrubbing
- `ssh-http-agent.mjs`: `http.Agent` opening a channel to the remote Unix
  socket for each HTTP socket (keep-alive)
- `connection.mjs`: `DockerConnection` with host key pinning (OpenSSH
  `SHA256:` fingerprints), API version negotiation, AbortSignal-based
  timeouts and a bounded request concurrency

Not wired anywhere yet (no mixin, API or UI).

Integration tests against a real SSH server + dockerd are skipped unless
`XO_DOCKER_TEST_SSH_HOST` (and related variables) are set.
2026-09-24 16:24:59 +00:00
481 changed files with 30920 additions and 8847 deletions

View File

@@ -37,7 +37,7 @@ exports.merge = merge
const obfuscate = value => replace(value, OBFUSCATED_VALUE)
exports.obfuscate = obfuscate
const SENSITIVE_PARAMS = ['token', 'passphrase', /password/i, 'encryptionKey']
const SENSITIVE_PARAMS = ['token', 'passphrase', /password/i, /private_?key/i, 'encryptionKey']
const isSensitiveParam = name =>
SENSITIVE_PARAMS.some(pattern => (typeof pattern === 'string' ? pattern === name : pattern.test(name)))

View File

@@ -0,0 +1,57 @@
'use strict'
const { describe, it } = require('node:test')
const assert = require('assert').strict
const { merge, obfuscate, OBFUSCATED_VALUE, replace } = require('./')
describe('replace()', () => {
it('replaces the sensitive string params, recursively', () => {
assert.deepEqual(
replace(
{
host: 'example.org',
password: 'secret',
adminPassword: 'secret',
passphrase: 'secret',
token: 'secret',
encryptionKey: 'secret',
privateKey: 'secret',
private_key: 'secret',
sshPrivateKey: 'secret',
nested: [{ privatekey: 'secret', username: 'root' }],
},
'X'
),
{
host: 'example.org',
password: 'X',
adminPassword: 'X',
passphrase: 'X',
token: 'X',
encryptionKey: 'X',
privateKey: 'X',
private_key: 'X',
sshPrivateKey: 'X',
nested: [{ privatekey: 'X', username: 'root' }],
}
)
})
it('keeps non string values', () => {
assert.deepEqual(replace({ password: null, privateKey: undefined, token: 42 }, 'X'), {
password: null,
privateKey: undefined,
token: 42,
})
})
})
describe('obfuscate() and merge()', () => {
it('merge() restores the obfuscated values', () => {
const value = { username: 'root', privateKey: 'secret' }
const obfuscated = obfuscate(value)
assert.deepEqual(obfuscated, { username: 'root', privateKey: OBFUSCATED_VALUE })
assert.deepEqual(merge({ ...obfuscated, username: 'admin' }, value), { username: 'admin', privateKey: 'secret' })
})
})

View File

@@ -18,6 +18,7 @@
"node": ">=8.10"
},
"scripts": {
"postversion": "npm publish --access public"
"postversion": "npm publish --access public",
"test": "node --test"
}
}

View File

@@ -6,6 +6,7 @@ export * from './lib/xen-orchestra-xapi.mjs'
export * from './lib/xen-orchestra-acl.mjs'
export * from './lib/xen-orchestra-plugins.mjs'
export * from './lib/xen-orchestra-v2v.mjs'
export * from './lib/xen-orchestra-docker.mjs'
export * from './lib/complex-matcher.mjs'
export * from './lib/rest-api.mjs'
export * from './lib/xen-orchestra-vmware-explorer.mjs'

View File

@@ -0,0 +1,173 @@
// DTOs of the Docker engines reached through SSH (xo-server `xo-mixins/docker.mjs`)
//
// Dates are milliseconds since the epoch. Optional values which do not apply
// are omitted, except the stats values which are `null` when they cannot be
// computed.
export type XoDockerContainerState = 'created' | 'running' | 'paused' | 'restarting' | 'removing' | 'exited' | 'dead'
export type XoDockerContainerHealth = 'starting' | 'healthy' | 'unhealthy'
export type XoDockerContainerAction = 'start' | 'stop' | 'restart' | 'pause' | 'unpause'
export type XoDockerPort = {
/** only for a published port, absent when published on all interfaces of an old daemon */
ip?: string
privatePort: number
/** absent when the port is not published */
publicPort?: number
protocol: string
}
export type XoDockerCompose = {
project: string
service?: string
containerNumber?: number
oneOff?: boolean
workingDir?: string
configFiles?: string[]
}
export type XoDockerNetwork = {
name: string
ipAddress?: string
ipv6Address?: string
}
export type XoDockerMount = {
type: string
name?: string
source: string
destination: string
readOnly: boolean
}
export type XoDockerHealthCheck = {
failingStreak: number
lastCheckAt?: number
lastExitCode?: number
}
export type XoDockerRestartPolicy = {
/** `no` when the container has no restart policy */
name: string
maximumRetryCount: number
}
/**
* Stats of one container, like `docker stats`
*/
export type XoDockerContainerStats = {
sampledAt: number | null
/** 100 means one full CPU: can go up to `100 * onlineCpus` */
cpuPercent: number | null
onlineCpus?: number
/** bytes, without the reclaimable page cache */
memoryUsage: number | null
memoryLimit: number | null
memoryPercent: number | null
networkRx: number | null
networkTx: number | null
blockRead: number | null
blockWrite: number | null
pids: number | null
}
export type XoDockerComposeSummary = {
projects: { name: string; containers: number; running: number }[]
}
export type XoDockerError = {
/** DockerError code, e.g. `SSH_AUTH_FAILED` */
code: string
message: string
data?: Record<string, unknown>
}
/** Podman is told from Docker by its `GET /version` */
export type XoDockerEngineKind = 'docker' | 'podman'
export type XoDockerEngineInfoConnected = {
status: 'connected'
kind: XoDockerEngineKind
asOf: number
/** the daemon's ID, not the engine's */
daemonId?: string
name?: string
engineVersion?: string
/** the Docker API version negotiated by XO */
apiVersion?: string
/** the newest Docker API version of the daemon */
daemonApiVersion?: string
minApiVersion?: string
operatingSystem?: string
osType?: string
kernelVersion?: string
architecture?: string
cpus?: number
/** bytes */
memory?: number
storageDriver?: string
loggingDriver?: string
cgroupDriver?: string
cgroupVersion?: string
rootless: boolean
containers: { total?: number; running?: number; paused?: number; stopped?: number }
images?: number
warnings: string[]
compose: XoDockerComposeSummary
}
export type XoDockerEngineInfoDisconnected = {
status: 'unreachable' | 'auth-failed' | 'host-key-mismatch'
asOf: number
error: XoDockerError
}
/**
* Live information about an engine: `status` tells whether it could be reached
*/
export type XoDockerEngineInfo = XoDockerEngineInfoConnected | XoDockerEngineInfoDisconnected
export type XoDockerSocketDiagnostic = {
code: 'socket-missing' | 'not-a-socket' | 'permission-denied' | 'forwarding-disabled' | 'probe-failed'
message: string
}
export type XoDockerEngineTestResult = {
ok: boolean
apiVersion?: string
engineVersion?: string
/** observed SSH host key, `SHA256:…` */
fingerprint?: string
algorithm?: string
error?: XoDockerError
/** only when the Docker socket could not be opened */
diagnostic?: XoDockerSocketDiagnostic
}
export type XoDockerLogEntry = {
/** RFC 3339 date with nanoseconds, absent with `timestamps: false` */
timestamp?: string
stream: 'stdout' | 'stderr'
message: string
}
export type XoDockerLogs = {
entries: XoDockerLogEntry[]
/** the logs have been cut: at `docker.maxLogsSize`, or when reading them timed out */
truncated: boolean
/** reading stopped at `docker.logsTimeout` (overall) or `docker.logsIdleTimeout` (no data) */
timedOut: boolean
asOf: number
}
/**
* Failure of one engine in a container listing
*/
export type XoDockerContainerListError = {
$engine: string
$VM?: string
code: string
message: string
}

View File

@@ -8,6 +8,8 @@ import type {
XoAuthenticationToken,
XoBackupRepository,
XoConfigBackupArchive,
XoDockerContainer,
XoDockerEngine,
XoGroup,
XoHost,
XoMetadataBackupJob,
@@ -32,6 +34,14 @@ import { VatesTask } from './lib/vates-task.mjs'
import type { PluginRestRouteDefinition } from './lib/rest-api.mjs'
import type { VmwareInventory } from './lib/xen-orchestra-vmware-explorer.mjs'
import type { XoV2vStatus } from './lib/xen-orchestra-v2v.mjs'
import type {
XoDockerContainerAction,
XoDockerContainerListError,
XoDockerContainerStats,
XoDockerEngineInfo,
XoDockerEngineTestResult,
XoDockerLogs,
} from './lib/xen-orchestra-docker.mjs'
import type { RPU_RECOVERY_STEP_NAME } from './common.mjs'
import {
Xapi,
@@ -219,6 +229,28 @@ export type EsxiConnectionParams = {
sslVerify: boolean
}
/**
* Properties of a Docker engine, as accepted by `createDockerEngine` and
* `updateDockerEngine`
*
* On update, omitted properties are kept, `null` or `''` clears them (`port`
* and `socketPath` are reset to their defaults).
*/
export type XoDockerEngineProperties = {
$VM?: XoVm['id'] | null
label?: string | null
host?: string | null
port?: number | null
username?: string
password?: string | null
privateKey?: string | null
passphrase?: string | null
socketPath?: string | null
hostKeyFingerprint?: string | null
/** transient, never stored: pin the observed host key when there is no fingerprint */
acceptUnknownHostKey?: boolean
}
export type XoApp = EventEmitter & {
hooks: EventEmitter
_redis: {
@@ -298,6 +330,20 @@ export type XoApp = EventEmitter & {
) => Promise<{ bypassOtp: boolean; expiration: number; user: XoUser }>
backupGuard(objectId: XapiXoRecord['id'], opts?: { bypassBackupCheck?: boolean; operation: string }): Promise<void>
/* Throw if no authorization */
/**
* raw Docker Engine API request (admin-only REST passthrough), bounded by `docker.maxRawRequestSize` and
* `docker.maxRawResponseSize`
*/
callDockerEngineRawApi(
id: XoDockerEngine['id'],
opts: {
method: string
path: string
headers?: Record<string, string>
body?: Readable
signal?: AbortSignal
}
): Promise<{ statusCode: number; headers: Record<string, string | string[] | undefined>; body: Readable }>
checkFeatureAuthorization(featureCode: FeatureCode): Promise<void>
/* whether this machine can run the tools of an import from VMware */
checkEsxiDependencies(): Promise<XoV2vStatus>
@@ -339,6 +385,8 @@ export type XoApp = EventEmitter & {
/** keyed by temporary IDs, which can be used as keys in `props.settings` */
schedules: Record<string, Pick<XoSchedule, 'cron' | 'enabled' | 'name' | 'timezone'>>
): Promise<XoMetadataBackupJob>
/** connects first (TOFU: DockerError HOST_KEY_UNKNOWN without fingerprint), saves nothing on failure */
createDockerEngine(properties: XoDockerEngineProperties): Promise<XoDockerEngine>
createAuthenticationToken(opts: {
client?: {
id?: string
@@ -377,6 +425,8 @@ export type XoApp = EventEmitter & {
): Promise<boolean>
deleteAclV2Privilege(privilegeId: XoAclBasePrivilege['id'], options?: { force?: boolean }): Promise<boolean>
deleteAclV2Role(roleId: XoAclRole['id'], options?: { force?: boolean }): Promise<boolean>
deleteDockerContainer(id: XoDockerContainer['id'], opts?: { force?: boolean; removeVolumes?: boolean }): Promise<void>
deleteDockerEngine(id: XoDockerEngine['id']): Promise<void>
deleteGroup(id: XoGroup['id']): Promise<void>
deleteSchedule(id: XoSchedule['id']): Promise<void>
deleteUser(id: XoUser['id']): Promise<void>
@@ -407,6 +457,8 @@ export type XoApp = EventEmitter & {
userId: XoUser['id'],
opts?: { bypassAuthorization?: boolean; fromGroup?: boolean; fromUser?: boolean }
): Promise<XoAclRole[]>
/** never connects */
getAllDockerEngines(): Promise<XoDockerEngine[]>
getAllGroups(): Promise<XoGroup[]>
getAllProxies(): Promise<XoProxy[]>
getAllJobs<T extends AnyXoJob['type']>(type: T): Promise<Extract<AnyXoJob, { type: T }>[]>
@@ -457,6 +509,38 @@ export type XoApp = EventEmitter & {
filter: (log: AnyXoLog) => boolean
limit?: number
}): Promise<AnyXoLog[]>
getDockerContainer(id: XoDockerContainer['id']): Promise<XoDockerContainer>
/**
* never connects: the container and the objects it belongs to, from its engine (the container itself may not
* exist), e.g. for the ACLs
*/
getDockerContainerScope(
id: XoDockerContainer['id']
): Promise<Pick<XoDockerContainer, 'id' | '$engine' | '$VM' | '$pool'>>
getDockerContainerLogs(
id: XoDockerContainer['id'],
opts?: {
tail?: number
since?: number | string
until?: number | string
stdout?: boolean
stderr?: boolean
timestamps?: boolean
}
): Promise<XoDockerLogs>
/** the stats sampler's latest sample if ready, else one `stream=false` call (~1-2 s) */
getDockerContainerStats(id: XoDockerContainer['id']): Promise<XoDockerContainerStats>
/** an engine which fails does not fail the list, see `errors` */
getDockerContainers(opts: {
engines: XoDockerEngine['id'][]
all?: boolean
stats?: boolean
forceRefresh?: boolean
}): Promise<{ containers: XoDockerContainer[]; errors: XoDockerContainerListError[]; asOf: number }>
/** never connects */
getDockerEngine(id: XoDockerEngine['id']): Promise<XoDockerEngine>
/** connects, never throws for connection problems (see `status`) */
getDockerEngineInfo(id: XoDockerEngine['id']): Promise<XoDockerEngineInfo>
getGroup(id: XoGroup['id']): Promise<XoGroup>
getHVSupportedVersions: undefined | (() => Promise<{ [key: XoHost['productBrand']]: string }>)
getJob<T extends AnyXoJob>(id: T['id']): Promise<T>
@@ -597,8 +681,11 @@ export type XoApp = EventEmitter & {
setVmResourceSet(vmId: XoVm['id'], resourceSetId: string | null, force?: boolean): Promise<void>
shareVmResourceSet(vmId: XoVm['id']): Promise<void>
removeUserFromGroup(userId: XoUser['id'], id: XoGroup['id']): Promise<void>
runDockerContainerAction(id: XoDockerContainer['id'], action: XoDockerContainerAction): Promise<void>
runJob(job: AnyXoJob, schedule: XoSchedule): void
runWithApiContext: (user: XoUser | undefined, fn: () => void) => Promise<unknown>
/** new, non pooled, connection; never throws for connection problems */
testDockerEngine(id: XoDockerEngine['id']): Promise<XoDockerEngineTestResult>
testPlugin(id: XoPlugin['id'], data?: unknown): Promise<void>
testRemote(
id: XoBackupRepository['id']
@@ -660,6 +747,7 @@ export type XoApp = EventEmitter & {
force?: boolean
}
): Promise<XoAclRole>
updateDockerEngine(id: XoDockerEngine['id'], properties: XoDockerEngineProperties): Promise<XoDockerEngine>
updateGroup(
id: XoGroup['id'],
updates: {

View File

@@ -20,6 +20,18 @@ import type {
} from './common.mjs'
import type * as CMType from './lib/complex-matcher.mjs'
import { XoAclBasePrivilege, XoAclRole } from './lib/xen-orchestra-acl.mjs'
import type {
XoDockerCompose,
XoDockerContainerHealth,
XoDockerContainerState,
XoDockerContainerStats,
XoDockerEngineKind,
XoDockerHealthCheck,
XoDockerMount,
XoDockerNetwork,
XoDockerPort,
XoDockerRestartPolicy,
} from './lib/xen-orchestra-docker.mjs'
import type { XenApiHost, XenApiPool } from './xen-api.mjs'
import type {
XoAuditPlugin,
@@ -85,6 +97,11 @@ type BaseXoVm = BaseXapiXo & {
cpuWeight?: number
creation: Record<string, string>
current_operations: Record<string, VM_OPERATIONS>
/**
* @deprecated legacy xscontainer data scraped from `other_config`, use the
* `XoDockerEngine`/`XoDockerContainer` records (`/rest/v0/docker-engines`,
* `/rest/v0/docker-containers`) instead
*/
docker?: {
containers?: string[]
enabled: boolean
@@ -258,6 +275,84 @@ export type XoGpuGroup = BaseXapiXo & {
type: 'gpuGroup'
}
/**
* A Docker engine reached through SSH (`direct-streamlocal` to its socket)
*
* Secrets (password, private key, passphrase) are never included.
*/
export type XoDockerEngine = {
id: Branded<'docker-engine'>
/** VM running the engine, absent for an engine which is not a VM */
$VM?: XoVm['id']
/** pool of the VM, denormalized at read time */
$pool?: XoPool['id']
label?: string
/** absent: resolved from the addresses reported by the VM at connection time */
host?: string
resolvedHost?: string
port: number
username: string
socketPath: string
/** pinned SSH host key, `SHA256:…` as printed by `ssh-keygen -l` */
hostKeyFingerprint?: string
hostKeyAlgorithm?: string
hasPassword: boolean
hasPrivateKey: boolean
/** Docker or Podman: from the current connection, else the last one, absent until a connection negotiated */
kind?: XoDockerEngineKind
/** state of the pooled connection, reading it never connects */
connectionStatus: 'idle' | 'connected' | 'error'
/** last connection failure, if any */
error?: { code: string; message: string }
}
/**
* A container of a Docker engine, fetched live
*
* The fields after `mounts` come from an inspection: they are absent from the
* list entries of stopped containers (and above `docker.inspectThreshold`).
*/
export type XoDockerContainer = {
/** `<engine id>_<full Docker id>` */
id: Branded<'docker-container'>
$engine: XoDockerEngine['id']
$VM?: XoVm['id']
$pool?: XoPool['id']
dockerId: string
name?: string
image: string
imageId: string
command: string
createdAt?: number
state: XoDockerContainerState
/** human readable status, e.g. `Up 3 hours (healthy)` */
status?: string
exitCode?: number
health?: XoDockerContainerHealth
ports: XoDockerPort[]
labels: Record<string, string>
compose?: XoDockerCompose
networks: XoDockerNetwork[]
mounts: XoDockerMount[]
startedAt?: number
finishedAt?: number
oomKilled?: boolean
error?: string
healthCheck?: XoDockerHealthCheck
restartPolicy?: XoDockerRestartPolicy
restartCount?: number
tty?: boolean
hostname?: string
workingDir?: string
user?: string
/** only with `stats=true`, for running and paused containers: latest sample of the engine's stats sampler */
stats?: XoDockerContainerStats
/** only with `stats=true`: the first samples are not there yet (`stats` missing, or `cpuPercent: null`) */
statsPending?: boolean
}
export type XoGroup = {
id: Branded<'group'>
name: string
@@ -763,6 +858,8 @@ export type XoTask = {
| 'backup-job'
| 'backup-log'
| 'backup-repository'
| 'docker-container'
| 'docker-engine'
| 'group'
| 'plugin'
| 'proxy'
@@ -984,6 +1081,8 @@ export type NonXapiXoRecord =
| XoProxy
| XoJob
| XoBackupRepository
| XoDockerContainer
| XoDockerEngine
| XoSchedule
| XoServer
| XoTask

View File

@@ -27,7 +27,6 @@ import { formatFilenameDate } from './_filenameDate.mjs'
import { isMetadataFile } from './_backupType.mjs'
import {
isKnownJournalEvent,
purgeBackupJournal,
readBackupJournal,
writeBackupJournalEntries,
writeBackupJournalEntry,
@@ -560,14 +559,6 @@ export class RemoteAdapter {
return readBackupJournal(this._handler, cursor, opts)
}
/**
* @param {number} before timestamp in ms, the journal days before its own are removed
* @returns {Promise<void>}
*/
async purgeBackupJournal(before) {
return purgeBackupJournal(this._handler, before)
}
// Same as `readBackupJournal()`, with the current metadata of the added and changed backups
// attached, so that a listing can be brought up to date from the result alone, in a single
// round-trip for a caller which is not on this host.

View File

@@ -393,47 +393,6 @@ describe('readBackupJournal()', { concurrency: 1 }, () => {
})
})
describe('purgeBackupJournal()', { concurrency: 1 }, () => {
const DAY = 24 * 60 * 60 * 1e3
const HOUR = 60 * 60 * 1e3
// midnight of the given number of days ago, so that the tests do not depend on the time they run at
const daysAgo = n => (Math.floor(Date.now() / DAY) - n) * DAY
const writeEntryAt = timestamp =>
writeJournalEntryAt(timestamp, { event: 'add', vmUuid, filename: `/${rootPath}/${timestamp}.json` })
test('removes the days before the one of `before`, and keeps that day whole', async () => {
for (const n of [3, 2]) {
await writeEntryAt(daysAgo(n) + HOUR)
}
// after the entry of its own day: that entry is kept all the same
await adapter.purgeBackupJournal(daysAgo(2) + 2 * HOUR)
assert.deepEqual(await listJournalDays(), [formatJournalDay(daysAgo(2))])
})
test('skips a day which cannot be removed, and removes the next ones', async t => {
for (const n of [3, 2]) {
await writeEntryAt(daysAgo(n))
}
const lockedDay = formatJournalDay(daysAgo(3))
const rmtree = handler.rmtree.bind(handler)
t.mock.method(handler, 'rmtree', async path => {
if (path === `/${BACKUP_JOURNAL_DIR}/${lockedDay}`) {
throw Object.assign(new Error('EPERM: operation not permitted'), { code: 'EPERM' })
}
return rmtree(path)
})
await adapter.purgeBackupJournal(Date.now())
assert.deepEqual(await listJournalDays(), [lockedDay])
})
})
describe('readBackupJournalEvents()', { concurrency: 1 }, () => {
// records the paths whose metadata is read from now on, to check a replay does not re-read the
// same backup once per event

View File

@@ -309,47 +309,3 @@ export async function readBackupJournal(handler, cursor, { mustExist = false } =
return entries
}
/**
* Removes the journal entries of the days before the one of `before`.
*
* Whole days are removed, entries are never removed one by one: the day of `before` is kept entirely,
* whatever the time of its entries.
*
* A day which cannot be removed is skipped, e.g. its files are immutable (`EPERM` on a local
* repository, `AccessDenied` from the policy of a bucket): it must not keep the later days from being
* removed, and the next purge tries it again. Only a failure to list the journal rejects.
*
* A purge warns once, with its first failure and their count: where deletes are refused, every day
* before `before` fails again on each purge, one more each day.
*
* @param {RemoteHandler} handler
* @param {number} before timestamp in ms
* @returns {Promise<void>}
*/
export async function purgeBackupJournal(handler, before) {
const minDay = formatJournalDay(before)
const days = await handler.list(`/${BACKUP_JOURNAL_DIR}`, {
filter: name => isDayName(name) && name < minDay,
ignoreMissing: true,
})
let firstFailure
let nFailures = 0
// one day at a time: this runs in the background, it must not compete with the backups for the
// remote
for (const day of days) {
const path = `/${BACKUP_JOURNAL_DIR}/${day}`
try {
await handler.rmtree(path)
debug('journal day purged', { path })
} catch (error) {
if (firstFailure === undefined) {
firstFailure = { error, path }
}
++nFailures
}
}
if (firstFailure !== undefined) {
warn('failed to purge some journal days', { ...firstFailure, nFailures })
}
}

View File

@@ -65,11 +65,6 @@ export class IncrementalXapiWriter extends MixinXapiWriter(AbstractIncrementalWr
const snapshotCandidates = new Map()
// skip orphan snapshots (active VDI destroyed): they can't be validated against an active disk
const replicaSnapshots = sr.$VDIs.filter(
vdi => vdi?.managed && vdi?.is_a_snapshot && vdi.$snapshot_of !== undefined
)
for (const [baseUuid, srcVdiuid] of baseUuidToSrcVdi) {
let target
@@ -77,9 +72,11 @@ export class IncrementalXapiWriter extends MixinXapiWriter(AbstractIncrementalWr
if (contentKey !== undefined) {
debug('got one content key, look for a candidate')
target = replicaSnapshots.find(
target = sr.$VDIs.find(
vdi =>
vdi.other_config[CONTENT_KEY] === contentKey &&
vdi?.managed &&
vdi?.is_a_snapshot &&
vdi.other_config[CONTENT_KEY] === contentKey && // &&
// ensure we don't replicate on ourself or any of the vdi in the source chain
vdi.$snapshot_of.uuid !== srcVdiuid
)
@@ -88,11 +85,13 @@ export class IncrementalXapiWriter extends MixinXapiWriter(AbstractIncrementalWr
// fall back for older snapshots
if (target === undefined) {
debug('content key not here or not found , look by jobid ')
target = replicaSnapshots.find(
target = sr.$VDIs.find(
vdi =>
vdi?.managed &&
vdi?.is_a_snapshot &&
vdi.other_config[JOB_ID] === this._job.id &&
vdi.other_config[VM_UUID] === this._vmUuid &&
vdi.other_config[COPY_OF] === baseUuid
vdi?.other_config[COPY_OF] === baseUuid
)
}
if (target !== undefined) {

View File

@@ -43,7 +43,7 @@ A VM directory holds **both** the full and the incremental backups of that VM: t
Transient entries, not listed in the trees below:
- `xo-vm-backups/<VM UUID>.lock`, held while a job writes to that VM's folder and while `cleanVm` cleans or merges it (after a job, after a deletion, or in the merge worker on local remotes). It is effective on S3 (an object rewritten every 30 seconds) and Azure (blob lease) too. When listing VMs, entries starting with `.` and entries ending with `.lock` are ignored.
- `xo-vm-backups/<VM UUID>.lock`, held for the duration of a job run on that VM. When listing VMs, entries starting with `.` and entries ending with `.lock` are ignored.
- `xo-vm-backups/.queue/clean-vm/<YYYYMMDD>T<HHmmss>-<random>`, the merge worker queue
- `.<VHD file name>.merge.json`, in a VDI directory, interrupted merge states.
@@ -167,7 +167,6 @@ Append-only log of what happened to the VM backup metadata.
- entries are never modified nor overwritten, so it works on an immutable remote
- written unencrypted, so it stays readable without the encryption key
- one directory per day: a reader lists only the days it misses, a purge drops whole directories
- xo-server removes the days older than `backups.journalRetention` from every enabled remote when it starts, then once a day; it always keeps the `fullListingInterval` of the remote, during which it reads the journal back; a day which cannot be removed is skipped, and the next purge tries it again
- the time part has a fixed width, so sorting the names by name sorts them by date
- `event` is `add`, `change` or `del`, and the file content also has a `reason` field
- the name of the file is only there to be read by a human: XO reads every field from the file content

View File

@@ -0,0 +1,42 @@
Talks to the Docker Engine API of a remote host through SSH: the requests go over `direct-streamlocal@openssh.com` channels to the host's Docker socket, so nothing has to be installed on the host besides an OpenSSH server (≥ 6.7) and a user allowed to use the socket. It is the transport of the Docker integration of Xen Orchestra, and has no XO concepts.
- host key pinning (`SHA256:…` fingerprint), or trust on first use with `acceptUnknownHostKey` and `observedHostKey`
- API version negotiation (between `MIN_API_VERSION` and `MAX_API_VERSION`)
- one SSH connection per host, HTTP keep-alive over its channels, a bounded number of concurrent requests
- typed errors (`DockerError` and its `code`: `SSH_AUTH_FAILED`, `HOST_KEY_MISMATCH`, `DOCKER_SOCKET_UNREACHABLE`…)
- helpers: a connection pool with idle GC and a negative cache (`DockerConnectionPool`), a stats sampler (`DockerStatsSampler`), the log stream demuxer (`createStdcopyDemuxer`) and normalizers of the Docker responses
```js
import { readFileSync } from 'node:fs'
import { DockerConnection, normalizeContainerListEntry, DockerError } from '@xen-orchestra/docker-ssh'
const env = process.env // host, user, key path…
const connection = new DockerConnection({
host: env.XO_DOCKER_TEST_SSH_HOST,
port: Number(env.XO_DOCKER_TEST_SSH_PORT),
username: env.XO_DOCKER_TEST_SSH_USER,
privateKey: readFileSync(env.XO_DOCKER_TEST_SSH_KEY),
socketPath: env.XO_DOCKER_TEST_SOCKET,
// pinned host key: a different key is refused with HOST_KEY_MISMATCH
hostKeyFingerprint: env.XO_DOCKER_TEST_SSH_FINGERPRINT,
})
try {
await connection.connect()
const { body: version } = await connection.request({ path: '/version' })
console.log('Docker %s, API %s negotiated', version.Version, connection.apiVersion)
const { body: containers } = await connection.request({
path: '/containers/json',
query: { all: 1, filters: JSON.stringify({ name: ['^/xo-', '^/demo-'] }) },
})
for (const container of containers.map(normalizeContainerListEntry)) {
console.log('%s\t%s\t%s', container.name, container.state, container.image)
}
} catch (error) {
if (error instanceof DockerError) console.error(error.code, error.message)
else throw error
} finally {
await connection.close()
}
```

View File

@@ -0,0 +1 @@
src/docker-api.gen.mts linguist-generated=true

View File

@@ -0,0 +1 @@
../../scripts/npmignore

View File

@@ -0,0 +1,75 @@
<!-- DO NOT EDIT MANUALLY, THIS FILE HAS BEEN GENERATED -->
# @xen-orchestra/docker-ssh
[![Package Version](https://badgen.net/npm/v/@xen-orchestra/docker-ssh)](https://npmjs.org/package/@xen-orchestra/docker-ssh) ![License](https://badgen.net/npm/license/@xen-orchestra/docker-ssh) [![PackagePhobia](https://badgen.net/bundlephobia/minzip/@xen-orchestra/docker-ssh)](https://bundlephobia.com/result?p=@xen-orchestra/docker-ssh) [![Node compatibility](https://badgen.net/npm/node/@xen-orchestra/docker-ssh)](https://npmjs.org/package/@xen-orchestra/docker-ssh)
> Docker Engine API client reaching the Docker socket of a remote host through SSH
## Install
Installation of the [npm package](https://npmjs.org/package/@xen-orchestra/docker-ssh):
```sh
npm install --save @xen-orchestra/docker-ssh
```
## Usage
Talks to the Docker Engine API of a remote host through SSH: the requests go over `direct-streamlocal@openssh.com` channels to the host's Docker socket, so nothing has to be installed on the host besides an OpenSSH server (≥ 6.7) and a user allowed to use the socket. It is the transport of the Docker integration of Xen Orchestra, and has no XO concepts.
- host key pinning (`SHA256:…` fingerprint), or trust on first use with `acceptUnknownHostKey` and `observedHostKey`
- API version negotiation (between `MIN_API_VERSION` and `MAX_API_VERSION`)
- one SSH connection per host, HTTP keep-alive over its channels, a bounded number of concurrent requests
- typed errors (`DockerError` and its `code`: `SSH_AUTH_FAILED`, `HOST_KEY_MISMATCH`, `DOCKER_SOCKET_UNREACHABLE`…)
- helpers: a connection pool with idle GC and a negative cache (`DockerConnectionPool`), a stats sampler (`DockerStatsSampler`), the log stream demuxer (`createStdcopyDemuxer`) and normalizers of the Docker responses
```js
import { readFileSync } from 'node:fs'
import { DockerConnection, normalizeContainerListEntry, DockerError } from '@xen-orchestra/docker-ssh'
const env = process.env // host, user, key path…
const connection = new DockerConnection({
host: env.XO_DOCKER_TEST_SSH_HOST,
port: Number(env.XO_DOCKER_TEST_SSH_PORT),
username: env.XO_DOCKER_TEST_SSH_USER,
privateKey: readFileSync(env.XO_DOCKER_TEST_SSH_KEY),
socketPath: env.XO_DOCKER_TEST_SOCKET,
// pinned host key: a different key is refused with HOST_KEY_MISMATCH
hostKeyFingerprint: env.XO_DOCKER_TEST_SSH_FINGERPRINT,
})
try {
await connection.connect()
const { body: version } = await connection.request({ path: '/version' })
console.log('Docker %s, API %s negotiated', version.Version, connection.apiVersion)
const { body: containers } = await connection.request({
path: '/containers/json',
query: { all: 1, filters: JSON.stringify({ name: ['^/xo-', '^/demo-'] }) },
})
for (const container of containers.map(normalizeContainerListEntry)) {
console.log('%s\t%s\t%s', container.name, container.state, container.image)
}
} catch (error) {
if (error instanceof DockerError) console.error(error.code, error.message)
else throw error
} finally {
await connection.close()
}
```
## Contributions
Contributions are _very_ welcomed, either on the documentation or on
the code.
You may:
- report any [issue](https://github.com/vatesfr/xen-orchestra/issues)
you've encountered;
- fork and create a pull request.
## License
[AGPL-3.0-or-later](https://spdx.org/licenses/AGPL-3.0-or-later) © [Vates SAS](https://vates.fr)

View File

@@ -0,0 +1,6 @@
// @ts-check
import eslint from '@eslint/js'
import tseslint from 'typescript-eslint'
export default tseslint.config(eslint.configs.recommended, tseslint.configs.recommended)

View File

@@ -0,0 +1,54 @@
{
"name": "@xen-orchestra/docker-ssh",
"version": "0.0.0",
"main": "./dist/index.mjs",
"types": "./dist/index.d.mts",
"license": "AGPL-3.0-or-later",
"private": false,
"type": "module",
"description": "Docker Engine API client reaching the Docker socket of a remote host through SSH",
"keywords": [
"docker",
"ssh",
"streamlocal",
"xen-orchestra"
],
"dependencies": {
"@vates/types": "^2.0.1",
"@xen-orchestra/log": "^0.7.2",
"ssh2": "^1.16.0"
},
"devDependencies": {
"@eslint/js": "^9.19.0",
"@types/node": "^22.3.0",
"@types/ssh2": "^1.15.5",
"rimraf": "^6.0.1",
"typescript": "~5.6",
"typescript-eslint": "^8.61.0",
"yaml": "^2.9.0"
},
"scripts": {
"build": "tsc",
"clean": "rimraf dist/",
"dev": "tsc --watch",
"generate-api-types": "node scripts/generate-api-types.mjs",
"postversion": "npm publish --access public",
"prebuild": "rimraf dist/",
"predev": "yarn run prebuild",
"test": "tsc && node --test \"dist/**/*.test.mjs\""
},
"homepage": "https://github.com/vatesfr/xen-orchestra/tree/master/@xen-orchestra/docker-ssh",
"bugs": "https://github.com/vatesfr/xen-orchestra/issues",
"repository": {
"directory": "@xen-orchestra/docker-ssh",
"type": "git",
"url": "https://github.com/vatesfr/xen-orchestra.git"
},
"author": {
"name": "Vates SAS",
"url": "https://vates.fr"
},
"engines": {
"node": ">=22"
}
}

View File

@@ -0,0 +1,140 @@
#!/usr/bin/env node
// Generates `src/docker-api.gen.mts`: the TypeScript types of the Docker Engine
// API definitions this package reads, from the official OpenAPI (Swagger 2.0)
// specifications published by Docker.
//
// - API 1.44 (`MAX_API_VERSION` in `src/connection.mts`) for everything
// - API 1.48 for the stats: before it, the spec documents the stats response as
// a plain `object` (the field names did not change, `ContainerStatsResponse`
// only documents them)
//
// Only the definitions reachable from `ROOTS` are kept. The inspect response is
// inline in the 1.44 spec: it is added as `ContainerInspectResponse`, the name
// later specs use.
//
// yarn generate-api-types # needs network access (specs + npx)
import { execFileSync } from 'node:child_process'
import { mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs'
import { tmpdir } from 'node:os'
import { join } from 'node:path'
import { parse } from 'yaml'
const SPEC_URL = version => `https://docs.docker.com/reference/api/engine/version/v${version}.yaml`
const API_VERSION = '1.44'
const STATS_API_VERSION = '1.48'
const OPENAPI_TYPESCRIPT = 'openapi-typescript@5.4.2' // last major reading Swagger 2.0
const ROOTS = [
'SystemVersion',
'SystemInfo',
'ContainerSummary',
'ContainerInspectResponse',
'ContainerConfig',
'ContainerState',
'Health',
'HealthcheckResult',
'Port',
'EndpointSettings',
'MountPoint',
'RestartPolicy',
]
const STATS_ROOTS = ['ContainerStatsResponse']
async function fetchSpec(version) {
const response = await fetch(SPEC_URL(version))
if (!response.ok) {
throw new Error(`${SPEC_URL(version)}: ${response.status}`)
}
return parse(await response.text())
}
function getResponseSchema(spec, path) {
const { responses } = spec.paths[path].get
return (responses[200] ?? responses['200']).schema
}
// definitions reachable from `roots`, following every `$ref`
function pickDefinitions(definitions, roots) {
const picked = {}
const visit = value => {
if (Array.isArray(value)) {
value.forEach(visit)
} else if (value !== null && typeof value === 'object') {
for (const [key, child] of Object.entries(value)) {
if (key === '$ref' && typeof child === 'string') {
add(child.slice('#/definitions/'.length))
} else {
visit(child)
}
}
}
}
const add = name => {
if (picked[name] === undefined) {
if (definitions[name] === undefined) {
throw new Error(`missing definition ${name}`)
}
picked[name] = definitions[name]
visit(definitions[name])
}
}
roots.forEach(add)
return picked
}
const spec = await fetchSpec(API_VERSION)
const statsSpec = await fetchSpec(STATS_API_VERSION)
const definitions = pickDefinitions(
{ ...spec.definitions, ContainerInspectResponse: getResponseSchema(spec, '/containers/{id}/json') },
ROOTS
)
const statsDefinitions = pickDefinitions(statsSpec.definitions, STATS_ROOTS)
for (const name of Object.keys(statsDefinitions)) {
if (definitions[name] !== undefined) {
throw new Error(`${name} is in both specs`)
}
}
const dir = mkdtempSync(join(tmpdir(), 'docker-api-types-'))
try {
const input = join(dir, 'spec.json')
const output = join(dir, 'types.ts')
writeFileSync(
input,
JSON.stringify({
swagger: '2.0',
info: { title: 'Docker Engine API (subset)', version: API_VERSION },
paths: {},
definitions: { ...definitions, ...statsDefinitions },
})
)
execFileSync('npx', ['--yes', OPENAPI_TYPESCRIPT, input, '--output', output], { stdio: 'inherit' })
const types = readFileSync(output, 'utf8')
// no paths, no operations: only `definitions` is useful
.replace(/^export interface paths \{\}\n\n/m, '')
.replace(/^export interface operations \{\}\n\n/m, '')
.replace(/^export interface external \{\}\n?/m, '')
const target = new URL('../src/docker-api.gen.mts', import.meta.url)
writeFileSync(
target,
`// Generated by scripts/generate-api-types.mjs, do not edit.
//
// Docker Engine API ${API_VERSION} definitions read by this package (and the stats
// definitions of API ${STATS_API_VERSION}), from the official specifications:
// ${SPEC_URL(API_VERSION)}
// ${SPEC_URL(STATS_API_VERSION)}
//
// These are what the daemon is documented to send, they are not checked at
// runtime: see \`wire.mts\` for how this package uses them.
${types.trim()}
`
)
execFileSync('npx', ['prettier', '--write', target.pathname], { stdio: 'inherit' })
console.log('definitions:', Object.keys(definitions).length + Object.keys(statsDefinitions).length)
} finally {
rmSync(dir, { recursive: true, force: true })
}

View File

@@ -0,0 +1,314 @@
// Integration tests against a real Docker daemon reached through a real SSH
// server.
//
// Skipped unless the following environment variables are set:
//
// - XO_DOCKER_TEST_SSH_HOST
// - XO_DOCKER_TEST_SSH_PORT (default: 22)
// - XO_DOCKER_TEST_SSH_USER
// - XO_DOCKER_TEST_SSH_KEY: path of an authorized private key
// - XO_DOCKER_TEST_SSH_BAD_KEY: path of a private key which is NOT authorized
// - XO_DOCKER_TEST_SSH_FINGERPRINT: host key fingerprint (`SHA256:…`, ED25519)
// - XO_DOCKER_TEST_SOCKET: path of the Docker socket on the SSH host
// - XO_DOCKER_TEST_SSH_NOFWD_PORT (optional): port of an SSH server on the same
// host with `AllowStreamLocalForwarding no` and the same authorized key
import assert from 'node:assert/strict'
import { readFileSync } from 'node:fs'
import { createServer, type AddressInfo } from 'node:net'
import test from 'node:test'
import { Client } from 'ssh2'
import {
DockerConnection,
MAX_API_VERSION,
type DockerConnectionInternals,
type DockerConnectionOptions,
type SshClient,
} from './connection.mjs'
import {
DOCKER_SOCKET_UNREACHABLE,
HOST_KEY_MISMATCH,
HOST_KEY_UNKNOWN,
CONNECTION_CLOSED,
SSH_AUTH_FAILED,
SSH_UNREACHABLE,
TIMEOUT,
type DockerError,
} from './errors.mjs'
import { type DockerConnectionFacade, DockerConnectionPool } from './pool.mjs'
import type { DockerInfo, DockerVersion } from './wire.mjs'
const { after, before, describe, it } = test
const {
XO_DOCKER_TEST_SSH_HOST: host,
XO_DOCKER_TEST_SSH_PORT: port = '22',
XO_DOCKER_TEST_SSH_USER: username,
XO_DOCKER_TEST_SSH_KEY: keyPath,
XO_DOCKER_TEST_SSH_BAD_KEY: badKeyPath,
XO_DOCKER_TEST_SSH_FINGERPRINT: fingerprint,
XO_DOCKER_TEST_SOCKET: socketPath,
XO_DOCKER_TEST_SSH_NOFWD_PORT: noForwardingPort,
} = process.env
const skip = host === undefined ? 'XO_DOCKER_TEST_SSH_HOST is not set' : false
// a local TCP port on which nothing listens
async function getClosedPort() {
const server = createServer()
await new Promise<void>(resolve => server.listen(0, '127.0.0.1', resolve))
// a TCP server: an `AddressInfo`
const { port } = server.address() as AddressInfo
await new Promise(resolve => server.close(resolve))
return port
}
describe('DockerConnection (real SSH + dockerd)', { skip }, () => {
let privateKey: Buffer, badPrivateKey: Buffer
const connections: DockerConnection[] = []
// `!`: the environment is set, the tests are skipped otherwise
before(() => {
privateKey = readFileSync(keyPath!)
badPrivateKey = readFileSync(badKeyPath!)
})
after(async () => {
await Promise.all(connections.map(connection => connection.close()))
})
const createConnection = (opts?: Partial<DockerConnectionOptions>, internals?: DockerConnectionInternals) => {
const connection = new DockerConnection(
{
host: host!,
port: Number(port),
username: username!,
privateKey,
socketPath,
hostKeyFingerprint: fingerprint,
connectTimeout: 5e3,
requestTimeout: 10e3,
...opts,
},
internals
)
connections.push(connection)
return connection
}
describe('with the right fingerprint', () => {
let connection: DockerConnection
before(async () => {
connection = createConnection()
await connection.connect()
})
it('negotiates the API version', () => {
assert.equal(connection.apiVersion, MAX_API_VERSION)
assert.match(connection.engineVersion!, /^\d+\.\d+/)
assert.equal(connection.observedHostKey!.fingerprint, fingerprint)
})
it('GET /version', async () => {
const { statusCode, body } = await connection.request({ path: '/version' })
assert.equal(statusCode, 200)
assert.equal((body as DockerVersion).Version, connection.engineVersion)
})
it('GET /containers/json?all=1', async () => {
const { body } = await connection.request({ path: '/containers/json', query: { all: 1 } })
assert.ok(Array.isArray(body))
for (const container of body) {
assert.equal(typeof container.Id, 'string')
}
})
it('GET /info', async () => {
const { body } = await connection.request({ path: '/info' })
assert.equal(typeof (body as DockerInfo).ID, 'string')
assert.equal(typeof (body as DockerInfo).Containers, 'number')
})
it('handles 10 concurrent requests', async () => {
const results = await Promise.all(
Array.from({ length: 10 }, (_, i) => connection.request({ path: i % 2 === 0 ? '/info' : '/containers/json' }))
)
for (const { statusCode } of results) {
assert.equal(statusCode, 200)
}
})
it('reports Docker errors', async () => {
await assert.rejects(connection.request({ path: '/containers/xo-does-not-exist/json' }), (error: DockerError) => {
assert.equal(error.code, 'DOCKER_API_ERROR')
assert.equal(error.data!.statusCode, 404)
assert.match(error.message, /No such container/)
return true
})
})
})
it('times out with TIMEOUT on a long-lived request and stays usable', async () => {
const connection = createConnection({ requestTimeout: 500 })
await connection.connect()
// `/events` never ends by itself
await assert.rejects(connection.request({ path: '/events' }), { code: TIMEOUT })
const controller = new AbortController()
const events = await connection.requestStream({ path: '/events', signal: controller.signal })
// the stream outlives requestTimeout
await new Promise(resolve => setTimeout(resolve, 700))
assert.equal(events.destroyed, false)
controller.abort()
const { statusCode } = await connection.request({ path: '/_ping' })
assert.equal(statusCode, 200)
})
it('SSH connection losses: the pool replaces the lost connection (no reuse of dead channels, no leaked slots)', async () => {
const clients: SshClient[] = []
const lost: DockerConnection[] = []
const pool = new DockerConnectionPool()
const use = <T,>(fn: (connection: DockerConnectionFacade) => Promise<T>) =>
pool.use(
{ id: 'engine' },
() => {
const connection = createConnection(
{ requestTimeout: 2e3 },
{
createClient: () => {
const client = new Client()
clients.push(client)
return client
},
}
)
lost.push(connection)
return connection
},
fn
)
try {
// more drops than the max number of free sockets and concurrent requests
for (let i = 0; i < 5; ++i) {
await use(connection =>
Promise.all([connection.request({ path: '/_ping' }), connection.request({ path: '/_ping' })])
)
// simulate a network failure
clients.at(-1)!._sock!.destroy()
await new Promise(resolve => setTimeout(resolve, 100))
// removed from the pool, closed for good, without leaked slots
assert.deepEqual(pool.getState('engine'), { status: 'idle' })
const dead = lost.at(-1)!
assert.equal(dead.closed, true)
assert.deepEqual(dead.activeRequests, { requests: 0, streams: 0 })
await assert.rejects(dead.request({ path: '/_ping' }), { code: CONNECTION_CLOSED })
const start = Date.now()
const results = await use(connection =>
Promise.all(
Array.from({ length: 3 }, () => connection.request({ path: '/_ping' }).then(({ statusCode }) => statusCode))
)
)
assert.deepEqual(results, [200, 200, 200])
assert.ok(Date.now() - start < 2e3)
}
// one SSH session per connection
assert.equal(clients.length, 6)
assert.equal(lost.length, 6)
} finally {
await pool.destroy()
}
})
it('close() rejects queued requests with CONNECTION_CLOSED and does not reconnect', async () => {
const clients: SshClient[] = []
const connection = createConnection(
{},
{
createClient: () => {
const client = new Client()
clients.push(client)
return client
},
}
)
await connection.connect()
const results = Array.from({ length: 20 }, () =>
connection.request({ path: '/containers/json', query: { all: 1 } }).then(
() => 'ok',
error => error.code
)
)
await connection.close()
for (const result of await Promise.all(results)) {
assert.equal(result, CONNECTION_CLOSED)
}
await new Promise(resolve => setTimeout(resolve, 200))
assert.equal(clients.length, 1)
assert.equal(clients[0]._sock!.destroyed, true)
})
it('fails with HOST_KEY_MISMATCH on a wrong fingerprint', async () => {
const connection = createConnection({ hostKeyFingerprint: 'SHA256:AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA' })
await assert.rejects(connection.connect(), (error: DockerError) => {
assert.equal(error.code, HOST_KEY_MISMATCH)
assert.equal(error.data!.expected, 'SHA256:AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA')
assert.equal(error.data!.actual, fingerprint)
return true
})
})
it('fails with HOST_KEY_UNKNOWN without fingerprint', async () => {
const connection = createConnection({ hostKeyFingerprint: undefined })
await assert.rejects(connection.connect(), (error: DockerError) => {
assert.equal(error.code, HOST_KEY_UNKNOWN)
assert.equal(error.data!.fingerprint, fingerprint)
assert.equal(error.data!.algorithm, 'ssh-ed25519')
return true
})
assert.equal(connection.observedHostKey!.fingerprint, fingerprint)
})
it('accepts an unknown host key when asked to', async () => {
const connection = createConnection({ hostKeyFingerprint: undefined, acceptUnknownHostKey: true })
await connection.connect()
assert.equal(connection.observedHostKey!.fingerprint, fingerprint)
})
it('fails with SSH_AUTH_FAILED with a bad key', async () => {
const connection = createConnection({ privateKey: badPrivateKey })
await assert.rejects(connection.connect(), (error: DockerError) => {
assert.equal(error.code, SSH_AUTH_FAILED)
assert.doesNotMatch(JSON.stringify(error.data) + JSON.stringify(error.cause), /PRIVATE KEY/)
return true
})
})
it('fails with DOCKER_SOCKET_UNREACHABLE with a wrong socket path', async () => {
const connection = createConnection({ socketPath: '/xo-does-not-exist/docker.sock' })
await assert.rejects(connection.connect(), { code: DOCKER_SOCKET_UNREACHABLE })
})
it('fails with SSH_UNREACHABLE on a closed port', async () => {
const connection = createConnection({ port: await getClosedPort() })
await assert.rejects(connection.connect(), { code: SSH_UNREACHABLE })
})
it(
'fails with DOCKER_SOCKET_UNREACHABLE when stream local forwarding is disabled (OpenSSH answers CONNECT_FAILED)',
{ skip: noForwardingPort === undefined ? 'XO_DOCKER_TEST_SSH_NOFWD_PORT is not set' : false },
async () => {
const connection = createConnection({
port: Number(noForwardingPort),
hostKeyFingerprint: undefined,
acceptUnknownHostKey: true,
})
await assert.rejects(connection.connect(), (error: DockerError) => {
assert.equal(error.code, DOCKER_SOCKET_UNREACHABLE)
assert.equal(error.data!.reason, 2)
assert.equal(error.data!.description, 'open failed')
return true
})
}
)
})

File diff suppressed because it is too large Load Diff

View File

@@ -0,0 +1,967 @@
import assert from 'node:assert/strict'
import { EventEmitter, once } from 'node:events'
import { mkdtemp, rm } from 'node:fs/promises'
import { createServer, type IncomingMessage, type Server, type ServerResponse } from 'node:http'
import { connect as netConnect, type Socket } from 'node:net'
import { Duplex } from 'node:stream'
import { tmpdir } from 'node:os'
import { join } from 'node:path'
import test from 'node:test'
import {
compareApiVersions,
computeFingerprint,
DockerConnection,
getKeyAlgorithm,
MAX_API_VERSION,
negotiateApiVersion,
normalizeFingerprint,
parseFingerprint,
verifyHostKey,
type DockerConnectionOptions,
} from './connection.mjs'
import {
DOCKER_API_ERROR,
DOCKER_API_VERSION_UNSUPPORTED,
DOCKER_SOCKET_UNREACHABLE,
HOST_KEY_MISMATCH,
CONNECTION_CLOSED,
HOST_KEY_UNKNOWN,
SSH_AUTH_FAILED,
TIMEOUT,
type DockerError,
} from './errors.mjs'
import type { ClientCallback, ClientChannel, ConnectConfig } from 'ssh2'
const { after, before, beforeEach, describe, it } = test
// generated with `ssh-keygen -t ed25519`, fingerprints from `ssh-keygen -lf`
const ED25519_KEY = 'AAAAC3NzaC1lZDI1NTE5AAAAIDIKbtnnl0BlnKuKjKJoUJOsCWA910CX/XMkuMh4Ornr'
const ED25519_FINGERPRINT = 'SHA256:xo1L4JygV0hw5XQ+LHcn2iI3C9GvGsDRBNh+q7iQazs'
const RSA_KEY =
'AAAAB3NzaC1yc2EAAAADAQABAAAAgQDgLtqnXodwWvIQMujeXcGidrnppkGG5W+gk9bZHwi054aQfV3LNEZtq7wctk2EYeyVzZgFmcGOsfhu+L578Xe09zj92SovHsu9a+V1FxjAbRrnZMdG4bGSXyimSrGyM1XdzSs6dmh7gaX4DY2+peLkoAtObD6WwpvK0tfhYOFpkQ=='
const RSA_FINGERPRINT = 'SHA256:oADNJ8NlHsMYm0YHHYG3FN/qcWHowk7e/7L9V/Rm6yk'
describe('host key fingerprint', () => {
it('matches ssh-keygen -lf', () => {
assert.equal(computeFingerprint(Buffer.from(ED25519_KEY, 'base64')), ED25519_FINGERPRINT)
assert.equal(computeFingerprint(Buffer.from(RSA_KEY, 'base64')), RSA_FINGERPRINT)
})
it('extracts the key algorithm', () => {
assert.equal(getKeyAlgorithm(Buffer.from(ED25519_KEY, 'base64')), 'ssh-ed25519')
assert.equal(getKeyAlgorithm(Buffer.from(RSA_KEY, 'base64')), 'ssh-rsa')
assert.equal(getKeyAlgorithm(Buffer.from([0, 0, 0, 10, 1])), undefined)
})
it('normalizes user input', () => {
assert.equal(normalizeFingerprint(' xo1L4JygV0hw5XQ+LHcn2iI3C9GvGsDRBNh+q7iQazs= '), ED25519_FINGERPRINT)
assert.equal(normalizeFingerprint(ED25519_FINGERPRINT), ED25519_FINGERPRINT)
})
it('parses a whole ssh-keygen -l line, taking the algorithm from its type', () => {
const fp = ED25519_FINGERPRINT
assert.deepEqual(parseFingerprint(`256 ${fp} root@host (ED25519)`), { fingerprint: fp, algorithm: 'ssh-ed25519' })
assert.deepEqual(parseFingerprint(` 384 ${fp} a comment with spaces (ECDSA) `), {
fingerprint: fp,
algorithm: 'ecdsa-sha2-nistp384',
})
assert.deepEqual(parseFingerprint(`3072 ${fp} no comment (RSA)`), { fingerprint: fp, algorithm: 'ssh-rsa' })
assert.deepEqual(parseFingerprint(`256 ${fp} (ED25519)`), { fingerprint: fp, algorithm: 'ssh-ed25519' })
assert.deepEqual(parseFingerprint(`256 ${fp} (FOO)`), { fingerprint: fp, algorithm: undefined })
assert.deepEqual(parseFingerprint(fp.slice('SHA256:'.length) + '='), { fingerprint: fp, algorithm: undefined })
})
it('verifyHostKey() mentions the presented algorithm on HOST_KEY_MISMATCH', () => {
assert.throws(() => verifyHostKey(Buffer.from(RSA_KEY, 'base64'), { expectedFingerprint: ED25519_FINGERPRINT }), {
code: HOST_KEY_MISMATCH,
message: /\(ssh-rsa\)/,
})
})
it('verifyHostKey() accepts the expected key', () => {
assert.deepEqual(verifyHostKey(Buffer.from(ED25519_KEY, 'base64'), { expectedFingerprint: ED25519_FINGERPRINT }), {
fingerprint: ED25519_FINGERPRINT,
algorithm: 'ssh-ed25519',
})
})
it('verifyHostKey() rejects a missing fingerprint with HOST_KEY_UNKNOWN', () => {
assert.throws(
() => verifyHostKey(Buffer.from(ED25519_KEY, 'base64'), {}),
(error: DockerError) =>
error.code === HOST_KEY_UNKNOWN &&
error.data!.fingerprint === ED25519_FINGERPRINT &&
error.data!.algorithm === 'ssh-ed25519'
)
})
it('verifyHostKey() treats a null fingerprint as missing', () => {
assert.throws(() => verifyHostKey(Buffer.from(ED25519_KEY, 'base64'), { expectedFingerprint: null }), {
code: HOST_KEY_UNKNOWN,
})
})
it('verifyHostKey() accepts an unknown key when asked to', () => {
assert.equal(
verifyHostKey(Buffer.from(ED25519_KEY, 'base64'), { acceptUnknownHostKey: true }).fingerprint,
ED25519_FINGERPRINT
)
})
it('verifyHostKey() rejects another key with HOST_KEY_MISMATCH', () => {
assert.throws(
() => verifyHostKey(Buffer.from(ED25519_KEY, 'base64'), { expectedFingerprint: RSA_FINGERPRINT }),
(error: DockerError) =>
error.code === HOST_KEY_MISMATCH &&
error.data!.expected === RSA_FINGERPRINT &&
error.data!.actual === ED25519_FINGERPRINT
)
})
})
describe('DockerConnection (real ssh2 client, no network)', () => {
it('fails with SSH_AUTH_FAILED on an unparsable private key, without leaking it', async () => {
const connection = new DockerConnection({
host: '127.0.0.1',
username: 'user',
privateKey: 'not a key: TOP-SECRET',
passphrase: 'hunter2',
})
await assert.rejects(connection.connect(), (error: DockerError) => {
assert.equal(error.code, SSH_AUTH_FAILED)
assert.doesNotMatch(
JSON.stringify({ ...error, cause: error.cause, message: error.cause!.message }),
/TOP-SECRET|hunter2/
)
return true
})
// must not wait for a `close` which will never come
const start = Date.now()
await connection.close()
assert.ok(Date.now() - start < 1e3)
})
})
describe('negotiateApiVersion()', () => {
it('compares versions numerically', () => {
assert.ok(compareApiVersions('1.9', '1.10') < 0)
assert.ok(compareApiVersions('1.43', '1.43') === 0)
assert.ok(compareApiVersions('2.0', '1.99') > 0)
})
it('uses the lowest of the max versions', () => {
assert.equal(negotiateApiVersion({ ApiVersion: '1.47', MinAPIVersion: '1.24' }), MAX_API_VERSION)
assert.equal(negotiateApiVersion({ ApiVersion: '1.41', MinAPIVersion: '1.12' }), '1.41')
})
it('rejects a too old daemon', () => {
assert.throws(() => negotiateApiVersion({ ApiVersion: '1.23' }), { code: DOCKER_API_VERSION_UNSUPPORTED })
})
it("negotiates Podman's Docker-compatible API (ApiVersion 1.41, MinAPIVersion 1.24)", () => {
assert.equal(negotiateApiVersion({ ApiVersion: '1.41', MinAPIVersion: '1.24' }), '1.41')
})
it('negotiates 1.44 with Docker 29 (MinAPIVersion 1.44)', () => {
assert.equal(negotiateApiVersion({ ApiVersion: '1.52', MinAPIVersion: '1.44' }), '1.44')
})
it("uses the daemon's oldest version, with a warning, when it does not support our max version", () => {
const symbol = Symbol.for('@xen-orchestra/log')
const global = globalThis as unknown as Record<symbol, unknown>
const transport = global[symbol]
const logs: { level: number; message: string }[] = []
global[symbol] = (log: { level: number; message: string }) => logs.push(log)
try {
assert.equal(negotiateApiVersion({ ApiVersion: '1.52', MinAPIVersion: '1.45' }), '1.45')
} finally {
global[symbol] = transport
}
assert.equal(logs.length, 1)
assert.match(logs[0].message, /does not support the API version/)
})
it('ignores an inconsistent MinAPIVersion', () => {
assert.equal(negotiateApiVersion({ ApiVersion: '1.52', MinAPIVersion: '1.60' }), MAX_API_VERSION)
assert.equal(negotiateApiVersion({ ApiVersion: '1.52', MinAPIVersion: 'x' }), MAX_API_VERSION)
})
it('rejects an invalid answer', () => {
assert.throws(() => negotiateApiVersion({}), { code: DOCKER_API_VERSION_UNSUPPORTED })
})
})
/**
* Minimal stand-in for `ssh2.Client`: channels are plain connections to a
* local Unix socket.
*/
/**
* Mimic an ssh2 channel whose SSH connection is gone: writes are swallowed,
* nothing is ever received, and `destroy()` emits neither `close` nor `error`
* (like ssh2's Channel#destroy() once the connection is lost).
*/
function createDeadChannel() {
const channel = new Duplex({
read() {},
write(chunk, encoding, cb) {
cb()
},
})
channel.destroy = function (this: Duplex) {
return this
}
return channel
}
// what `DockerConnection` passes to ssh2: its `hostVerifier` is synchronous
type FakeConnectConfig = Omit<ConnectConfig, 'hostVerifier'> & { hostVerifier?: (keyBlob: Buffer) => boolean }
class FakeSshClient extends EventEmitter {
channels: Socket[] = []
channelsOpened = 0
connectConfig!: FakeConnectConfig
// host key presented to the host verifier (if any)
hostKey = Buffer.from(ED25519_KEY, 'base64')
deadChannels = false
// when false, end() does not emit close (unresponsive server)
endEmitsClose = true
openError: Error | undefined
_sock: { destroyed: boolean; destroy: () => boolean } = {
destroyed: false,
destroy: () => (this._sock.destroyed = true),
}
connect(config: FakeConnectConfig) {
this.connectConfig = config
process.nextTick(() => {
if (config.hostVerifier !== undefined && !config.hostVerifier(this.hostKey)) {
this.emit('error', Object.assign(new Error('Host denied (verification failed)'), { level: 'handshake' }))
this.emit('close')
return
}
this.emit('ready')
})
return this
}
openssh_forwardOutStreamLocal(socketPath: string, cb: (error: Error | undefined, channel: Duplex) => void) {
if (this.openError !== undefined) {
process.nextTick(cb, this.openError)
return this
}
++this.channelsOpened
if (this.deadChannels) {
process.nextTick(cb, undefined, createDeadChannel())
return this
}
const socket = netConnect(socketPath)
this.channels.push(socket)
socket.once('connect', () => cb(undefined, socket))
socket.once('error', cb)
return this
}
// what ssh2 does to its channels when the connection is lost: they emit
// `close` but stay writable
simulateDrop() {
for (const channel of this.channels) {
channel.removeAllListeners('data')
channel.pause()
channel.write = (chunk: unknown, encoding?: unknown, cb?: () => void) => {
if (typeof encoding === 'function') cb = encoding as () => void
cb?.()
return true
}
channel.destroy = function (this: Socket) {
return this
}
channel.emit('close')
}
this.channels = []
}
end() {
if (this.endEmitsClose) {
process.nextTick(() => this.emit('close'))
}
return this
}
// part of `SshClient`, replaced by the tests which use it
// eslint-disable-next-line @typescript-eslint/no-unused-vars
exec(command: string, cb: ClientCallback): this {
throw new Error('not implemented')
}
}
describe('DockerConnection (fake daemon)', () => {
let dir: string, socketPath: string, server: Server
let handler: (req: IncomingMessage, res: ServerResponse) => void, requests: string[]
before(async () => {
dir = await mkdtemp(join(tmpdir(), 'xo-docker-test-'))
socketPath = join(dir, 'docker.sock')
server = createServer((req, res) => {
requests.push(req.url!)
handler(req, res)
})
server.listen(socketPath)
await once(server, 'listening')
})
after(async () => {
server.closeAllConnections()
server.close()
await rm(dir, { recursive: true, force: true })
})
const json = (res: ServerResponse, statusCode: number, body: unknown) => {
res.writeHead(statusCode, { 'content-type': 'application/json' })
res.end(JSON.stringify(body))
}
const defaultHandler = (req: IncomingMessage, res: ServerResponse) => {
if (req.url === '/version') {
return json(res, 200, { Version: '27.3.1', ApiVersion: '1.47', MinAPIVersion: '1.24' })
}
if (req.url!.startsWith(`/v${MAX_API_VERSION}/containers/json`)) {
return json(res, 200, [{ Id: 'abc', Names: ['/foo'] }])
}
if (req.url === `/v${MAX_API_VERSION}/containers/missing/json`) {
return json(res, 404, { message: 'No such container: missing' })
}
if (req.url === `/v${MAX_API_VERSION}/echo`) {
const chunks: Buffer[] = []
req.on('data', chunk => chunks.push(chunk))
req.on('end', () => json(res, 201, { method: req.method, body: JSON.parse(Buffer.concat(chunks).toString()) }))
return
}
if (req.url === `/v${MAX_API_VERSION}/logs`) {
res.writeHead(200, { 'content-type': 'application/vnd.docker.raw-stream' })
res.end('line 1\nline 2\n')
return
}
if (req.url === `/v${MAX_API_VERSION}/stream`) {
// headers, then a body which never ends
res.writeHead(200, { 'content-type': 'application/json' })
res.write('{}\n')
return
}
if (req.url!.startsWith('/v1.40/raw') || req.url!.startsWith(`/v${MAX_API_VERSION}/raw`)) {
return json(res, 418, { url: req.url })
}
if (req.url === `/v${MAX_API_VERSION}/hang`) {
// never answers
return
}
res.writeHead(500)
res.end()
}
beforeEach(() => {
handler = defaultHandler
requests = []
})
const createConnection = (opts: Partial<DockerConnectionOptions> = {}) => {
const client = new FakeSshClient()
const connection = new DockerConnection(
{
host: 'fake',
username: 'user',
password: 'secret',
hostKeyFingerprint: ED25519_FINGERPRINT,
socketPath,
requestTimeout: 1e3,
...opts,
},
{ createClient: () => client }
)
return { client, connection }
}
it('exec() times out when the session channel is never opened, and drops a late one', async () => {
const { client, connection } = createConnection({ requestTimeout: 50 })
let callback: ClientCallback | undefined
client.exec = (command, cb) => {
callback = cb
return client
}
await assert.rejects(connection.exec('true'), { code: TIMEOUT })
let destroyed = false
const late = new Duplex({ read() {}, write: (chunk, encoding, cb) => cb() })
late.destroy = function (this: Duplex) {
destroyed = true
return this
}
callback!(undefined, late as unknown as ClientChannel)
assert.ok(destroyed)
await connection.close()
})
it('exec() ends stdin and collects the output', async () => {
const { client, connection } = createConnection()
let stdinEnded = false
client.exec = (command, cb) => {
const channel = Object.assign(
new Duplex({ read() {}, write: (chunk, encoding, cb) => cb(), final: cb => ((stdinEnded = true), cb()) }),
{ stderr: new EventEmitter() }
)
process.nextTick(cb, undefined, channel as unknown as ClientChannel)
setImmediate(() => {
channel.push('ok\n')
channel.emit('exit', 0)
channel.emit('close')
})
return client
}
assert.deepEqual(await connection.exec('true'), { code: 0, signal: undefined, stdout: 'ok\n', stderr: '' })
assert.ok(stdinEnded)
await connection.close()
})
it('reports a daemon closing the channel or answering garbage as DOCKER_API_ERROR', async () => {
const { connection } = createConnection()
await connection.connect()
handler = req => req.socket.destroy()
await assert.rejects(connection.request({ path: '/containers/json' }), { code: DOCKER_API_ERROR })
handler = req => req.socket.end('garbage\r\n\r\n')
await assert.rejects(connection.request({ path: '/containers/json' }), { code: DOCKER_API_ERROR })
await connection.close()
})
it('caps a buffered response at 8 MiB by default, maxSize allows more', async () => {
const { connection } = createConnection({ requestTimeout: 10e3 })
await connection.connect()
handler = (req, res) => {
res.writeHead(200, { 'content-type': 'application/octet-stream' })
res.end(Buffer.alloc(9 * 1024 * 1024))
}
await assert.rejects(connection.request({ path: '/big' }), { code: DOCKER_API_ERROR })
const { body } = await connection.request({ path: '/big', maxSize: 16 * 1024 * 1024 })
assert.equal((body as Buffer).length, 9 * 1024 * 1024)
await connection.close()
})
it('drops keep-alive channels closed by an SSH connection loss (still writable)', async () => {
const { client, connection } = createConnection()
await Promise.all([
connection.request({ path: '/containers/json' }),
connection.request({ path: '/containers/json' }),
])
const opened = client.channelsOpened
client.simulateDrop()
const results = await Promise.all([
connection.request({ path: '/containers/json' }),
connection.request({ path: '/containers/json' }),
])
for (const { statusCode } of results) {
assert.equal(statusCode, 200)
}
assert.ok(client.channelsOpened > opened)
await connection.close()
})
it('settles and releases the slot when a channel never emits close or error', async () => {
const { client, connection } = createConnection({ requestTimeout: 50 })
await connection.connect()
client.deadChannels = true
// the channel used by the negotiation is now dead too
client.simulateDrop()
// more than the max concurrency: leaked slots would make the last ones
// wait forever in the queue (they would still TIMEOUT, so check timing)
for (let i = 0; i < 10; ++i) {
const start = Date.now()
await assert.rejects(connection.request({ path: '/containers/json' }), { code: TIMEOUT })
assert.ok(Date.now() - start < 1e3)
}
client.deadChannels = false
connection.request({ path: '/containers/json' }).catch(() => {})
// a free slot is available immediately
const { statusCode } = await connection.request({ path: '/containers/json', signal: AbortSignal.timeout(1e3) })
assert.equal(statusCode, 200)
await connection.close()
})
it('close() destroys the SSH socket when the server does not close the connection', async () => {
const client = new FakeSshClient()
client.endEmitsClose = false
const connection = new DockerConnection(
{ host: 'fake', username: 'user', hostKeyFingerprint: ED25519_FINGERPRINT, socketPath },
{ createClient: () => client, closeTimeout: 50 }
)
await connection.connect()
await connection.close()
assert.equal(client._sock.destroyed, true)
})
it('close() rejects queued and in-flight requests with CONNECTION_CLOSED and does not reconnect', async () => {
handler = (req: IncomingMessage, res: ServerResponse) =>
req.url === '/version' ? defaultHandler(req, res) : setTimeout(() => json(res, 200, {}), 300).unref()
let clients = 0
const connection = new DockerConnection(
{ host: 'fake', username: 'user', hostKeyFingerprint: ED25519_FINGERPRINT, socketPath, requestTimeout: 5e3 },
{
createClient: () => {
++clients
return new FakeSshClient()
},
}
)
await connection.connect()
const results = Array.from({ length: 12 }, () =>
connection.request({ path: '/slow' }).then(
() => 'ok',
error => error.code
)
)
await new Promise(resolve => setTimeout(resolve, 50))
await connection.close()
assert.deepEqual(await Promise.all(results), Array(12).fill(CONNECTION_CLOSED))
assert.equal(clients, 1)
await connection.close()
})
it('accepts an unknown host key via acceptUnknownHostKey, without requesting an algorithm', async () => {
const client = new FakeSshClient()
const connection = new DockerConnection(
{ host: 'fake', username: 'user', socketPath, acceptUnknownHostKey: true, hostKeyFingerprint: null },
{ createClient: () => client }
)
await connection.connect()
assert.equal(client.connectConfig.algorithms, undefined)
assert.equal(connection.observedHostKey!.fingerprint, ED25519_FINGERPRINT)
await connection.close()
})
it('requests the configured host key algorithm', async () => {
const { client, connection } = createConnection({
hostKeyAlgorithm: 'ssh-rsa',
hostKeyFingerprint: RSA_FINGERPRINT,
})
client.hostKey = Buffer.from(RSA_KEY, 'base64')
await connection.connect()
assert.deepEqual(client.connectConfig.algorithms, { serverHostKey: ['rsa-sha2-512', 'rsa-sha2-256', 'ssh-rsa'] })
await connection.close()
})
it('maps a missing host key type to HOST_KEY_MISMATCH when the algorithm is pinned', async () => {
const { client, connection } = createConnection({
hostKeyAlgorithm: 'ssh-rsa',
hostKeyFingerprint: RSA_FINGERPRINT,
})
client.connect = function (this: FakeSshClient, config: FakeConnectConfig) {
this.connectConfig = config
process.nextTick(() => {
this.emit(
'error',
Object.assign(new Error('Handshake failed: no matching host key format'), { level: 'handshake' })
)
this.emit('close')
})
return this
}
await assert.rejects(connection.connect(), (error: DockerError) => {
assert.equal(error.code, HOST_KEY_MISMATCH)
assert.equal(error.data!.expectedAlgorithm, 'ssh-rsa')
return true
})
})
it('treats a null hostKeyFingerprint as missing (HOST_KEY_UNKNOWN)', async () => {
const { connection } = createConnection({ hostKeyFingerprint: null })
await assert.rejects(connection.connect(), (error: DockerError) => {
assert.equal(error.code, HOST_KEY_UNKNOWN)
assert.equal(error.data!.fingerprint, ED25519_FINGERPRINT)
return true
})
})
it('the caller signal interrupts a pending API version negotiation', async () => {
handler = () => {}
const { connection } = createConnection({ requestTimeout: 10e3 })
const start = Date.now()
await assert.rejects(connection.request({ path: '/info', signal: AbortSignal.timeout(100) }), { code: TIMEOUT })
assert.ok(Date.now() - start < 1e3)
await connection.close()
})
it('negotiates with Podman (API 1.41) and tells it from Docker', async () => {
handler = (req: IncomingMessage, res: ServerResponse) =>
req.url === '/version'
? json(res, 200, {
Version: '5.4.2',
ApiVersion: '1.41',
MinAPIVersion: '1.24',
Platform: { Name: 'linux/amd64/debian-13' },
Components: [{ Name: 'Podman Engine', Version: '5.4.2', Details: { MinAPIVersion: '4.0.0' } }],
})
: json(res, 200, req.url)
const { connection } = createConnection()
assert.equal(connection.engineKind, undefined)
const { body } = await connection.request({ path: '/info' })
assert.equal(body, '/v1.41/info')
assert.equal(connection.apiVersion, '1.41')
assert.equal(connection.engineKind, 'podman')
await connection.close()
})
it('reports TIMEOUT (not DOCKER_API_ERROR) when aborted while reading an error body', async () => {
handler = (req: IncomingMessage, res: ServerResponse) => {
if (req.url === '/version') {
return defaultHandler(req, res)
}
res.writeHead(500, { 'content-type': 'application/json' })
res.write('{"message":')
// never ends
}
const { connection } = createConnection({ requestTimeout: 200 })
await connection.connect()
await assert.rejects(connection.request({ path: '/info' }), { code: TIMEOUT })
await assert.rejects(connection.requestStream({ path: '/info' }), { code: TIMEOUT })
await connection.close()
})
it('configures ssh2 as expected', async () => {
const { client, connection } = createConnection()
await connection.connect()
const { connectConfig } = client
assert.equal(connectConfig.port, 22)
assert.equal(connectConfig.keepaliveInterval, 10e3)
assert.equal(connectConfig.keepaliveCountMax, 3)
assert.equal(connectConfig.hostHash, undefined)
assert.equal(typeof connectConfig.hostVerifier, 'function')
assert.equal(connectConfig.hostVerifier!(Buffer.from(ED25519_KEY, 'base64')), true)
assert.equal(connectConfig.hostVerifier!(Buffer.from(RSA_KEY, 'base64')), false)
assert.equal(connection.observedHostKey!.fingerprint, RSA_FINGERPRINT)
await connection.close()
})
it('negotiates the API version once and prefixes paths', async () => {
const { connection } = createConnection()
const results = await Promise.all([
connection.request({ path: '/containers/json', query: { all: 1, filters: { status: ['running'] } } }),
connection.request({ path: '/containers/json' }),
connection.request({ path: '/containers/json' }),
])
assert.equal(connection.apiVersion, MAX_API_VERSION)
assert.equal(connection.engineVersion, '27.3.1')
assert.equal(connection.engineKind, 'docker')
assert.equal(requests.filter(url => url === '/version').length, 1)
assert.equal(
requests.find(url => url.includes('filters')),
`/v${MAX_API_VERSION}/containers/json?all=1&filters=%7B%22status%22%3A%5B%22running%22%5D%7D`
)
for (const { statusCode, body } of results) {
assert.equal(statusCode, 200)
assert.deepEqual(body, [{ Id: 'abc', Names: ['/foo'] }])
}
await connection.close()
})
it('uses the daemon version when lower than ours', async () => {
handler = (req: IncomingMessage, res: ServerResponse) =>
req.url === '/version'
? json(res, 200, { Version: '20.10.0', ApiVersion: '1.41', MinAPIVersion: '1.12' })
: json(res, 200, { url: req.url })
const { connection } = createConnection()
const { body } = await connection.request({ path: '/info' })
assert.equal((body as { url: string }).url, '/v1.41/info')
await connection.close()
})
it('fails with DOCKER_API_VERSION_UNSUPPORTED and retries negotiation later', async () => {
handler = (req: IncomingMessage, res: ServerResponse) => json(res, 200, { Version: '1.11', ApiVersion: '1.23' })
const { connection } = createConnection()
await assert.rejects(connection.connect(), { code: DOCKER_API_VERSION_UNSUPPORTED })
await assert.rejects(connection.request({ path: '/info' }), { code: DOCKER_API_VERSION_UNSUPPORTED })
assert.equal(requests.filter(url => url === '/version').length, 2)
await connection.close()
})
it('reuses channels across sequential requests (keep-alive)', async () => {
const { client, connection } = createConnection()
for (let i = 0; i < 5; ++i) {
await connection.request({ path: '/containers/json' })
}
// 1 for /version + 5 requests, all on the same channel
assert.equal(requests.length, 6)
assert.equal(client.channelsOpened, 1)
await connection.close()
})
it('opens several channels for concurrent requests', async () => {
const { client, connection } = createConnection()
await connection.connect()
await Promise.all(Array.from({ length: 10 }, () => connection.request({ path: '/containers/json' })))
// bounded by maxSockets
assert.ok(client.channelsOpened > 1 && client.channelsOpened <= 8, `${client.channelsOpened} channels`)
await connection.close()
})
it('sends JSON bodies', async () => {
const { connection } = createConnection()
const { statusCode, body } = await connection.request({ method: 'POST', path: '/echo', body: { foo: 'bar' } })
assert.equal(statusCode, 201)
assert.deepEqual(body, { method: 'POST', body: { foo: 'bar' } })
await connection.close()
})
it('returns a Buffer for non-JSON responses', async () => {
const { connection } = createConnection()
const { body } = await connection.request({ path: '/logs' })
assert.ok(Buffer.isBuffer(body))
assert.equal(body.toString(), 'line 1\nline 2\n')
await connection.close()
})
it('streams responses', async () => {
const { connection } = createConnection()
const response = await connection.requestStream({ path: '/logs' })
const chunks = []
for await (const chunk of response) {
chunks.push(chunk)
}
assert.equal(Buffer.concat(chunks).toString(), 'line 1\nline 2\n')
await connection.close()
})
it('long-lived streams do not use the request slots (phase 4)', async () => {
const { client, connection } = createConnection()
await connection.connect()
const streams = await Promise.all(
Array.from({ length: 20 }, () => connection.requestStream({ path: '/stream', longLived: true }))
)
// closing the connection aborts them
streams.forEach(stream => stream.on('error', () => {}))
assert.deepEqual(connection.activeRequests, { requests: 0, streams: 20 })
// one channel per stream, on the same SSH connection
assert.ok(client.channelsOpened >= 21, `${client.channelsOpened} channels`)
// the regular requests are not starved
await Promise.all(Array.from({ length: 10 }, () => connection.request({ path: '/containers/json' })))
// a stream releases its slot when destroyed, and its channel is not reused
streams[0].destroy()
await once(streams[0], 'close')
assert.equal(connection.activeRequests.streams, 19)
await connection.close()
// not `once()`: it rejects on `error`
await Promise.all(
streams.slice(1).map(stream => (stream.closed ? undefined : new Promise(resolve => stream.on('close', resolve))))
)
assert.deepEqual(connection.activeRequests, { requests: 0, streams: 0 })
})
it('raw requests: verbatim path and query, version prefix unless present, errors returned (phase 4)', async () => {
const { connection } = createConnection()
const read = async (response: IncomingMessage) => {
const chunks: Buffer[] = []
for await (const chunk of response) {
chunks.push(chunk)
}
return JSON.parse(Buffer.concat(chunks).toString())
}
let response = await connection.requestStream({ path: '/raw?a=1&b=%2F', raw: true, longLived: true })
assert.equal(response.statusCode, 418)
assert.deepEqual(await read(response), { url: `/v${MAX_API_VERSION}/raw?a=1&b=%2F` })
response = await connection.requestStream({ path: '/v1.40/raw', raw: true })
assert.deepEqual(await read(response), { url: '/v1.40/raw' })
await connection.close()
})
it('fails with DOCKER_API_ERROR on non-2xx', async () => {
const { connection } = createConnection()
await assert.rejects(connection.request({ path: '/containers/missing/json' }), (error: DockerError) => {
assert.equal(error.code, DOCKER_API_ERROR)
assert.equal(error.data!.statusCode, 404)
assert.equal(error.message, 'No such container: missing')
return true
})
await assert.rejects(connection.requestStream({ path: '/containers/missing/json' }), {
code: DOCKER_API_ERROR,
data: {
host: 'fake',
port: 22,
socketPath,
path: '/containers/missing/json',
statusCode: 404,
message: 'No such container: missing',
},
})
await connection.close()
})
it('reads at most 4 KiB of an error body and truncates the message (hostile daemon)', async () => {
let written = 0
handler = (req: IncomingMessage, res: ServerResponse) => {
if (req.url === '/version') {
return defaultHandler(req, res)
}
if (req.url!.endsWith('/object')) {
return json(res, 500, { message: { toString: 'x' } })
}
if (req.url!.endsWith('/text')) {
res.writeHead(500, { 'content-type': 'text/plain' })
return res.end('y'.repeat(3000))
}
// a never-ending JSON error body
res.writeHead(500, { 'content-type': 'application/json' })
res.write('{"message":"')
const chunk = 'x'.repeat(64 * 1024)
const write = () => {
let more = true
while (more && !res.destroyed && written < 100 * 1024 * 1024) {
written += chunk.length
more = res.write(chunk)
}
if (!more) {
res.once('drain', write)
}
}
write()
}
const { connection } = createConnection({ requestTimeout: 5e3 })
await connection.connect()
const start = Date.now()
for (const call of [
() => connection.request({ path: '/flood' }),
() => connection.requestStream({ path: '/flood' }),
]) {
await assert.rejects(call(), (error: DockerError) => {
assert.equal(error.code, DOCKER_API_ERROR)
assert.equal(error.data!.statusCode, 500)
assert.ok(written < 10 * 1024 * 1024, `${written} bytes written by the daemon`)
assert.ok(error.message.length <= 1024, `message of ${error.message.length} chars`)
assert.ok((error.data!.message as string).length <= 1024)
return true
})
}
assert.ok(Date.now() - start < 2e3, 'does not wait for the whole body')
assert.ok(written < 10 * 1024 * 1024, `${written} bytes written by the daemon`)
await assert.rejects(connection.request({ path: '/object' }), (error: DockerError) => {
assert.equal(error.message, 'Docker API error 500')
assert.equal(error.data!.message, undefined)
return true
})
await assert.rejects(connection.request({ path: '/text' }), (error: DockerError) => {
assert.ok(error.message.length <= 1024)
assert.match(error.message, /^y+…$/)
return true
})
// still usable
handler = defaultHandler
await connection.request({ path: '/containers/json' })
await connection.close()
})
it('times out with TIMEOUT (requestTimeout)', async () => {
const { connection } = createConnection({ requestTimeout: 200 })
await connection.connect()
const start = Date.now()
await assert.rejects(connection.request({ path: '/hang' }), { code: TIMEOUT })
const duration = Date.now() - start
assert.ok(duration >= 150 && duration < 1e3, `${duration}ms`)
await assert.rejects(connection.requestStream({ path: '/hang' }), { code: TIMEOUT })
// the connection is still usable
await connection.request({ path: '/containers/json' })
await connection.close()
})
it('aborts with TIMEOUT (caller signal)', async () => {
const { connection } = createConnection({ requestTimeout: 10e3 })
await connection.connect()
const controller = new AbortController()
setTimeout(() => controller.abort(), 50)
await assert.rejects(connection.request({ path: '/hang', signal: controller.signal }), { code: TIMEOUT })
await assert.rejects(connection.request({ path: '/hang', signal: AbortSignal.abort() }), { code: TIMEOUT })
await connection.close()
})
it('maps channel open failures', async () => {
const { client, connection } = createConnection()
client.openError = Object.assign(new Error('(SSH) Channel open failure: open failed'), { reason: 2 })
await assert.rejects(connection.connect(), (error: DockerError) => {
assert.equal(error.code, DOCKER_SOCKET_UNREACHABLE)
assert.equal(error.data!.socketPath, socketPath)
assert.doesNotMatch(JSON.stringify(error.data), /secret/)
return true
})
await connection.close()
})
it('one instance = one SSH session: never reconnects after close()', async () => {
let clients = 0
const connection = new DockerConnection(
{ host: 'fake', username: 'user', hostKeyFingerprint: ED25519_FINGERPRINT, socketPath },
{
createClient: () => {
++clients
return new FakeSshClient()
},
}
)
await connection.request({ path: '/containers/json' })
await connection.close()
assert.equal(connection.closed, true)
await assert.rejects(connection.request({ path: '/containers/json' }), { code: CONNECTION_CLOSED })
await assert.rejects(connection.connect(), { code: CONNECTION_CLOSED })
assert.equal(clients, 1)
})
it('a lost SSH session closes the connection: requests fail with CONNECTION_CLOSED, onClose() is called once', async () => {
handler = (req: IncomingMessage, res: ServerResponse) =>
req.url === '/version' ? defaultHandler(req, res) : setTimeout(() => json(res, 200, {}), 300).unref()
let clients = 0
let client!: FakeSshClient
const connection = new DockerConnection(
{ host: 'fake', username: 'user', hostKeyFingerprint: ED25519_FINGERPRINT, socketPath, requestTimeout: 5e3 },
{
createClient: () => {
++clients
return (client = new FakeSshClient())
},
}
)
let closes = 0
connection.onClose(() => ++closes)
await connection.connect()
// in-flight (8) and queued (4) requests
const results = Array.from({ length: 12 }, () =>
connection.request({ path: '/slow' }).then(
() => 'ok',
error => error.code
)
)
await new Promise(resolve => setTimeout(resolve, 50))
client.emit('close')
assert.deepEqual(await Promise.all(results), Array(12).fill(CONNECTION_CLOSED))
assert.equal(connection.closed, true)
assert.deepEqual(connection.activeRequests, { requests: 0, streams: 0 })
await assert.rejects(connection.request({ path: '/containers/json' }), { code: CONNECTION_CLOSED })
await connection.close()
assert.equal(closes, 1)
assert.equal(clients, 1)
})
it('a failed SSH connection is not retried by the same instance', async () => {
let clients = 0
const connection = new DockerConnection(
{ host: 'fake', username: 'user', socketPath, hostKeyFingerprint: null },
{
createClient: () => {
++clients
return new FakeSshClient()
},
}
)
let closes = 0
connection.onClose(() => ++closes)
await assert.rejects(connection.connect(), { code: HOST_KEY_UNKNOWN })
await assert.rejects(connection.request({ path: '/containers/json' }), { code: HOST_KEY_UNKNOWN })
assert.equal(clients, 1)
await connection.close()
assert.equal(closes, 0)
})
})

View File

@@ -0,0 +1,145 @@
// Cooldown of the SSH attempts which failed in a way that OpenSSH (>= 9.8)
// penalizes with PerSourcePenalties: authentication failures, and handshakes
// aborted before authentication (host key refused, connection lost…).
//
// Too many of them in a short window make the SSH server refuse every
// connection from XO's address, for all the engines behind it. After such a
// failure, new manual attempts (create, update, test) with the *same*
// parameters are refused locally for `cooldown` ms (SSH_COOLDOWN); changing
// the parameters (e.g. fixing the key) is allowed right away.
//
// It also recognizes the symptom of a penalty: the server closing the
// connection before the handshake (`Connection lost before handshake`) soon
// after failures from XO → SSH_REFUSED_PENALTY with a hint.
//
// Keys are opaque strings (e.g. `engine:<id>`, `target:<host>:<port>`), the
// identity is an opaque hash of the attempt's parameters.
import {
DockerError,
HOST_KEY_MISMATCH,
HOST_KEY_UNKNOWN,
isDockerError,
SSH_AUTH_FAILED,
SSH_COOLDOWN,
SSH_ERROR,
SSH_REFUSED_PENALTY,
} from './errors.mjs'
export const DEFAULT_COOLDOWN = 10e3
// OpenSSH's default maximum penalty (`PerSourcePenalties max:600`)
export const DEFAULT_PENALTY_WINDOW = 10 * 60e3
// errors which, raised while connecting, arm the cooldown
const TRIGGER_CODES = new Set([HOST_KEY_MISMATCH, HOST_KEY_UNKNOWN, SSH_AUTH_FAILED, SSH_ERROR, SSH_REFUSED_PENALTY])
const PENALTY_HINT =
'the SSH server closed the connection before the handshake: the SSH server may be temporarily refusing this address (OpenSSH PerSourcePenalties), after recent failed attempts from XO'
const isHandshakeLoss = (error: unknown): boolean =>
isDockerError(error) &&
error.code === SSH_ERROR &&
typeof error.cause?.message === 'string' &&
error.cause.message.startsWith('Connection lost before handshake')
export class SshCooldown {
#cooldown: number
// key → { identity, code, until }
#entries = new Map<string, { identity: string; code: string; until: number }>()
// key → time of the last failure (any identity)
#lastFailures = new Map<string, number>()
#now: () => number
#penaltyWindow: number
/**
* @param opts.cooldown ms, 0 disables the refusal (not the SSH_REFUSED_PENALTY mapping)
* @param opts.penaltyWindow ms after a failure during which a lost handshake is reported as SSH_REFUSED_PENALTY
* @param opts.now for tests
*/
constructor({
cooldown = DEFAULT_COOLDOWN,
penaltyWindow = DEFAULT_PENALTY_WINDOW,
now = Date.now,
}: { cooldown?: number; penaltyWindow?: number; now?: () => number } = {}) {
this.#cooldown = cooldown
this.#penaltyWindow = penaltyWindow
this.#now = now
}
/** number of tracked keys, for tests */
get size(): number {
return new Set([...this.#entries.keys(), ...this.#lastFailures.keys()]).size
}
#prune(now: number) {
for (const [key, entry] of this.#entries) {
if (entry.until <= now) {
this.#entries.delete(key)
}
}
for (const [key, time] of this.#lastFailures) {
if (time + this.#penaltyWindow <= now) {
this.#lastFailures.delete(key)
}
}
}
/**
* @throws {DockerError} SSH_COOLDOWN if one of the keys failed recently with the same identity
*/
check(keys: string[], identity: string): void {
const now = this.#now()
this.#prune(now)
let until = 0
let code: string | undefined
for (const key of keys) {
const entry = this.#entries.get(key)
if (entry !== undefined && entry.identity === identity && entry.until > until) {
until = entry.until
code = entry.code
}
}
if (until !== 0) {
const retryAfter = Math.max(1, Math.ceil((until - now) / 1e3))
throw new DockerError(
SSH_COOLDOWN,
`a recent SSH attempt with the same parameters failed (${code}): retry in ${retryAfter} s, or change the parameters`,
{ data: { lastCode: code, retryAt: until, retryAfter } }
)
}
}
/**
* Record a connection failure, and convert it if it looks like a penalty.
*
* @returns the error to throw instead of `error`
*/
onFailure<E>(keys: string[], identity: string, error: E): E | DockerError {
if (!isDockerError(error) || !TRIGGER_CODES.has(error.code) || error.data?.failFast) {
return error
}
const now = this.#now()
this.#prune(now)
let result: DockerError = error
if (isHandshakeLoss(error) && keys.some(key => this.#lastFailures.has(key))) {
result = new DockerError(SSH_REFUSED_PENALTY, PENALTY_HINT, { data: error.data, cause: error.cause })
}
for (const key of keys) {
this.#lastFailures.set(key, now)
if (this.#cooldown > 0) {
this.#entries.set(key, { identity, code: result.code, until: now + this.#cooldown })
}
}
return result
}
/**
* Forget the cooldown of keys after a success (not the failure history: a
* penalty may still be running for other parameters).
*/
clear(keys: string[]): void {
for (const key of keys) {
this.#entries.delete(key)
}
}
}

View File

@@ -0,0 +1,108 @@
import assert from 'node:assert/strict'
import { describe, it } from 'node:test'
import { SshCooldown } from './cooldown.mjs'
import {
DOCKER_SOCKET_UNREACHABLE,
DockerError,
HOST_KEY_UNKNOWN,
SSH_AUTH_FAILED,
SSH_COOLDOWN,
SSH_ERROR,
SSH_REFUSED_PENALTY,
SSH_UNREACHABLE,
} from './errors.mjs'
const createClock = (start = 1e6) => {
const clock = () => clock.time
clock.time = start
return clock
}
const authFailed = () => new DockerError(SSH_AUTH_FAILED, 'SSH authentication failed')
const lostHandshake = () =>
new DockerError(SSH_ERROR, 'SSH error', { cause: new Error('Connection lost before handshake') })
describe('SshCooldown', () => {
it('refuses the same identity for the cooldown after an authentication failure, not another one', () => {
const now = createClock()
const cooldown = new SshCooldown({ cooldown: 10e3, now })
const keys = ['engine:a', 'target:h:22']
assert.equal(cooldown.onFailure(keys, 'id1', authFailed()).code, SSH_AUTH_FAILED)
now.time += 4e3
assert.throws(
() => cooldown.check(keys, 'id1'),
(error: DockerError) => {
assert.equal(error.code, SSH_COOLDOWN)
assert.equal(error.data!.lastCode, SSH_AUTH_FAILED)
assert.equal(error.data!.retryAfter, 6)
assert.equal(error.data!.retryAt, 1e6 + 10e3)
return true
}
)
// same address, other engine, same identity: refused through the target key
assert.throws(() => cooldown.check(['engine:b', 'target:h:22'], 'id1'), { code: SSH_COOLDOWN })
// parameters changed: allowed
cooldown.check(keys, 'id2')
now.time += 6e3
cooldown.check(keys, 'id1')
})
it('only authentication, host key and handshake failures arm it, and not the fail-fast copies', () => {
const cooldown = new SshCooldown({ now: createClock() })
for (const code of [SSH_UNREACHABLE, DOCKER_SOCKET_UNREACHABLE]) {
cooldown.onFailure(['k'], 'id', new DockerError(code, code))
}
cooldown.onFailure(['k'], 'id', new DockerError(SSH_AUTH_FAILED, 'x', { data: { failFast: true } }))
cooldown.onFailure(['k'], 'id', new Error('not a DockerError'))
cooldown.check(['k'], 'id')
cooldown.onFailure(['k'], 'id', new DockerError(HOST_KEY_UNKNOWN, 'unknown'))
assert.throws(() => cooldown.check(['k'], 'id'), { code: SSH_COOLDOWN })
})
it('a success clears it', () => {
const cooldown = new SshCooldown({ now: createClock() })
cooldown.onFailure(['k'], 'id', authFailed())
cooldown.clear(['k'])
cooldown.check(['k'], 'id')
})
it('cooldown 0 disables the refusal', () => {
const cooldown = new SshCooldown({ cooldown: 0, now: createClock() })
cooldown.onFailure(['k'], 'id', authFailed())
cooldown.check(['k'], 'id')
})
it('a handshake lost soon after failures → SSH_REFUSED_PENALTY with a hint, not without history', () => {
const now = createClock()
const cooldown = new SshCooldown({ cooldown: 0, penaltyWindow: 60e3, now })
// no history: kept as is
assert.equal(cooldown.onFailure(['target:h:22'], 'id', lostHandshake()).code, SSH_ERROR)
now.time += 61e3
cooldown.onFailure(['target:h:22'], 'id', authFailed())
now.time += 30e3
const error = cooldown.onFailure(['target:h:22', 'engine:x'], 'other', lostHandshake())
assert.equal(error.code, SSH_REFUSED_PENALTY)
assert.match(error.message, /temporarily refusing this address \(OpenSSH PerSourcePenalties\)/)
assert.equal(error.cause!.message, 'Connection lost before handshake')
// outside the window
now.time += 61e3
assert.equal(cooldown.onFailure(['target:h:22'], 'id', lostHandshake()).code, SSH_ERROR)
})
it('prunes the expired entries', () => {
const now = createClock()
const cooldown = new SshCooldown({ cooldown: 1e3, penaltyWindow: 5e3, now })
cooldown.onFailure(['a', 'b'], 'id', authFailed())
assert.equal(cooldown.size, 2)
now.time += 5e3
cooldown.check(['c'], 'id')
assert.equal(cooldown.size, 0)
})
})

File diff suppressed because it is too large Load Diff

View File

@@ -0,0 +1,226 @@
// Error codes of the Docker transport (SSH → docker.sock).
//
// They are stable identifiers meant to be consumed by the API/UI, the message
// is only informative.
export const SSH_AUTH_FAILED = 'SSH_AUTH_FAILED'
export const SSH_UNREACHABLE = 'SSH_UNREACHABLE'
// generic SSH failure which does not fit in a more specific code (protocol
// error, handshake failure, disconnection by the server…)
export const SSH_ERROR = 'SSH_ERROR'
// the SSH server closed the connection before the handshake shortly after
// other failures from XO: probably OpenSSH's PerSourcePenalties (>= 9.8)
// refusing XO's address for a while
export const SSH_REFUSED_PENALTY = 'SSH_REFUSED_PENALTY'
// refused locally, without connecting: a recent attempt with the same
// parameters failed (authentication, host key, handshake), see
// `docker.authFailureCooldown`; `data.retryAfter` is in seconds
export const SSH_COOLDOWN = 'SSH_COOLDOWN'
export const HOST_KEY_UNKNOWN = 'HOST_KEY_UNKNOWN'
export const HOST_KEY_MISMATCH = 'HOST_KEY_MISMATCH'
export const STREAM_LOCAL_FORWARDING_DISABLED = 'STREAM_LOCAL_FORWARDING_DISABLED'
export const DOCKER_SOCKET_UNREACHABLE = 'DOCKER_SOCKET_UNREACHABLE'
// the SSH server is not (detected as) OpenSSH, `direct-streamlocal@openssh.com`
// cannot be used
export const STREAM_LOCAL_UNSUPPORTED = 'STREAM_LOCAL_UNSUPPORTED'
export const DOCKER_API_ERROR = 'DOCKER_API_ERROR'
export const DOCKER_API_VERSION_UNSUPPORTED = 'DOCKER_API_VERSION_UNSUPPORTED'
export const TIMEOUT = 'TIMEOUT'
export const POOL_EXHAUSTED = 'POOL_EXHAUSTED'
// the request was interrupted (or never sent) because `close()` was called
export const CONNECTION_CLOSED = 'CONNECTION_CLOSED'
// raw passthrough: the request body exceeds `docker.maxRawRequestSize`
export const RAW_REQUEST_TOO_LARGE = 'RAW_REQUEST_TOO_LARGE'
// raw passthrough: the response exceeds `docker.maxRawResponseSize`
export const RAW_RESPONSE_TOO_LARGE = 'RAW_RESPONSE_TOO_LARGE'
// SSH_MSG_CHANNEL_OPEN_FAILURE reason codes (RFC 4254 § 5.1)
export const SSH_OPEN_ADMINISTRATIVELY_PROHIBITED = 1
export const SSH_OPEN_CONNECT_FAILED = 2
// keys which must never end up in an error (data or cause)
const SENSITIVE_KEYS = new Set(['passphrase', 'password', 'privateKey', 'authHandler', 'agent', 'sock'])
/**
* Returns a shallow copy of `value` without any sensitive entries.
*/
export function scrub(value: unknown): unknown {
if (value === null || typeof value !== 'object' || Buffer.isBuffer(value)) {
return value
}
if (Array.isArray(value)) {
return value.map(scrub)
}
const result: Record<string, unknown> = {}
for (const key of Object.keys(value)) {
if (!SENSITIVE_KEYS.has(key)) {
result[key] = scrub((value as Record<string, unknown>)[key])
}
}
return result
}
/**
* Error kept as the `cause` of a DockerError: a clean copy of the original one
* (see `sanitizeCause()`), with the diagnosis fields of ssh2 and Node errors
* (`code`, `level`, `reason`…).
*/
export type DockerErrorCause = Error & Record<string, unknown>
// fields of an ssh2 (or Node) error kept by `sanitizeCause()`
const CAUSE_KEYS = ['code', 'level', 'reason', 'description', 'errno', 'syscall', 'address', 'port', 'fatal'] as const
/**
* Copy of an ssh2 error that only keeps the fields useful for diagnosis.
*
* ssh2 errors do not reference the connection config in this version but
* nothing prevents a future version (or some intermediate code) to attach it,
* so rebuild a clean error instead of keeping the original object.
*/
function sanitizeCause(error: unknown): DockerErrorCause | undefined {
if (error === undefined || error === null) {
return undefined
}
if (!(error instanceof Error)) {
return new Error(String(error)) as DockerErrorCause
}
const copy = new Error(error.message) as DockerErrorCause
copy.name = error.name
copy.stack = error.stack
for (const key of CAUSE_KEYS) {
const value = (error as DockerErrorCause)[key]
if (value !== undefined) {
copy[key] = value
}
}
if (error.cause !== undefined) {
copy.cause = sanitizeCause(error.cause)
}
return copy
}
/** Non-sensitive details of a DockerError (sensitive keys are removed, see `scrub()`) */
export type DockerErrorData = Record<string, unknown>
export class DockerError extends Error {
// `declare`: no class fields, which would define the properties (even
// `undefined` ones) before the constructor assigns them
declare code: string
declare data?: DockerErrorData
declare cause?: DockerErrorCause
/**
* @param code one of the exported codes
*/
constructor(code: string, message: string, { data, cause }: { data?: object; cause?: unknown } = {}) {
const sanitizedCause = sanitizeCause(cause)
super(message, sanitizedCause === undefined ? undefined : { cause: sanitizedCause })
this.name = 'DockerError'
this.code = code
if (data !== undefined) {
this.data = scrub(data) as DockerErrorData
}
}
}
export const isDockerError = (error: unknown): error is DockerError => error instanceof DockerError
// the properties of an unknown error which are looked at (reading them on a
// primitive gives `undefined`)
type ErrorLike = { name?: unknown; message?: unknown; level?: unknown; reason?: unknown } | null | undefined
const isAbortOrTimeout = (error: unknown) =>
(error as ErrorLike)?.name === 'AbortError' || (error as ErrorLike)?.name === 'TimeoutError'
/**
* Convert an error raised by ssh2 (or by the transport around it) to a
* DockerError.
*
* Already converted errors are returned as is.
*
* @param context non-sensitive context added to `data`
*/
export function fromSshError(
error: unknown,
context: { host?: string; port?: number; socketPath?: string } = {}
): DockerError {
if (isDockerError(error)) {
return error
}
const data: DockerErrorData = { ...context }
const errorLike = error as ErrorLike
if (isAbortOrTimeout(error)) {
return new DockerError(TIMEOUT, 'operation timed out or was aborted', { data, cause: error })
}
const level = errorLike?.level
if (level === 'client-authentication') {
return new DockerError(SSH_AUTH_FAILED, 'SSH authentication failed', { data, cause: error })
}
if (level === 'client-timeout') {
// either the ready timeout (connect + handshake + auth) or the keepalive
// timeout
return new DockerError(SSH_UNREACHABLE, 'SSH server did not answer in time', { data, cause: error })
}
if (level === 'client-socket' || level === 'client-dns') {
return new DockerError(SSH_UNREACHABLE, 'SSH server is unreachable', { data, cause: error })
}
// channel open failure, see onChannelOpenFailure() in ssh2/lib/utils.js
//
// `reason` is the numeric code from SSH_MSG_CHANNEL_OPEN_FAILURE, or `''`
// when the server closed the channel instead of answering. The server's
// description is only available in the message (no dedicated property).
const reason = errorLike?.reason
if (reason !== undefined) {
data.reason = reason
data.description = String(errorLike!.message).replace(/^\(SSH\) Channel open failure: /, '')
if (reason === SSH_OPEN_ADMINISTRATIVELY_PROHIBITED) {
return new DockerError(
STREAM_LOCAL_FORWARDING_DISABLED,
'stream local forwarding is disabled on the SSH server',
{
data,
cause: error,
}
)
}
if (reason === SSH_OPEN_CONNECT_FAILED) {
// OpenSSH (checked with 10.0) answers CONNECT_FAILED with the
// description `open failed` in every case: missing socket, permission
// denied, *and* AllowStreamLocalForwarding/DisableForwarding (in
// serverloop.c, `reason` keeps its CONNECT_FAILED default for
// `direct-streamlocal@openssh.com`), so the cause cannot be
// distinguished from the client side.
//
// ADMINISTRATIVELY_PROHIBITED is still handled above for other servers.
return new DockerError(
DOCKER_SOCKET_UNREACHABLE,
'cannot open the Docker socket through SSH (missing socket, missing permission, or stream local forwarding disabled)',
{ data, cause: error }
)
}
return new DockerError(SSH_ERROR, 'SSH channel open failure', { data, cause: error })
}
// thrown synchronously by `Client#connect()` when the key cannot be used
// (unparsable, wrong passphrase…), the message does not contain the key
const message = errorLike?.message
if (
typeof message === 'string' &&
(message.startsWith('Cannot parse privateKey') || message.startsWith('privateKey value does not'))
) {
return new DockerError(SSH_AUTH_FAILED, 'the SSH private key cannot be used', { data, cause: error })
}
if (typeof message === 'string' && message.startsWith('strictVendor enabled')) {
return new DockerError(STREAM_LOCAL_UNSUPPORTED, 'the SSH server does not support stream local forwarding', {
data,
cause: error,
})
}
return new DockerError(SSH_ERROR, 'SSH error', { data, cause: error })
}

View File

@@ -0,0 +1,118 @@
import assert from 'node:assert/strict'
import test from 'node:test'
import {
DOCKER_SOCKET_UNREACHABLE,
DockerError,
fromSshError,
scrub,
SSH_AUTH_FAILED,
SSH_ERROR,
SSH_UNREACHABLE,
STREAM_LOCAL_FORWARDING_DISABLED,
STREAM_LOCAL_UNSUPPORTED,
TIMEOUT,
} from './errors.mjs'
const { describe, it } = test
function sshError(message: string, props: object) {
return Object.assign(new Error(message), props)
}
describe('fromSshError()', () => {
const cases: [string, Error, string][] = [
[
'auth failure',
sshError('All configured authentication methods failed', { level: 'client-authentication' }),
SSH_AUTH_FAILED,
],
[
'socket error',
sshError('connect ECONNREFUSED 127.0.0.1:1', { level: 'client-socket', code: 'ECONNREFUSED' }),
SSH_UNREACHABLE,
],
['ready timeout', sshError('Timed out while waiting for handshake', { level: 'client-timeout' }), SSH_UNREACHABLE],
['DNS error', sshError('getaddrinfo ENOTFOUND foo', { level: 'client-dns', code: 'ENOTFOUND' }), SSH_UNREACHABLE],
[
'administratively prohibited',
sshError('(SSH) Channel open failure: ', { reason: 1 }),
STREAM_LOCAL_FORWARDING_DISABLED,
],
['connect failed', sshError('(SSH) Channel open failure: open failed', { reason: 2 }), DOCKER_SOCKET_UNREACHABLE],
[
'channel closed',
sshError('(SSH) Channel open failure: server closed channel unexpectedly', { reason: '' }),
SSH_ERROR,
],
[
'strict vendor',
new Error('strictVendor enabled and server is not OpenSSH or compatible version'),
STREAM_LOCAL_UNSUPPORTED,
],
['AbortError', new DOMException('This operation was aborted', 'AbortError'), TIMEOUT],
['TimeoutError', new DOMException('The operation was aborted due to timeout', 'TimeoutError'), TIMEOUT],
['handshake error', sshError('Host denied (verification failed)', { level: 'handshake' }), SSH_ERROR],
['unknown', new Error('something'), SSH_ERROR],
]
for (const [name, error, code] of cases) {
it(`maps ${name} to ${code}`, () => {
const result = fromSshError(error, { host: 'h', port: 22 })
assert.ok(result instanceof DockerError)
assert.equal(result.code, code)
assert.equal(result.data!.host, 'h')
assert.equal(result.cause!.message, error.message)
})
}
it('keeps the channel open failure details', () => {
const result = fromSshError(sshError('(SSH) Channel open failure: open failed', { reason: 2 }))
assert.equal(result.data!.reason, 2)
assert.equal(result.data!.description, 'open failed')
assert.equal(result.cause!.reason, 2)
})
it('returns DockerError as is', () => {
const error = new DockerError(TIMEOUT, 'foo')
assert.equal(fromSshError(error), error)
})
it('does not leak credentials attached to the original error', () => {
const error = sshError('All configured authentication methods failed', {
level: 'client-authentication',
config: { password: 'hunter2', privateKey: 'KEY' },
password: 'hunter2',
})
// the context is not supposed to contain credentials
const result = fromSshError(error, { host: 'h', password: 'hunter2', privateKey: 'KEY' } as { host: string })
const serialized = JSON.stringify({ data: result.data, cause: result.cause, ...result.cause })
assert.doesNotMatch(serialized, /hunter2|KEY/)
assert.equal(result.cause!.config, undefined)
assert.equal(result.cause!.password, undefined)
assert.equal(result.cause!.level, 'client-authentication')
})
})
describe('scrub()', () => {
it('removes sensitive keys recursively', () => {
assert.deepEqual(
scrub({ a: 1, password: 'x', nested: { privateKey: 'y', passphrase: 'z', b: [{ password: 1, c: 2 }] } }),
{
a: 1,
nested: { b: [{ c: 2 }] },
}
)
})
})
describe('DockerError', () => {
it('has code, data and a sanitized cause', () => {
const cause = Object.assign(new Error('boom'), { code: 'ECONNRESET', password: 'secret' })
const error = new DockerError(SSH_ERROR, 'msg', { data: { host: 'h', password: 'secret' }, cause })
assert.equal(error.name, 'DockerError')
assert.equal(error.code, SSH_ERROR)
assert.deepEqual(error.data, { host: 'h' })
assert.equal(error.cause!.code, 'ECONNRESET')
assert.equal(error.cause!.password, undefined)
})
})

File diff suppressed because it is too large Load Diff

View File

@@ -0,0 +1,189 @@
// Real payloads recorded from Docker Engine 29.8.1 (rootless, cgroup v2), at the
// negotiated API version 1.43 (`GET /v1.43/…`). Host-specific values (user
// name, host name, paths, engine ID) have been scrubbed. Do not edit by hand:
// re-record them instead.
import type { DockerInfo, DockerVersion } from '../wire.mjs'
export const INFO = {
Architecture: 'x86_64',
BridgeNfIp6tables: false,
BridgeNfIptables: false,
CDISpecDirs: ['/etc/cdi', '/var/run/cdi', '/home/docker/.config/cdi', '/home/docker/.docker-run/cdi'],
CPUSet: false,
CPUShares: true,
CgroupDriver: 'systemd',
CgroupVersion: '2',
ContainerdCommit: {
Expected: '1294c24a7da8e5a793ed378161673abe94118892',
ID: '1294c24a7da8e5a793ed378161673abe94118892',
},
Containers: 8,
ContainersPaused: 1,
ContainersRunning: 5,
ContainersStopped: 2,
CpuCfsPeriod: true,
CpuCfsQuota: true,
Debug: false,
DefaultRuntime: 'runc',
DockerRootDir: '/home/docker/.local/share/docker',
Driver: 'overlayfs',
DriverStatus: [['driver-type', 'io.containerd.snapshotter.v1']],
ExperimentalBuild: false,
GenericResources: null,
HttpProxy: '',
HttpsProxy: '',
ID: '00000000-0000-4000-8000-000000000000',
IPv4Forwarding: true,
Images: 3,
IndexServerAddress: 'https://index.docker.io/v1/',
InitBinary: 'docker-init',
InitCommit: {
Expected: 'de40ad0',
ID: 'de40ad0',
},
Isolation: '',
KernelVersion: '6.12.101+deb13-amd64',
Labels: [],
LiveRestoreEnabled: false,
LoggingDriver: 'json-file',
MemTotal: 5157838848,
MemoryLimit: true,
NCPU: 6,
NEventsListener: 0,
NFd: 156,
NGoroutines: 262,
Name: 'docker-host',
NoProxy: '',
OSType: 'linux',
OSVersion: '13',
OomKillDisable: false,
OperatingSystem: 'Debian GNU/Linux 13 (trixie)',
PidsLimit: true,
Plugins: {
Authorization: null,
Log: ['awslogs', 'fluentd', 'gcplogs', 'gelf', 'journald', 'json-file', 'local', 'splunk', 'syslog'],
Network: ['bridge', 'host', 'ipvlan', 'macvlan', 'null', 'overlay'],
Volume: ['local'],
},
ProductLicense: 'Community Engine',
RegistryConfig: {
AllowNondistributableArtifactsCIDRs: null,
AllowNondistributableArtifactsHostnames: null,
IndexConfigs: {
'docker.io': {
Mirrors: [],
Name: 'docker.io',
Official: true,
Secure: true,
},
},
InsecureRegistryCIDRs: ['::1/128', '127.0.0.0/8'],
Mirrors: [],
},
RuncCommit: {
Expected: 'v1.5.1-0-g8f2685a',
ID: 'v1.5.1-0-g8f2685a',
},
Runtimes: {
'io.containerd.runc.v2': {
path: 'runc',
},
runc: {
path: 'runc',
},
},
SecurityOptions: ['name=seccomp,profile=builtin', 'name=rootless', 'name=cgroupns'],
ServerVersion: '29.8.1',
SwapLimit: true,
Swarm: {
ControlAvailable: false,
Error: '',
LocalNodeState: 'inactive',
NodeAddr: '',
NodeID: '',
RemoteManagers: null,
},
SystemTime: '2026-09-24T16:56:16.993022218Z',
Warnings: [
'WARNING: No cpuset support',
'WARNING: No io.weight support',
'WARNING: No io.weight (per device) support',
'WARNING: No io.max (rbps) support',
'WARNING: No io.max (wbps) support',
'WARNING: No io.max (riops) support',
'WARNING: No io.max (wiops) support',
],
} satisfies DockerInfo
export const VERSION = {
Platform: {
Name: 'Docker Engine - Community',
},
Version: '29.8.1',
ApiVersion: '1.56',
MinAPIVersion: '1.40',
Os: 'linux',
Arch: 'amd64',
Components: [
{
Name: 'Engine',
Version: '29.8.1',
Details: {
ApiVersion: '1.56',
Arch: 'amd64',
BuildTime: '2026-09-15T16:27:24.000000000+00:00',
Experimental: 'false',
GitCommit: '464cd50',
GoVersion: 'go1.26.8',
KernelVersion: '6.12.101+deb13-amd64',
MinAPIVersion: '1.40',
Module: 'github.com/moby/moby/v2',
ModuleVersion: 'v2.0.0+unknown',
Os: 'linux',
},
},
{
Name: 'containerd',
Version: 'v2.3.5',
Details: {
GitCommit: '1294c24a7da8e5a793ed378161673abe94118892',
},
},
{
Name: 'runc',
Version: '1.5.1',
Details: {
GitCommit: 'v1.5.1-0-g8f2685a',
},
},
{
Name: 'docker-init',
Version: '0.19.0',
Details: {
GitCommit: 'de40ad0',
},
},
{
Name: 'rootlesskit',
Version: '3.1.0',
Details: {
ApiVersion: '1.1.2',
NetworkDriver: 'slirp4netns',
PortDriver: 'builtin',
StateDir: '/home/docker/.docker-run/dockerd-rootless',
},
},
{
Name: 'slirp4netns',
Version: '1.3.5',
Details: {
GitCommit: '7132ff3ba66cf0eebd8c9a83b9f23838bc84c518',
},
},
],
GitCommit: '464cd50',
GoVersion: 'go1.26.8',
KernelVersion: '6.12.101+deb13-amd64',
BuildTime: '2026-09-15T16:27:24.000000000+00:00',
} satisfies DockerVersion

View File

@@ -0,0 +1,22 @@
// Real payloads recorded from Docker Engine 29.8.1 (rootless, cgroup v2), at the
// negotiated API version 1.43 (`GET /v1.43/…`). Host-specific values (user
// name, host name, paths, engine ID) have been scrubbed. Do not edit by hand:
// re-record them instead.
//
// `GET /containers/{id}/logs?stdout=1&stderr=1&timestamps=1&tail=100`: the
// response `Content-Type` and the base64-encoded body.
export const LOGS_NGINX = {
contentType: 'application/vnd.docker.multiplexed-stream',
body: 'AQAAAAAAAIAyMDI2LTA5LTI0VDE2OjU0OjM3Ljc5NjMzMDIyMVogL2RvY2tlci1lbnRyeXBvaW50LnNoOiAvZG9ja2VyLWVudHJ5cG9pbnQuZC8gaXMgbm90IGVtcHR5LCB3aWxsIGF0dGVtcHQgdG8gcGVyZm9ybSBjb25maWd1cmF0aW9uCgEAAAAAAABpMjAyNi0wOS0yNFQxNjo1NDozNy43OTY0MDA2NTJaIC9kb2NrZXItZW50cnlwb2ludC5zaDogTG9va2luZyBmb3Igc2hlbGwgc2NyaXB0cyBpbiAvZG9ja2VyLWVudHJ5cG9pbnQuZC8KAQAAAAAAAHUyMDI2LTA5LTI0VDE2OjU0OjM3Ljc5ODY3MjU3NlogL2RvY2tlci1lbnRyeXBvaW50LnNoOiBMYXVuY2hpbmcgL2RvY2tlci1lbnRyeXBvaW50LmQvMTAtbGlzdGVuLW9uLWlwdjYtYnktZGVmYXVsdC5zaAoBAAAAAAAAfTIwMjYtMDktMjRUMTY6NTQ6MzcuODEyMDI1MzA1WiAxMC1saXN0ZW4tb24taXB2Ni1ieS1kZWZhdWx0LnNoOiBpbmZvOiBHZXR0aW5nIHRoZSBjaGVja3N1bSBvZiAvZXRjL25naW54L2NvbmYuZC9kZWZhdWx0LmNvbmYKAQAAAAAAAH8yMDI2LTA5LTI0VDE2OjU0OjM3Ljg1NjUyODE2NVogMTAtbGlzdGVuLW9uLWlwdjYtYnktZGVmYXVsdC5zaDogaW5mbzogRW5hYmxlZCBsaXN0ZW4gb24gSVB2NiBpbiAvZXRjL25naW54L2NvbmYuZC9kZWZhdWx0LmNvbmYKAQAAAAAAAG0yMDI2LTA5LTI0VDE2OjU0OjM3Ljg1Njc4MTc4M1ogL2RvY2tlci1lbnRyeXBvaW50LnNoOiBTb3VyY2luZyAvZG9ja2VyLWVudHJ5cG9pbnQuZC8xNS1sb2NhbC1yZXNvbHZlcnMuZW52c2gKAQAAAAAAAHEyMDI2LTA5LTI0VDE2OjU0OjM3Ljg1NzY0OTQwMVogL2RvY2tlci1lbnRyeXBvaW50LnNoOiBMYXVuY2hpbmcgL2RvY2tlci1lbnRyeXBvaW50LmQvMjAtZW52c3Vic3Qtb24tdGVtcGxhdGVzLnNoCgEAAAAAAABxMjAyNi0wOS0yNFQxNjo1NDozNy44NjY1NzE4MzNaIC9kb2NrZXItZW50cnlwb2ludC5zaDogTGF1bmNoaW5nIC9kb2NrZXItZW50cnlwb2ludC5kLzMwLXR1bmUtd29ya2VyLXByb2Nlc3Nlcy5zaAoBAAAAAAAAYTIwMjYtMDktMjRUMTY6NTQ6MzcuODcwMDc3Mjg5WiAvZG9ja2VyLWVudHJ5cG9pbnQuc2g6IENvbmZpZ3VyYXRpb24gY29tcGxldGU7IHJlYWR5IGZvciBzdGFydCB1cAoCAAAAAAAAYDIwMjYtMDktMjRUMTY6NTQ6MzcuODgzMjcwMTQ4WiAyMDI2LzA5LzI0IDE2OjU0OjM3IFtub3RpY2VdIDEjMTogdXNpbmcgdGhlICJlcG9sbCIgZXZlbnQgbWV0aG9kCgIAAAAAAABOMjAyNi0wOS0yNFQxNjo1NDozNy44ODMyOTEzMTBaIDIwMjYvMDkvMjQgMTY6NTQ6MzcgW25vdGljZV0gMSMxOiBuZ2lueC8xLjMxLjYKAgAAAAAAAGYyMDI2LTA5LTI0VDE2OjU0OjM3Ljg4MzI5ODM1N1ogMjAyNi8wOS8yNCAxNjo1NDozNyBbbm90aWNlXSAxIzE6IGJ1aWx0IGJ5IGdjYyAxNS4yLjAgKEFscGluZSAxNS4yLjApIAoCAAAAAAAAYDIwMjYtMDktMjRUMTY6NTQ6MzcuODgzMzA0Mzc5WiAyMDI2LzA5LzI0IDE2OjU0OjM3IFtub3RpY2VdIDEjMTogT1M6IExpbnV4IDYuMTIuMTAxK2RlYjEzLWFtZDY0CgIAAAAAAABnMjAyNi0wOS0yNFQxNjo1NDozNy44ODMzMTAzMjBaIDIwMjYvMDkvMjQgMTY6NTQ6MzcgW25vdGljZV0gMSMxOiBnZXRybGltaXQoUkxJTUlUX05PRklMRSk6IDEwMjQ6NTI0Mjg4CgIAAAAAAABYMjAyNi0wOS0yNFQxNjo1NDozNy44ODMzMjc5MzBaIDIwMjYvMDkvMjQgMTY6NTQ6MzcgW25vdGljZV0gMSMxOiBzdGFydCB3b3JrZXIgcHJvY2Vzc2VzCgIAAAAAAABZMjAyNi0wOS0yNFQxNjo1NDozNy44ODM1OTA1NTlaIDIwMjYvMDkvMjQgMTY6NTQ6MzcgW25vdGljZV0gMSMxOiBzdGFydCB3b3JrZXIgcHJvY2VzcyAzMAoCAAAAAAAAWTIwMjYtMDktMjRUMTY6NTQ6MzcuODgzNzU1OTk5WiAyMDI2LzA5LzI0IDE2OjU0OjM3IFtub3RpY2VdIDEjMTogc3RhcnQgd29ya2VyIHByb2Nlc3MgMzEKAgAAAAAAAFkyMDI2LTA5LTI0VDE2OjU0OjM3Ljg4NDY4NjA1MlogMjAyNi8wOS8yNCAxNjo1NDozNyBbbm90aWNlXSAxIzE6IHN0YXJ0IHdvcmtlciBwcm9jZXNzIDMyCgIAAAAAAABZMjAyNi0wOS0yNFQxNjo1NDozNy44ODQ2OTc4NjRaIDIwMjYvMDkvMjQgMTY6NTQ6MzcgW25vdGljZV0gMSMxOiBzdGFydCB3b3JrZXIgcHJvY2VzcyAzMwoCAAAAAAAAWTIwMjYtMDktMjRUMTY6NTQ6MzcuODg1MDA1ODQzWiAyMDI2LzA5LzI0IDE2OjU0OjM3IFtub3RpY2VdIDEjMTogc3RhcnQgd29ya2VyIHByb2Nlc3MgMzQKAgAAAAAAAFkyMDI2LTA5LTI0VDE2OjU0OjM3Ljg4NTAzNTMxMlogMjAyNi8wOS8yNCAxNjo1NDozNyBbbm90aWNlXSAxIzE6IHN0YXJ0IHdvcmtlciBwcm9jZXNzIDM1CgEAAAAAAAB6MjAyNi0wOS0yNFQxNjo1NjowNS41NzM0OTQwOTdaIDE3Mi4xNy4wLjEgLSAtIFsyNC9TZXAvMjAyNjoxNjo1NjowNSArMDAwMF0gIkdFVCAvIEhUVFAvMS4xIiAyMDAgODk2ICItIiAiY3VybC84LjE0LjEiICItIgoBAAAAAAAAgTIwMjYtMDktMjRUMTY6NTY6MDUuNTg3OTY2NzI5WiAxNzIuMTcuMC4xIC0gLSBbMjQvU2VwLzIwMjY6MTY6NTY6MDUgKzAwMDBdICJHRVQgL21pc3NpbmcgSFRUUC8xLjEiIDQwNCAxNTMgIi0iICJjdXJsLzguMTQuMSIgIi0iCgIAAAAAAADzMjAyNi0wOS0yNFQxNjo1NjowNS41ODc5NjU3MjNaIDIwMjYvMDkvMjQgMTY6NTY6MDUgW2Vycm9yXSAzMyMzMzogKjIgb3BlbigpICIvdXNyL3NoYXJlL25naW54L2h0bWwvbWlzc2luZyIgZmFpbGVkICgyOiBObyBzdWNoIGZpbGUgb3IgZGlyZWN0b3J5KSwgY2xpZW50OiAxNzIuMTcuMC4xLCBzZXJ2ZXI6IGxvY2FsaG9zdCwgcmVxdWVzdDogIkdFVCAvbWlzc2luZyBIVFRQLzEuMSIsIGhvc3Q6ICIxMjcuMC4wLjE6ODA4MCIK',
}
export const LOGS_EXITED = {
contentType: 'application/vnd.docker.multiplexed-stream',
body: 'AQAAAAAAADIyMDI2LTA5LTI0VDE2OjU0OjM4LjM3NzE3Mzk2OFogZmFpbGluZyBvbiBwdXJwb3NlCg==',
}
export const LOGS_TTY = {
contentType: 'application/vnd.docker.raw-stream',
body: 'MjAyNi0wOS0yNFQxNjo1NjowNS4xMTAzNTUwMzBaIHR0eSBsaW5lIG9uZQ0KMjAyNi0wOS0yNFQxNjo1NjowNS4xMTA5ODg5OTlaIHR0eSBsaW5lIHR3bw0KMjAyNi0wOS0yNFQxNjo1NjowNS4xNzA2MDM4OTlaIG5vIG5ld2xpbmUgYXQgZW5k',
}

View File

@@ -0,0 +1,560 @@
// Real payloads recorded from Docker Engine 29.8.1 (rootless, cgroup v2), at the
// negotiated API version 1.43 (`GET /v1.43/…`). Host-specific values (user
// name, host name, paths, engine ID) have been scrubbed. Do not edit by hand:
// re-record them instead.
//
// `STATS_BUSY` is a container running a busy loop (one full core).
// `STATS_STREAM_NGINX` are the first two objects of `?stream=true`: the first one
// has no `precpu_stats.system_cpu_usage`.
import type { DockerStatsSample } from '../wire.mjs'
export const STATS_NGINX_IDLE = {
id: '0f5359257668ff1fd83db09c2c906d810a4363ebeeffdf02f8a9e47faf41f731',
name: '/xo-nginx',
os_type: 'linux',
read: '2026-09-24T16:56:14.968764848Z',
cpu_stats: {
cpu_usage: {
total_usage: 115914000,
usage_in_kernelmode: 60038000,
usage_in_usermode: 55876000,
},
system_cpu_usage: 15705826330000000,
online_cpus: 6,
throttling_data: {
periods: 0,
throttled_periods: 0,
throttled_time: 0,
},
},
memory_stats: {
usage: 8650752,
stats: {
active_anon: 5148672,
active_file: 1650688,
anon: 5144576,
anon_thp: 0,
file: 2301952,
file_dirty: 0,
file_mapped: 282624,
file_writeback: 0,
inactive_anon: 0,
inactive_file: 647168,
kernel_stack: 114688,
pgactivate: 0,
pgdeactivate: 0,
pgfault: 4588,
pglazyfree: 0,
pglazyfreed: 0,
pgmajfault: 14,
pgrefill: 0,
pgscan: 0,
pgsteal: 0,
shmem: 4096,
slab: 545152,
slab_reclaimable: 201448,
slab_unreclaimable: 343704,
sock: 0,
thp_collapse_alloc: 0,
thp_fault_alloc: 2,
unevictable: 0,
workingset_activate: 0,
workingset_nodereclaim: 0,
workingset_refault: 0,
},
limit: 5157838848,
},
networks: {
eth0: {
rx_bytes: 2357,
rx_packets: 33,
rx_errors: 0,
rx_dropped: 0,
tx_bytes: 2220,
tx_packets: 13,
tx_errors: 0,
tx_dropped: 0,
},
},
pids_stats: {
current: 7,
limit: 5851,
},
blkio_stats: {
io_service_bytes_recursive: null,
io_serviced_recursive: null,
io_queue_recursive: null,
io_service_time_recursive: null,
io_wait_time_recursive: null,
io_merged_recursive: null,
io_time_recursive: null,
sectors_recursive: null,
},
num_procs: 0,
storage_stats: {},
preread: '2026-09-24T16:56:13.963804807Z',
precpu_stats: {
cpu_usage: {
total_usage: 115914000,
usage_in_kernelmode: 60038000,
usage_in_usermode: 55876000,
},
system_cpu_usage: 15705820350000000,
online_cpus: 6,
throttling_data: {
periods: 0,
throttled_periods: 0,
throttled_time: 0,
},
},
} satisfies DockerStatsSample
export const STATS_BUSY = {
id: '109f6bbd3d699034fd925bff4eef8e606102d33a1ce108b3f16957298c7f528f',
name: '/xo-cap-busy',
os_type: 'linux',
read: '2026-09-24T16:56:53.616857151Z',
cpu_stats: {
cpu_usage: {
total_usage: 4628010000,
usage_in_kernelmode: 19989000,
usage_in_usermode: 4608020000,
},
system_cpu_usage: 15706056470000000,
online_cpus: 6,
throttling_data: {
periods: 0,
throttled_periods: 0,
throttled_time: 0,
},
},
memory_stats: {
usage: 368640,
stats: {
active_anon: 65536,
active_file: 0,
anon: 65536,
anon_thp: 0,
file: 4096,
file_dirty: 0,
file_mapped: 0,
file_writeback: 0,
inactive_anon: 0,
inactive_file: 4096,
kernel_stack: 16384,
pgactivate: 0,
pgdeactivate: 0,
pgfault: 722,
pglazyfree: 0,
pglazyfreed: 0,
pgmajfault: 0,
pgrefill: 0,
pgscan: 0,
pgsteal: 0,
shmem: 0,
slab: 205112,
slab_reclaimable: 73768,
slab_unreclaimable: 131344,
sock: 0,
thp_collapse_alloc: 0,
thp_fault_alloc: 2,
unevictable: 0,
workingset_activate: 0,
workingset_nodereclaim: 0,
workingset_refault: 0,
},
limit: 5157838848,
},
networks: {
eth0: {
rx_bytes: 816,
rx_packets: 8,
rx_errors: 0,
rx_dropped: 0,
tx_bytes: 126,
tx_packets: 3,
tx_errors: 0,
tx_dropped: 0,
},
},
pids_stats: {
current: 1,
limit: 5851,
},
blkio_stats: {
io_service_bytes_recursive: null,
io_serviced_recursive: null,
io_queue_recursive: null,
io_service_time_recursive: null,
io_wait_time_recursive: null,
io_merged_recursive: null,
io_time_recursive: null,
sectors_recursive: null,
},
num_procs: 0,
storage_stats: {},
preread: '2026-09-24T16:56:52.61298099Z',
precpu_stats: {
cpu_usage: {
total_usage: 3624588000,
usage_in_kernelmode: 19989000,
usage_in_usermode: 3604599000,
},
system_cpu_usage: 15706050480000000,
online_cpus: 6,
throttling_data: {
periods: 0,
throttled_periods: 0,
throttled_time: 0,
},
},
} satisfies DockerStatsSample
export const STATS_PAUSED = {
id: '20fc8ce5f266072556c77fbacb4a010b6ca5da1d281317c5118b824932b53537',
name: '/xo-paused',
os_type: 'linux',
read: '2026-09-24T16:56:16.975869586Z',
cpu_stats: {
cpu_usage: {
total_usage: 59056000,
usage_in_kernelmode: 27780000,
usage_in_usermode: 31275000,
},
system_cpu_usage: 15705838330000000,
online_cpus: 6,
throttling_data: {
periods: 0,
throttled_periods: 0,
throttled_time: 0,
},
},
memory_stats: {
usage: 348160,
stats: {
active_anon: 49152,
active_file: 0,
anon: 49152,
anon_thp: 0,
file: 0,
file_dirty: 0,
file_mapped: 0,
file_writeback: 0,
inactive_anon: 0,
inactive_file: 0,
kernel_stack: 16384,
pgactivate: 0,
pgdeactivate: 0,
pgfault: 718,
pglazyfree: 0,
pglazyfreed: 0,
pgmajfault: 0,
pgrefill: 0,
pgscan: 0,
pgsteal: 0,
shmem: 0,
slab: 199672,
slab_reclaimable: 69576,
slab_unreclaimable: 130096,
sock: 0,
thp_collapse_alloc: 0,
thp_fault_alloc: 2,
unevictable: 0,
workingset_activate: 0,
workingset_nodereclaim: 0,
workingset_refault: 0,
},
limit: 5157838848,
},
networks: {
eth0: {
rx_bytes: 1194,
rx_packets: 17,
rx_errors: 0,
rx_dropped: 0,
tx_bytes: 126,
tx_packets: 3,
tx_errors: 0,
tx_dropped: 0,
},
},
pids_stats: {
current: 1,
limit: 5851,
},
blkio_stats: {
io_service_bytes_recursive: null,
io_serviced_recursive: null,
io_queue_recursive: null,
io_service_time_recursive: null,
io_wait_time_recursive: null,
io_merged_recursive: null,
io_time_recursive: null,
sectors_recursive: null,
},
num_procs: 0,
storage_stats: {},
preread: '2026-09-24T16:56:15.97180589Z',
precpu_stats: {
cpu_usage: {
total_usage: 59056000,
usage_in_kernelmode: 27780000,
usage_in_usermode: 31275000,
},
system_cpu_usage: 15705832320000000,
online_cpus: 6,
throttling_data: {
periods: 0,
throttled_periods: 0,
throttled_time: 0,
},
},
} satisfies DockerStatsSample
export const STATS_EXITED = {
id: '42af13ee1713b7f4e51e3704da91f4c4eba213b28dce23a94be7f5a63bd251fe',
name: '/xo-exited',
os_type: 'linux',
read: '0001-01-01T00:00:00Z',
cpu_stats: {
cpu_usage: {
total_usage: 0,
usage_in_kernelmode: 0,
usage_in_usermode: 0,
},
throttling_data: {
periods: 0,
throttled_periods: 0,
throttled_time: 0,
},
},
memory_stats: {},
pids_stats: {},
blkio_stats: {
io_service_bytes_recursive: null,
io_serviced_recursive: null,
io_queue_recursive: null,
io_service_time_recursive: null,
io_wait_time_recursive: null,
io_merged_recursive: null,
io_time_recursive: null,
sectors_recursive: null,
},
num_procs: 0,
storage_stats: {},
preread: '0001-01-01T00:00:00Z',
precpu_stats: {
cpu_usage: {
total_usage: 0,
usage_in_kernelmode: 0,
usage_in_usermode: 0,
},
throttling_data: {
periods: 0,
throttled_periods: 0,
throttled_time: 0,
},
},
} satisfies DockerStatsSample
export const STATS_STREAM_NGINX = [
{
id: '0f5359257668ff1fd83db09c2c906d810a4363ebeeffdf02f8a9e47faf41f731',
name: '/xo-nginx',
os_type: 'linux',
read: '2026-09-24T16:56:54.620055649Z',
cpu_stats: {
cpu_usage: {
total_usage: 115914000,
usage_in_kernelmode: 60038000,
usage_in_usermode: 55876000,
},
system_cpu_usage: 15706062390000000,
online_cpus: 6,
throttling_data: {
periods: 0,
throttled_periods: 0,
throttled_time: 0,
},
},
memory_stats: {
usage: 8650752,
stats: {
active_anon: 5148672,
active_file: 1650688,
anon: 5144576,
anon_thp: 0,
file: 2301952,
file_dirty: 0,
file_mapped: 262144,
file_writeback: 0,
inactive_anon: 0,
inactive_file: 647168,
kernel_stack: 114688,
pgactivate: 0,
pgdeactivate: 0,
pgfault: 4588,
pglazyfree: 0,
pglazyfreed: 0,
pgmajfault: 14,
pgrefill: 0,
pgscan: 0,
pgsteal: 0,
shmem: 4096,
slab: 545152,
slab_reclaimable: 201448,
slab_unreclaimable: 343704,
sock: 0,
thp_collapse_alloc: 0,
thp_fault_alloc: 2,
unevictable: 0,
workingset_activate: 0,
workingset_nodereclaim: 0,
workingset_refault: 0,
},
limit: 5157838848,
},
networks: {
eth0: {
rx_bytes: 2483,
rx_packets: 36,
rx_errors: 0,
rx_dropped: 0,
tx_bytes: 2220,
tx_packets: 13,
tx_errors: 0,
tx_dropped: 0,
},
},
pids_stats: {
current: 7,
limit: 5851,
},
blkio_stats: {
io_service_bytes_recursive: null,
io_serviced_recursive: null,
io_queue_recursive: null,
io_service_time_recursive: null,
io_wait_time_recursive: null,
io_merged_recursive: null,
io_time_recursive: null,
sectors_recursive: null,
},
num_procs: 0,
storage_stats: {},
preread: '0001-01-01T00:00:00Z',
precpu_stats: {
cpu_usage: {
total_usage: 0,
usage_in_kernelmode: 0,
usage_in_usermode: 0,
},
throttling_data: {
periods: 0,
throttled_periods: 0,
throttled_time: 0,
},
},
},
{
id: '0f5359257668ff1fd83db09c2c906d810a4363ebeeffdf02f8a9e47faf41f731',
name: '/xo-nginx',
os_type: 'linux',
read: '2026-09-24T16:56:55.625086818Z',
cpu_stats: {
cpu_usage: {
total_usage: 115914000,
usage_in_kernelmode: 60038000,
usage_in_usermode: 55876000,
},
system_cpu_usage: 15706068340000000,
online_cpus: 6,
throttling_data: {
periods: 0,
throttled_periods: 0,
throttled_time: 0,
},
},
memory_stats: {
usage: 8650752,
stats: {
active_anon: 5148672,
active_file: 1650688,
anon: 5144576,
anon_thp: 0,
file: 2301952,
file_dirty: 0,
file_mapped: 262144,
file_writeback: 0,
inactive_anon: 0,
inactive_file: 647168,
kernel_stack: 114688,
pgactivate: 0,
pgdeactivate: 0,
pgfault: 4588,
pglazyfree: 0,
pglazyfreed: 0,
pgmajfault: 14,
pgrefill: 0,
pgscan: 0,
pgsteal: 0,
shmem: 4096,
slab: 545152,
slab_reclaimable: 201448,
slab_unreclaimable: 343704,
sock: 0,
thp_collapse_alloc: 0,
thp_fault_alloc: 2,
unevictable: 0,
workingset_activate: 0,
workingset_nodereclaim: 0,
workingset_refault: 0,
},
limit: 5157838848,
},
networks: {
eth0: {
rx_bytes: 2483,
rx_packets: 36,
rx_errors: 0,
rx_dropped: 0,
tx_bytes: 2220,
tx_packets: 13,
tx_errors: 0,
tx_dropped: 0,
},
},
pids_stats: {
current: 7,
limit: 5851,
},
blkio_stats: {
io_service_bytes_recursive: null,
io_serviced_recursive: null,
io_queue_recursive: null,
io_service_time_recursive: null,
io_wait_time_recursive: null,
io_merged_recursive: null,
io_time_recursive: null,
sectors_recursive: null,
},
num_procs: 0,
storage_stats: {},
preread: '2026-09-24T16:56:54.620055649Z',
precpu_stats: {
cpu_usage: {
total_usage: 115914000,
usage_in_kernelmode: 60038000,
usage_in_usermode: 55876000,
},
system_cpu_usage: 15706062390000000,
online_cpus: 6,
throttling_data: {
periods: 0,
throttled_periods: 0,
throttled_time: 0,
},
},
},
] satisfies DockerStatsSample[]

View File

@@ -0,0 +1,21 @@
// Docker Engine API client reaching the Docker socket of a remote host through
// SSH (`direct-streamlocal@openssh.com` channels), with nothing to install on
// the host. No XO concepts here: see xo-server's `xo-mixins/docker.mjs`.
export * from './connection.mjs'
export * from './cooldown.mjs'
export * from './errors.mjs'
export * from './normalize.mjs'
// not `export *`: both export a `DEFAULT_IDLE_TIMEOUT`
export {
DockerConnectionPool,
type DockerConnectionFacade,
type DockerConnectionState,
type PoolableConnection,
} from './pool.mjs'
export * from './requests.mjs'
export { DockerStatsSampler, type DockerStatsSamplerOptions } from './stats-sampler.mjs'
export * from './ssh-http-agent.mjs'
export * from './stdcopy.mjs'
export * from './ttl-cache.mjs'
export type * from './wire.mjs'

View File

@@ -0,0 +1,206 @@
// Integration tests of the logs demuxing and of the normalization against a
// real Docker daemon reached through a real SSH server.
//
// Same environment variables as `connection.integration.test.mjs` (skipped
// unless XO_DOCKER_TEST_SSH_HOST is set), and these containers on the daemon:
//
// - `xo-nginx`: running `nginx:alpine`, port 80 published on 8080
// - `xo-exited`: `alpine sh -c 'echo failing on purpose; exit 3'`, exited
// - `xo-tty`: `alpine` run with `-t`, exited, which printed `tty line one`,
// `tty line two` (on stderr) and `no newline at end`
import assert from 'node:assert/strict'
import { readFileSync } from 'node:fs'
import { pipeline } from 'node:stream/promises'
import test from 'node:test'
import type { XoDockerContainerStats } from '@vates/types'
import { DockerConnection } from './connection.mjs'
import { normalizeContainerInspect, normalizeContainerListEntry, normalizeContainerStats } from './normalize.mjs'
import { createLogLineParser, createStdcopyDemuxer, isMultiplexedStream, type DockerLogLine } from './stdcopy.mjs'
import type { DockerContainerSummary, DockerInspect } from './wire.mjs'
const { after, before, describe, it } = test
const {
XO_DOCKER_TEST_SSH_HOST: host,
XO_DOCKER_TEST_SSH_PORT: port = '22',
XO_DOCKER_TEST_SSH_USER: username,
XO_DOCKER_TEST_SSH_KEY: keyPath,
XO_DOCKER_TEST_SSH_FINGERPRINT: fingerprint,
XO_DOCKER_TEST_SOCKET: socketPath,
} = process.env
const skip = host === undefined ? 'XO_DOCKER_TEST_SSH_HOST is not set' : false
describe('logs and stats (real SSH + dockerd)', { skip }, () => {
let connection: DockerConnection
// `!`: the environment is set, the tests are skipped otherwise
before(async () => {
connection = new DockerConnection({
host: host!,
port: Number(port),
username: username!,
privateKey: readFileSync(keyPath!),
socketPath,
hostKeyFingerprint: fingerprint,
connectTimeout: 5e3,
requestTimeout: 10e3,
})
await connection.connect()
})
after(async () => {
await connection?.close()
})
async function inspect(name: string) {
const { body } = await connection.request({ path: `/containers/${name}/json` })
return normalizeContainerInspect(body as DockerInspect)
}
async function getLogs(name: string, query: Record<string, unknown> = {}) {
const container = await inspect(name)
const response = await connection.requestStream({
path: `/containers/${name}/logs`,
query: { stdout: 1, stderr: 1, timestamps: 1, tail: 100, ...query },
})
const tty = !isMultiplexedStream(response.headers['content-type'], container.tty, connection.apiVersion)
assert.equal(tty, container.tty, 'the content type agrees with Config.Tty')
const demuxer = createStdcopyDemuxer({ tty })
const entries: DockerLogLine[] = []
await pipeline(response, demuxer, createLogLineParser(), async (source: AsyncIterable<DockerLogLine>) => {
for await (const entry of source) {
entries.push(entry)
}
})
assert.equal(demuxer.truncated, false)
return { entries, contentType: response.headers['content-type'] }
}
const assertTimestamp = (timestamp: string | undefined, since: number) => {
assert.match(timestamp!, /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d{1,9})?Z$/)
const time = Date.parse(timestamp!)
assert.ok(time >= since && time <= Date.now() + 60e3, timestamp)
}
it('reads the logs of xo-exited', async () => {
const container = await inspect('xo-exited')
const { entries, contentType } = await getLogs('xo-exited')
assert.equal(contentType, 'application/vnd.docker.multiplexed-stream')
assert.equal(entries.length, 1)
const [{ stream, timestamp, message }] = entries
assert.equal(stream, 'stdout')
assert.equal(message, 'failing on purpose')
assertTimestamp(timestamp, container.startedAt! - 1e3)
})
it('reads the logs of xo-nginx, stdout and stderr', async () => {
const container = await inspect('xo-nginx')
const { entries } = await getLogs('xo-nginx')
assert.ok(entries.length > 5)
for (const { stream, timestamp, message } of entries) {
assert.ok(stream === 'stdout' || stream === 'stderr')
// since its creation: it may have been restarted (e.g. by the REST proof)
assertTimestamp(timestamp, container.createdAt! - 1e3)
assert.equal(typeof message, 'string')
assert.ok(!message.includes('\n'))
}
// the entrypoint writes on stdout, nginx notices go to stderr
assert.ok(entries.some(_ => _.stream === 'stdout' && _.message.includes('/docker-entrypoint.sh')))
assert.ok(entries.some(_ => _.stream === 'stderr' && _.message.includes('[notice]')))
})
it('honours tail', async () => {
const { entries } = await getLogs('xo-nginx', { tail: 2 })
assert.equal(entries.length, 2)
})
it('reads the logs of a TTY container', async () => {
const container = await inspect('xo-tty')
const { entries, contentType } = await getLogs('xo-tty')
assert.equal(contentType, 'application/vnd.docker.raw-stream')
assert.deepEqual(
entries.map(({ stream, message }) => [stream, message]),
[
['stdout', 'tty line one'],
['stdout', 'tty line two'],
['stdout', 'no newline at end'],
]
)
for (const { timestamp } of entries) {
assertTimestamp(timestamp, container.startedAt! - 1e3)
}
})
it('reads and normalizes the stats of xo-nginx (stream=false)', async () => {
const container = await inspect('xo-nginx')
const start = Date.now()
const { body } = await connection.request({ path: '/containers/xo-nginx/stats', query: { stream: false } })
const stats = normalizeContainerStats(body)
// `!`: checked by the assertions (a `null` compares as 0, an `undefined` as NaN)
// dockerd pre-reads a sample, precpu_stats is valid
assert.equal(typeof stats.cpuPercent, 'number')
assert.ok(stats.cpuPercent! >= 0 && stats.cpuPercent! <= 100 * stats.onlineCpus!, String(stats.cpuPercent))
assert.ok(stats.onlineCpus! >= 1)
assert.ok(
stats.memoryUsage! > 0 && stats.memoryUsage! <= (body as { memory_stats: { usage: number } }).memory_stats.usage
)
assert.ok(stats.memoryLimit! >= stats.memoryUsage!)
assert.ok(stats.memoryPercent! > 0 && stats.memoryPercent! <= 100)
assert.ok(stats.pids! >= 1)
assert.ok(stats.networkRx! >= 0)
assert.ok(stats.sampledAt! >= Math.max(container.startedAt!, start - 5e3) && stats.sampledAt! <= Date.now() + 60e3)
})
it('reads and normalizes streamed stats of xo-nginx (stream=true)', async () => {
const controller = new AbortController()
const response = await connection.requestStream({
path: '/containers/xo-nginx/stats',
query: { stream: true },
signal: controller.signal,
})
const samples: XoDockerContainerStats[] = []
try {
let buffer = ''
for await (const chunk of response) {
buffer += chunk
let i
while ((i = buffer.indexOf('\n')) !== -1) {
samples.push(normalizeContainerStats(JSON.parse(buffer.slice(0, i))))
buffer = buffer.slice(i + 1)
}
if (samples.length >= 2) {
break
}
}
} finally {
controller.abort()
}
const [first, second] = samples
// the first object of a stream has no previous CPU sample
assert.equal(first.cpuPercent, null)
assert.equal(typeof second.cpuPercent, 'number')
assert.ok(second.sampledAt! > first.sampledAt!)
assert.ok(second.memoryUsage! > 0)
})
it('normalizes the real container list', async () => {
const { body } = await connection.request({ path: '/containers/json', query: { all: 1 } })
const containers = new Map(
(body as DockerContainerSummary[]).map(normalizeContainerListEntry).map(container => [container.name, container])
)
const nginx = containers.get('xo-nginx')!
assert.equal(nginx.state, 'running')
assert.deepEqual(nginx.ports, [{ ip: '0.0.0.0', privatePort: 80, publicPort: 8080, protocol: 'tcp' }])
assert.deepEqual((await inspect('xo-nginx')).ports, nginx.ports)
const exited = containers.get('xo-exited')!
assert.equal(exited.state, 'exited')
assert.equal(exited.exitCode, 3)
assert.equal((await inspect('xo-exited')).exitCode, 3)
})
})

View File

@@ -0,0 +1,599 @@
// Docker Engine API wire shapes → XO DTOs.
//
// Pure functions, written against API 1.44 (`MAX_API_VERSION`) and tolerant of
// fields missing in older versions. Timestamps are converted to ms since the
// epoch. Optional values which do not apply are left `undefined` (so they are
// omitted from JSON), except the stats values which are `null` when they cannot
// be computed.
//
// The container environment (`Config.Env`) is deliberately never exposed: it
// routinely contains secrets.
import type {
XoDockerCompose,
XoDockerContainer,
XoDockerContainerHealth,
XoDockerContainerStats,
XoDockerEngineInfoConnected,
XoDockerEngineKind,
XoDockerMount,
XoDockerNetwork,
XoDockerPort,
} from '@vates/types'
import type {
DockerBlkioStats,
DockerContainerConfig,
DockerContainerStateInfo,
DockerContainerSummary,
DockerCpuStats,
DockerEndpointSettings,
DockerInfo,
DockerInspect,
DockerMemoryStats,
DockerMountPoint,
DockerPort,
DockerPortMap,
DockerStatsSample,
DockerVersion,
} from './wire.mjs'
/**
* A container as normalized from the daemon: without the fields added by XO
* (`id`, `$engine`…).
*/
export type NormalizedDockerContainer = Omit<
XoDockerContainer,
'id' | '$engine' | '$VM' | '$pool' | 'stats' | 'statsPending'
>
/**
* `GET /info` (and `GET /version`) normalized: `XoDockerEngineInfoConnected`
* without the fields added by XO, and with the daemon's ID (`id`) and newest
* API version (`apiVersion`).
*/
export type NormalizedDockerEngineInfo = Omit<
XoDockerEngineInfoConnected,
'status' | 'asOf' | 'daemonId' | 'daemonApiVersion' | 'compose'
> & {
/** the daemon's ID */
id?: string
}
// Go's zero `time.Time`, used by dockerd for dates which are not set
const ZERO_DATE_RE = /^0001-01-01T00:00:00(?:\.0+)?Z$/
/**
* @param date RFC 3339 date
* @returns ms since the epoch
*/
export function parseDockerDate(date: unknown): number | undefined {
if (typeof date !== 'string' || date === '' || ZERO_DATE_RE.test(date)) {
return undefined
}
const time = Date.parse(date)
return Number.isNaN(time) ? undefined : time
}
// === Container name, state, status
/**
* Primary name of a container, without its leading `/`.
*
* With legacy links, `Names` also contains aliases like `/other/alias`: the
* primary name is the one without any other `/` (what the Docker CLI shows).
*/
export function getContainerName(names: string[] | undefined): string | undefined {
if (names === undefined || names.length === 0) {
return undefined
}
const name = names.find(name => name.lastIndexOf('/') === 0) ?? names[0]
return name.startsWith('/') ? name.slice(1) : name
}
/**
* Parse the human readable `Status` of a list entry, e.g. `Exited (3) 2 hours
* ago`, `Up 5 minutes (healthy)`, `Up 1 second (health: starting)`,
* `Restarting (1) 3 seconds ago`, `Up 3 hours (Paused)`.
*/
export function parseContainerStatus(status: string | undefined): {
exitCode?: number
health?: XoDockerContainerHealth
} {
const result: { exitCode?: number; health?: XoDockerContainerHealth } = {}
if (typeof status !== 'string') {
return result
}
const exitCodeMatch = /^(?:Exited|Restarting) \((-?\d+)\)/.exec(status)
if (exitCodeMatch !== null) {
result.exitCode = Number(exitCodeMatch[1])
}
const healthMatch = /\((healthy|unhealthy|health: starting)\)/.exec(status)
if (healthMatch !== null) {
result.health = healthMatch[1] === 'health: starting' ? 'starting' : (healthMatch[1] as 'healthy' | 'unhealthy')
}
return result
}
/**
* @param status `State.Health.Status`
* @returns `undefined` if the container has no health check
*/
function normalizeHealthStatus(status: string | undefined): XoDockerContainerHealth | undefined {
return status === 'starting' || status === 'healthy' || status === 'unhealthy' ? status : undefined
}
// === Ports
const WILDCARD_IPV4 = '0.0.0.0'
const WILDCARD_IPV6 = '::'
/**
* Normalize, dedupe and sort ports.
*
* When a port is published on all interfaces, dockerd reports it twice: once
* for `0.0.0.0` and once for `::`. The `::` entry is dropped in that case (the
* port stays reported as `0.0.0.0`). An IPv6-only binding keeps `::`.
*/
function dedupePorts(ports: XoDockerPort[]): XoDockerPort[] {
const byKey = new Map<string, XoDockerPort>()
for (const port of ports) {
byKey.set(`${port.privatePort}/${port.protocol}/${port.publicPort}/${port.ip}`, port)
}
const result: XoDockerPort[] = []
for (const port of byKey.values()) {
if (
port.ip === WILDCARD_IPV6 &&
byKey.has(`${port.privatePort}/${port.protocol}/${port.publicPort}/${WILDCARD_IPV4}`)
) {
continue
}
result.push(port)
}
return result.sort(
(a, b) =>
a.privatePort - b.privatePort ||
a.protocol.localeCompare(b.protocol) ||
(a.publicPort ?? 0) - (b.publicPort ?? 0) ||
(a.ip ?? '').localeCompare(b.ip ?? '')
)
}
function makePort({
ip,
privatePort,
publicPort,
protocol = 'tcp',
}: {
ip?: string
privatePort: number
publicPort?: number
protocol?: string
}): XoDockerPort {
const port: XoDockerPort = { privatePort, protocol }
if (publicPort !== undefined && publicPort !== 0) {
port.publicPort = publicPort
if (ip !== undefined && ip !== '') {
port.ip = ip
}
}
return port
}
/**
* Ports of a container list entry (`Ports`).
*/
export function normalizeListPorts(ports: DockerPort[] | undefined): XoDockerPort[] {
return dedupePorts(
(ports ?? []).map(({ IP, PrivatePort, PublicPort, Type }) =>
makePort({ ip: IP, privatePort: PrivatePort, publicPort: PublicPort, protocol: Type })
)
)
}
/**
* Ports of an inspected container (`NetworkSettings.Ports`), e.g.
* `{ "80/tcp": [{ "HostIp": "0.0.0.0", "HostPort": "8080" }], "443/tcp": null }`.
*/
export function normalizeInspectPorts(ports: DockerPortMap | undefined): XoDockerPort[] {
const result: XoDockerPort[] = []
for (const [key, bindings] of Object.entries(ports ?? {})) {
const [privatePort, protocol = 'tcp'] = key.split('/')
if (bindings === null || bindings.length === 0) {
result.push(makePort({ privatePort: Number(privatePort), protocol }))
} else {
for (const { HostIp, HostPort } of bindings) {
result.push(makePort({ ip: HostIp, privatePort: Number(privatePort), publicPort: Number(HostPort), protocol }))
}
}
}
return dedupePorts(result)
}
// === Labels, networks, mounts
const COMPOSE_LABEL_PREFIX = 'com.docker.compose.'
/**
* Docker Compose project and service of a container, from its labels.
*/
export function getComposeInfo(labels: Record<string, string> | undefined): XoDockerCompose | undefined {
const project = labels?.[COMPOSE_LABEL_PREFIX + 'project']
if (project === undefined || project === '') {
return undefined
}
const get = (name: string): string | undefined => {
// `labels!`: set, it contains the project
const value = labels![COMPOSE_LABEL_PREFIX + name]
return value === '' ? undefined : value
}
const compose: XoDockerCompose = { project }
const service = get('service')
if (service !== undefined) {
compose.service = service
}
const containerNumber = Number(get('container-number'))
if (Number.isInteger(containerNumber)) {
compose.containerNumber = containerNumber
}
const oneOff = get('oneoff')
if (oneOff !== undefined) {
compose.oneOff = oneOff.toLowerCase() === 'true'
}
const workingDir = get('project.working_dir')
if (workingDir !== undefined) {
compose.workingDir = workingDir
}
const configFiles = get('project.config_files')
if (configFiles !== undefined) {
compose.configFiles = configFiles.split(',')
}
return compose
}
/**
* @param networks `NetworkSettings.Networks`
*/
export function normalizeNetworks(networks: Record<string, DockerEndpointSettings> | undefined): XoDockerNetwork[] {
return Object.entries(networks ?? {}).map(([name, { IPAddress, GlobalIPv6Address }]) => {
const network: XoDockerNetwork = { name }
if (IPAddress) {
network.ipAddress = IPAddress
}
if (GlobalIPv6Address) {
network.ipv6Address = GlobalIPv6Address
}
return network
})
}
export function normalizeMounts(mounts: DockerMountPoint[] | undefined): XoDockerMount[] {
return (mounts ?? []).map(({ Type, Name, Source, Destination, RW }) => {
const mount: XoDockerMount = { type: Type, source: Source, destination: Destination, readOnly: !RW }
if (Name) {
mount.name = Name
}
return mount
})
}
// === Containers
/**
* Entry of `GET /containers/json`.
*/
export function normalizeContainerListEntry(entry: DockerContainerSummary): NormalizedDockerContainer {
const labels = entry.Labels ?? {}
const { exitCode, health } = parseContainerStatus(entry.Status)
const container: NormalizedDockerContainer = {
dockerId: entry.Id,
name: getContainerName(entry.Names),
image: entry.Image,
imageId: entry.ImageID,
command: entry.Command,
createdAt: entry.Created * 1e3,
state: entry.State,
status: entry.Status,
exitCode: entry.State === 'exited' || entry.State === 'dead' || entry.State === 'restarting' ? exitCode : undefined,
health,
ports: normalizeListPorts(entry.Ports),
labels,
compose: getComposeInfo(labels),
networks: normalizeNetworks(entry.NetworkSettings?.Networks),
mounts: normalizeMounts(entry.Mounts),
}
return container
}
// same format as the `Command` of list entries: arguments containing a space
// are single-quoted (without any escaping, like dockerd does)
function formatCommand(path: string, args: string[] = []): string {
return [path, ...args.map(arg => (arg.includes(' ') ? `'${arg}'` : arg))].join(' ')
}
/**
* `GET /containers/{id}/json`.
*
* Contains the same fields as a list entry (except `status`, the human readable
* one), plus the details only available from an inspection.
*/
export function normalizeContainerInspect(data: DockerInspect): NormalizedDockerContainer {
const {
// typed as complete objects: dockerd always sends `Config.Image` and
// `State.Status`
Config: config = {} as DockerContainerConfig,
HostConfig: hostConfig = {},
NetworkSettings: networkSettings = {},
State: state = {} as DockerContainerStateInfo,
} = data
const labels = config.Labels ?? {}
const status = state.Status
const health = state.Health
const lastHealthCheck = health?.Log?.at(-1)
const restartPolicy = hostConfig.RestartPolicy
const container: NormalizedDockerContainer = {
dockerId: data.Id,
name: getContainerName([data.Name]),
image: config.Image,
imageId: data.Image,
command: formatCommand(data.Path, data.Args),
createdAt: parseDockerDate(data.Created),
state: status,
exitCode: status === 'exited' || status === 'dead' || status === 'restarting' ? state.ExitCode : undefined,
health: normalizeHealthStatus(health?.Status),
ports: normalizeInspectPorts(networkSettings.Ports),
labels,
compose: getComposeInfo(labels),
networks: normalizeNetworks(networkSettings.Networks),
mounts: normalizeMounts(data.Mounts),
startedAt: parseDockerDate(state.StartedAt),
finishedAt: parseDockerDate(state.FinishedAt),
oomKilled: state.OOMKilled,
error: state.Error || undefined,
healthCheck:
health === undefined || normalizeHealthStatus(health.Status) === undefined
? undefined
: {
failingStreak: health.FailingStreak,
lastCheckAt: parseDockerDate(lastHealthCheck?.End ?? lastHealthCheck?.Start),
lastExitCode: lastHealthCheck?.ExitCode,
},
restartPolicy: {
// `Name` is empty when the container was created without restart policy
name: restartPolicy?.Name || 'no',
maximumRetryCount: restartPolicy?.MaximumRetryCount ?? 0,
},
restartCount: data.RestartCount,
tty: config.Tty === true,
hostname: config.Hostname,
workingDir: config.WorkingDir || undefined,
user: config.User || undefined,
}
return container
}
// === Stats
// every stats value comes from the daemon: only finite numbers are accepted,
// never numeric strings (which the sums would concatenate), objects, NaN or
// Infinity, and every computed value is checked again (huge values overflow)
const isNumber = (value: unknown): value is number => typeof value === 'number' && Number.isFinite(value)
// byte, page, process counters
const isCounter = (value: unknown): value is number => isNumber(value) && value >= 0
const finiteOrNull = (value: unknown): number | null => (isNumber(value) ? value : null)
// arrays included: their properties are read like the ones of any object
const isObject = (value: unknown): value is Record<string, unknown> => typeof value === 'object' && value !== null
/**
* CPU usage in percent, like `docker stats`: 100 means one full CPU, so the
* value can go up to `100 * onlineCpus`.
*
* `null` when it cannot be computed: first sample of a stream, or of a
* container which is not running (no `precpu_stats.system_cpu_usage`), no
* elapsed system time (would give `Infinity`/`NaN`) or counters which went
* backwards (container restarted between the samples).
*
* @param cpuStats `cpu_stats`
* @param precpuStats `precpu_stats`
*/
export function computeCpuPercent(
cpuStats: DockerCpuStats | undefined,
precpuStats: DockerCpuStats | undefined
): { cpuPercent: number | null; onlineCpus: number | undefined } {
const onlineCpusValue = cpuStats?.online_cpus
const percpuUsage = cpuStats?.cpu_usage?.percpu_usage
const onlineCpus =
// `as number`: a safe integer
Number.isSafeInteger(onlineCpusValue) && (onlineCpusValue as number) > 0
? (onlineCpusValue as number)
: (Array.isArray(percpuUsage) && percpuUsage.length) || undefined
const total = cpuStats?.cpu_usage?.total_usage
const preTotal = precpuStats?.cpu_usage?.total_usage
const system = cpuStats?.system_cpu_usage
const preSystem = precpuStats?.system_cpu_usage
if (
onlineCpus === undefined ||
!isCounter(total) ||
!isCounter(preTotal) ||
!isCounter(system) ||
!isCounter(preSystem) ||
!(preSystem > 0)
) {
return { cpuPercent: null, onlineCpus }
}
const cpuDelta = total - preTotal
const systemDelta = system - preSystem
if (!(systemDelta > 0) || cpuDelta < 0) {
return { cpuPercent: null, onlineCpus }
}
return { cpuPercent: finiteOrNull((cpuDelta / systemDelta) * onlineCpus * 100), onlineCpus }
}
/**
* Memory used by a container, without the page cache which can be reclaimed,
* like `docker stats`:
*
* - cgroup v1: `usage - total_inactive_file` (Docker CLI ≥ 20.10), or
* `usage - cache` with daemons which do not report `total_inactive_file`
* - cgroup v2: `usage - inactive_file`
*
* @param memoryStats `memory_stats`
* @returns bytes
*/
export function computeMemoryUsage(memoryStats: DockerMemoryStats | undefined): number | null {
const usage = memoryStats?.usage
if (!isCounter(usage)) {
return null
}
// `memoryStats!`: set, it has a `usage`
const stats = isObject(memoryStats!.stats) ? memoryStats!.stats : {}
let cache
if ('total_inactive_file' in stats) {
cache = stats.total_inactive_file // cgroup v1
} else if ('inactive_file' in stats) {
cache = stats.inactive_file // cgroup v2
} else {
cache = stats.cache // cgroup v1 (old daemons)
}
return isCounter(cache) && cache < usage ? usage - cache : usage
}
/**
* Sum of the bytes read and written, from `blkio_stats.io_service_bytes_recursive`.
*/
function computeBlockIo(blkioStats: DockerBlkioStats | undefined): {
blockRead: number | null
blockWrite: number | null
} {
const entries = blkioStats?.io_service_bytes_recursive
if (!Array.isArray(entries)) {
return { blockRead: null, blockWrite: null }
}
let blockRead = 0
let blockWrite = 0
for (const entry of entries) {
if (!isObject(entry) || typeof entry.op !== 'string' || !isCounter(entry.value)) {
continue
}
// `Read`/`Write` on cgroup v1, `read`/`write` on cgroup v2
const lowerOp = entry.op.toLowerCase()
if (lowerOp === 'read') {
blockRead += entry.value
} else if (lowerOp === 'write') {
blockWrite += entry.value
}
}
return { blockRead: finiteOrNull(blockRead), blockWrite: finiteOrNull(blockWrite) }
}
function computeNetworkIo(networks: unknown): { networkRx: number | null; networkTx: number | null } {
if (!isObject(networks)) {
return { networkRx: null, networkTx: null }
}
let networkRx = 0
let networkTx = 0
for (const network of Object.values(networks)) {
if (!isObject(network)) {
continue
}
if (isCounter(network.rx_bytes)) {
networkRx += network.rx_bytes
}
if (isCounter(network.tx_bytes)) {
networkTx += network.tx_bytes
}
}
return { networkRx: finiteOrNull(networkRx), networkTx: finiteOrNull(networkTx) }
}
/**
* One object of `GET /containers/{id}/stats` (`stream=false`, or each object
* of `stream=true`). Never send `one-shot=true`: `precpu_stats` would be empty.
*
* Linux containers only: Windows ones have a different CPU accounting, and get
* a `null` `cpuPercent`.
*
* @param value anything: it comes from the daemon, every value is checked
*/
export function normalizeContainerStats(value: unknown): XoDockerContainerStats {
if (!isObject(value) || Array.isArray(value)) {
throw new TypeError('stats must be an object')
}
// see `DockerStatsSample`: the values are `unknown`
const stats = value as DockerStatsSample
const isWindows = stats.os_type === 'windows'
const { cpuPercent, onlineCpus } = isWindows
? { cpuPercent: null, onlineCpus: undefined }
: computeCpuPercent(stats.cpu_stats, stats.precpu_stats)
const memoryStats: DockerMemoryStats | undefined = isObject(stats.memory_stats) ? stats.memory_stats : undefined
const memoryUsage = isWindows
? isCounter(memoryStats?.privateworkingset)
? memoryStats.privateworkingset
: null
: computeMemoryUsage(memoryStats)
const memoryLimit = isCounter(memoryStats?.limit) && memoryStats.limit > 0 ? memoryStats.limit : null
return {
sampledAt: parseDockerDate(stats.read) ?? null,
cpuPercent,
onlineCpus,
memoryUsage,
memoryLimit,
memoryPercent:
memoryUsage !== null && memoryLimit !== null ? finiteOrNull((memoryUsage / memoryLimit) * 100) : null,
...computeNetworkIo(stats.networks),
...computeBlockIo(stats.blkio_stats),
pids: isCounter(stats.pids_stats?.current) ? stats.pids_stats.current : null,
}
}
// === Engine
const PODMAN_RE = /podman/i
/**
* Podman's Docker-compatible API is told from Docker by the components and the
* platform of its `GET /version` (e.g. `Podman Engine`).
*/
export function getEngineKind(version: DockerVersion | undefined): XoDockerEngineKind {
const components = Array.isArray(version?.Components) ? version.Components : []
return components.some(component => PODMAN_RE.test(String(component?.Name))) ||
PODMAN_RE.test(String(version?.Platform?.Name))
? 'podman'
: 'docker'
}
/**
* `GET /info`, and optionally `GET /version` for the daemon's API versions.
*/
export function normalizeEngineInfo(info: DockerInfo, version?: DockerVersion): NormalizedDockerEngineInfo {
const securityOptions = info.SecurityOptions ?? []
return {
id: info.ID,
kind: getEngineKind(version),
name: info.Name,
engineVersion: info.ServerVersion ?? version?.Version,
apiVersion: version?.ApiVersion,
minApiVersion: version?.MinAPIVersion,
operatingSystem: info.OperatingSystem,
osType: info.OSType,
kernelVersion: info.KernelVersion,
architecture: info.Architecture,
cpus: info.NCPU,
memory: info.MemTotal,
storageDriver: info.Driver,
loggingDriver: info.LoggingDriver,
cgroupDriver: info.CgroupDriver,
cgroupVersion: info.CgroupVersion,
rootless: securityOptions.some(option => option === 'name=rootless' || option.startsWith('name=rootless,')),
containers: {
total: info.Containers,
running: info.ContainersRunning,
paused: info.ContainersPaused,
stopped: info.ContainersStopped,
},
images: info.Images,
warnings: info.Warnings ?? [],
}
}

View File

@@ -0,0 +1,687 @@
import assert from 'node:assert/strict'
import test from 'node:test'
import { CONTAINER_LIST, INSPECT_BY_NAME } from './fixtures/containers.mjs'
import { INFO, VERSION } from './fixtures/engine.mjs'
import { STATS_BUSY, STATS_EXITED, STATS_NGINX_IDLE, STATS_PAUSED, STATS_STREAM_NGINX } from './fixtures/stats.mjs'
import {
computeCpuPercent,
computeMemoryUsage,
getComposeInfo,
getContainerName,
getEngineKind,
normalizeContainerInspect,
normalizeContainerListEntry,
normalizeContainerStats,
normalizeEngineInfo,
normalizeInspectPorts,
normalizeListPorts,
parseContainerStatus,
parseDockerDate,
} from './normalize.mjs'
import type { DockerCpuStats, DockerPort, DockerStatsSample } from './wire.mjs'
const { describe, it } = test
// the copies of stats are typed `DockerStatsSample`, whose values are `unknown`:
// the tests change them like a hostile daemon would
const clone = <T,>(value: T): T => JSON.parse(JSON.stringify(value))
// `!`: the fixtures contain these containers
const listEntry = (name: string) => CONTAINER_LIST.find(entry => entry.Names!.includes('/' + name))!
const listed = (name: string) => normalizeContainerListEntry(listEntry(name))
const inspected = (name: string) => normalizeContainerInspect(INSPECT_BY_NAME[name])
describe('parseDockerDate()', () => {
it('parses RFC 3339 dates with nanoseconds', () => {
assert.equal(parseDockerDate('2026-09-24T16:54:40.2704229Z'), Date.UTC(2026, 8, 24, 16, 54, 40, 270))
})
it('returns undefined for Go zero dates and invalid values', () => {
assert.equal(parseDockerDate('0001-01-01T00:00:00Z'), undefined)
assert.equal(parseDockerDate(''), undefined)
assert.equal(parseDockerDate(undefined), undefined)
assert.equal(parseDockerDate('not a date'), undefined)
})
})
describe('getContainerName()', () => {
it('strips the leading slash', () => {
assert.equal(getContainerName(['/xo-nginx']), 'xo-nginx')
})
it('ignores legacy link aliases', () => {
assert.equal(getContainerName(['/web/db', '/db']), 'db')
})
it('handles missing names', () => {
assert.equal(getContainerName([]), undefined)
assert.equal(getContainerName(undefined), undefined)
})
})
describe('parseContainerStatus()', () => {
const cases: [string | undefined, object][] = [
['Exited (3) 2 minutes ago', { exitCode: 3 }],
['Exited (0) 8 seconds ago', { exitCode: 0 }],
['Exited (137) About an hour ago', { exitCode: 137 }],
['Exited (-1) 1 second ago', { exitCode: -1 }],
['Restarting (1) 3 seconds ago', { exitCode: 1 }],
['Up 2 minutes', {}],
['Up 2 minutes (healthy)', { health: 'healthy' }],
['Up 2 minutes (unhealthy)', { health: 'unhealthy' }],
['Up 1 second (health: starting)', { health: 'starting' }],
['Up 2 minutes (Paused)', {}],
['Created', {}],
['Dead', {}],
['Removal In Progress', {}],
[undefined, {}],
]
for (const [status, expected] of cases) {
it(String(status), () => {
assert.deepEqual(parseContainerStatus(status), expected)
})
}
it('parses the real statuses', () => {
for (const entry of CONTAINER_LIST) {
const { exitCode } = parseContainerStatus(entry.Status)
const inspect = INSPECT_BY_NAME[getContainerName(entry.Names)!]
if (entry.State === 'exited') {
assert.equal(exitCode, inspect.State!.ExitCode)
} else {
assert.equal(exitCode, undefined)
}
}
})
})
describe('ports', () => {
it('dedupes 0.0.0.0 and :: bindings of the same port', () => {
assert.deepEqual(listed('xo-nginx').ports, [{ ip: '0.0.0.0', privatePort: 80, publicPort: 8080, protocol: 'tcp' }])
assert.deepEqual(inspected('xo-nginx').ports, listed('xo-nginx').ports)
})
it('keeps loopback, UDP and unpublished ports, sorted', () => {
const expected = [
{ ip: '0.0.0.0', privatePort: 53, publicPort: 5353, protocol: 'udp' },
{ ip: '127.0.0.1', privatePort: 80, publicPort: 9090, protocol: 'tcp' },
]
assert.deepEqual(listed('xo-cap-busy').ports, expected)
assert.deepEqual(inspected('xo-cap-busy').ports, expected)
// exposed, not published
assert.deepEqual(listed('demo-cache-1').ports, [{ privatePort: 6379, protocol: 'tcp' }])
assert.deepEqual(inspected('xo-healthy').ports, [{ privatePort: 80, protocol: 'tcp' }])
})
it('keeps IPv6-only bindings and specific addresses', () => {
assert.deepEqual(
normalizeListPorts([
{ IP: '::', PrivatePort: 80, PublicPort: 8080, Type: 'tcp' },
{ IP: '192.0.2.1', PrivatePort: 80, PublicPort: 8081, Type: 'tcp' },
{ IP: '::1', PrivatePort: 80, PublicPort: 8081, Type: 'tcp' },
// the IPv4 wildcard of another public port does not hide it
{ IP: '0.0.0.0', PrivatePort: 80, PublicPort: 8082, Type: 'tcp' },
]),
[
{ ip: '::', privatePort: 80, publicPort: 8080, protocol: 'tcp' },
{ ip: '::1', privatePort: 80, publicPort: 8081, protocol: 'tcp' },
{ ip: '192.0.2.1', privatePort: 80, publicPort: 8081, protocol: 'tcp' },
{ ip: '0.0.0.0', privatePort: 80, publicPort: 8082, protocol: 'tcp' },
]
)
})
it('removes exact duplicates and handles missing values', () => {
const port: DockerPort = { IP: '0.0.0.0', PrivatePort: 80, PublicPort: 8080, Type: 'tcp' }
assert.deepEqual(normalizeListPorts([port, { ...port }]), [
{ ip: '0.0.0.0', privatePort: 80, publicPort: 8080, protocol: 'tcp' },
])
assert.deepEqual(normalizeListPorts(undefined), [])
assert.deepEqual(normalizeInspectPorts(undefined), [])
assert.deepEqual(normalizeInspectPorts({ '80/tcp': [], 443: null }), [
{ privatePort: 80, protocol: 'tcp' },
{ privatePort: 443, protocol: 'tcp' },
])
})
})
describe('getComposeInfo()', () => {
it('extracts the project and service', () => {
assert.deepEqual(listed('demo-web-1').compose, {
project: 'demo',
service: 'web',
containerNumber: 1,
oneOff: false,
workingDir: '/srv/compose-demo',
configFiles: ['/srv/compose-demo/compose.yaml'],
})
assert.deepEqual(inspected('demo-web-1').compose, listed('demo-web-1').compose)
assert.equal(listed('demo-cache-1').compose!.service, 'cache')
})
it('is undefined outside of a Compose project', () => {
assert.equal(listed('xo-nginx').compose, undefined)
assert.equal(getComposeInfo(undefined), undefined)
assert.equal(getComposeInfo({ 'com.docker.compose.project': '' }), undefined)
})
it('only requires the project label', () => {
assert.deepEqual(
getComposeInfo({
'com.docker.compose.project': 'p',
'com.docker.compose.oneoff': 'True',
'com.docker.compose.project.config_files': 'a.yaml,b.yaml',
}),
{ project: 'p', oneOff: true, configFiles: ['a.yaml', 'b.yaml'] }
)
})
})
describe('normalizeContainerListEntry()', () => {
it('normalizes a running container', () => {
const entry = listEntry('xo-nginx')
assert.deepEqual(listed('xo-nginx'), {
dockerId: entry.Id,
name: 'xo-nginx',
image: 'nginx:alpine',
imageId: entry.ImageID,
command: "/docker-entrypoint.sh nginx -g 'daemon off;'",
createdAt: entry.Created * 1e3,
state: 'running',
status: entry.Status,
exitCode: undefined,
health: undefined,
ports: [{ ip: '0.0.0.0', privatePort: 80, publicPort: 8080, protocol: 'tcp' }],
labels: entry.Labels,
compose: undefined,
networks: [{ name: 'bridge', ipAddress: '172.17.0.2' }],
mounts: [],
})
})
it('gives the exit code of exited containers only', () => {
assert.equal(listed('xo-exited').state, 'exited')
assert.equal(listed('xo-exited').exitCode, 3)
assert.equal(listed('xo-tty').exitCode, 0)
assert.equal(listed('xo-cap-created').state, 'created')
assert.equal(listed('xo-cap-created').exitCode, undefined)
})
it('gives the health status', () => {
assert.equal(listed('xo-healthy').health, 'healthy')
assert.equal(listed('xo-unhealthy').health, 'unhealthy')
assert.equal(listed('xo-paused').state, 'paused')
assert.equal(listed('xo-paused').health, undefined)
})
it('normalizes mounts', () => {
assert.deepEqual(listed('xo-cap-busy').mounts, [
{
type: 'volume',
name: 'xo-cap-vol',
source: '/home/docker/.local/share/docker/volumes/xo-cap-vol/_data',
destination: '/data',
readOnly: false,
},
{ type: 'bind', source: '/etc/hostname', destination: '/host-hostname', readOnly: true },
])
assert.deepEqual(inspected('xo-cap-busy').mounts, listed('xo-cap-busy').mounts)
})
it('only gives known states', () => {
for (const entry of CONTAINER_LIST) {
assert.ok(
['created', 'running', 'paused', 'restarting', 'removing', 'exited', 'dead'].includes(
normalizeContainerListEntry(entry).state
)
)
}
})
})
describe('normalizeContainerInspect()', () => {
it('is consistent with the list entry', () => {
for (const entry of CONTAINER_LIST) {
const name = getContainerName(entry.Names)!
const { status, createdAt, ...fromList } = normalizeContainerListEntry(entry)
const fromInspect = inspected(name)
for (const [key, value] of Object.entries(fromList)) {
assert.deepEqual(fromInspect[key as keyof typeof fromInspect], value, `${name}: ${key}`)
}
assert.equal(Math.floor(fromInspect.createdAt! / 1e3) * 1e3, createdAt)
}
})
it('gives the details of a running container', () => {
const container = inspected('xo-cap-busy')
assert.equal(container.startedAt, Date.parse(INSPECT_BY_NAME['xo-cap-busy'].State!.StartedAt!))
assert.equal(container.finishedAt, undefined)
assert.deepEqual(container.restartPolicy, { name: 'unless-stopped', maximumRetryCount: 0 })
assert.equal(container.restartCount, 0)
assert.equal(container.tty, false)
assert.equal(container.oomKilled, false)
assert.equal(container.error, undefined)
assert.equal(container.healthCheck, undefined)
})
it('never exposes the environment', () => {
assert.ok(INSPECT_BY_NAME['xo-cap-busy'].Config!.Env!.includes('SECRET_TOKEN=hunter2'))
assert.doesNotMatch(JSON.stringify(inspected('xo-cap-busy')), /hunter2|SECRET_TOKEN/)
assert.doesNotMatch(JSON.stringify(listed('xo-cap-busy')), /hunter2|SECRET_TOKEN/)
})
it('gives the exit code and dates of an exited container', () => {
const container = inspected('xo-exited')
assert.equal(container.exitCode, 3)
assert.equal(container.startedAt, Date.parse('2026-09-24T16:54:38.102Z'))
assert.equal(container.finishedAt, Date.parse('2026-09-24T16:54:38.379Z'))
assert.deepEqual(container.restartPolicy, { name: 'no', maximumRetryCount: 0 })
})
it('handles a created container', () => {
const container = inspected('xo-cap-created')
assert.equal(container.state, 'created')
assert.equal(container.exitCode, undefined)
assert.equal(container.startedAt, undefined)
})
it('detects TTY containers', () => {
assert.equal(inspected('xo-tty').tty, true)
assert.equal(inspected('xo-nginx').tty, false)
})
it('gives the health check status', () => {
const healthy = inspected('xo-healthy')
const log = INSPECT_BY_NAME['xo-healthy'].State!.Health!.Log!
assert.equal(healthy.health, 'healthy')
assert.deepEqual(healthy.healthCheck, {
failingStreak: 0,
lastCheckAt: Date.parse(log.at(-1)!.End!),
lastExitCode: 0,
})
const unhealthy = inspected('xo-unhealthy')
assert.equal(unhealthy.health, 'unhealthy')
assert.ok(unhealthy.healthCheck!.failingStreak > 0)
assert.equal(unhealthy.healthCheck!.lastExitCode, 1)
})
it('handles missing optional parts (old API versions)', () => {
const data = clone(INSPECT_BY_NAME['xo-nginx'])
delete data.HostConfig!.RestartPolicy
delete data.NetworkSettings
delete data.Mounts
delete data.Config!.Labels
const container = normalizeContainerInspect(data)
assert.deepEqual(container.restartPolicy, { name: 'no', maximumRetryCount: 0 })
assert.deepEqual(container.ports, [])
assert.deepEqual(container.networks, [])
assert.deepEqual(container.mounts, [])
assert.deepEqual(container.labels, {})
})
})
describe('computeCpuPercent()', () => {
it('computes the CPU usage of a busy container (one full core)', () => {
const { cpuPercent, onlineCpus } = computeCpuPercent(STATS_BUSY.cpu_stats, STATS_BUSY.precpu_stats)
assert.equal(onlineCpus, 6)
const { cpu_stats: cpu, precpu_stats: precpu } = STATS_BUSY
assert.equal(
cpuPercent,
((cpu.cpu_usage.total_usage - precpu.cpu_usage.total_usage) / (cpu.system_cpu_usage - precpu.system_cpu_usage)) *
6 *
100
)
assert.ok(cpuPercent! > 95 && cpuPercent! < 105, String(cpuPercent))
})
it('gives 0 for an idle container', () => {
assert.equal(computeCpuPercent(STATS_NGINX_IDLE.cpu_stats, STATS_NGINX_IDLE.precpu_stats).cpuPercent, 0)
assert.equal(computeCpuPercent(STATS_PAUSED.cpu_stats, STATS_PAUSED.precpu_stats).cpuPercent, 0)
})
it('falls back to percpu_usage when online_cpus is missing', () => {
const cpu = clone<DockerCpuStats>(STATS_BUSY.cpu_stats)
const precpu = clone<DockerCpuStats>(STATS_BUSY.precpu_stats)
delete cpu.online_cpus
delete precpu.online_cpus
cpu.cpu_usage!.percpu_usage = [1, 2, 3, 4]
const { cpuPercent, onlineCpus } = computeCpuPercent(cpu, precpu)
assert.equal(onlineCpus, 4)
const expected = (computeCpuPercent(STATS_BUSY.cpu_stats, STATS_BUSY.precpu_stats).cpuPercent! * 4) / 6
assert.ok(Math.abs(cpuPercent! - expected) < 1e-9, `${cpuPercent} ≠ ${expected}`)
delete cpu.cpu_usage!.percpu_usage
assert.deepEqual(computeCpuPercent(cpu, precpu), { cpuPercent: null, onlineCpus: undefined })
})
it('gives null, not Infinity, when system_cpu_usage is 0', () => {
const cpu = clone<DockerCpuStats>(STATS_BUSY.cpu_stats)
const precpu = clone<DockerCpuStats>(STATS_BUSY.precpu_stats)
precpu.system_cpu_usage = 0
assert.equal(computeCpuPercent(cpu, precpu).cpuPercent, null)
precpu.system_cpu_usage = cpu.system_cpu_usage
assert.equal(computeCpuPercent(cpu, precpu).cpuPercent, null)
cpu.system_cpu_usage = 0
precpu.system_cpu_usage = 0
assert.equal(computeCpuPercent(cpu, precpu).cpuPercent, null)
})
it('gives null for the first object of a stream (no precpu_stats.system_cpu_usage)', () => {
const [first, second] = STATS_STREAM_NGINX
assert.equal(first.precpu_stats.system_cpu_usage, undefined)
assert.equal(computeCpuPercent(first.cpu_stats, first.precpu_stats).cpuPercent, null)
assert.equal(computeCpuPercent(second.cpu_stats, second.precpu_stats).cpuPercent, 0)
})
it('gives null when the counters went backwards', () => {
const cpu = clone<DockerCpuStats>(STATS_BUSY.cpu_stats)
cpu.cpu_usage!.total_usage = 0
assert.equal(computeCpuPercent(cpu, STATS_BUSY.precpu_stats).cpuPercent, null)
})
it('gives null without any data', () => {
assert.equal(computeCpuPercent(STATS_EXITED.cpu_stats, STATS_EXITED.precpu_stats).cpuPercent, null)
assert.equal(computeCpuPercent(undefined, undefined).cpuPercent, null)
})
})
describe('computeMemoryUsage()', () => {
it('subtracts inactive_file on cgroup v2', () => {
const { usage, stats } = STATS_NGINX_IDLE.memory_stats
assert.equal(computeMemoryUsage(STATS_NGINX_IDLE.memory_stats), usage - stats.inactive_file)
})
// cgroup v1 shape (`docker stats` from a cgroup v1 host, Docker 24)
const V1 = {
usage: 104857600,
max_usage: 209715200,
limit: 2147483648,
stats: {
active_anon: 50331648,
active_file: 16777216,
cache: 41943040,
inactive_anon: 0,
inactive_file: 25165824,
rss: 52428800,
total_active_file: 16777216,
total_cache: 41943040,
total_inactive_file: 20971520,
total_rss: 52428800,
},
}
it('subtracts total_inactive_file on cgroup v1', () => {
assert.equal(computeMemoryUsage(V1), V1.usage - V1.stats.total_inactive_file)
})
it('subtracts cache on cgroup v1 without total_inactive_file', () => {
const memoryStats = { usage: V1.usage, stats: { cache: V1.stats.cache, rss: V1.stats.rss } }
assert.equal(computeMemoryUsage(memoryStats), V1.usage - V1.stats.cache)
})
it('does not return a negative value', () => {
assert.equal(computeMemoryUsage({ usage: 1000, stats: { inactive_file: 2000 } }), 1000)
assert.equal(computeMemoryUsage({ usage: 1000 }), 1000)
})
it('gives null without data', () => {
assert.equal(computeMemoryUsage(STATS_EXITED.memory_stats), null)
assert.equal(computeMemoryUsage(undefined), null)
})
})
describe('normalizeContainerStats()', () => {
it('normalizes the stats of a running container', () => {
const { memory_stats: memory } = STATS_NGINX_IDLE
const memoryUsage = memory.usage - memory.stats.inactive_file
assert.deepEqual(normalizeContainerStats(STATS_NGINX_IDLE), {
sampledAt: Date.parse(STATS_NGINX_IDLE.read),
cpuPercent: 0,
onlineCpus: 6,
memoryUsage,
memoryLimit: memory.limit,
memoryPercent: (memoryUsage / memory.limit) * 100,
networkRx: STATS_NGINX_IDLE.networks.eth0.rx_bytes,
networkTx: STATS_NGINX_IDLE.networks.eth0.tx_bytes,
// no io controller delegated to the rootless daemon
blockRead: null,
blockWrite: null,
pids: 7,
})
})
it('gives nulls for a stopped container', () => {
assert.deepEqual(normalizeContainerStats(STATS_EXITED), {
sampledAt: null,
cpuPercent: null,
onlineCpus: undefined,
memoryUsage: null,
memoryLimit: null,
memoryPercent: null,
networkRx: null,
networkTx: null,
blockRead: null,
blockWrite: null,
pids: null,
})
})
it('never gives NaN or Infinity (which would serialize to null)', () => {
for (const stats of [STATS_BUSY, STATS_EXITED, STATS_PAUSED, ...STATS_STREAM_NGINX]) {
const normalized = normalizeContainerStats(stats)
for (const value of Object.values(normalized)) {
assert.ok(value === null || value === undefined || Number.isFinite(value))
}
}
})
it('sums the block I/O (cgroup v1 and v2 op names) and the network interfaces', () => {
const stats = clone<DockerStatsSample>(STATS_NGINX_IDLE)
stats.blkio_stats!.io_service_bytes_recursive = [
{ major: 8, minor: 0, op: 'Read', value: 100 },
{ major: 8, minor: 0, op: 'Write', value: 10 },
{ major: 8, minor: 16, op: 'read', value: 200 },
{ major: 8, minor: 16, op: 'write', value: 20 },
{ major: 8, minor: 16, op: 'Total', value: 330 },
]
;(stats.networks as Record<string, unknown>).eth1 = { rx_bytes: 1, tx_bytes: 2 }
const { blockRead, blockWrite, networkRx, networkTx } = normalizeContainerStats(stats)
assert.deepEqual(
{ blockRead, blockWrite, networkRx, networkTx },
{
blockRead: 300,
blockWrite: 30,
networkRx: STATS_NGINX_IDLE.networks.eth0.rx_bytes + 1,
networkTx: STATS_NGINX_IDLE.networks.eth0.tx_bytes + 2,
}
)
})
it('does not compute the CPU usage of Windows containers', () => {
const stats = { ...clone(STATS_BUSY), os_type: 'windows', memory_stats: { privateworkingset: 1234 } }
const normalized = normalizeContainerStats(stats)
assert.equal(normalized.cpuPercent, null)
assert.equal(normalized.memoryUsage, 1234)
})
// a hostile (or buggy) daemon controls every value: only finite numbers may
// come out, never strings (concatenated by the sums), objects or NaN/Infinity
describe('hostile values', () => {
const HOSTILE = ['1000', '', 'x', NaN, Infinity, -Infinity, { valueOf: 1 }, [1], true, null, 1e308]
const assertOnlyFinite = (normalized: object) => {
for (const [key, value] of Object.entries(normalized)) {
assert.ok(
value === null || value === undefined || (typeof value === 'number' && Number.isFinite(value)),
`${key}: ${typeof value} ${String(value)}`
)
}
}
it('in the block I/O and network sums', () => {
for (const hostile of HOSTILE) {
const stats = clone<DockerStatsSample>(STATS_NGINX_IDLE)
stats.blkio_stats!.io_service_bytes_recursive = [
{ op: 'Read', value: 100 },
{ op: 'Read', value: hostile },
{ op: 'Write', value: hostile },
{ op: 'Write', value: 1e308 },
]
stats.networks = { eth0: { rx_bytes: 10, tx_bytes: hostile }, eth1: { rx_bytes: hostile, tx_bytes: 1e308 } }
const normalized = normalizeContainerStats(stats)
assertOnlyFinite(normalized)
if (typeof hostile === 'number' && Number.isFinite(hostile)) {
continue // 1e308: the sums overflow, checked by assertOnlyFinite
}
assert.equal(normalized.blockRead, 100, String(hostile))
assert.equal(normalized.networkRx, 10, String(hostile))
}
})
it('in the entries themselves (non-object entries, op not a string)', () => {
const stats = clone<DockerStatsSample>(STATS_NGINX_IDLE)
stats.blkio_stats!.io_service_bytes_recursive = [null, 'x', 1, { op: 1, value: 1 }, { op: 'read', value: 2 }]
stats.networks = { eth0: null, eth1: 'x', eth2: { rx_bytes: 3, tx_bytes: 4 } }
const normalized = normalizeContainerStats(stats)
assert.equal(normalized.blockRead, 2)
assert.equal(normalized.networkRx, 3)
assert.equal(normalized.networkTx, 4)
stats.networks = 'eth0'
assertOnlyFinite(normalizeContainerStats(stats))
})
it('in privateworkingset (Windows)', () => {
for (const hostile of HOSTILE) {
const stats = { os_type: 'windows', memory_stats: { privateworkingset: hostile, limit: 1e-300 } }
assertOnlyFinite(normalizeContainerStats(stats))
}
})
it('in the CPU and memory counters, online_cpus and pids', () => {
for (const hostile of HOSTILE) {
for (const set of [
(s: DockerStatsSample) => (s.cpu_stats!.online_cpus = hostile),
(s: DockerStatsSample) => (s.cpu_stats!.cpu_usage!.total_usage = hostile),
(s: DockerStatsSample) => (s.precpu_stats!.cpu_usage!.total_usage = hostile),
(s: DockerStatsSample) => (s.cpu_stats!.system_cpu_usage = hostile),
(s: DockerStatsSample) => (s.precpu_stats!.system_cpu_usage = hostile),
(s: DockerStatsSample) => (s.cpu_stats!.cpu_usage!.percpu_usage = hostile),
(s: DockerStatsSample) => (s.memory_stats!.usage = hostile),
(s: DockerStatsSample) => (s.memory_stats!.limit = hostile),
(s: DockerStatsSample) => ((s.memory_stats!.stats as Record<string, unknown>).inactive_file = hostile),
(s: DockerStatsSample) => (s.pids_stats!.current = hostile),
(s: DockerStatsSample) => (s.read = hostile),
]) {
const stats = clone<DockerStatsSample>(STATS_BUSY)
set(stats)
assertOnlyFinite(normalizeContainerStats(stats))
}
}
})
it('does not accept numeric strings for online_cpus', () => {
const stats = clone<DockerStatsSample>(STATS_BUSY)
stats.cpu_stats!.online_cpus = '4'
delete stats.cpu_stats!.cpu_usage!.percpu_usage
const normalized = normalizeContainerStats(stats)
assert.equal(normalized.onlineCpus, undefined)
assert.equal(normalized.cpuPercent, null)
})
it('huge values which overflow give null, not Infinity', () => {
const stats = clone<DockerStatsSample>(STATS_BUSY)
stats.cpu_stats!.online_cpus = 1e308
stats.memory_stats = { usage: 1e308, limit: 1e-300, stats: {} }
const normalized = normalizeContainerStats(stats)
assertOnlyFinite(normalized)
assert.equal(normalized.cpuPercent, null)
assert.equal(normalized.memoryPercent, null)
})
it('a non-object stats value throws (the sampler drops the stream)', () => {
for (const value of [null, 1, 'x']) {
assert.throws(() => normalizeContainerStats(value))
}
})
})
})
// `GET /version` of Podman 5 (Docker-compatible API)
const PODMAN_VERSION = {
Platform: { Name: 'linux/amd64/debian-13' },
Components: [
{
Name: 'Podman Engine',
Version: '5.4.2',
Details: {
APIVersion: '5.4.2',
Arch: 'amd64',
BuildTime: '2025-04-30T00:00:00Z',
Experimental: 'false',
GitCommit: '',
GoVersion: 'go1.24.2',
KernelVersion: '6.12.101+deb13-amd64',
MinAPIVersion: '4.0.0',
Os: 'linux',
},
},
],
Version: '5.4.2',
ApiVersion: '1.41',
MinAPIVersion: '1.24',
Os: 'linux',
Arch: 'amd64',
}
describe('getEngineKind()', () => {
it('tells Podman from Docker', () => {
assert.equal(getEngineKind(VERSION), 'docker')
assert.equal(getEngineKind(PODMAN_VERSION), 'podman')
})
it('from the platform alone, defaults to docker', () => {
assert.equal(getEngineKind({ Platform: { Name: 'Podman Engine' } }), 'podman')
assert.equal(getEngineKind(undefined), 'docker')
assert.equal(getEngineKind({ Components: 'garbage' } as never), 'docker')
assert.equal(getEngineKind({ Components: [null] } as never), 'docker')
})
})
describe('normalizeEngineInfo()', () => {
it('normalizes /info and /version', () => {
assert.deepEqual(normalizeEngineInfo(INFO, VERSION), {
id: INFO.ID,
kind: 'docker',
name: 'docker-host',
engineVersion: '29.8.1',
apiVersion: '1.56',
minApiVersion: '1.40',
operatingSystem: 'Debian GNU/Linux 13 (trixie)',
osType: 'linux',
kernelVersion: INFO.KernelVersion,
architecture: 'x86_64',
cpus: 6,
memory: INFO.MemTotal,
storageDriver: 'overlayfs',
loggingDriver: 'json-file',
cgroupDriver: 'systemd',
cgroupVersion: '2',
rootless: true,
containers: { total: 8, running: 5, paused: 1, stopped: 2 },
images: 3,
warnings: INFO.Warnings,
})
})
it('works without /version and on a rootful daemon', () => {
const info = normalizeEngineInfo({ ...INFO, SecurityOptions: ['name=seccomp,profile=builtin'], Warnings: null })
assert.equal(info.engineVersion, '29.8.1')
assert.equal(info.apiVersion, undefined)
assert.equal(info.rootless, false)
assert.deepEqual(info.warnings, [])
})
it('tells Podman', () => {
assert.equal(normalizeEngineInfo(INFO, PODMAN_VERSION).kind, 'podman')
})
})

View File

@@ -0,0 +1,504 @@
// Pool of Docker connections, one per engine.
//
// - key = engine id + revision: bumping the revision (credential/host update)
// makes the pool open a new connection instead of reusing the old one; the
// revision is opaque, e.g. a hash of the connection parameters, so that a
// connection can never serve other parameters than the ones it was opened
// with
// - concurrent first uses of an engine share one SSH handshake
// - a connection whose SSH session ends (lost, or closed) is removed: the next
// use opens a new one, through `createConnection` and the negative cache
// - idle connections are closed after `idleTimeout` by one shared, unref'd
// sweeper
// - at most `maxConnections`: the least recently used idle connection is
// evicted, and POOL_EXHAUSTED is thrown when all of them are busy
// - negative cache: after a connection failure, uses of the engine fail fast
// for `failureTtl`, and the last error stays available (`getState()`) until a
// connection succeeds or the engine is invalidated
//
// No XO concepts here: the caller provides the connection factory.
import { createLogger } from '@xen-orchestra/log'
import type { XoDockerEngineKind } from '@vates/types'
import type { DockerConnection } from './connection.mjs'
import {
CONNECTION_CLOSED,
DOCKER_API_VERSION_UNSUPPORTED,
DOCKER_SOCKET_UNREACHABLE,
DockerError,
HOST_KEY_MISMATCH,
HOST_KEY_UNKNOWN,
isDockerError,
POOL_EXHAUSTED,
SSH_AUTH_FAILED,
SSH_ERROR,
SSH_REFUSED_PENALTY,
SSH_UNREACHABLE,
STREAM_LOCAL_FORWARDING_DISABLED,
STREAM_LOCAL_UNSUPPORTED,
} from './errors.mjs'
const { debug, warn } = createLogger('xo:docker:pool')
export const DEFAULT_MAX_CONNECTIONS = 20
export const DEFAULT_IDLE_TIMEOUT = 5 * 60e3
export const DEFAULT_FAILURE_TTL = 30e3
export const DEFAULT_SWEEP_INTERVAL = 30e3
// errors raised while using an established connection which mean that the
// engine itself is unusable: they evict the connection and are negatively
// cached, like connection failures
//
// Not included: Docker API errors (4xx/5xx of one request), TIMEOUT (one slow
// request), POOL_EXHAUSTED and CONNECTION_CLOSED (local conditions)
const ENGINE_FAILURE_CODES = new Set([
DOCKER_API_VERSION_UNSUPPORTED,
DOCKER_SOCKET_UNREACHABLE,
HOST_KEY_MISMATCH,
HOST_KEY_UNKNOWN,
SSH_AUTH_FAILED,
SSH_ERROR,
SSH_REFUSED_PENALTY,
SSH_UNREACHABLE,
STREAM_LOCAL_FORWARDING_DISABLED,
STREAM_LOCAL_UNSUPPORTED,
])
const LOCAL_CODES = new Set([CONNECTION_CLOSED, POOL_EXHAUSTED])
const isEngineFailure = (error: unknown): error is DockerError =>
isDockerError(error) && ENGINE_FAILURE_CODES.has(error.code)
// what is exposed of an error in `getState()`
const summarizeError = (error: unknown): { code: string; message: string } => ({
code: isDockerError(error) ? error.code : 'UNKNOWN_ERROR',
message: String((error as { message?: unknown } | null | undefined)?.message ?? error),
})
const makeKey = (id: string, revision: number | string | undefined) => `${id}:${revision ?? 0}`
/**
* What the users of a pooled connection get, see `createFacade()`.
*/
export type DockerConnectionFacade = Pick<
DockerConnection,
'apiVersion' | 'engineKind' | 'engineVersion' | 'observedHostKey' | 'request' | 'requestStream' | 'exec'
>
/**
* What the pool uses of a connection: a `DockerConnection`, or a stand-in in
* tests.
*/
export type PoolableConnection = DockerConnectionFacade & Pick<DockerConnection, 'connect' | 'close' | 'onClose'>
/** State of an engine's connection, see `getState()` */
export type DockerConnectionState = {
status: 'idle' | 'connected' | 'error'
error?: { code: string; message: string }
/** only when connected */
kind?: XoDockerEngineKind
}
type Entry = {
closed: boolean
closing?: Promise<void>
connected: boolean
connection: PoolableConnection | undefined
facade: DockerConnectionFacade | undefined
id: string
key: string
lastUsed: number
ready: Promise<void>
refs: number
}
// a failure is anything a connection attempt threw, a DockerError in practice
type Failure = { error: unknown; until: number }
/**
* Facade given to the users of a pooled connection: neither `connect()` nor
* `close()`, and new requests are refused once the pool has closed the
* connection (eviction, invalidation, destroy).
*/
function createFacade(entry: Entry): DockerConnectionFacade {
// set before the facade is created
const { connection } = entry as Entry & { connection: PoolableConnection }
const assertOpen = () => {
if (entry.closed) {
throw new DockerError(CONNECTION_CLOSED, 'the Docker connection has been closed')
}
}
return {
get apiVersion() {
return connection.apiVersion
},
get engineKind() {
return connection.engineKind
},
get engineVersion() {
return connection.engineVersion
},
get observedHostKey() {
return connection.observedHostKey
},
async request(opts) {
assertOpen()
return connection.request(opts)
},
async requestStream(opts) {
assertOpen()
return connection.requestStream(opts)
},
async exec(command, opts) {
assertOpen()
return connection.exec(command, opts)
},
}
}
export class DockerConnectionPool {
#destroyed = false
// key → entry
#entries = new Map<string, Entry>()
// key → { error, until }
#failures = new Map<string, Failure>()
#failureTtl: number
#idleTimeout: number
#maxConnections: number
#now: () => number
#onSweep: (() => void) | undefined
#sweeper: NodeJS.Timeout | undefined
#sweepInterval: number
/**
* @param opts.idleTimeout ms
* @param opts.failureTtl ms
* @param opts.sweepInterval ms
* @param opts.onSweep called on each sweep, e.g. to clean caches
* @param opts.now for tests
*/
constructor({
maxConnections = DEFAULT_MAX_CONNECTIONS,
idleTimeout = DEFAULT_IDLE_TIMEOUT,
failureTtl = DEFAULT_FAILURE_TTL,
sweepInterval = DEFAULT_SWEEP_INTERVAL,
onSweep,
now = Date.now,
}: {
maxConnections?: number
idleTimeout?: number
failureTtl?: number
sweepInterval?: number
onSweep?: () => void
now?: () => number
} = {}) {
this.#failureTtl = failureTtl
this.#idleTimeout = idleTimeout
this.#maxConnections = maxConnections
this.#now = now
this.#onSweep = onSweep
this.#sweepInterval = sweepInterval
}
/** number of connections (established or being established) */
get size(): number {
return this.#entries.size
}
/**
* Passive state of an engine's connection, never connects.
*/
getState(id: string, revision?: number | string): DockerConnectionState {
const key = makeKey(id, revision)
const failure = this.#failures.get(key)
if (failure !== undefined) {
return { status: 'error', error: summarizeError(failure.error) }
}
const entry = this.#entries.get(key)
if (!entry?.connected) {
return { status: 'idle' }
}
const kind = entry.connection?.engineKind
return kind === undefined ? { status: 'connected' } : { status: 'connected', kind }
}
/**
* Forget the last failure of an engine (e.g. after a successful manual test).
*/
clearFailure(id: string): void {
this.#deleteFailures(id)
}
/**
* Run `fn` with the connection of an engine, connecting if necessary.
*
* The connection is considered busy (never evicted) while `fn` runs.
*
* @param createConnection returns a new, not yet connected, connection
*/
async use<T>(
engine: { id: string; revision?: number | string },
createConnection: () => Promise<PoolableConnection> | PoolableConnection,
fn: (connection: DockerConnectionFacade) => Promise<T> | T
): Promise<T> {
const { connection, release } = await this.hold(engine, createConnection)
try {
const result = await fn(connection)
release()
return result
} catch (error) {
release(error)
throw error
}
}
/**
* Same as `use()` for a connection held across calls (e.g. by a stats
* sampler): busy (never evicted) until `release()` is called.
*
* `release(error)` with an engine failure evicts the connection and
* negatively caches the failure, like an error thrown by the `fn` of `use()`.
*
* @returns `release` is idempotent
*/
async hold(
{ id, revision }: { id: string; revision?: number | string },
createConnection: () => Promise<PoolableConnection> | PoolableConnection
): Promise<{ connection: DockerConnectionFacade; release: (error?: unknown) => void }> {
const entry = await this.#acquire(id, revision, createConnection)
let released = false
return {
// set once the entry is ready
connection: entry.facade!,
release: error => {
if (released) {
return
}
released = true
if (isEngineFailure(error) && this.#entries.get(entry.key) === entry) {
debug('engine failure while using a connection', { id, code: error.code })
this.#setFailure(entry.key, error)
this.#close(entry)
}
--entry.refs
entry.lastUsed = this.#now()
},
}
}
async #acquire(
id: string,
revision: number | string | undefined,
createConnection: () => Promise<PoolableConnection> | PoolableConnection
): Promise<Entry> {
if (this.#destroyed) {
throw new DockerError(CONNECTION_CLOSED, 'the Docker connection pool has been destroyed')
}
const key = makeKey(id, revision)
const failure = this.#failures.get(key)
if (failure !== undefined && failure.until > this.#now()) {
// a DockerError in practice, anything else is reported as SSH_ERROR
const error = failure.error as { code?: string; message: string; data?: object }
throw new DockerError(error.code ?? SSH_ERROR, error.message, {
data: { ...error.data, failFast: true, retryAt: failure.until },
cause: error,
})
}
let entry = this.#entries.get(key)
if (entry === undefined) {
entry = this.#create(id, key, createConnection)
}
++entry.refs
entry.lastUsed = this.#now()
try {
await entry.ready
} catch (error) {
--entry.refs
throw error
}
if (entry.closed) {
--entry.refs
throw new DockerError(CONNECTION_CLOSED, 'the Docker connection has been closed')
}
return entry
}
#create(id: string, key: string, createConnection: () => Promise<PoolableConnection> | PoolableConnection): Entry {
if (this.#entries.size >= this.#maxConnections) {
this.#evictOne()
}
// the failures of the other revisions of an engine are stale: they would
// otherwise stay in memory until the engine is invalidated
this.#deleteFailures(id, key)
const entry: Entry = {
closed: false,
connected: false,
connection: undefined,
facade: undefined,
id,
key,
lastUsed: this.#now(),
// replaced right below, `entry` must exist before the promise runs
ready: undefined as unknown as Promise<void>,
refs: 0,
}
entry.ready = (async () => {
const connection = await createConnection()
entry.connection = connection
entry.facade = createFacade(entry)
connection.onClose(() => {
if (this.#entries.get(key) === entry) {
debug('Docker connection closed, removed from the pool', { id })
}
this.#close(entry)
})
if (entry.closed) {
throw new DockerError(CONNECTION_CLOSED, 'the Docker connection has been closed')
}
await connection.connect()
})().then(
() => {
entry.connected = true
if (this.#entries.get(key) === entry) {
this.#failures.delete(key)
}
},
error => {
if (this.#entries.get(key) === entry) {
this.#entries.delete(key)
if (!(isDockerError(error) && LOCAL_CODES.has(error.code))) {
this.#setFailure(key, error)
}
}
entry.closed = true
entry.connection?.close().catch(error => warn('failed to close a Docker connection', { error }))
throw error
}
)
// unhandled rejections are prevented: waiters handle it
entry.ready.catch(() => {})
this.#entries.set(key, entry)
this.#startSweeper()
return entry
}
#setFailure(key: string, error: unknown): void {
this.#failures.set(key, { error, until: this.#now() + this.#failureTtl })
}
// failures of all the revisions of an engine, except `keep`
#deleteFailures(id: string, keep?: string): void {
for (const key of this.#failures.keys()) {
if (key !== keep && key.startsWith(id + ':')) {
this.#failures.delete(key)
}
}
}
#evictOne(): void {
let lru: Entry | undefined
for (const entry of this.#entries.values()) {
if (entry.refs === 0 && entry.connected && (lru === undefined || entry.lastUsed < lru.lastUsed)) {
lru = entry
}
}
if (lru === undefined) {
throw new DockerError(POOL_EXHAUSTED, 'too many Docker connections in use', {
data: { maxConnections: this.#maxConnections },
})
}
debug('evicting the least recently used Docker connection', { id: lru.id })
this.#close(lru)
}
/**
* Remove an entry from the pool and close its connection.
*
* @returns never rejects
*/
#close(entry: Entry): Promise<void> {
if (this.#entries.get(entry.key) === entry) {
this.#entries.delete(entry.key)
}
if (this.#entries.size === 0) {
this.#stopSweeper()
}
if (entry.closed && entry.closing !== undefined) {
return entry.closing
}
entry.closed = true
entry.closing = entry.ready
.catch(() => {})
.then(() => entry.connection?.close())
.catch(error => warn('failed to close a Docker connection', { id: entry.id, error }))
return entry.closing
}
#startSweeper(): void {
if (this.#sweeper === undefined && !this.#destroyed) {
this.#sweeper = setInterval(() => this.sweep(), this.#sweepInterval)
this.#sweeper.unref()
}
}
#stopSweeper(): void {
if (this.#sweeper !== undefined) {
clearInterval(this.#sweeper)
this.#sweeper = undefined
}
}
/**
* Close the connections idle for more than `idleTimeout`.
*
* Called periodically while the pool has connections, exposed for tests.
*/
sweep(): void {
const limit = this.#now() - this.#idleTimeout
for (const entry of Array.from(this.#entries.values())) {
if (entry.refs === 0 && entry.connected && entry.lastUsed <= limit) {
debug('closing an idle Docker connection', { id: entry.id })
this.#close(entry)
}
}
try {
this.#onSweep?.()
} catch (error) {
warn('onSweep', { error })
}
}
/**
* Close the connections of an engine (all revisions) and forget its last
* failure.
*/
async invalidate(id: string): Promise<void> {
this.clearFailure(id)
const promises: Promise<void>[] = []
for (const entry of Array.from(this.#entries.values())) {
if (entry.id === id) {
promises.push(this.#close(entry))
}
}
await Promise.all(promises)
}
/**
* Close every connection, the pool cannot be used afterwards.
*/
async destroy(): Promise<void> {
this.#destroyed = true
this.#stopSweeper()
this.#failures.clear()
await Promise.all(Array.from(this.#entries.values(), entry => this.#close(entry)))
}
}

View File

@@ -0,0 +1,454 @@
import assert from 'node:assert/strict'
import { describe, it } from 'node:test'
import {
CONNECTION_CLOSED,
DOCKER_API_ERROR,
DockerError,
POOL_EXHAUSTED,
SSH_AUTH_FAILED,
SSH_UNREACHABLE,
} from './errors.mjs'
import type { DockerRequestOptions } from './connection.mjs'
import { type DockerConnectionFacade, DockerConnectionPool } from './pool.mjs'
class FakeConnection {
static instances: FakeConnection[] = []
closed = 0
connected = false
connects = 0
connectDelay: number
connectError: DockerError | undefined
onCloseListener: (() => void) | undefined
constructor({ connectError, connectDelay = 0 }: { connectError?: DockerError; connectDelay?: number } = {}) {
this.connectDelay = connectDelay
this.connectError = connectError
FakeConnection.instances.push(this)
}
engineKind: 'docker' | 'podman' | undefined = undefined
get apiVersion() {
return '1.43'
}
async connect() {
++this.connects
await new Promise(resolve => setTimeout(resolve, this.connectDelay))
if (this.connectError !== undefined) {
throw this.connectError
}
this.connected = true
}
async close() {
++this.closed
this.connected = false
}
onClose(listener: () => void) {
this.onCloseListener = listener
}
// the SSH session ends on its own (network failure, server restart…)
simulateLoss() {
this.connected = false
this.onCloseListener?.()
}
async request({ path }: DockerRequestOptions) {
return { statusCode: 200, headers: {}, body: path }
}
// not used by these tests, but part of `PoolableConnection`
get engineVersion() {
return undefined
}
get observedHostKey() {
return undefined
}
async requestStream(): Promise<never> {
throw new Error('not implemented')
}
async exec(): Promise<never> {
throw new Error('not implemented')
}
}
const createClock = (start = 1e6) => {
const clock = () => clock.time
clock.time = start
return clock
}
const engine = (id: string, revision: number | string = 0) => ({ id, revision })
const idle = () => {}
describe('DockerConnectionPool', () => {
it('shares one handshake between concurrent first uses', async () => {
const pool = new DockerConnectionPool()
let created = 0
const create = () => {
++created
return new FakeConnection({ connectDelay: 20 })
}
const results = await Promise.all(
Array.from({ length: 10 }, (_, i) => pool.use(engine('a'), create, c => c.request({ path: '/' + i })))
)
assert.equal(created, 1)
assert.deepEqual(
results.map(_ => _.body),
Array.from({ length: 10 }, (_, i) => '/' + i)
)
assert.deepEqual(pool.getState('a', 0), { status: 'connected' })
await pool.destroy()
})
it('reuses the connection for later uses and uses a new one for a new revision', async () => {
const pool = new DockerConnectionPool()
const connections = []
const create = () => {
const connection = new FakeConnection()
connections.push(connection)
return connection
}
await pool.use(engine('a', 0), create, idle)
await pool.use(engine('a', 0), create, idle)
assert.equal(connections.length, 1)
await pool.use(engine('a', 1), create, idle)
assert.equal(connections.length, 2)
assert.deepEqual(pool.getState('a', 0), { status: 'connected' })
assert.deepEqual(pool.getState('b', 0), { status: 'idle' })
await pool.destroy()
})
it('getState() gives the kind of a connected engine', async () => {
const pool = new DockerConnectionPool()
await pool.use(engine('a'), () => Object.assign(new FakeConnection(), { engineKind: 'podman' as const }), idle)
assert.deepEqual(pool.getState('a', 0), { status: 'connected', kind: 'podman' })
await pool.destroy()
})
it('negative cache: fails fast after a connection failure, then retries after failureTtl', async () => {
const now = createClock()
const pool = new DockerConnectionPool({ failureTtl: 30e3, now })
let created = 0
const create = () => {
++created
return new FakeConnection({ connectError: new DockerError(SSH_UNREACHABLE, 'unreachable') })
}
await assert.rejects(pool.use(engine('a'), create, idle), { code: SSH_UNREACHABLE })
assert.equal(created, 1)
assert.equal(FakeConnection.instances.at(-1)!.closed, 1, 'the failed connection is closed')
now.time += 10e3
await assert.rejects(pool.use(engine('a'), create, idle), (error: DockerError) => {
assert.equal(error.code, SSH_UNREACHABLE)
assert.equal(error.data!.failFast, true)
assert.equal(error.data!.retryAt, 1e6 + 30e3)
return true
})
assert.equal(created, 1, 'no new attempt during failureTtl')
// the error is exposed passively, without connecting
assert.deepEqual(pool.getState('a', 0), {
status: 'error',
error: { code: SSH_UNREACHABLE, message: 'unreachable' },
})
now.time += 25e3
await assert.rejects(pool.use(engine('a'), create, idle), { code: SSH_UNREACHABLE })
assert.equal(created, 2, 'retried after failureTtl')
await pool.destroy()
})
it('keeps reporting the last error after failureTtl, until a connection succeeds', async () => {
const now = createClock()
const pool = new DockerConnectionPool({ failureTtl: 30e3, now })
let error: DockerError | undefined = new DockerError(SSH_AUTH_FAILED, 'bad key')
const create = () => new FakeConnection({ connectError: error })
await assert.rejects(pool.use(engine('a'), create, idle))
now.time += 60e3
assert.equal(pool.getState('a').status, 'error')
error = undefined
await pool.use(engine('a'), create, idle)
assert.deepEqual(pool.getState('a'), { status: 'connected' })
await pool.destroy()
})
it('an engine failure while using a connection evicts it and is negatively cached', async () => {
const pool = new DockerConnectionPool()
const create = () => new FakeConnection()
await pool.use(engine('a'), create, idle)
const [connection] = FakeConnection.instances.slice(-1)
await assert.rejects(
pool.use(engine('a'), create, () => {
throw new DockerError(SSH_UNREACHABLE, 'connection lost')
}),
{ code: SSH_UNREACHABLE }
)
assert.equal(pool.size, 0)
assert.equal(connection.closed, 1)
assert.equal(pool.getState('a').status, 'error')
await assert.rejects(pool.use(engine('a'), create, idle), (error: DockerError) => error.data!.failFast === true)
await pool.destroy()
})
it('a Docker API error does not evict the connection', async () => {
const pool = new DockerConnectionPool()
const create = () => new FakeConnection()
await assert.rejects(
pool.use(engine('a'), create, () => {
throw new DockerError(DOCKER_API_ERROR, 'no such container', { data: { statusCode: 404 } })
}),
{ code: DOCKER_API_ERROR }
)
assert.equal(pool.size, 1)
assert.deepEqual(pool.getState('a'), { status: 'connected' })
await pool.destroy()
})
it('idle GC closes the connections unused for idleTimeout, not the busy ones', async () => {
const now = createClock()
const pool = new DockerConnectionPool({ idleTimeout: 5 * 60e3, now })
const create = () => new FakeConnection()
await pool.use(engine('idle'), create, idle)
const idleConnection = FakeConnection.instances.at(-1)!
let finish: (() => void) | undefined
const busy = pool.use(engine('busy'), create, () => new Promise<void>(resolve => (finish = resolve)))
await new Promise(resolve => setTimeout(resolve, 5))
const busyConnection = FakeConnection.instances.at(-1)!
now.time += 4 * 60e3
pool.sweep()
assert.equal(pool.size, 2, 'not idle long enough')
now.time += 2 * 60e3
pool.sweep()
await new Promise(resolve => setImmediate(resolve))
assert.equal(idleConnection.closed, 1)
assert.equal(busyConnection.closed, 0, 'busy connections are never collected')
assert.equal(pool.size, 1)
assert.deepEqual(pool.getState('idle'), { status: 'idle' })
finish!()
await busy
now.time += 6 * 60e3
pool.sweep()
assert.equal(pool.size, 0)
await pool.destroy()
})
it('the sweeper runs periodically, calls onSweep and stops on destroy', async () => {
let sweeps = 0
const pool = new DockerConnectionPool({ sweepInterval: 10, onSweep: () => ++sweeps })
await pool.use(engine('a'), () => new FakeConnection(), idle)
await new Promise(resolve => setTimeout(resolve, 35))
assert.ok(sweeps >= 2, `${sweeps} sweeps`)
await pool.destroy()
const count = sweeps
await new Promise(resolve => setTimeout(resolve, 25))
assert.equal(sweeps, count, 'no sweeps after destroy')
})
it('caps the connections: evicts the least recently used idle one', async () => {
const now = createClock()
const pool = new DockerConnectionPool({ maxConnections: 2, now })
const byId: Record<string, FakeConnection> = {}
const create = (id: string) => () => (byId[id] = new FakeConnection())
await pool.use(engine('a'), create('a'), idle)
now.time += 1e3
await pool.use(engine('b'), create('b'), idle)
now.time += 1e3
await pool.use(engine('a'), create('a2'), idle) // a is now the most recently used
assert.equal(byId.a2, undefined)
now.time += 1e3
await pool.use(engine('c'), create('c'), idle)
await new Promise(resolve => setImmediate(resolve))
assert.equal(pool.size, 2)
assert.equal(byId.b.closed, 1, 'b was the LRU')
assert.equal(byId.a.closed, 0)
assert.deepEqual(pool.getState('b'), { status: 'idle' })
await pool.destroy()
})
it('throws POOL_EXHAUSTED when all the connections are busy', async () => {
const pool = new DockerConnectionPool({ maxConnections: 2 })
const create = () => new FakeConnection()
const finishes: (() => void)[] = []
const busy = ['a', 'b'].map(id =>
pool.use(engine(id), create, () => new Promise<void>(resolve => finishes.push(resolve)))
)
await new Promise(resolve => setTimeout(resolve, 5))
let created = 0
await assert.rejects(
pool.use(
engine('c'),
() => {
++created
return new FakeConnection()
},
idle
),
{ code: POOL_EXHAUSTED }
)
assert.equal(created, 0)
// not an engine failure: not negatively cached
assert.deepEqual(pool.getState('c'), { status: 'idle' })
// a busy engine can still be used
await pool.use(engine('a'), create, idle)
finishes.forEach(finish => finish())
await Promise.all(busy)
await pool.use(engine('c'), create, idle)
await pool.destroy()
})
it('prunes the failures of the other revisions of an engine (fixes)', async () => {
const pool = new DockerConnectionPool()
const error = new DockerError(SSH_AUTH_FAILED, 'nope')
await assert.rejects(
pool.use(engine('a', 'old'), () => new FakeConnection({ connectError: error }), idle),
{ code: SSH_AUTH_FAILED }
)
assert.equal(pool.getState('a', 'old').status, 'error')
await pool.use(engine('a', 'new'), () => new FakeConnection(), idle)
assert.deepEqual(pool.getState('a', 'old'), { status: 'idle' })
assert.deepEqual(pool.getState('a', 'new'), { status: 'connected' })
await pool.destroy()
})
it('invalidate() closes the connections of an engine and forgets its failure', async () => {
const pool = new DockerConnectionPool()
await pool.use(engine('a'), () => new FakeConnection(), idle)
const connection = FakeConnection.instances.at(-1)!
await assert.rejects(
pool.use(engine('b'), () => new FakeConnection({ connectError: new DockerError(SSH_AUTH_FAILED, 'x') }), idle)
)
await pool.invalidate('a')
assert.equal(connection.closed, 1)
assert.equal(pool.size, 0)
await pool.invalidate('b')
assert.deepEqual(pool.getState('b'), { status: 'idle' })
await pool.destroy()
})
it('a connection closed by the pool refuses new requests', async () => {
const pool = new DockerConnectionPool()
let facade: DockerConnectionFacade | undefined
let started: (() => void) | undefined
let finish: (() => void) | undefined
const running = new Promise<void>(resolve => (started = resolve))
const done = pool.use(
engine('a'),
() => new FakeConnection(),
async connection => {
facade = connection
started!()
await new Promise<void>(resolve => (finish = resolve))
}
)
await running
await pool.invalidate('a')
await assert.rejects(facade!.request({ path: '/info' }), { code: CONNECTION_CLOSED })
finish!()
await done
await pool.destroy()
})
it('invalidation while connecting: the waiters get CONNECTION_CLOSED and the connection is closed', async () => {
const pool = new DockerConnectionPool()
const promise = pool.use(engine('a'), () => new FakeConnection({ connectDelay: 200 }), idle)
await new Promise(resolve => setTimeout(resolve, 2))
const connection = FakeConnection.instances.at(-1)!
await pool.invalidate('a')
await assert.rejects(promise, { code: CONNECTION_CLOSED })
assert.ok(connection.closed >= 1)
assert.deepEqual(pool.getState('a'), { status: 'idle' })
await pool.destroy()
})
it('a lost connection is removed: not reported connected, the next use opens a new one', async () => {
const pool = new DockerConnectionPool()
await pool.use(engine('a'), () => new FakeConnection(), idle)
const lost = FakeConnection.instances.at(-1)!
assert.deepEqual(pool.getState('a'), { status: 'connected' })
lost.simulateLoss()
assert.deepEqual(pool.getState('a'), { status: 'idle' })
assert.equal(pool.size, 0)
// not negatively cached: a lost session is not a connection failure
let created = 0
await pool.use(
engine('a'),
() => (++created, new FakeConnection()),
() => {}
)
assert.equal(created, 1)
assert.notEqual(FakeConnection.instances.at(-1), lost)
assert.ok(lost.closed >= 1)
await pool.destroy()
})
it('hold(): busy until released (idempotent), release(error) with an engine failure evicts and caches it', async () => {
const clock = createClock()
const pool = new DockerConnectionPool({ idleTimeout: 1e3, now: clock })
const held = await pool.hold(engine('a'), () => new FakeConnection())
const connection = FakeConnection.instances.at(-1)!
assert.equal((await held.connection.request({ path: '/info' })).body, '/info')
clock.time += 2e3
pool.sweep()
assert.equal(connection.closed, 0)
held.release()
held.release()
clock.time += 2e3
pool.sweep()
await new Promise(resolve => setImmediate(resolve))
assert.equal(connection.closed, 1)
const again = await pool.hold(engine('a'), () => new FakeConnection())
again.release(new DockerError(SSH_UNREACHABLE, 'lost'))
assert.equal(pool.getState('a').status, 'error')
await assert.rejects(
pool.hold(engine('a'), () => new FakeConnection()),
{ code: SSH_UNREACHABLE }
)
await pool.destroy()
})
it('destroy() closes everything, including pending connections, and refuses new uses', async () => {
const pool = new DockerConnectionPool()
await pool.use(engine('a'), () => new FakeConnection(), idle)
const established = FakeConnection.instances.at(-1)!
const pending = pool.use(engine('b'), () => new FakeConnection({ connectDelay: 200 }), idle)
await new Promise(resolve => setTimeout(resolve, 2))
const connecting = FakeConnection.instances.at(-1)!
await pool.destroy()
assert.equal(established.closed, 1)
assert.ok(connecting.closed >= 1)
await assert.rejects(pending, { code: CONNECTION_CLOSED })
assert.equal(pool.size, 0)
await assert.rejects(
pool.use(engine('a'), () => new FakeConnection(), idle),
{ code: CONNECTION_CLOSED }
)
})
})

View File

@@ -0,0 +1,313 @@
// Bounded requests built on a connection: container logs and the raw API
// passthrough. No XO concepts here: the caller validates the parameters,
// provides the limits and maps the errors (e.g. 404).
import { once } from 'node:events'
import type { IncomingHttpHeaders, IncomingMessage } from 'node:http'
import { type Readable, Transform } from 'node:stream'
import { finished } from 'node:stream/promises'
import type { XoDockerLogEntry, XoDockerLogs } from '@vates/types'
import { compareApiVersions, type DockerConnection } from './connection.mjs'
import { DOCKER_API_ERROR, DockerError, RAW_REQUEST_TOO_LARGE, RAW_RESPONSE_TOO_LARGE } from './errors.mjs'
import { normalizeContainerInspect } from './normalize.mjs'
import { createLogLineParser, createStdcopyDemuxer, isMultiplexedStream } from './stdcopy.mjs'
import type { DockerInspect } from './wire.mjs'
type Connection = Pick<DockerConnection, 'apiVersion' | 'request' | 'requestStream'>
export type ContainerLogsOptions = {
/** number of lines from the end */
tail: number
/** Docker timestamp (seconds since the epoch, fractional part allowed) */
since?: string
/** Docker timestamp (seconds since the epoch, fractional part allowed) */
until?: string
stdout?: boolean
stderr?: boolean
timestamps?: boolean
/** `Config.Tty` of the container if known, only used before API 1.42 (else inspected) */
tty?: boolean
/** max bytes read from the response, `truncated` above */
maxSize: number
/** max entries returned (dockerd splits lines over 64 KiB), `truncated` above */
maxEntries: number
/** max duration of the whole read (ms), `truncated` and `timedOut` above */
timeout: number
/** max duration without data (ms), `truncated` and `timedOut` above */
idleTimeout: number
}
/**
* Logs of a container, bounded in size, entries and time: on expiry, what has
* been read so far is returned.
*
* @throws {DockerError} e.g. DOCKER_API_ERROR with `data.statusCode` 404 for an unknown container
*/
export async function readContainerLogs(
connection: Connection,
dockerId: string,
{
tail,
since,
until,
stdout = true,
stderr = true,
timestamps = true,
tty,
maxSize,
maxEntries,
timeout,
idleTimeout,
}: ContainerLogsOptions
): Promise<XoDockerLogs> {
const path = `/containers/${encodeURIComponent(dockerId)}`
const query = {
// dockerd answers 400 without any of them: always ask for both, and
// filter afterwards
stdout: 1,
stderr: 1,
// always requested: without them, a message starting with something
// looking like a timestamp would be mangled by the line parser
timestamps: 1,
tail,
since,
until,
}
// the content type is only reliable from API 1.42, before that the TTY
// setting of the container decides
if (connection.apiVersion === undefined || compareApiVersions(connection.apiVersion, '1.42') < 0) {
if (tty === undefined) {
const { body } = await connection.request({ path: path + '/json' })
try {
tty = normalizeContainerInspect(body as DockerInspect).tty
} catch (error) {
throw new DockerError(DOCKER_API_ERROR, 'invalid answer from the Docker daemon', { cause: error })
}
}
} else {
tty = undefined
}
const asOf = Date.now()
const controller = new AbortController()
// the body is bounded in time too: dockerd may stall or trickle, which
// would keep the connection busy forever
const TIMED_OUT = new Error('logs deadline')
const ENOUGH = new Error('enough log entries')
let timedOut = false
let response: IncomingMessage | undefined
const expire = () => {
timedOut = true
if (response === undefined) {
controller.abort(new DOMException('Docker logs request timed out', 'TimeoutError'))
} else {
response.destroy(TIMED_OUT)
}
}
const deadline = setTimeout(expire, timeout)
let idleTimer: NodeJS.Timeout | undefined
const resetIdle = () => {
clearTimeout(idleTimer)
idleTimer = setTimeout(expire, idleTimeout)
}
try {
response = await connection.requestStream({ path: path + '/logs', query, signal: controller.signal })
// not reassigned below, for the closures
const body = response
resetIdle()
const demuxer = createStdcopyDemuxer({
tty: !isMultiplexedStream(body.headers['content-type'], tty, connection.apiVersion),
})
const parser = createLogLineParser()
const entries: XoDockerLogEntry[] = []
const streams = new Set([stdout && 'stdout', stderr && 'stderr'])
demuxer.pipe(parser)
demuxer.on('error', error => {
parser.destroy(error)
// interrupts the read loop below
body.destroy(error)
})
let tooManyEntries = false
const collected = (async () => {
for await (const entry of parser) {
if (!streams.has(entry.stream) || tooManyEntries) {
continue
}
if (entries.length === maxEntries) {
tooManyEntries = true
// stops the read loop below, what is still in the parser is
// drained (and dropped)
body.destroy(ENOUGH)
continue
}
entries.push(timestamps ? entry : { ...entry, timestamp: undefined })
}
})()
// awaited below, avoids an unhandled rejection meanwhile
collected.catch(() => {})
let truncated = false
try {
let size = 0
for await (const chunk of body) {
resetIdle()
if (size + chunk.length > maxSize) {
demuxer.write(chunk.subarray(0, maxSize - size))
truncated = true
break
}
size += chunk.length
if (!demuxer.write(chunk)) {
// rejects if the demuxer fails (e.g. invalid frame)
await once(demuxer, 'drain')
}
}
} catch (error) {
if (error !== TIMED_OUT && error !== ENOUGH) {
throw error
}
} finally {
clearTimeout(idleTimer)
// stops reading the response (and frees the channel) when truncated or
// timed out
body.destroy()
controller.abort()
demuxer.end()
}
await collected
return { entries, truncated: truncated || tooManyEntries || timedOut || demuxer.truncated, timedOut, asOf }
} finally {
clearTimeout(deadline)
clearTimeout(idleTimer)
}
}
/**
* Pass-through stream which fails with a DockerError of `code` once more than
* `maxSize` bytes went through.
*/
function createSizeLimiter(maxSize: number, code: string, message: string): Transform {
let size = 0
return new Transform({
transform(chunk, encoding, callback) {
size += chunk.length
if (size > maxSize) {
callback(new DockerError(code, message, { data: { maxSize } }))
} else {
callback(null, chunk)
}
},
})
}
export type RawRequestOptions = {
method: string
/** with its query string, prefixed with the negotiated API version unless it starts with `/v<version>/` */
path: string
/** sent as is */
headers?: Record<string, string>
body?: Readable
/** aborts the request and the response */
signal?: AbortSignal
/** the request body fails with RAW_REQUEST_TOO_LARGE above */
maxRequestSize: number
/** RAW_RESPONSE_TOO_LARGE above: thrown if announced by `content-length`, else the response body fails */
maxResponseSize: number
/** whole request, response body included (ms), 0 disables it */
timeout: number
}
export type RawResponse = {
statusCode: number
headers: IncomingHttpHeaders
body: Readable
/** resolves once the response body is done (consumed, failed or destroyed), never rejects */
done: Promise<void>
}
/**
* Raw Docker Engine API request (passthrough): sent on a dedicated channel
* (outside of the limit of concurrent requests), error responses are returned.
*
* On failure, the request body is not sent and what is still received from it
* is discarded: it is neither destroyed nor left piped.
*
* @throws {DockerError}
*/
export async function rawRequest(
connection: Connection,
{ method, path, headers = {}, body, signal, maxRequestSize, maxResponseSize, timeout }: RawRequestOptions
): Promise<RawResponse> {
// the whole lifetime of the request, response body included (e.g. `/events`
// or `logs?follow=1` would otherwise stay open as long as the client)
const controller = new AbortController()
const timer =
timeout > 0
? setTimeout(
() => controller.abort(new DOMException('raw Docker API request timed out', 'TimeoutError')),
timeout
)
: undefined
timer?.unref()
const requestSignal = AbortSignal.any([controller.signal, signal].filter(signal => signal !== undefined))
let requestBody: Transform | undefined
if (body !== undefined) {
const limiter = (requestBody = createSizeLimiter(
maxRequestSize,
RAW_REQUEST_TOO_LARGE,
'the request body is too large (docker.maxRawRequestSize)'
))
body.on('error', error => limiter.destroy(error))
body.pipe(limiter)
}
try {
const response = await connection.requestStream({
method,
path,
headers,
body: requestBody,
signal: requestSignal,
raw: true,
longLived: true,
})
const length = response.headers['content-length']
if (length !== undefined && Number(length) > maxResponseSize) {
response.destroy()
throw new DockerError(RAW_RESPONSE_TOO_LARGE, 'the response is too large (docker.maxRawResponseSize)', {
data: { maxSize: maxResponseSize, statusCode: response.statusCode },
})
}
const limited = createSizeLimiter(
maxResponseSize,
RAW_RESPONSE_TOO_LARGE,
'the response is too large (docker.maxRawResponseSize)'
)
response.on('error', error => limited.destroy(error))
limited.on('close', () => response.destroy())
response.pipe(limited)
return {
// always set on a client response
statusCode: response.statusCode!,
headers: response.headers,
body: limited,
done: finished(limited).then(
() => clearTimeout(timer),
() => clearTimeout(timer)
),
}
} catch (error) {
clearTimeout(timer)
if (requestBody !== undefined) {
body!.unpipe(requestBody)
requestBody.destroy()
body!.resume()
}
throw error
}
}

View File

@@ -0,0 +1,241 @@
import assert from 'node:assert/strict'
import type { IncomingMessage } from 'node:http'
import { PassThrough, Readable } from 'node:stream'
import { describe, it } from 'node:test'
import type { DockerBufferedRequestOptions, DockerResponse, DockerStreamRequestOptions } from './connection.mjs'
import { INSPECT_BY_NAME } from './fixtures/containers.mjs'
import { DOCKER_API_ERROR, DockerError, RAW_REQUEST_TOO_LARGE, RAW_RESPONSE_TOO_LARGE, TIMEOUT } from './errors.mjs'
import { type ContainerLogsOptions, rawRequest, readContainerLogs } from './requests.mjs'
const DOCKER_ID = 'a'.repeat(64)
// a multiplexed frame (stdout = 1, stderr = 2)
const frame = (text: string, stream = 1) => {
const payload = Buffer.from(text)
const header = Buffer.from([stream, 0, 0, 0, 0, 0, 0, 0])
header.writeUInt32BE(payload.length, 4)
return Buffer.concat([header, payload])
}
// a response body (`IncomingMessage` stand-in) fed by the test
const createBody = (headers: Record<string, string>, statusCode = 200) =>
Object.assign(new Readable({ read() {} }), { headers, statusCode }) as Readable & IncomingMessage
class FakeConnection {
apiVersion: string | undefined = '1.44'
requests: DockerBufferedRequestOptions[] = []
streams: DockerStreamRequestOptions[] = []
inspect: unknown = INSPECT_BY_NAME['xo-nginx']
respond: (opts: DockerStreamRequestOptions) => Promise<IncomingMessage> = async () => {
throw new Error('not implemented')
}
async request(opts: DockerBufferedRequestOptions): Promise<DockerResponse> {
this.requests.push(opts)
return { statusCode: 200, headers: {}, body: this.inspect }
}
requestStream(opts: DockerStreamRequestOptions): Promise<IncomingMessage> {
this.streams.push(opts)
return this.respond(opts)
}
}
const LIMITS: Omit<ContainerLogsOptions, 'tail'> = {
maxSize: 1024 * 1024,
maxEntries: 1000,
timeout: 5e3,
idleTimeout: 5e3,
}
describe('readContainerLogs()', () => {
it('requests both streams with timestamps, filters and strips them afterwards', async () => {
const connection = new FakeConnection()
connection.respond = async () => {
const body = createBody({ 'content-type': 'application/vnd.docker.multiplexed-stream' })
body.push(frame('2026-09-24T12:00:00.000000000Z out\n'))
body.push(frame('2026-09-24T12:00:01.000000000Z err\n', 2))
body.push(null)
return body
}
const logs = await readContainerLogs(connection, DOCKER_ID, {
...LIMITS,
tail: 10,
since: '1.5',
stderr: false,
timestamps: false,
})
assert.deepEqual(logs.entries, [{ stream: 'stdout', timestamp: undefined, message: 'out' }])
assert.equal(logs.truncated, false)
assert.equal(logs.timedOut, false)
assert.deepEqual(connection.streams[0].query, {
stdout: 1,
stderr: 1,
timestamps: 1,
tail: 10,
since: '1.5',
until: undefined,
})
assert.equal(connection.streams[0].path, `/containers/${DOCKER_ID}/logs`)
// API ≥ 1.42: the content type is reliable, no inspection
assert.equal(connection.requests.length, 0)
})
it('before API 1.42: inspects the container for its TTY setting unless given', async () => {
const connection = new FakeConnection()
connection.apiVersion = '1.41'
const nginx = INSPECT_BY_NAME['xo-nginx']
connection.inspect = { ...nginx, Config: { ...nginx.Config, Tty: true } }
connection.respond = async () => {
const body = createBody({ 'content-type': 'application/vnd.docker.raw-stream' })
body.push('2026-09-24T12:00:00.000000000Z raw\n')
body.push(null)
return body
}
const logs = await readContainerLogs(connection, DOCKER_ID, { ...LIMITS, tail: 10 })
assert.deepEqual(
logs.entries.map(_ => _.message),
['raw']
)
assert.equal(connection.requests[0].path, `/containers/${DOCKER_ID}/json`)
await readContainerLogs(connection, DOCKER_ID, { ...LIMITS, tail: 10, tty: true })
assert.equal(connection.requests.length, 1)
connection.inspect = 'garbage'
await assert.rejects(readContainerLogs(connection, DOCKER_ID, { ...LIMITS, tail: 10 }), {
code: DOCKER_API_ERROR,
})
})
it('cuts at maxSize and at maxEntries (truncated)', async () => {
const connection = new FakeConnection()
connection.respond = async () => {
const body = createBody({ 'content-type': 'application/vnd.docker.multiplexed-stream' })
for (let i = 0; i < 10; ++i) {
body.push(frame(`2026-09-24T12:00:00Z line ${i}\n`))
}
body.push(null)
return body
}
let logs = await readContainerLogs(connection, DOCKER_ID, { ...LIMITS, tail: 10, maxEntries: 3 })
assert.equal(logs.entries.length, 3)
assert.equal(logs.truncated, true)
logs = await readContainerLogs(connection, DOCKER_ID, { ...LIMITS, tail: 10, maxSize: frame('x').length * 2 })
assert.ok(logs.entries.length < 10)
assert.equal(logs.truncated, true)
assert.equal(logs.timedOut, false)
})
it('stops after idleTimeout without data, with what has been read', async () => {
const connection = new FakeConnection()
let body: Readable | undefined
connection.respond = async () => {
body = createBody({ 'content-type': 'application/vnd.docker.multiplexed-stream' })
body.push(frame('2026-09-24T12:00:00Z only\n'))
return body as IncomingMessage
}
const start = Date.now()
const logs = await readContainerLogs(connection, DOCKER_ID, { ...LIMITS, tail: 10, idleTimeout: 100 })
assert.ok(Date.now() - start < 1e3)
assert.deepEqual(
{ timedOut: logs.timedOut, truncated: logs.truncated, messages: logs.entries.map(_ => _.message) },
{ timedOut: true, truncated: true, messages: ['only'] }
)
assert.equal(body!.destroyed, true)
})
it('aborts the request itself after timeout', async () => {
const connection = new FakeConnection()
connection.respond = ({ signal }) =>
new Promise((resolve, reject) => signal!.addEventListener('abort', () => reject(signal!.reason)))
await assert.rejects(readContainerLogs(connection, DOCKER_ID, { ...LIMITS, tail: 10, timeout: 50 }), {
name: 'TimeoutError',
})
})
})
describe('rawRequest()', () => {
const OPTS = { method: 'GET', path: '/info', maxRequestSize: 10, maxResponseSize: 10, timeout: 0 }
it('sends a raw long-lived request and passes the response through', async () => {
const connection = new FakeConnection()
connection.respond = async () => {
const body = createBody({ 'content-type': 'text/plain' }, 418)
body.push('teapot')
body.push(null)
return body
}
const response = await rawRequest(connection, { ...OPTS, headers: { 'x-a': 'b' } })
assert.equal(response.statusCode, 418)
assert.equal((await response.body.toArray()).join(''), 'teapot')
await response.done
const { raw, longLived, headers, path, method } = connection.streams[0]
assert.deepEqual(
{ raw, longLived, headers, path, method },
{
raw: true,
longLived: true,
headers: { 'x-a': 'b' },
path: '/info',
method: 'GET',
}
)
})
it('caps the response: announced size thrown, streamed size fails the body', async () => {
const connection = new FakeConnection()
let response: Readable | undefined
connection.respond = async () => (response = createBody({ 'content-length': '11' }))
await assert.rejects(rawRequest(connection, OPTS), { code: RAW_RESPONSE_TOO_LARGE })
assert.equal(response!.destroyed, true)
connection.respond = async () => {
const body = createBody({})
body.push('x'.repeat(11))
return body
}
const { body, done } = await rawRequest(connection, OPTS)
await assert.rejects(body.toArray(), { code: RAW_RESPONSE_TOO_LARGE })
await done
})
it('caps the request body', async () => {
const connection = new FakeConnection()
let sent: Readable | undefined
connection.respond = async ({ body }) => {
sent = body as Readable
return createBody({})
}
const body = new PassThrough()
await rawRequest(connection, { ...OPTS, method: 'POST', body })
body.end('x'.repeat(11))
await assert.rejects(sent!.toArray(), { code: RAW_REQUEST_TOO_LARGE })
})
it('on failure: the caller body is unpiped and drained, not destroyed', async () => {
const connection = new FakeConnection()
connection.respond = async () => {
throw new DockerError(TIMEOUT, 'no')
}
const body = new PassThrough()
await assert.rejects(rawRequest(connection, { ...OPTS, method: 'POST', body }), { code: TIMEOUT })
assert.equal(body.destroyed, false)
// drained: writing does not stall
assert.equal(body.write('x'), true)
})
it('the timeout covers the response body', async () => {
const connection = new FakeConnection()
connection.respond = async ({ signal }) => {
const body = createBody({})
signal!.addEventListener('abort', () => body.destroy(signal!.reason))
return body
}
const { body, done } = await rawRequest(connection, { ...OPTS, timeout: 50 })
await assert.rejects(body.toArray(), { name: 'TimeoutError' })
await done
})
})

View File

@@ -0,0 +1,207 @@
import { Agent, type AgentOptions, type ClientRequestArgs } from 'node:http'
import type { Socket } from 'node:net'
import type { Duplex } from 'node:stream'
import { createLogger } from '@xen-orchestra/log'
import { DockerError, fromSshError, SSH_UNREACHABLE, TIMEOUT } from './errors.mjs'
const { debug } = createLogger('xo:docker:ssh-http-agent')
function noop() {}
/**
* The `net.Socket` methods added by `decorateStream()`.
*/
export type DecoratedStream = Duplex & {
setKeepAlive(): void
setNoDelay(): void
setTimeout(): void
ref(): void
unref(): void
destroySoon: Duplex['destroy']
}
/**
* Make an ssh2 channel usable as an HTTP socket.
*
* Port of `decorateStream()` from `ssh2/lib/http-agents.js` (HTTP case): the
* HTTP client and the agent call these `net.Socket` methods which do not
* exist on a channel.
*
* Note: `setTimeout` is a no-op, therefore the `timeout` option of the agent
* and `req.setTimeout()` have no effect on these sockets, timeouts must be
* handled with an `AbortSignal`.
*/
export function decorateStream(duplex: Duplex): DecoratedStream {
// decorated in place: the methods are added below
const stream = duplex as DecoratedStream
stream.setKeepAlive = noop
stream.setNoDelay = noop
stream.setTimeout = noop
stream.ref = noop
stream.unref = noop
// Addition to ssh2's version: once the SSH connection is lost,
// Channel#destroy() emits neither `close` nor `error`, the agent would then
// keep counting the channel as an active socket forever (and eventually
// hit `maxSockets`). Make sure the agent forgets a destroyed channel.
let closed = false
let removed = false
stream.once('close', () => {
closed = true
})
const { destroy } = stream
stream.destroy = function (this: Duplex, ...args: Parameters<Duplex['destroy']>) {
const result = destroy.apply(this, args)
if (!removed) {
removed = true
// deferred: the agent may be iterating over its sockets (Agent#destroy())
process.nextTick(() => {
if (!closed) {
// handled by `installListeners()` in Node's lib/_http_agent.js
this.emit('agentRemove')
}
})
}
return result
}
stream.destroySoon = stream.destroy
return stream
}
/**
* HTTP agent sending requests to a Unix socket on a remote host through an
* already established SSH connection (`direct-streamlocal@openssh.com`
* channels).
*
* Unlike ssh2's own `HTTPAgent` which opens one SSH connection per socket,
* all channels are multiplexed on a single, shared, `ssh2.Client`.
*
* The `host` and `port` of the requests are ignored.
*/
/**
* What the agent needs of an `ssh2.Client` (its `openssh_forwardOutStreamLocal()`).
*/
export interface ForwardOutStreamLocalClient {
openssh_forwardOutStreamLocal(
socketPath: string,
callback: (error: Error | undefined, channel: Duplex) => void
): unknown
}
export class SshHttpAgent extends Agent {
#connectTimeout: number
#getClient: () => Promise<ForwardOutStreamLocalClient>
#socketPath: string
/**
* @param opts.getClient returns a connected (ready) client, must enforce its own timeout
* @param opts.socketPath path of the Unix socket on the remote host
* @param opts.connectTimeout max duration to open a channel once the client is ready (ms)
*/
constructor(
{
getClient,
socketPath,
connectTimeout,
}: { getClient: () => Promise<ForwardOutStreamLocalClient>; socketPath: string; connectTimeout: number },
agentOptions?: AgentOptions
) {
super({
keepAlive: true,
keepAliveMsecs: 10e3,
maxSockets: 8,
maxFreeSockets: 2,
...agentOptions,
})
this.#connectTimeout = connectTimeout
this.#getClient = getClient
this.#socketPath = socketPath
}
/**
* `http.Agent#removeSocket()` only removes a socket from the free list when
* it is no longer writable, but an ssh2 channel closed because the SSH
* connection has been lost stays writable: it would be reused and requests
* sent on it would never complete. Always remove it from the free list.
*/
removeSocket(socket: Duplex, options: ClientRequestArgs): void {
const name = this.getName(options)
const freeSockets = this.freeSockets[name]
if (freeSockets !== undefined) {
// the sockets of this agent are ssh2 channels, typed as `net.Socket` by @types/node
const index = freeSockets.indexOf(socket as Socket)
if (index !== -1) {
freeSockets.splice(index, 1)
if (freeSockets.length === 0) {
// `freeSockets` is only read-only in @types/node, `http.Agent` itself deletes its keys
delete (this.freeSockets as NodeJS.Dict<Socket[]>)[name]
}
}
}
// @ts-expect-error `removeSocket()` is internal to `http.Agent` (Node's lib/_http_agent.js), missing from @types/node
return super.removeSocket(socket, options)
}
/**
* Called by `http.Agent` when a new socket is needed.
*
* Async form: returns nothing and calls `cb` once.
*
* @param _options ignored (host/port are meaningless here)
*/
createConnection(_options: ClientRequestArgs, cb: (error: Error | null, socket?: Duplex) => void): undefined {
const socketPath = this.#socketPath
let settled = false
const settle = (error: unknown, stream?: Duplex) => {
if (settled) {
// too late: the caller already received an error, release the channel
stream?.destroy()
return
}
settled = true
clearTimeout(timer)
if (error == null) {
// no error: ssh2 gives a channel
cb(null, decorateStream(stream as Duplex))
} else {
cb(fromSshError(error, { socketPath }))
}
}
let timer: NodeJS.Timeout | undefined
this.#getClient().then(
client => {
if (settled) {
return
}
// started only once the client is ready so that a slow SSH connection
// is reported with its own error (see `getClient`)
timer = setTimeout(() => {
settle(
new DockerError(TIMEOUT, 'timed out while opening an SSH channel to the Docker socket', {
data: { socketPath, timeout: this.#connectTimeout },
})
)
}, this.#connectTimeout)
try {
client.openssh_forwardOutStreamLocal(socketPath, (error, stream) => {
if (error == null) {
debug('channel opened', { socketPath })
}
settle(error, stream)
})
} catch (error) {
// thrown synchronously when the client is not connected (anymore)
settle(
new DockerError(SSH_UNREACHABLE, 'the SSH connection is closed', { data: { socketPath }, cause: error })
)
}
},
error => settle(error)
)
}
}

View File

@@ -0,0 +1,356 @@
// Tier 3 of the container data (see the plan, §5): stats, never blocking.
//
// One sampler per engine, started by the first request asking for stats and
// stopped after `idleTimeout` without any reader. While alive, it holds one
// streaming `GET /containers/{id}/stats?stream=true` per running container (at
// most `maxContainers`) and keeps only the latest normalized sample of each:
// bounded memory, no history.
//
// dockerd pushes one JSON object per second per stream, each carrying its own
// `precpu_stats`, except the first one which has no previous sample
// (`cpuPercent: null`): a container is "pending" until its second sample.
//
// No XO concepts here: the caller provides `openStream()`, and tells which
// containers are running with `sync()` on each list refresh.
import type { Readable } from 'node:stream'
import type { XoDockerContainerStats } from '@vates/types'
import { createLogger } from '@xen-orchestra/log'
import { DOCKER_API_ERROR, isDockerError, POOL_EXHAUSTED, TIMEOUT } from './errors.mjs'
import { normalizeContainerStats } from './normalize.mjs'
const { debug, warn } = createLogger('xo:docker:stats-sampler')
export const DEFAULT_IDLE_TIMEOUT = 90e3
export const DEFAULT_MAX_CONTAINERS = 100
// a stats object is a few KiB, even with many networks and block devices
export const DEFAULT_MAX_OBJECT_SIZE = 256 * 1024
// a container whose stream failed or ended is not reopened before this delay
export const DEFAULT_RETRY_DELAY = 5e3
// dockerd sends one object per second: a daemon sending more (hostile or
// buggy) must not make us parse more, only the latest object is kept
export const DEFAULT_PARSE_INTERVAL = 1e3
// errors of one stream which do not concern the engine: the stream is dropped
// (and retried by a later `sync()` after `retryDelay`), the other streams are
// kept. Any other error (SSH failure, closed connection…) stops the sampler.
const isStreamError = (error: unknown): boolean =>
!isDockerError(error) || error.code === DOCKER_API_ERROR || error.code === TIMEOUT || error.code === POOL_EXHAUSTED
type StreamEntry = {
controller: AbortController
stream: Readable | undefined
stats: XoDockerContainerStats | undefined
samples: number
lastParse: number
pendingLine: string | undefined
parseTimer: NodeJS.Timeout | undefined
}
export type DockerStatsSamplerOptions = {
/** opens `GET /containers/{id}/stats?stream=true` (newline-delimited JSON objects) */
openStream: (dockerId: string, signal: AbortSignal) => Promise<Readable>
/** ms without `sync()`/`get()` after which the sampler stops */
idleTimeout?: number
/** max number of streams */
maxContainers?: number
/**
* max size of one JSON object (UTF-16 code units, roughly bytes), the stream is dropped above; checked on the
* pending partial object plus each received chunk, before scanning
*/
maxObjectSize?: number
/**
* min ms between two parsed objects of a stream, the latest one received in the meantime is parsed at the end of
* the interval
*/
parseInterval?: number
/** ms before reopening the stream of a container after a failure or an end */
retryDelay?: number
/** called once, with the error which stopped the sampler if any */
onStop?: (error?: unknown) => void
/** for tests */
now?: () => number
}
export class DockerStatsSampler {
#failures = new Map<string, number>() // Docker id → time after which it may be reopened
#idleTimeout: number
#idleTimer: NodeJS.Timeout | undefined
#lastRead: number
#maxContainers: number
#maxObjectSize: number
#now: () => number
#onStop: ((error?: unknown) => void) | undefined
#openStream: (dockerId: string, signal: AbortSignal) => Promise<Readable>
#parseInterval: number
#retryDelay: number
#stopped = false
#streams = new Map<string, StreamEntry>() // Docker id → { controller, stream, stats, samples, lastParse, pendingLine, parseTimer }
constructor({
openStream,
idleTimeout = DEFAULT_IDLE_TIMEOUT,
maxContainers = DEFAULT_MAX_CONTAINERS,
maxObjectSize = DEFAULT_MAX_OBJECT_SIZE,
retryDelay = DEFAULT_RETRY_DELAY,
parseInterval = DEFAULT_PARSE_INTERVAL,
onStop,
now = Date.now,
}: DockerStatsSamplerOptions) {
this.#openStream = openStream
this.#idleTimeout = idleTimeout
this.#maxContainers = maxContainers
this.#maxObjectSize = maxObjectSize
this.#retryDelay = retryDelay
this.#parseInterval = parseInterval
this.#onStop = onStop
this.#now = now
this.#lastRead = now()
this.#scheduleIdleCheck(idleTimeout)
}
get stopped(): boolean {
return this.#stopped
}
/** number of streams (opening or open) */
get size(): number {
return this.#streams.size
}
/**
* Streams the given containers, and only them: new ones are opened (up to
* `maxContainers`, the already streamed ones are kept first), the others are
* closed.
*
* @param dockerIds the running containers
*/
sync(dockerIds: Iterable<string>): void {
if (this.#stopped) {
return
}
this.#touch()
const ids = Array.from(new Set(dockerIds))
const now = this.#now()
const wanted = new Set<string>()
// the containers already streamed are kept first, to avoid churn when the
// cap is reached
for (const id of ids) {
if (this.#streams.has(id) && wanted.size < this.#maxContainers) {
wanted.add(id)
}
}
for (const id of ids) {
if (wanted.size >= this.#maxContainers) {
break
}
const retryAt = this.#failures.get(id)
if (retryAt === undefined || retryAt <= now) {
wanted.add(id)
}
}
for (const id of Array.from(this.#streams.keys())) {
if (!wanted.has(id)) {
this.#close(id)
}
}
// forget the failures of the containers which are gone
for (const id of Array.from(this.#failures.keys())) {
// `get(id)!`: `id` is a key
if (!ids.includes(id) || this.#failures.get(id)! <= now) {
this.#failures.delete(id)
}
}
for (const id of wanted) {
if (!this.#streams.has(id)) {
this.#open(id)
}
}
}
/**
* Latest sample of a container.
*
* @returns `undefined` if not streamed, `pending` until the second sample (the first one has no CPU usage)
*/
get(dockerId: string): { stats: XoDockerContainerStats | undefined; pending: boolean } | undefined {
if (this.#stopped) {
return
}
this.#touch()
const entry = this.#streams.get(dockerId)
if (entry === undefined) {
return
}
return { stats: entry.stats, pending: entry.samples < 2 }
}
/**
* Close every stream, the sampler cannot be used afterwards.
*
* @param error reason, passed to `onStop`
*/
stop(error?: unknown): void {
if (this.#stopped) {
return
}
this.#stopped = true
clearTimeout(this.#idleTimer)
for (const id of Array.from(this.#streams.keys())) {
this.#close(id)
}
this.#failures.clear()
debug('stopped', { error })
try {
this.#onStop?.(error)
} catch (error) {
warn('onStop', { error })
}
}
#touch() {
this.#lastRead = this.#now()
}
#scheduleIdleCheck(delay: number): void {
this.#idleTimer = setTimeout(() => {
const idle = this.#now() - this.#lastRead
if (idle >= this.#idleTimeout) {
debug('no reader, stopping')
this.stop()
} else {
this.#scheduleIdleCheck(this.#idleTimeout - idle)
}
}, delay)
this.#idleTimer.unref?.()
}
#close(id: string): void {
const entry = this.#streams.get(id)
if (entry !== undefined) {
this.#streams.delete(id)
clearTimeout(entry.parseTimer)
entry.pendingLine = undefined
entry.controller.abort()
entry.stream?.destroy()
}
}
// the stream of a container failed or ended on its own
#drop(id: string, entry: StreamEntry, error?: unknown): void {
if (this.#streams.get(id) !== entry) {
return
}
this.#close(id)
if (error !== undefined && !isStreamError(error)) {
this.stop(error)
return
}
this.#failures.set(id, this.#now() + this.#retryDelay)
if (error !== undefined && !(isDockerError(error) && error.code === DOCKER_API_ERROR)) {
debug('stats stream failed', { container: id, error })
}
}
#open(id: string): void {
const entry: StreamEntry = {
controller: new AbortController(),
stream: undefined,
stats: undefined,
samples: 0,
lastParse: -Infinity,
pendingLine: undefined,
parseTimer: undefined,
}
this.#streams.set(id, entry)
this.#openStream(id, entry.controller.signal).then(
stream => {
if (this.#streams.get(id) !== entry) {
// closed meanwhile
stream.destroy()
return
}
entry.stream = stream
this.#consume(id, entry, stream)
},
error => {
if (!entry.controller.signal.aborted) {
this.#drop(id, entry, error)
}
}
)
}
// parses the latest complete line received, unless one was parsed less than
// `parseInterval` ago: it is then parsed at the end of the interval (unless a
// newer one replaces it meanwhile)
#parse(id: string, entry: StreamEntry): void {
const line = entry.pendingLine
if (line === undefined || this.#streams.get(id) !== entry) {
return
}
const wait = entry.lastParse + this.#parseInterval - this.#now()
if (wait > 0) {
if (entry.parseTimer === undefined) {
entry.parseTimer = setTimeout(() => {
entry.parseTimer = undefined
this.#parse(id, entry)
}, wait)
entry.parseTimer.unref?.()
}
return
}
entry.pendingLine = undefined
entry.lastParse = this.#now()
let stats
try {
stats = normalizeContainerStats(JSON.parse(line))
} catch (error) {
this.#drop(id, entry, new Error('invalid stats object', { cause: error }))
return
}
entry.stats = stats
++entry.samples
}
#consume(id: string, entry: StreamEntry, stream: Readable): void {
// partial line after the last newline received
let buffer = ''
stream.setEncoding('utf8')
// strings: the encoding is set
stream.on('data', (chunk: string) => {
// checked before any scanning: a daemon cannot make us buffer or scan
// more than the cap, whatever the number of lines (a legitimate stream
// sends a few KiB per second, and a chunk is at most 64 KiB)
if (buffer.length + chunk.length > this.#maxObjectSize) {
this.#drop(id, entry, new Error('stats object too large'))
return
}
// only the latest complete line matters: the objects before it are
// older samples, never parsed
const last = chunk.lastIndexOf('\n')
if (last === -1) {
buffer += chunk
return
}
const previous = chunk.lastIndexOf('\n', last - 1)
const line = (previous === -1 ? buffer + chunk.slice(0, last) : chunk.slice(previous + 1, last)).trim()
buffer = chunk.slice(last + 1)
if (line !== '') {
entry.pendingLine = line
this.#parse(id, entry)
}
})
// `close` is always emitted, after `error` if any: the stream ended
// (container stopped) or its channel failed; if the whole connection is
// gone, the next `openStream()` fails with CONNECTION_CLOSED (or an SSH
// error) and stops the sampler
stream.on('error', error => {
debug('stats stream error', { container: id, error })
})
stream.on('close', () => this.#drop(id, entry))
}
}

View File

@@ -0,0 +1,450 @@
import assert from 'node:assert/strict'
import { once } from 'node:events'
import { mkdtemp, rm } from 'node:fs/promises'
import { createServer, get as httpGet, type IncomingMessage, type Server, type ServerResponse } from 'node:http'
import { tmpdir } from 'node:os'
import { join } from 'node:path'
import { PassThrough } from 'node:stream'
import { after, before, describe, it } from 'node:test'
import { DockerError } from './errors.mjs'
import { DockerStatsSampler } from './stats-sampler.mjs'
import type { DockerCpuStats, DockerStatsSample } from './wire.mjs'
const sleep = (ms: number) => new Promise(resolve => setTimeout(resolve, ms))
const tick = () => new Promise(resolve => setImmediate(resolve))
// a Docker stats object: `total` / `system` are the cumulated CPU counters,
// `pre` the previous ones (absent on the first object of a stream)
const statsObject = ({
total,
system,
pre,
memory = 100e6,
}: {
total: number
system: number
pre?: DockerCpuStats
memory?: number
}): DockerStatsSample => ({
read: '2026-09-24T12:00:00.000000000Z',
cpu_stats: { cpu_usage: { total_usage: total }, system_cpu_usage: system, online_cpus: 2 },
precpu_stats: pre === undefined ? { cpu_usage: { total_usage: 0 } } : pre,
memory_stats: { usage: memory, limit: 1e9, stats: { inactive_file: 0 } },
pids_stats: { current: 3 },
})
/**
* Fake `openStream()`: one PassThrough per call, controllable from the test.
*/
function createFakeDocker() {
const streams = new Map<string, PassThrough>()
const opened: string[] = []
const fake = {
opened,
streams,
fail: undefined as ((dockerId: string) => Error | undefined) | undefined,
openStream: async (dockerId: string, signal: AbortSignal) => {
opened.push(dockerId)
await tick()
const error = fake.fail?.(dockerId)
if (error !== undefined) {
throw error
}
const stream = new PassThrough()
signal.addEventListener('abort', () => stream.destroy(), { once: true })
streams.set(dockerId, stream)
return stream
},
push(dockerId: string, object: object) {
streams.get(dockerId)!.write(JSON.stringify(object) + '\n')
},
isOpen(dockerId: string) {
const stream = streams.get(dockerId)
return stream !== undefined && !stream.destroyed
},
}
return fake
}
describe('DockerStatsSampler', () => {
it('warms up: pending until the second sample, which has the CPU usage', async () => {
const fake = createFakeDocker()
const sampler = new DockerStatsSampler({ openStream: fake.openStream, parseInterval: 0 })
try {
sampler.sync(['a'])
// never blocks: known but no sample yet
assert.deepEqual(sampler.get('a'), { stats: undefined, pending: true })
await tick()
await tick()
fake.push('a', statsObject({ total: 1e9, system: 100e9 }))
await tick()
let sample = sampler.get('a')
assert.equal(sample!.pending, true)
assert.equal(sample!.stats!.cpuPercent, null)
assert.equal(sample!.stats!.memoryUsage, 100e6)
// 0.5 s of CPU over 10 s of system time on 2 CPUs → 10 %
fake.push(
'a',
statsObject({
total: 1.5e9,
system: 110e9,
pre: { cpu_usage: { total_usage: 1e9 }, system_cpu_usage: 100e9 },
})
)
await tick()
sample = sampler.get('a')
assert.equal(sample!.pending, false)
assert.equal(sample!.stats!.cpuPercent, 10)
assert.equal(sampler.get('unknown'), undefined)
} finally {
sampler.stop()
}
})
it('keeps only the latest sample, and handles objects split across chunks', async () => {
const fake = createFakeDocker()
const sampler = new DockerStatsSampler({ openStream: fake.openStream, parseInterval: 0 })
try {
sampler.sync(['a'])
await tick()
await tick()
const line = JSON.stringify(statsObject({ total: 1, system: 1, memory: 42 })) + '\n'
const stream = fake.streams.get('a')!
for (let i = 0; i < line.length; i += 7) {
stream.write(line.slice(i, i + 7))
await tick()
}
assert.equal(sampler.get('a')!.stats!.memoryUsage, 42)
fake.push('a', statsObject({ total: 2, system: 2, memory: 43 }))
await tick()
assert.equal(sampler.get('a')!.stats!.memoryUsage, 43)
} finally {
sampler.stop()
}
})
it('follows the containers: new streams opened, stopped ones closed', async () => {
const fake = createFakeDocker()
const sampler = new DockerStatsSampler({ openStream: fake.openStream })
try {
sampler.sync(['a', 'b'])
await tick()
await tick()
assert.deepEqual(fake.opened, ['a', 'b'])
assert.equal(sampler.size, 2)
sampler.sync(['b', 'c'])
await tick()
await tick()
assert.deepEqual(fake.opened, ['a', 'b', 'c'], 'b is not reopened')
assert.equal(fake.isOpen('a'), false, 'a is closed')
assert.equal(fake.isOpen('b'), true)
assert.equal(fake.isOpen('c'), true)
assert.equal(sampler.get('a'), undefined)
assert.equal(sampler.size, 2)
} finally {
sampler.stop()
}
})
it('a stream which ends (container stopped) is dropped, and reopened only after retryDelay', async () => {
const fake = createFakeDocker()
const sampler = new DockerStatsSampler({ openStream: fake.openStream, retryDelay: 50 })
try {
sampler.sync(['a'])
await tick()
await tick()
fake.streams.get('a')!.end()
await tick()
await tick()
assert.equal(sampler.get('a'), undefined)
sampler.sync(['a'])
assert.equal(sampler.get('a'), undefined, 'not retried right away')
await sleep(60)
sampler.sync(['a'])
assert.notEqual(sampler.get('a'), undefined)
assert.deepEqual(fake.opened, ['a', 'a'])
} finally {
sampler.stop()
}
})
it('a Docker API error (e.g. 404) drops only that container', async () => {
const fake = createFakeDocker()
fake.fail = id => (id === 'gone' ? new DockerError('DOCKER_API_ERROR', 'no such container') : undefined)
const sampler = new DockerStatsSampler({ openStream: fake.openStream })
try {
sampler.sync(['gone', 'a'])
await tick()
await tick()
assert.equal(sampler.stopped, false)
assert.equal(sampler.get('gone'), undefined)
assert.notEqual(sampler.get('a'), undefined)
} finally {
sampler.stop()
}
})
it('an engine failure stops the sampler, onStop gets the error', async () => {
const fake = createFakeDocker()
const error = new DockerError('SSH_UNREACHABLE', 'connection lost')
fake.fail = () => error
let stopError: unknown = 'not called'
const sampler = new DockerStatsSampler({
openStream: fake.openStream,
onStop: error => {
stopError = error
},
})
sampler.sync(['a', 'b'])
await tick()
await tick()
assert.equal(sampler.stopped, true)
assert.equal(stopError, error)
assert.equal(sampler.size, 0)
})
it('at most maxContainers streams, already streamed containers are kept first', async () => {
const fake = createFakeDocker()
const sampler = new DockerStatsSampler({ openStream: fake.openStream, maxContainers: 2 })
try {
sampler.sync(['a', 'b', 'c'])
await tick()
await tick()
assert.deepEqual(fake.opened, ['a', 'b'])
assert.equal(sampler.get('c'), undefined)
// c comes first now, but a and b are kept
sampler.sync(['c', 'b', 'a'])
await tick()
assert.deepEqual(fake.opened, ['a', 'b'])
// a is gone: c takes its place
sampler.sync(['c', 'b'])
await tick()
await tick()
assert.deepEqual(fake.opened, ['a', 'b', 'c'])
assert.equal(sampler.size, 2)
} finally {
sampler.stop()
}
})
it('an oversized object drops the stream (bounded memory)', async () => {
const fake = createFakeDocker()
const sampler = new DockerStatsSampler({ openStream: fake.openStream, maxObjectSize: 100 })
try {
sampler.sync(['a'])
await tick()
await tick()
fake.streams.get('a')!.write('x'.repeat(200))
await tick()
await tick()
assert.equal(sampler.get('a'), undefined)
assert.equal(fake.isOpen('a'), false)
} finally {
sampler.stop()
}
})
it('stops after idleTimeout without reader, readers keep it alive', async () => {
const fake = createFakeDocker()
let stops = 0
const sampler = new DockerStatsSampler({
openStream: fake.openStream,
idleTimeout: 80,
onStop: () => ++stops,
})
sampler.sync(['a'])
await tick()
await tick()
for (let i = 0; i < 4; ++i) {
await sleep(40)
sampler.get('a')
}
assert.equal(sampler.stopped, false, 'kept alive by get()')
await sleep(150)
assert.equal(sampler.stopped, true)
assert.equal(stops, 1)
assert.equal(fake.isOpen('a'), false, 'streams closed')
// no effect once stopped
sampler.sync(['a'])
assert.equal(sampler.get('a'), undefined)
assert.deepEqual(fake.opened, ['a'])
})
it('stop() closes every stream, including the ones being opened', async () => {
const fake = createFakeDocker()
let stops = 0
const sampler = new DockerStatsSampler({ openStream: fake.openStream, onStop: () => ++stops })
sampler.sync(['a'])
await tick()
await tick()
sampler.sync(['a', 'b']) // b is being opened
sampler.stop()
sampler.stop()
await tick()
await tick()
assert.equal(stops, 1)
assert.equal(fake.isOpen('a'), false)
assert.equal(fake.isOpen('b'), false)
assert.equal(sampler.size, 0)
})
})
// a hostile daemon behind a real HTTP server on a Unix socket, the streams
// being opened like `DockerConnection#requestStream()` returns them
describe('DockerStatsSampler against a hostile daemon', () => {
let dir: string, socketPath: string, server: Server
let handler: (req: IncomingMessage, res: ServerResponse) => void
before(async () => {
dir = await mkdtemp(join(tmpdir(), 'xo-docker-sampler-'))
socketPath = join(dir, 'docker.sock')
server = createServer((req, res) => handler(req, res))
server.listen(socketPath)
await once(server, 'listening')
})
after(async () => {
server.closeAllConnections()
server.close()
await rm(dir, { recursive: true, force: true })
})
const openStream = (dockerId: string, signal: AbortSignal) =>
new Promise<IncomingMessage>((resolve, reject) => {
const req = httpGet({ socketPath, path: `/containers/${dockerId}/stats?stream=1`, signal }, resolve)
req.on('error', reject)
})
// counts the JSON.parse() calls made while `fn` runs
async function countParses(fn: () => Promise<unknown>) {
const { parse } = JSON
let count = 0
JSON.parse = function (this: JSON, ...args: Parameters<typeof JSON.parse>) {
++count
return parse.apply(this, args)
}
try {
await fn()
} finally {
JSON.parse = parse
}
return count
}
const line = (memory: number) => JSON.stringify(statsObject({ total: 1, system: 1, memory })) + '\n'
it('a flood of objects in one burst is not fully parsed (latest complete line only)', async () => {
handler = (req, res) => {
res.writeHead(200, { 'content-type': 'application/json' })
// ~2.6 MB, split by the socket in chunks: only the last complete line of
// a chunk may be parsed, and at most about once per second
let body = ''
for (let i = 0; i < 10e3; ++i) {
body += line(i)
}
res.write(body)
}
const sampler = new DockerStatsSampler({ openStream })
try {
const parses = await countParses(async () => {
sampler.sync(['a'])
await sleep(300)
})
assert.notEqual(sampler.get('a'), undefined, 'the stream is kept')
assert.ok(sampler.get('a')!.stats !== undefined)
assert.ok(parses <= 2, `${parses} parses`)
} finally {
sampler.stop()
}
})
it('throttles the parsing to about once per second per stream, keeping the latest sample', async () => {
let res: ServerResponse
handler = (_req, _res) => {
res = _res
res.writeHead(200, { 'content-type': 'application/json' })
res.write(line(0))
}
const sampler = new DockerStatsSampler({ openStream, parseInterval: 300 })
try {
let parses = await countParses(async () => {
sampler.sync(['a'])
await sleep(50)
for (let i = 1; i <= 20; ++i) {
res.write(line(i))
await sleep(5)
}
await sleep(50)
})
assert.equal(parses, 1, 'only the first object within the interval')
assert.equal(sampler.get('a')!.stats!.memoryUsage, 0)
parses = await countParses(() => sleep(350))
assert.equal(parses, 1, 'the latest one at the end of the interval')
assert.equal(sampler.get('a')!.stats!.memoryUsage, 20)
} finally {
sampler.stop()
}
})
it('checks the buffer against the cap before scanning it', async () => {
handler = (req, res) => {
res.writeHead(200, { 'content-type': 'application/json' })
// many short lines in one chunk larger than the cap
res.write('{}\n'.repeat(200))
}
const sampler = new DockerStatsSampler({ openStream, maxObjectSize: 100 })
try {
const parses = await countParses(async () => {
sampler.sync(['a'])
await sleep(100)
})
assert.equal(parses, 0)
assert.equal(sampler.get('a'), undefined, 'dropped')
} finally {
sampler.stop()
}
})
it('an object which is not a stats object drops the stream', async () => {
handler = (req, res) => {
res.writeHead(200, { 'content-type': 'application/json' })
res.write('"just a string"\n')
}
const sampler = new DockerStatsSampler({ openStream })
try {
sampler.sync(['a'])
await sleep(100)
assert.equal(sampler.get('a'), undefined)
} finally {
sampler.stop()
}
})
it('hostile values never reach the samples', async () => {
handler = (req, res) => {
res.writeHead(200, { 'content-type': 'application/json' })
const object = statsObject({ total: 1, system: 1 })
object.networks = { eth0: { rx_bytes: '1', tx_bytes: { a: 1 } } }
object.memory_stats!.usage = '1000'
object.cpu_stats!.online_cpus = '4'
res.write(JSON.stringify(object) + '\n')
}
const sampler = new DockerStatsSampler({ openStream })
try {
sampler.sync(['a'])
await sleep(100)
const { stats } = sampler.get('a')!
for (const [key, value] of Object.entries(stats!)) {
assert.ok(value === null || value === undefined || Number.isFinite(value), key)
}
} finally {
sampler.stop()
}
})
})

View File

@@ -0,0 +1,273 @@
// Docker attach/logs stream decoding.
//
// When a container has no TTY, dockerd multiplexes stdout and stderr on the
// same HTTP body (`Content-Type: application/vnd.docker.multiplexed-stream`):
// each frame is an 8-byte header `[streamType, 0, 0, 0, size (uint32 BE)]`
// followed by `size` bytes of payload. With a TTY, the body is the raw output
// (`application/vnd.docker.raw-stream`), stdout and stderr merged.
//
// See https://docs.docker.com/reference/api/engine/version/v1.43/#tag/Container/operation/ContainerAttach
import { StringDecoder } from 'node:string_decoder'
import { Transform, type TransformCallback } from 'node:stream'
import type { XoDockerLogEntry } from '@vates/types'
import { compareApiVersions } from './connection.mjs'
import { DOCKER_API_ERROR, DockerError } from './errors.mjs'
export const MULTIPLEXED_STREAM_CONTENT_TYPE = 'application/vnd.docker.multiplexed-stream'
export const RAW_STREAM_CONTENT_TYPE = 'application/vnd.docker.raw-stream'
const HEADER_SIZE = 8
// stream type (1st byte of a frame header) → stream name
//
// type 3 (`systemErr`) is used by dockerd to report an error in the middle of
// an attach/exec stream, its payload is the error message
const STREAM_NAMES = ['stdin', 'stdout', 'stderr'] as const
const SYSTEM_ERR = 3
// only the beginning of a systemErr payload is kept (it becomes an error
// message), the rest is read and dropped
export const MAX_SYSTEM_ERR_SIZE = 64 * 1024
export type DockerStreamName = (typeof STREAM_NAMES)[number]
/** object emitted by `createStdcopyDemuxer()` */
export type DemuxedChunk = { stream: DockerStreamName; chunk: Buffer }
/** `createStdcopyDemuxer()` */
export type StdcopyDemuxer = Transform & { truncated: boolean }
/**
* Object emitted by `createLogLineParser()`: an `XoDockerLogEntry`, except
* that `stream` may be `stdin` (attach streams), and that `timestamp` is always
* present (`undefined` if the line has none).
*/
export type DockerLogLine = Omit<XoDockerLogEntry, 'stream' | 'timestamp'> & {
stream: DockerStreamName
timestamp: string | undefined
}
/**
* Whether a logs/attach response body is multiplexed (8-byte frames) or raw.
*
* The `Content-Type` is reliable since API 1.42. With older API versions (or
* an unknown one), a `raw-stream` content type is not conclusive and the
* container's `Config.Tty` decides, defaulting to multiplexed, which is what
* containers without TTY (the vast majority) produce.
*
* @param contentType response `Content-Type`
* @param tty `Config.Tty` of the container, if known
* @param apiVersion negotiated API version, e.g. `1.44`
*/
export function isMultiplexedStream(contentType: string | undefined, tty?: boolean, apiVersion?: string): boolean {
const type = contentType?.split(';')[0].trim().toLowerCase()
if (type === MULTIPLEXED_STREAM_CONTENT_TYPE) {
return true
}
if (type === RAW_STREAM_CONTENT_TYPE && apiVersion !== undefined && compareApiVersions(apiVersion, '1.42') >= 0) {
return false
}
return tty !== true
}
/**
* Transform stream: Docker logs/attach body (bytes) → `{ stream, chunk }`
* objects, `stream` being `stdout`, `stderr` or `stdin`, and `chunk` a
* `Buffer`.
*
* Frames can be split across any chunk boundary. Payloads are emitted as soon as
* they arrive, so a big frame is never buffered entirely: consumers must not
* assume one object per frame (see `createLogLineParser()`).
*
* If the input ends in the middle of a frame, the payload received so far has
* already been emitted and `demuxer.truncated` is set to `true`: the stream ends
* normally, so that the complete part of the logs remains usable.
*
* @param opts.tty raw mode: the input is not framed, every chunk is emitted as `stdout`
*/
export function createStdcopyDemuxer({ tty = false }: { tty?: boolean } = {}): StdcopyDemuxer {
if (tty) {
// `truncated` is added right below
const passthrough = new Transform({
readableObjectMode: true,
transform(chunk: Buffer, _encoding, callback) {
callback(null, { stream: 'stdout', chunk } satisfies DemuxedChunk)
},
}) as StdcopyDemuxer
passthrough.truncated = false
return passthrough
}
const header = Buffer.alloc(HEADER_SIZE)
let headerLength = 0
let stream: DockerStreamName | undefined // name of the stream of the current frame
let remaining = 0 // payload bytes still expected for the current frame
let systemErr: Buffer[] | undefined // chunks of a systemErr frame, emitted as an error
let systemErrSize = 0
// `truncated` is added right below
const demuxer = new Transform({
readableObjectMode: true,
transform(chunk: Buffer, _encoding, callback) {
let offset = 0
const { length } = chunk
while (offset < length) {
if (remaining === 0) {
// reading a header
const n = Math.min(HEADER_SIZE - headerLength, length - offset)
chunk.copy(header, headerLength, offset, offset + n)
headerLength += n
offset += n
if (headerLength < HEADER_SIZE) {
break
}
headerLength = 0
const type = header[0]
remaining = header.readUInt32BE(4)
if (type === SYSTEM_ERR) {
systemErr = []
systemErrSize = 0
} else if (type < STREAM_NAMES.length) {
stream = STREAM_NAMES[type]
} else {
callback(
new DockerError(DOCKER_API_ERROR, `invalid Docker stream: unknown stream type ${type}`, {
data: { header: header.toString('hex') },
})
)
return
}
if (remaining === 0 && systemErr !== undefined) {
callback(systemError(systemErr))
return
}
continue
}
// reading a payload
const n = Math.min(remaining, length - offset)
// subarray() does not copy: chunks come from the socket and are not reused
const payload = chunk.subarray(offset, offset + n)
offset += n
remaining -= n
if (systemErr !== undefined) {
if (systemErrSize < MAX_SYSTEM_ERR_SIZE) {
const kept = payload.subarray(0, MAX_SYSTEM_ERR_SIZE - systemErrSize)
systemErr.push(kept)
systemErrSize += kept.length
}
if (remaining === 0) {
callback(systemError(systemErr))
return
}
} else {
// `stream!`: set by the header of this frame
this.push({ stream: stream!, chunk: payload } satisfies DemuxedChunk)
}
}
callback()
},
flush(callback) {
if (headerLength !== 0 || remaining !== 0) {
;(this as StdcopyDemuxer).truncated = true
}
callback()
},
}) as StdcopyDemuxer
demuxer.truncated = false
return demuxer
}
function systemError(chunks: Buffer[]): DockerError {
return new DockerError(DOCKER_API_ERROR, `Docker stream error: ${Buffer.concat(chunks).toString().trim()}`)
}
// RFC3339Nano timestamp as prefixed by dockerd with `timestamps=1`, e.g.
// `2026-09-24T16:54:37.796330221Z` (trailing zeros of the fraction are
// trimmed, the fraction can be missing, the offset is `Z` in practice)
const TIMESTAMP_RE = /^(\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d{1,9})?(?:Z|[+-]\d{2}:\d{2})) /
const DEFAULT_MAX_LINE_LENGTH = 64 * 1024
/**
* Transform stream (object mode): `{ stream, chunk }` objects (from
* `createStdcopyDemuxer()`) → `{ stream, timestamp, message }` log entries.
*
* - lines are split on `\n`, a trailing `\r` (TTY output) is removed
* - each stream is buffered separately, so interleaved stdout/stderr chunks do
* not mix partial lines
* - `timestamp` is the RFC3339Nano string prefixed by dockerd with
* `timestamps=1`, kept verbatim (it has a nanosecond precision), or
* `undefined` if the line has none
* - a line longer than `maxLineLength` characters is split, which bounds the
* memory used by an output without new lines
* - the last line is emitted even if it does not end with a new line
*
* The input chunks may also be strings.
*/
export function createLogLineParser({
maxLineLength = DEFAULT_MAX_LINE_LENGTH,
}: { maxLineLength?: number } = {}): Transform {
// stream name → { decoder, pending }
const states = new Map<DockerStreamName, { decoder: StringDecoder; pending: string }>()
const getState = (stream: DockerStreamName) => {
let state = states.get(stream)
if (state === undefined) {
state = { decoder: new StringDecoder('utf8'), pending: '' }
states.set(stream, state)
}
return state
}
const emitLine = (parser: Transform, stream: DockerStreamName, line: string) => {
if (line.endsWith('\r')) {
line = line.slice(0, -1)
}
const match = TIMESTAMP_RE.exec(line)
parser.push(
(match === null
? { stream, timestamp: undefined, message: line }
: { stream, timestamp: match[1], message: line.slice(match[0].length) }) satisfies DockerLogLine
)
}
return new Transform({
objectMode: true,
transform(
{ stream, chunk }: { stream: DockerStreamName; chunk: Buffer | string },
_encoding: BufferEncoding,
callback: TransformCallback
) {
const state = getState(stream)
const text = state.pending + (typeof chunk === 'string' ? chunk : state.decoder.write(chunk))
const lines = text.split('\n')
// `pop()!`: `split()` gives at least one string
let pending = lines.pop()!
for (const line of lines) {
emitLine(this, stream, line)
}
while (pending.length > maxLineLength) {
emitLine(this, stream, pending.slice(0, maxLineLength))
pending = pending.slice(maxLineLength)
}
state.pending = pending
callback()
},
flush(callback) {
for (const [stream, state] of states) {
const last = state.pending + state.decoder.end()
if (last !== '') {
emitLine(this, stream, last)
}
}
states.clear()
callback()
},
})
}

View File

@@ -0,0 +1,326 @@
import assert from 'node:assert/strict'
import { Readable, type Transform } from 'node:stream'
import { pipeline } from 'node:stream/promises'
import test from 'node:test'
import { DOCKER_API_ERROR, type DockerError } from './errors.mjs'
import { LOGS_EXITED, LOGS_NGINX, LOGS_TTY } from './fixtures/logs.mjs'
import {
createLogLineParser,
createStdcopyDemuxer,
isMultiplexedStream,
MAX_SYSTEM_ERR_SIZE,
MULTIPLEXED_STREAM_CONTENT_TYPE,
RAW_STREAM_CONTENT_TYPE,
type DemuxedChunk,
type DockerLogLine,
} from './stdcopy.mjs'
const { describe, it } = test
const NGINX_BODY = Buffer.from(LOGS_NGINX.body, 'base64')
const EXITED_BODY = Buffer.from(LOGS_EXITED.body, 'base64')
const TTY_BODY = Buffer.from(LOGS_TTY.body, 'base64')
function frame(type: number, payload: string | Buffer) {
const data = Buffer.from(payload)
const header = Buffer.alloc(8)
header[0] = type
header.writeUInt32BE(data.length, 4)
return Buffer.concat([header, data])
}
const bytes = (buffer: Buffer) => Array.from(buffer, byte => Buffer.from([byte]))
// `T`: the objects emitted by the last transform (`DemuxedChunk` or `DockerLogLine` in these tests)
async function run<T = DemuxedChunk>(chunks: unknown[], ...transforms: Transform[]): Promise<T[]> {
const output: T[] = []
// @ts-expect-error @types/node has no overload of pipeline() for a variable number of transforms (rest argument)
await pipeline(Readable.from(chunks), ...transforms, async (source: AsyncIterable<T>) => {
for await (const object of source) {
output.push(object)
}
})
return output
}
// concatenates the emitted chunks of each stream
function byStream(objects: DemuxedChunk[]) {
const result: Record<string, Buffer> = {}
for (const { stream, chunk } of objects) {
result[stream] = Buffer.concat([result[stream] ?? Buffer.alloc(0), chunk])
}
return Object.fromEntries(Object.entries(result).map(([stream, buffer]) => [stream, buffer.toString()]))
}
// splits a multiplexed body into frames, the simple way
function parseFrames(body: Buffer) {
const frames: { type: number; payload: string }[] = []
for (let offset = 0; offset < body.length; ) {
const size = body.readUInt32BE(offset + 4)
frames.push({ type: body[offset], payload: body.subarray(offset + 8, offset + 8 + size).toString() })
offset += 8 + size
}
return frames
}
describe('createStdcopyDemuxer()', () => {
it('demuxes the real logs of a container, fed at once', async () => {
const objects = await run([EXITED_BODY], createStdcopyDemuxer())
assert.deepEqual(
objects.map(({ stream, chunk }) => ({ stream, text: chunk.toString() })),
[{ stream: 'stdout', text: '2026-09-24T16:54:38.377173968Z failing on purpose\n' }]
)
})
it('demuxes real logs fed byte-at-a-time', async () => {
const frames = parseFrames(NGINX_BODY)
const expected = {
stdout: frames
.filter(_ => _.type === 1)
.map(_ => _.payload)
.join(''),
stderr: frames
.filter(_ => _.type === 2)
.map(_ => _.payload)
.join(''),
}
assert.ok(expected.stdout.length > 0 && expected.stderr.length > 0)
const demuxer = createStdcopyDemuxer()
const objects = await run(bytes(NGINX_BODY), demuxer)
assert.deepEqual(byStream(objects), expected)
assert.equal(demuxer.truncated, false)
for (const { chunk } of objects) {
assert.ok(Buffer.isBuffer(chunk))
}
})
it('handles a frame boundary at any position', async () => {
const body = Buffer.concat([
frame(1, 'out 1\n'),
frame(2, 'err 1\n'),
frame(1, ''),
frame(1, 'out 2\n'),
frame(0, 'in\n'),
])
for (let i = 0; i <= body.length; ++i) {
for (let j = i; j <= body.length; j += 3) {
const chunks = [body.subarray(0, i), body.subarray(i, j), body.subarray(j)].filter(_ => _.length !== 0)
assert.deepEqual(byStream(await run(chunks, createStdcopyDemuxer())), {
stdout: 'out 1\nout 2\n',
stderr: 'err 1\n',
stdin: 'in\n',
})
}
}
})
it('keeps the order of interleaved stdout and stderr frames', async () => {
const body = Buffer.concat([frame(1, 'a'), frame(2, 'b'), frame(1, 'c'), frame(2, 'd')])
const objects = await run(bytes(body), createStdcopyDemuxer())
assert.deepEqual(
objects.map(({ stream, chunk }) => stream + ':' + chunk),
['stdout:a', 'stderr:b', 'stdout:c', 'stderr:d']
)
})
it('emits big payloads without waiting for the end of the frame', async () => {
const payload = Buffer.alloc(1024 * 1024, 'x')
const body = frame(1, payload)
const chunks = [body.subarray(0, 1000), body.subarray(1000, 500e3), body.subarray(500e3)]
const objects = await run(chunks, createStdcopyDemuxer())
assert.equal(objects.length, 3)
assert.equal(Buffer.concat(objects.map(_ => _.chunk)).length, payload.length)
})
describe('truncated trailing frame', () => {
const [firstFrameSize] = [8 + NGINX_BODY.readUInt32BE(4)]
it('in the payload: emits what was received and sets `truncated`', async () => {
const cut = firstFrameSize + 8 + 10
const demuxer = createStdcopyDemuxer()
const objects = await run(bytes(NGINX_BODY.subarray(0, cut)), demuxer)
assert.equal(demuxer.truncated, true)
const text = Buffer.concat(objects.map(_ => _.chunk)).toString()
assert.equal(text.length, firstFrameSize - 8 + 10)
assert.ok(text.startsWith(NGINX_BODY.subarray(8, firstFrameSize).toString()))
})
it('in the header: drops the partial header and sets `truncated`', async () => {
const demuxer = createStdcopyDemuxer()
const objects = await run([NGINX_BODY.subarray(0, firstFrameSize + 5)], demuxer)
assert.equal(demuxer.truncated, true)
assert.equal(
Buffer.concat(objects.map(_ => _.chunk)).toString(),
NGINX_BODY.subarray(8, firstFrameSize).toString()
)
})
})
it('fails on an unknown stream type', async () => {
await assert.rejects(run([Buffer.concat([frame(1, 'ok'), frame(7, 'ko')])], createStdcopyDemuxer()), {
code: DOCKER_API_ERROR,
message: /unknown stream type 7/,
})
})
it('fails with the message of a systemErr frame', async () => {
await assert.rejects(run(bytes(Buffer.concat([frame(1, 'ok'), frame(3, 'boom\n')])), createStdcopyDemuxer()), {
code: DOCKER_API_ERROR,
message: 'Docker stream error: boom',
})
})
it('keeps only the first MAX_SYSTEM_ERR_SIZE bytes of a systemErr payload', async () => {
const payload = 'x'.repeat(MAX_SYSTEM_ERR_SIZE) + 'DROPPED'.repeat(1e4)
const big = frame(3, payload)
// split in several chunks: the cap spans chunks
const chunks = []
for (let i = 0; i < big.length; i += 10e3) {
chunks.push(big.subarray(i, i + 10e3))
}
await assert.rejects(run(chunks, createStdcopyDemuxer()), (error: DockerError) => {
assert.equal(error.code, DOCKER_API_ERROR)
assert.equal(error.message, 'Docker stream error: ' + 'x'.repeat(MAX_SYSTEM_ERR_SIZE))
return true
})
})
it('passes raw (TTY) streams through as stdout', async () => {
const demuxer = createStdcopyDemuxer({ tty: true })
const objects = await run(bytes(TTY_BODY), demuxer)
assert.equal(objects.length, TTY_BODY.length)
assert.deepEqual(byStream(objects), { stdout: TTY_BODY.toString() })
assert.equal(demuxer.truncated, false)
})
})
describe('createLogLineParser()', () => {
it('parses real non-TTY logs, fed byte-at-a-time', async () => {
const entries = await run<DockerLogLine>(bytes(NGINX_BODY), createStdcopyDemuxer(), createLogLineParser())
const frames = parseFrames(NGINX_BODY)
// with timestamps=1, dockerd sends one line per frame
assert.equal(entries.length, frames.length)
entries.forEach((entry, i) => {
assert.equal(entry.stream, frames[i].type === 1 ? 'stdout' : 'stderr')
assert.equal(`${entry.timestamp} ${entry.message}\n`, frames[i].payload)
assert.match(entry.timestamp!, /^2026-09-24T16:5\d:\d\d\.\d+Z$/)
})
assert.deepEqual(entries[0], {
stream: 'stdout',
timestamp: '2026-09-24T16:54:37.796330221Z',
message: '/docker-entrypoint.sh: /docker-entrypoint.d/ is not empty, will attempt to perform configuration',
})
assert.ok(entries.some(_ => _.stream === 'stderr' && _.message.includes('[notice]')))
assert.ok(entries.some(_ => _.stream === 'stdout' && _.message.includes('"GET / HTTP/1.1" 200')))
})
it('parses real TTY logs: strips \\r, emits the last line without new line', async () => {
const entries = await run<DockerLogLine>(
bytes(TTY_BODY),
createStdcopyDemuxer({ tty: true }),
createLogLineParser()
)
assert.deepEqual(entries, [
{ stream: 'stdout', timestamp: '2026-09-24T16:56:05.110355030Z', message: 'tty line one' },
// written on stderr by the container, but a TTY merges both
{ stream: 'stdout', timestamp: '2026-09-24T16:56:05.110988999Z', message: 'tty line two' },
{ stream: 'stdout', timestamp: '2026-09-24T16:56:05.170603899Z', message: 'no newline at end' },
])
})
it('buffers partial lines per stream', async () => {
const body = Buffer.concat([
frame(1, 'hel'),
frame(2, 'err '),
frame(1, 'lo\nwor'),
frame(2, 'line\n'),
frame(1, 'ld'),
])
const entries = await run<DockerLogLine>([body], createStdcopyDemuxer(), createLogLineParser())
assert.deepEqual(entries, [
{ stream: 'stdout', timestamp: undefined, message: 'hello' },
{ stream: 'stderr', timestamp: undefined, message: 'err line' },
{ stream: 'stdout', timestamp: undefined, message: 'world' },
])
})
it('extracts the leading RFC3339Nano timestamp', async () => {
const lines = [
'2026-09-24T16:54:37.796330221Z message',
'2026-09-24T16:54:37.7Z trimmed fraction',
'2026-09-24T16:54:37Z no fraction',
'2026-09-24T18:54:37.123+02:00 offset',
'2026-09-24T16:54:37.796330221Z ',
'no timestamp',
'2026-09-24T16:54:37Z',
' 2026-09-24T16:54:37Z leading space',
]
const entries = await run<DockerLogLine>(
[{ stream: 'stdout', chunk: Buffer.from(lines.join('\n')) }],
createLogLineParser()
)
assert.deepEqual(
entries.map(({ timestamp, message }) => [timestamp, message]),
[
['2026-09-24T16:54:37.796330221Z', 'message'],
['2026-09-24T16:54:37.7Z', 'trimmed fraction'],
['2026-09-24T16:54:37Z', 'no fraction'],
['2026-09-24T18:54:37.123+02:00', 'offset'],
['2026-09-24T16:54:37.796330221Z', ''],
[undefined, 'no timestamp'],
[undefined, '2026-09-24T16:54:37Z'],
[undefined, ' 2026-09-24T16:54:37Z leading space'],
]
)
})
it('keeps empty lines', async () => {
const entries = await run<DockerLogLine>(
[{ stream: 'stdout', chunk: Buffer.from('a\n\n\nb\n') }],
createLogLineParser()
)
assert.deepEqual(
entries.map(_ => _.message),
['a', '', '', 'b']
)
})
it('decodes multi-byte UTF-8 characters split across chunks', async () => {
const text = 'héllo wörld 🐳\n'
const chunks = bytes(Buffer.from(text)).map(chunk => ({ stream: 'stdout', chunk }))
const entries = await run<DockerLogLine>(chunks, createLogLineParser())
assert.deepEqual(entries, [{ stream: 'stdout', timestamp: undefined, message: 'héllo wörld 🐳' }])
})
it('splits lines longer than maxLineLength', async () => {
const chunks = [
{ stream: 'stdout', chunk: Buffer.from('x'.repeat(25)) },
{ stream: 'stdout', chunk: 'yy\nz' },
]
const entries = await run<DockerLogLine>(chunks, createLogLineParser({ maxLineLength: 10 }))
assert.deepEqual(
entries.map(_ => _.message),
['x'.repeat(10), 'x'.repeat(10), 'xxxxxyy', 'z']
)
})
})
describe('isMultiplexedStream()', () => {
it('trusts the content type since API 1.42', () => {
assert.equal(isMultiplexedStream(LOGS_NGINX.contentType, undefined, '1.43'), true)
assert.equal(isMultiplexedStream(LOGS_TTY.contentType, undefined, '1.43'), false)
assert.equal(isMultiplexedStream(RAW_STREAM_CONTENT_TYPE, false, '1.42'), false)
assert.equal(isMultiplexedStream(`${MULTIPLEXED_STREAM_CONTENT_TYPE}; charset=utf-8`, true, '1.24'), true)
})
it('falls back to Config.Tty before API 1.42, or when the content type is unknown', () => {
assert.equal(isMultiplexedStream(RAW_STREAM_CONTENT_TYPE, false, '1.41'), true)
assert.equal(isMultiplexedStream(RAW_STREAM_CONTENT_TYPE, true, '1.41'), false)
assert.equal(isMultiplexedStream(undefined, true, '1.43'), false)
assert.equal(isMultiplexedStream('text/plain', false), true)
// defaults to multiplexed, like most containers
assert.equal(isMultiplexedStream(undefined, undefined), true)
})
})

View File

@@ -0,0 +1,106 @@
/**
* Cache of async results with a time to live.
*
* - concurrent `get()` of a missing key share the same pending promise
* - rejections are not cached
* - expired entries are only removed by `sweep()`, `delete()` or
* `deleteByPrefix()`: call `sweep()` periodically
* - a value fetched while its key is deleted is not cached (the caller still
* gets it)
*
* Not `lru-cache` (whose `fetch()` has the rest, with `ignoreFetchAbort`): its
* `keys()` does not list pending fetches, so `deleteByPrefix()` could not drop
* them, and a list fetched with an engine's previous credentials would be
* cached after the credentials change (checked with lru-cache 11.5).
*/
type Entry = { promise: Promise<unknown>; value: unknown; expiresAt: number | undefined }
export class AsyncTtlCache {
// key → { promise, value, expiresAt } (`expiresAt` undefined while pending)
#entries = new Map<string, Entry>()
#expiresIn: number
#now: () => number
/**
* @param opts.expiresIn ms
* @param opts.now for tests
*/
constructor({ expiresIn, now = Date.now }: { expiresIn: number; now?: () => number }) {
this.#expiresIn = expiresIn
this.#now = now
}
get size() {
return this.#entries.size
}
/**
* The type of a cached value is not checked: a key must always be used with
* functions returning the same type.
*
* @param opts.forceRefresh ignore a cached value (a pending one is still shared)
*/
get<T>(key: string, fn: () => Promise<T>, { forceRefresh = false }: { forceRefresh?: boolean } = {}): Promise<T> {
const current = this.#entries.get(key)
if (current !== undefined) {
if (current.expiresAt === undefined) {
return current.promise as Promise<T>
}
if (!forceRefresh && current.expiresAt > this.#now()) {
return current.promise as Promise<T>
}
}
const entry: { expiresAt: number | undefined; promise: Promise<T>; value: T | undefined } = {
expiresAt: undefined,
// replaced right below, `entry` must exist before the callbacks run
promise: undefined as unknown as Promise<T>,
value: undefined,
}
entry.promise = (async () => fn())().then(
value => {
if (this.#entries.get(key) === entry) {
entry.value = value
entry.expiresAt = this.#now() + this.#expiresIn
}
return value
},
error => {
if (this.#entries.get(key) === entry) {
this.#entries.delete(key)
}
throw error
}
)
this.#entries.set(key, entry)
return entry.promise
}
/**
* Value of a key if it is cached and not expired, without fetching it.
*/
peek(key: string): unknown {
const entry = this.#entries.get(key)
if (entry !== undefined && entry.expiresAt !== undefined && entry.expiresAt > this.#now()) {
return entry.value
}
}
deleteByPrefix(prefix: string) {
for (const key of Array.from(this.#entries.keys())) {
if (key.startsWith(prefix)) {
this.#entries.delete(key)
}
}
}
/** Remove expired entries. */
sweep() {
const now = this.#now()
for (const [key, entry] of Array.from(this.#entries)) {
if (entry.expiresAt !== undefined && entry.expiresAt <= now) {
this.#entries.delete(key)
}
}
}
}

View File

@@ -0,0 +1,68 @@
import assert from 'node:assert/strict'
import { describe, it } from 'node:test'
import { AsyncTtlCache } from './ttl-cache.mjs'
const createClock = () => {
const clock = () => clock.time
clock.time = 0
return clock
}
describe('AsyncTtlCache', () => {
it('shares pending fetches and caches values for expiresIn', async () => {
const now = createClock()
const cache = new AsyncTtlCache({ expiresIn: 10, now })
let calls = 0
const fn = async () => ++calls
assert.deepEqual(await Promise.all([cache.get('k', fn), cache.get('k', fn)]), [1, 1])
assert.equal(cache.peek('k'), 1)
now.time = 9
assert.equal(await cache.get('k', fn), 1)
now.time = 10
assert.equal(cache.peek('k'), undefined)
assert.equal(await cache.get('k', fn), 2)
})
it('does not cache rejections', async () => {
const cache = new AsyncTtlCache({ expiresIn: 10 })
await assert.rejects(
cache.get('k', async () => {
throw new Error('boom')
}),
/boom/
)
assert.equal(cache.size, 0)
assert.equal(await cache.get('k', async () => 'ok'), 'ok')
})
it('forceRefresh ignores a cached value', async () => {
const cache = new AsyncTtlCache({ expiresIn: 1e3 })
await cache.get('k', async () => 1)
assert.equal(await cache.get('k', async () => 2, { forceRefresh: true }), 2)
assert.equal(cache.peek('k'), 2)
})
it('deleteByPrefix() and sweep()', async () => {
const now = createClock()
const cache = new AsyncTtlCache({ expiresIn: 10, now })
await cache.get('a:1', async () => 1)
await cache.get('a:2', async () => 2)
await cache.get('b:1', async () => 3)
cache.deleteByPrefix('a:')
assert.equal(cache.size, 1)
now.time = 10
cache.sweep()
assert.equal(cache.size, 0)
})
it('a value fetched before a deletion is not cached', async () => {
const cache = new AsyncTtlCache({ expiresIn: 1e3 })
let resolve: ((value: string) => void) | undefined
const promise = cache.get('k', () => new Promise<string>(_resolve => (resolve = _resolve)))
cache.deleteByPrefix('k')
resolve!('stale')
assert.equal(await promise, 'stale')
assert.equal(cache.peek('k'), undefined)
})
})

View File

@@ -0,0 +1,161 @@
// Docker Engine API wire shapes read by this package. Internal: the XO DTOs are
// in `@vates/types`.
//
// Built from the types generated from Docker's OpenAPI specifications
// (`docker-api.gen.mts`, see `scripts/generate-api-types.mjs`): only the fields
// read by the transport and the normalizers are picked, their types come from
// the spec. The daemon sends more (hence the index signatures), and older API
// versions may omit some of them. Departures from the spec are commented.
//
// These types are what the daemon is expected to send, they are not checked,
// except for the stats: a hostile or buggy daemon controls every value (see
// `normalizeContainerStats()`), which are therefore `unknown`.
import type { definitions as Api } from './docker-api.gen.mjs'
/** the fields `K` of the spec definition `T`, the others being allowed but unknown */
type Wire<T, K extends keyof T> = Pick<T, K> & { [key: string]: unknown }
/**
* `T` with the fields `K` required: sent by every daemon, relied upon by the
* normalizers (an intersection, not `Omit`, which would lose the properties of a
* type with an index signature)
*/
type WithRequired<T, K extends keyof T> = T & { [P in K]-?: NonNullable<T[P]> }
/** `GET /version` */
export type DockerVersion = Wire<
Api['SystemVersion'],
'Version' | 'ApiVersion' | 'MinAPIVersion' | 'Platform' | 'Components'
>
/** `GET /info` */
export type DockerInfo = Wire<
Api['SystemInfo'],
| 'ID'
| 'Name'
| 'ServerVersion'
| 'OperatingSystem'
| 'OSType'
| 'KernelVersion'
| 'Architecture'
| 'NCPU'
| 'MemTotal'
| 'Driver'
| 'LoggingDriver'
| 'CgroupDriver'
| 'CgroupVersion'
| 'Containers'
| 'ContainersRunning'
| 'ContainersPaused'
| 'ContainersStopped'
| 'Images'
> & {
// not in the spec: `null` when empty
SecurityOptions?: Api['SystemInfo']['SecurityOptions'] | null
Warnings?: Api['SystemInfo']['Warnings'] | null
}
export type DockerContainerState = NonNullable<Api['ContainerState']['Status']>
/** entry of `Ports` in `GET /containers/json` */
export type DockerPort = Wire<Api['Port'], 'IP' | 'PrivatePort' | 'PublicPort' | 'Type'>
/**
* `NetworkSettings.Ports` of `GET /containers/{id}/json`, e.g.
* `{ "80/tcp": [{ "HostIp": "0.0.0.0", "HostPort": "8080" }], "443/tcp": null }`
* (not in the spec: `null` for an exposed port which is not published)
*/
export type DockerPortMap = Record<string, WithRequired<Api['PortBinding'], 'HostIp' | 'HostPort'>[] | null>
/** value of `NetworkSettings.Networks` */
export type DockerEndpointSettings = Wire<Api['EndpointSettings'], 'IPAddress' | 'GlobalIPv6Address'>
export type DockerMountPoint = WithRequired<
Wire<Api['MountPoint'], 'Type' | 'Name' | 'Source' | 'Destination' | 'RW'>,
'Type' | 'Source' | 'Destination' | 'RW'
>
/** entry of `GET /containers/json` */
export type DockerContainerSummary = WithRequired<
Wire<
Api['ContainerSummary'],
'Id' | 'Names' | 'Image' | 'ImageID' | 'Command' | 'Created' | 'Status' | 'Ports' | 'Labels' | 'Mounts'
>,
'Id' | 'Image' | 'ImageID' | 'Command' | 'Created'
> & {
// the spec says `string`
State: DockerContainerState
NetworkSettings?: { Networks?: Record<string, DockerEndpointSettings>; [key: string]: unknown }
Mounts?: DockerMountPoint[]
}
/** `Config` of `GET /containers/{id}/json` */
export type DockerContainerConfig = WithRequired<
Wire<Api['ContainerConfig'], 'Image' | 'Labels' | 'Tty' | 'Hostname' | 'WorkingDir' | 'User' | 'Env'>,
'Image'
>
export type DockerHealthCheckResult = Wire<Api['HealthcheckResult'], 'Start' | 'End' | 'ExitCode' | 'Output'>
/** `State` of `GET /containers/{id}/json` */
export type DockerContainerStateInfo = WithRequired<
Wire<Api['ContainerState'], 'Status' | 'ExitCode' | 'OOMKilled' | 'Error' | 'StartedAt' | 'FinishedAt'>,
'Status'
> & {
/** only for a container with a health check */
Health?: WithRequired<Wire<Api['Health'], 'Status' | 'FailingStreak'>, 'FailingStreak'> & {
Log?: DockerHealthCheckResult[]
}
}
/** `GET /containers/{id}/json` */
export type DockerInspect = WithRequired<
Wire<Api['ContainerInspectResponse'], 'Id' | 'Name' | 'Image' | 'Path' | 'Args' | 'Created' | 'RestartCount'>,
'Id' | 'Name' | 'Image' | 'Path'
> & {
Config?: DockerContainerConfig
HostConfig?: { RestartPolicy?: Api['RestartPolicy']; [key: string]: unknown }
NetworkSettings?: {
Ports?: DockerPortMap
Networks?: Record<string, DockerEndpointSettings>
[key: string]: unknown
}
State?: DockerContainerStateInfo
Mounts?: DockerMountPoint[]
}
// === Stats: never trusted
//
// The keys come from the spec (API 1.48, the first one documenting the stats),
// every value is `unknown`: the objects are typed as such so that they can be
// read with optional chaining, which gives `undefined` whatever they really
// are (the keys read are not properties of the prototypes of the primitives).
// No index signature: reading a key which is not in the spec does not compile.
type Untrusted<T> = { [K in keyof T]?: unknown }
/** `cpu_stats` and `precpu_stats` */
export type DockerCpuStats = Omit<Untrusted<Api['ContainerCPUStats']>, 'cpu_usage'> & {
cpu_usage?: Untrusted<Api['ContainerCPUUsage']>
}
/** `memory_stats` (`stats`: cgroup counters, e.g. `inactive_file`; `privateworkingset`: Windows) */
export type DockerMemoryStats = Untrusted<Api['ContainerMemoryStats']>
/** `blkio_stats` (`io_service_bytes_recursive`: `{ op, value }` entries) */
export type DockerBlkioStats = Untrusted<Api['ContainerBlkioStats']>
/** one object of `GET /containers/{id}/stats` */
export type DockerStatsSample = Omit<
Untrusted<Api['ContainerStatsResponse']>,
'cpu_stats' | 'precpu_stats' | 'memory_stats' | 'blkio_stats' | 'pids_stats'
> & {
cpu_stats?: DockerCpuStats
precpu_stats?: DockerCpuStats
memory_stats?: DockerMemoryStats
blkio_stats?: DockerBlkioStats
pids_stats?: Untrusted<Api['ContainerPidsStats']>
/** sent by the daemon (e.g. `windows`), missing from the spec */
os_type?: unknown
}

View File

@@ -0,0 +1,16 @@
{
"compilerOptions": {
"outDir": "./dist",
"rootDir": "./src",
"strict": true,
"module": "ESNext",
"moduleResolution": "bundler",
"target": "es2022",
"skipLibCheck": true,
"types": ["node"], // Only use types from Node.js and packages that are explicitly imported
"declaration": true // Generates `.d.ts` files for type safety
},
"include": ["./src/**/*"],
"exclude": ["./node_modules", "./dist"]
}

View File

@@ -1,4 +0,0 @@
// the error of proper-lockfile, which LocalHandler uses: callers and the documentation know this one
export default function lockedError(path) {
return Object.assign(new Error('Lock file is already being held'), { code: 'ELOCKED', file: path })
}

View File

@@ -1,12 +1,9 @@
import { BlobServiceClient, StorageSharedKeyCredential } from '@azure/storage-blob'
import { createLogger } from '@xen-orchestra/log'
import { pTimeout } from 'promise-toolbox'
import { parse } from 'xo-remote-parser'
import { join, split } from './path'
import RemoteHandlerAbstract from './abstract'
import copyStreamToBuffer from './_copyStreamToBuffer'
import lockedError from './_lockedError.js'
import { randomUUID } from 'node:crypto'
import { PassThrough, Transform, pipeline } from 'stream'
createLogger('xo:fs:azure')
@@ -14,52 +11,7 @@ const MAX_BLOCK_SIZE = 1024 * 1024 * 4000 // 4000 MiB
const MIN_BLOCK_SIZE = 1024 * 1024 * 4 // 4 MiB, default max block size
const MAX_BLOCK_COUNT = 50000
const AZURE_BATCH_MAX_REQUEST = 256 // BATCH_MAX_REQUEST constant from Azure
const { debug, warn, info } = createLogger('xo:fs:azure')
// how long the lease of a lock lasts without being renewed, in seconds: the longest finite lease Azure allows, as an
// infinite one would outlive a holder which crashed, and block the path until someone breaks it by hand
export const LEASE_DURATION = 60
// how often a holder renews the lease of its lock: 4 renewals per lease, so that a holder survives a few slow or
// failed requests without losing its lock
export const RENEW_INTERVAL = 15e3
// how long a renewal, or a reacquisition, waits for its requests: a hung one counts as a failed one, and the next
// renewal must still run before the lease expires, so RENEW_INTERVAL + RENEW_TIMEOUT + RENEW_INTERVAL < LEASE_DURATION
// (15 s + 20 s + 15 s < 60 s)
export const RENEW_TIMEOUT = 20e3
// leases the blob, creating it first, or throws `lockedError(path)`
//
// The holder of the lock deletes the blob when it releases it: when that happens between the upload and the
// acquisition, one more attempt. Losing a second race means another contender got it.
async function takeLease(blobClient, leaseClient, path) {
for (let attempt = 0; attempt < 2; ++attempt) {
try {
await blobClient.upload('', 0, { conditions: { ifNoneMatch: '*' } })
} catch (error) {
// 409: the blob exists; 412: it exists and is leased, and a write without the lease ID is refused
if (error.statusCode !== 409 && error.statusCode !== 412) {
throw error
}
}
try {
await leaseClient.acquireLease(LEASE_DURATION)
return
} catch (error) {
// 409: another lease is active
if (error.statusCode === 409) {
throw lockedError(path)
}
// 404: the blob was deleted since the upload
if (error.statusCode !== 404) {
throw error
}
}
}
throw lockedError(path)
}
const { warn, info } = createLogger('xo:fs:azure')
export default class AzureHandler extends RemoteHandlerAbstract {
#container
@@ -378,89 +330,4 @@ export default class AzureHandler extends RemoteHandlerAbstract {
await blobBatchClient.submitBatch(batch)
}
}
// Locks with a blob lease, Azure's own lock on a blob: Azure enforces its expiry, so there is no clock to compare,
// and a renewal writes nothing, where rewriting the blob would leave a copy every time on accounts with versioning
// or soft delete. An acquisition does leave one copy per lock taken, as the blob is created then deleted on release:
// a lease needs a blob to hold it.
//
// The requests are sent with the blob client directly, not through the handler's methods: those go through the
// handler's concurrency limit, and a renewal queued behind long uploads would let the lease expire.
//
// As with `LocalHandler#_lock()`, losing the lock while holding it is only logged, and the release function never
// rejects. A renewal which finds the lease gone takes the lock back, and the lock is given up only when another
// holder has it: any other error is a failed request, and the next renewal tries again.
async _lock(path) {
// `<path>.lock`, the name of the local lock directory: the listings skip it already
const blobClient = this.#containerClient.getBlockBlobClient(this.#makeFullPath(`${path}.lock`))
// Azure requires a GUID. Proposing it, rather than letting Azure pick one, makes the retry of the SDK harmless
// when the response of an acquisition is lost: acquiring with the ID of the active lease succeeds
const leaseId = randomUUID()
const leaseClient = blobClient.getBlobLeaseClient(leaseId)
await takeLease(blobClient, leaseClient, path)
let lastRenewal = Date.now()
let lost = false
let released = false
let renewing = Promise.resolve()
let timeout
async function renew() {
try {
await pTimeout.call(leaseClient.renewLease(), RENEW_TIMEOUT)
lastRenewal = Date.now()
return
} catch (error) {
// 404: the blob is gone; 409: it is leased to someone else
if (error.statusCode !== 404 && error.statusCode !== 409) {
// a failed request is not a lost lock: it is lost only if the lease expires and someone takes it, which the
// next successful request finds out; it repeats every interval while Azure fails, hence debug
debug('lock could not be renewed', { error, path, sinceLastRenewal: Date.now() - lastRenewal })
return
}
}
warn('lock compromised', { path })
try {
await pTimeout.call(takeLease(blobClient, leaseClient, path), RENEW_TIMEOUT)
lastRenewal = Date.now()
info('compromised lock was reacquired', { path })
} catch (error) {
lost = error.code === 'ELOCKED'
warn('compromised lock could not be reacquired', { error, path })
}
}
function schedule() {
timeout = setTimeout(() => {
renewing = renew().then(() => {
if (!released && !lost) {
schedule()
}
})
}, RENEW_INTERVAL)
timeout.unref()
}
schedule()
return async () => {
released = true
clearTimeout(timeout)
try {
// a renewal in flight which found the blob deleted would take the lock again
await renewing
// only deletes the blob while the lease is ours: after a lost lock, it is someone else's
await blobClient.delete({ conditions: { leaseId } })
} catch (error) {
// 404: the blob is gone; 412: it is not leased to `leaseId`
if (error.statusCode !== 404 && error.statusCode !== 412) {
warn('lock could not be released', { error, path })
}
}
}
}
}

View File

@@ -1,252 +0,0 @@
import { after, afterEach, before, beforeEach, describe, it, mock } from 'node:test'
import { strict as assert } from 'assert'
import 'dotenv/config'
import sinon from 'sinon'
import { ContainerClient } from '@azure/storage-blob'
import { getHandler } from '.'
import AzureHandler, { LEASE_DURATION, RENEW_INTERVAL, RENEW_TIMEOUT } from './azure.js'
// needs a real container, on Azure or Azurite
//
// xo_fs_azure='azure://<account>:<key>@<host>/<container>/<dir>' yarn workspace @xen-orchestra/fs test
const url = process.env.xo_fs_azure
describe('AzureHandler#lock()', { skip: url === undefined }, () => {
let handler
before(async () => {
handler = getHandler({ url }).addPrefix(`xo-fs-tests-${Date.now()}`)
await handler.sync()
})
after(async () => {
await handler?.forget()
})
it('refuses a held lock until it is released', async () => {
const lock = await handler.lock('vm')
try {
await assert.rejects(handler.lock('vm'), { code: 'ELOCKED' })
} finally {
await lock.dispose()
}
const again = await handler.lock('vm')
await again.dispose()
})
})
// `AzureHandler#_lock()` against a stubbed blob client: each status code it maps is checked through the lock it takes
describe('AzureHandler#_lock with stubbed blob client', () => {
let blob
let leaseClient
let getBlockBlobClientStub
let handler
const httpError = statusCode => Object.assign(new Error(`HTTP ${statusCode}`), { statusCode })
// one renewal, after `RENEW_INTERVAL`
async function renewOnce() {
mock.timers.tick(RENEW_INTERVAL)
await new Promise(resolve => setImmediate(resolve))
}
// a request which hangs until `RENEW_TIMEOUT` gives up on it
async function timeOut() {
mock.timers.tick(RENEW_TIMEOUT)
await new Promise(resolve => setImmediate(resolve))
}
beforeEach(() => {
mock.timers.enable({ apis: ['setTimeout', 'Date'] })
leaseClient = {
acquireLease: sinon.stub().resolves(),
renewLease: sinon.stub().resolves(),
}
blob = {
upload: sinon.stub().resolves(),
delete: sinon.stub().resolves(),
getBlobLeaseClient: sinon.stub().returns(leaseClient),
}
getBlockBlobClientStub = sinon.stub(ContainerClient.prototype, 'getBlockBlobClient').returns(blob)
handler = new AzureHandler({ url: 'azure://account:a2V5@account.blob.core.windows.net/container/dir' })
})
afterEach(() => {
getBlockBlobClientStub.restore()
mock.timers.reset()
})
it('leases the blob next to the path, under the directory of the handler, with a GUID of its own', async () => {
const release = await handler._lock('vm')
assert.deepEqual(getBlockBlobClientStub.firstCall.args, ['dir/vm.lock'])
assert.match(
blob.getBlobLeaseClient.firstCall.args[0],
/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/
)
assert.deepEqual(leaseClient.acquireLease.firstCall.args, [LEASE_DURATION])
await release()
})
describe('create', () => {
// 409: the blob exists; 412: it exists and is leased
for (const statusCode of [409, 412]) {
it(`goes on to acquire the lease when create fails with ${statusCode}`, async () => {
blob.upload.rejects(httpError(statusCode))
const release = await handler._lock('vm')
assert.deepEqual(blob.upload.firstCall.args, ['', 0, { conditions: { ifNoneMatch: '*' } }])
assert.equal(leaseClient.acquireLease.callCount, 1)
await release()
})
}
it('rethrows an unexpected create error', async () => {
blob.upload.rejects(httpError(500))
await assert.rejects(handler._lock('vm'), { statusCode: 500 })
assert.equal(leaseClient.acquireLease.callCount, 0)
})
})
describe('acquire', () => {
it('reports a lease held by another as ELOCKED', async () => {
leaseClient.acquireLease.rejects(httpError(409))
await assert.rejects(handler._lock('vm'), { code: 'ELOCKED' })
})
it('retries once when the blob is gone, then gives up as ELOCKED', async () => {
leaseClient.acquireLease.rejects(httpError(404))
await assert.rejects(handler._lock('vm'), { code: 'ELOCKED' })
assert.equal(blob.upload.callCount, 2)
assert.equal(leaseClient.acquireLease.callCount, 2)
})
it('takes the lock when the blob is back on the retry', async () => {
leaseClient.acquireLease.onFirstCall().rejects(httpError(404))
const release = await handler._lock('vm')
assert.equal(blob.upload.callCount, 2)
await release()
})
it('rethrows an unexpected acquire error', async () => {
leaseClient.acquireLease.rejects(httpError(500))
await assert.rejects(handler._lock('vm'), { statusCode: 500 })
})
})
describe('renew', () => {
// 404: the blob is gone; 409: it is leased to someone else. Either way the lock is taken again
for (const statusCode of [404, 409]) {
it(`takes the lock again when renewal fails with ${statusCode}`, async () => {
const release = await handler._lock('vm')
leaseClient.renewLease.rejects(httpError(statusCode))
await renewOnce()
assert.equal(leaseClient.renewLease.callCount, 1)
assert.equal(leaseClient.acquireLease.callCount, 2)
await release()
})
}
it('keeps the lock and renews again when renewal fails with another error', async () => {
const release = await handler._lock('vm')
leaseClient.renewLease.rejects(httpError(500))
await renewOnce()
await renewOnce()
assert.equal(leaseClient.renewLease.callCount, 2)
assert.equal(leaseClient.acquireLease.callCount, 1)
await release()
})
it('gives up on a renewal which hangs, and renews again', async () => {
const release = await handler._lock('vm')
leaseClient.renewLease.onFirstCall().returns(new Promise(() => {}))
await renewOnce()
await timeOut()
await renewOnce()
assert.equal(leaseClient.renewLease.callCount, 2)
assert.equal(leaseClient.acquireLease.callCount, 1)
await release()
})
it('gives up on a reacquisition which hangs, and renews again', async () => {
const release = await handler._lock('vm')
leaseClient.renewLease.onFirstCall().rejects(httpError(409))
leaseClient.acquireLease.onSecondCall().returns(new Promise(() => {}))
await renewOnce()
await timeOut()
await renewOnce()
assert.equal(leaseClient.renewLease.callCount, 2)
assert.equal(leaseClient.acquireLease.callCount, 2)
await release()
})
it('stops renewing once released', async () => {
const release = await handler._lock('vm')
await renewOnce()
await release()
await renewOnce()
assert.equal(leaseClient.renewLease.callCount, 1)
})
it('gives up the lock when another holder has the lease', async () => {
const release = await handler._lock('vm')
leaseClient.renewLease.rejects(httpError(409))
leaseClient.acquireLease.rejects(httpError(409))
await renewOnce()
await renewOnce()
assert.equal(leaseClient.renewLease.callCount, 1)
assert.equal(leaseClient.acquireLease.callCount, 2)
await release()
})
it('waits for a renewal in flight before releasing', async () => {
const release = await handler._lock('vm')
let renewed
leaseClient.renewLease.returns(new Promise(resolve => (renewed = resolve)))
await renewOnce()
const releasing = release()
await new Promise(resolve => setImmediate(resolve))
assert.equal(blob.delete.callCount, 0)
renewed()
await releasing
assert.equal(blob.delete.callCount, 1)
})
})
describe('remove', () => {
it('deletes the blob only while the lease is ours', async () => {
const release = await handler._lock('vm')
await release()
const [leaseId] = blob.getBlobLeaseClient.firstCall.args
assert.deepEqual(blob.delete.firstCall.args, [{ conditions: { leaseId } }])
})
// 404: the blob is gone; 412: it is not leased to us. Both are fine, and release never rejects anyway
for (const statusCode of [404, 412, 500]) {
it(`releases without rejecting when delete fails with ${statusCode}`, async () => {
const release = await handler._lock('vm')
blob.delete.rejects(httpError(statusCode))
await release()
assert.equal(blob.delete.callCount, 1)
})
}
})
})

View File

@@ -19,7 +19,6 @@ import { getApplyMd5BodyChecksumPlugin } from '@aws-sdk/middleware-apply-body-ch
import { Agent as HttpAgent } from 'http'
import { Agent as HttpsAgent } from 'https'
import { createLogger } from '@xen-orchestra/log'
import lockedError from './_lockedError.js'
import { PassThrough, Transform, pipeline } from 'stream'
import { parse } from 'xo-remote-parser'
import copyStreamToBuffer from './_copyStreamToBuffer.js'
@@ -37,13 +36,6 @@ const MAX_PART_NUMBER = 10000
const MIN_PART_SIZE = 5 * 1024 * 1024
const { debug, info, warn } = createLogger('xo:fs:s3')
// how often a holder rewrites its lock object
export const REFRESH_INTERVAL = 30e3
// how long a lock object may go without being rewritten before a contender takes it over: a holder survives a few
// failed refreshes, and one which crashed blocks the path for 3 minutes at most
export const STALE_AFTER = 180e3
export default class S3Handler extends RemoteHandlerAbstract {
#bucket
#dir
@@ -51,8 +43,6 @@ export default class S3Handler extends RemoteHandlerAbstract {
#httpAgent
#httpsAgent
#immutable = false
// the S3 user may not read the bucket's Object Lock configuration: whether it is enabled is unknown
#objectLockUnknown = false
#maxPartSize
#maxPartNumber
#minPartSize
@@ -524,12 +514,6 @@ export default class S3Handler extends RemoteHandlerAbstract {
if (error.$metadata.httpStatusCode === 403) {
info(`s3 user doesnt have enough privilege to check for Object Lock, enable content MD5 header`)
this.#s3.middlewareStack.use(getApplyMd5BodyChecksumPlugin(this.#s3.config))
if (!this.#objectLockUnknown) {
warn(
'the S3 user cannot read the Object Lock configuration of the bucket (s3:GetBucketObjectLockConfiguration), nothing is locked on this remote'
)
}
this.#objectLockUnknown = true
} else if (error.Code === 'ObjectLockConfigurationNotFoundError' || error.$metadata.httpStatusCode === 501) {
info(`Object lock is not available or not configured, don't add the content MD5 header`)
} else {
@@ -537,77 +521,4 @@ export default class S3Handler extends RemoteHandlerAbstract {
}
}
}
// Object Lock buckets keep the no-op lock of `RemoteHandlerAbstract`: every write of the lock object would leave
// a version retained for the whole retention period. So do the buckets whose Object Lock configuration the S3
// user cannot read (see `_sync()`).
//
// The lock is an object rewritten with plain writes, which every S3 provider supports: it is held while it is
// fresher than STALE_AFTER. It is not atomic: two contenders which find it free at the same time both take it, and
// a holder whose refreshes failed for STALE_AFTER keeps writing in a folder someone else took over.
//
// Its age is read on the provider's clock alone, `Last-Modified` against the `Date` of the response: XO's clock may
// not agree with the provider's, and one more than 2.5 minutes ahead would take over a lock its holder keeps
// refreshing (the SDK corrects its own clock only from 5 minutes off).
async _lock(path) {
if (this.isImmutable() || this.#objectLockUnknown) {
return super._lock(path)
}
// `<path>.lock`, the name of the local lock directory: the listings skip it already
const params = this.#createParams(`${path}.lock`)
// the requests are sent with the S3 client directly, not through the handler's methods: those go through the
// handler's concurrency limit, and a refresh queued behind long uploads would let the lock go stale
const write = () => this.#s3.send(new PutObjectCommand({ ...params, Body: '' }))
// the output of a HEAD has no `Date`: it is read from the response
let date
const head = new HeadObjectCommand(params)
head.middlewareStack.add(
next => async args => {
const result = await next(args)
date = result.response.headers.date
return result
},
{ step: 'deserialize' }
)
let current
try {
current = await this.#s3.send(head)
} catch (error) {
if (error.name !== 'NotFound') {
throw error
}
}
// a provider which omits `Last-Modified` or `Date` never lets a lock be taken over: it stays held until released
const age = Date.parse(date) - current?.LastModified?.getTime()
if (current !== undefined && (Number.isNaN(age) || age <= STALE_AFTER)) {
throw lockedError(path)
}
await write()
let refreshing = Promise.resolve()
const interval = setInterval(() => {
refreshing = write().then(
() => {},
// a failed refresh is not a lost lock: the next one tries again
error => debug('lock could not be refreshed', { error, path })
)
}, REFRESH_INTERVAL)
interval.unref()
return async () => {
clearInterval(interval)
try {
// a refresh landing after the delete would write the lock again
await refreshing
await this.#s3.send(new DeleteObjectCommand(params))
} catch (error) {
warn('lock could not be released', { error, path })
}
}
}
}

View File

@@ -1,216 +0,0 @@
import { after, before, describe, it, beforeEach, afterEach, mock } from 'node:test'
import { strict as assert } from 'assert'
import 'dotenv/config'
import sinon from 'sinon'
import {
DeleteObjectCommand,
GetObjectLockConfigurationCommand,
HeadObjectCommand,
PutObjectCommand,
S3Client,
} from '@aws-sdk/client-s3'
import { getHandler } from '.'
import S3Handler, { REFRESH_INTERVAL, STALE_AFTER } from './s3.js'
// needs a real bucket without Object Lock: on an Object Lock bucket the lock is the no-op one, the second
// `lock()` succeeds, and this test fails
//
// xo_fs_s3='s3://<key>:<secret>@<host>/<bucket>/<dir>' yarn workspace @xen-orchestra/fs test
const url = process.env.xo_fs_s3
describe('S3Handler#lock()', { skip: url === undefined }, () => {
let handler
before(async () => {
handler = getHandler({ url }).addPrefix(`xo-fs-tests-${Date.now()}`)
await handler.sync()
})
after(async () => {
await handler?.forget()
})
it('refuses a held lock until it is released', async () => {
const lock = await handler.lock('vm')
try {
await assert.rejects(handler.lock('vm'), { code: 'ELOCKED' })
} finally {
await lock.dispose()
}
const again = await handler.lock('vm')
await again.dispose()
})
})
const createHandler = () => new S3Handler({ url: 's3://key:secret@localhost/bucket/dir' })
const s3Error = (name, httpStatusCode) => Object.assign(new Error(name), { name, $metadata: { httpStatusCode } })
// lets the async callback of a timer which just fired run to its end
const flush = () => new Promise(resolve => setImmediate(resolve))
const KEY = 'dir/vm.lock'
// `S3Handler#_lock()` against a stubbed `S3Client#send()`
describe('S3Handler#_lock() with a stubbed S3Client', () => {
// by key
let objects
// what the provider does wrong, which each test sets
let faults
// how far the provider's clock is ahead of XO's
let clockOffset
let send
const providerDate = () => new Date(Date.now() + clockOffset)
beforeEach(() => {
mock.timers.enable({ apis: ['setInterval', 'Date'] })
objects = new Map()
faults = {}
clockOffset = 0
send = sinon.stub(S3Client.prototype, 'send').callsFake(async command => {
const { Key } = command.input
const current = objects.get(Key)
if (command instanceof PutObjectCommand) {
if (faults.putStatus !== undefined) {
throw s3Error('InternalError', faults.putStatus)
}
// resolved by the test
if (faults.pendingPut !== undefined) {
await faults.pendingPut
}
objects.set(Key, { lastModified: providerDate() })
return {}
}
if (command instanceof HeadObjectCommand) {
if (current === undefined) {
throw s3Error('NotFound', 404)
}
// the lock reads the `Date` of the response in a middleware of the command, which this stub bypasses: run it
// on a response of its own
await command.middlewareStack.resolve(
async () => ({ response: { headers: { date: providerDate().toUTCString() } } }),
{}
)({ input: command.input })
return { LastModified: current.lastModified }
}
if (command instanceof DeleteObjectCommand) {
objects.delete(Key)
return {}
}
if (command instanceof GetObjectLockConfigurationCommand) {
if (faults.objectLock) {
return { ObjectLockConfiguration: { ObjectLockEnabled: 'Enabled' } }
}
throw s3Error('AccessDenied', 403)
}
throw new Error(`unexpected ${command.constructor.name}`)
})
})
afterEach(() => {
send.restore()
mock.timers.reset()
})
const writes = () => send.getCalls().filter(call => call.args[0] instanceof PutObjectCommand).length
for (const [what, objectLock] of [
['on an Object Lock bucket', true],
['when the S3 user cannot read the Object Lock configuration', false],
]) {
it(`takes no lock ${what}`, async () => {
faults.objectLock = objectLock
const handler = createHandler()
await handler._sync()
assert.equal(handler.isImmutable(), objectLock)
const release = await handler._lock('vm')
await release()
// the only request read the Object Lock configuration
assert.equal(send.callCount, 1)
})
}
it('takes <path>.lock in the directory of the remote, rewrites it every REFRESH_INTERVAL, and deletes it', async () => {
const release = await createHandler()._lock('vm')
assert.equal(objects.get(KEY).lastModified.getTime(), Date.now())
mock.timers.tick(REFRESH_INTERVAL)
await flush()
assert.equal(writes(), 2)
assert.equal(objects.get(KEY).lastModified.getTime(), Date.now())
await release()
assert.equal(objects.has(KEY), false)
})
it('refuses a held lock, and leaves it untouched', async () => {
const handler = createHandler()
const release = await handler._lock('vm')
try {
await assert.rejects(handler._lock('vm'), { code: 'ELOCKED' })
assert.equal(writes(), 1)
} finally {
await release()
}
})
it("takes over a stale lock, not a fresh one, on the provider's clock", async () => {
// XO's clock 2 minutes ahead: on it, the lock would look stale after 1 minute
clockOffset = -120e3
objects.set(KEY, { lastModified: providerDate() })
mock.timers.tick(STALE_AFTER)
await assert.rejects(createHandler()._lock('vm'), { code: 'ELOCKED' })
// the resolution of `Date`
mock.timers.tick(1e3)
const release = await createHandler()._lock('vm')
assert.equal(objects.get(KEY).lastModified.getTime(), providerDate().getTime())
await release()
})
it('keeps the lock when a refresh fails, and refreshes again', async () => {
const release = await createHandler()._lock('vm')
faults.putStatus = 500
mock.timers.tick(REFRESH_INTERVAL)
await flush()
assert.equal(objects.get(KEY).lastModified.getTime(), Date.now() - REFRESH_INTERVAL)
faults.putStatus = undefined
mock.timers.tick(REFRESH_INTERVAL)
await flush()
assert.equal(objects.get(KEY).lastModified.getTime(), Date.now())
await release()
assert.equal(objects.has(KEY), false)
})
it('waits for a refresh in flight before deleting the lock', async () => {
const release = await createHandler()._lock('vm')
let resolvePut
faults.pendingPut = new Promise(resolve => {
resolvePut = resolve
})
mock.timers.tick(REFRESH_INTERVAL)
const released = release()
await flush()
assert.equal(objects.has(KEY), true)
resolvePut()
await released
assert.equal(objects.has(KEY), false)
})
})

View File

@@ -2,13 +2,11 @@
## **next**
- [Web-Core/UiButtonIcon] Update icon buttons design, with a counter replacing the notification dot (PR [#10799](https://github.com/vatesfr/xen-orchestra/pull/10799))
- [Mobile/Side panels] Full-page menus on mobile with "Change state" in "More actions", side panel actions shown as buttons when there is room, and fixes for long names in headers and menu placement (PR [#10745](https://github.com/vatesfr/xen-orchestra/pull/10745))
- [Side panels] Side panels can be resized like the treeview, whose default width now adapts to the screen size (PR [#10725](https://github.com/vatesfr/xen-orchestra/pull/10725))
- [Side panels] Values stay next to their label when they fit and move below it otherwise, fields with several values (IP addresses, bond devices) get a copy button per value and a "Copy all" action, and rows, links and statuses are more evenly spaced and sized (PR [#10733](https://github.com/vatesfr/xen-orchestra/pull/10733))
- [Treeview] Fix translations of the tooltip for VM and host statuses in treeview (PR [#10643](https://github.com/vatesfr/xen-orchestra/pull/10643))
- [Web-Core/UiDropdownButton] Update dropdown buttons design (PR [#9850](https://github.com/vatesfr/xen-orchestra/pull/9850))
- [Tables] Tables are filtered as you type, half a second after the last keystroke, or right away with Enter; the "Search" button is removed (PR [#10797](https://github.com/vatesfr/xen-orchestra/pull/10797))
## **0.27.0** (2026-10-29)

View File

@@ -38,7 +38,7 @@
Ctx
</sup>
</th>
<td class="type">
<td>
<CodeHighlight :code="param.getTypeLabel()" />
</td>
<td class="reset-param">
@@ -161,10 +161,6 @@ function openRawValueModal(code: string) {
}
}
.type :deep(.code-highlight) {
white-space: pre-wrap;
}
.help {
font-style: italic;
color: var(--color-neutral-txt-secondary);

View File

@@ -7,7 +7,7 @@
</template>
</UiTitle>
<div class="container">
<UiQuerySearchBar v-bind="searchBindings" />
<UiQuerySearchBar @search="(value: string) => (searchQuery = value)" />
<VtsTable :state :pagination-bindings sticky="right">
<thead>
<tr>
@@ -35,12 +35,11 @@ import UiQuerySearchBar from '@core/components/ui/query-search-bar/UiQuerySearch
import UiTitle from '@core/components/ui/title/UiTitle.vue'
import { usePagination } from '@core/composables/pagination.composable.ts'
import { useRouteQuery } from '@core/composables/route-query.composable.ts'
import { useSearchFilter } from '@core/composables/search-filter.composable.ts'
import { useTableState } from '@core/composables/table-state.composable.ts'
import { icon } from '@core/icons'
import { usePifColumns } from '@core/tables/column-sets/pif-columns.ts'
import { logicNot } from '@vueuse/math'
import { computed } from 'vue'
import { computed, ref } from 'vue'
import { useI18n } from 'vue-i18n'
const { pifs } = defineProps<{
@@ -76,10 +75,21 @@ const getIpConfigurationMode = (ipMode: string) => {
}
}
const { items: filteredPifs, searchBindings } = useSearchFilter(
() => pifs,
pif => [...Object.values(pif), getNetworkName(pif.network)]
)
const searchQuery = ref('')
const filteredPifs = computed(() => {
const searchTerm = searchQuery.value.trim().toLocaleLowerCase()
if (!searchTerm) {
return pifs
}
return pifs.filter(pif =>
[...Object.values(pif), getNetworkName(pif.network)].some(value =>
String(value).toLocaleLowerCase().includes(searchTerm)
)
)
})
const state = useTableState({
busy: logicNot(isReady),

View File

@@ -7,7 +7,7 @@
</template>
</UiTitle>
<div class="container">
<UiQuerySearchBar v-bind="searchBindings" />
<UiQuerySearchBar @search="value => (searchQuery = value)" />
<VtsTable :state :pagination-bindings sticky="right">
<thead>
<tr>
@@ -38,10 +38,10 @@ import UiQuerySearchBar from '@core/components/ui/query-search-bar/UiQuerySearch
import UiTitle from '@core/components/ui/title/UiTitle.vue'
import { usePagination } from '@core/composables/pagination.composable.ts'
import { useRouteQuery } from '@core/composables/route-query.composable.ts'
import { useSearchFilter } from '@core/composables/search-filter.composable.ts'
import { useTableState } from '@core/composables/table-state.composable.ts'
import { useNetworkColumns } from '@core/tables/column-sets/network-columns.ts'
import { logicNot } from '@vueuse/math'
import { computed, ref } from 'vue'
import { useI18n } from 'vue-i18n'
const { networks } = defineProps<{
@@ -60,7 +60,19 @@ const selectedNetworkId = useRouteQuery('id')
const getLockingMode = (lockingMode: string) => (lockingMode === 'disabled' ? t('disabled') : t('unlocked'))
const { items: filteredNetworks, searchBindings } = useSearchFilter(() => networks)
const searchQuery = ref('')
const filteredNetworks = computed(() => {
const searchTerm = searchQuery.value.trim().toLocaleLowerCase()
if (!searchTerm) {
return networks
}
return networks.filter(network =>
Object.values(network).some(value => String(value).toLocaleLowerCase().includes(searchTerm))
)
})
const { pageRecords: paginatedNetworks, paginationBindings } = usePagination('internal-networks', filteredNetworks)

View File

@@ -7,7 +7,7 @@
</template>
</UiTitle>
<div class="container">
<UiQuerySearchBar v-bind="searchBindings" />
<UiQuerySearchBar @search="value => (searchQuery = value)" />
<VtsTable :state :pagination-bindings sticky="right">
<thead>
<tr>
@@ -38,10 +38,9 @@ import UiQuerySearchBar from '@core/components/ui/query-search-bar/UiQuerySearch
import UiTitle from '@core/components/ui/title/UiTitle.vue'
import { usePagination } from '@core/composables/pagination.composable.ts'
import { useRouteQuery } from '@core/composables/route-query.composable.ts'
import { useSearchFilter } from '@core/composables/search-filter.composable.ts'
import { useTableState } from '@core/composables/table-state.composable.ts'
import { useNetworkColumns } from '@core/tables/column-sets/network-columns.ts'
import { computed } from 'vue'
import { computed, ref } from 'vue'
import { useI18n } from 'vue-i18n'
const { networks, busy, error } = defineProps<{
@@ -71,7 +70,19 @@ const getNetworkVlan = (network: XenApiNetwork) => {
const getLockingMode = (lockingMode: string) => (lockingMode === 'disabled' ? t('disabled') : t('unlocked'))
const { items: filteredNetworks, searchBindings } = useSearchFilter(() => networks)
const searchQuery = ref('')
const filteredNetworks = computed(() => {
const searchTerm = searchQuery.value.trim().toLocaleLowerCase()
if (!searchTerm) {
return networks
}
return networks.filter(network =>
Object.values(network).some(value => String(value).toLocaleLowerCase().includes(searchTerm))
)
})
const { pageRecords: paginatedNetworks, paginationBindings } = usePagination('networks', filteredNetworks)

View File

@@ -3,7 +3,7 @@
<UiTitle>
{{ t('hosts') }}
</UiTitle>
<UiQuerySearchBar v-bind="searchBindings" />
<UiQuerySearchBar @search="(value: string) => (searchQuery = value)" />
<div class="container">
<VtsTable :pagination-bindings :state sticky="right">
<thead>
@@ -34,12 +34,11 @@ import UiQuerySearchBar from '@core/components/ui/query-search-bar/UiQuerySearch
import UiTitle from '@core/components/ui/title/UiTitle.vue'
import { usePagination } from '@core/composables/pagination.composable.ts'
import { useRouteQuery } from '@core/composables/route-query.composable.ts'
import { useSearchFilter } from '@core/composables/search-filter.composable.ts'
import { useTableState } from '@core/composables/table-state.composable.ts'
import { icon } from '@core/icons'
import { useHostColumns } from '@core/tables/column-sets/host-columns.ts'
import { logicAnd, logicNot, logicOr } from '@vueuse/math'
import { computed } from 'vue'
import { computed, ref } from 'vue'
import { useI18n } from 'vue-i18n'
const {
@@ -64,7 +63,19 @@ const hasError = logicOr(() => error, hasPifError)
const selectedHostId = useRouteQuery('id')
const { items: filteredHosts, searchBindings } = useSearchFilter(() => rawHosts)
const searchQuery = ref('')
const filteredHosts = computed(() => {
const searchTerm = searchQuery.value.trim().toLocaleLowerCase()
if (!searchTerm) {
return rawHosts
}
return rawHosts.filter(host =>
Object.values(host).some(value => String(value).toLocaleLowerCase().includes(searchTerm))
)
})
const state = useTableState({
busy: logicNot(isReady),

View File

@@ -3,7 +3,7 @@
<UiTitle>
{{ t('storage-repositories') }}
</UiTitle>
<UiQuerySearchBar v-bind="searchBindings" />
<UiQuerySearchBar @search="value => (searchQuery = value)" />
<div class="container">
<VtsTable :state :pagination-bindings sticky="right">
<thead>
@@ -33,13 +33,12 @@ import UiQuerySearchBar from '@core/components/ui/query-search-bar/UiQuerySearch
import UiTitle from '@core/components/ui/title/UiTitle.vue'
import { usePagination } from '@core/composables/pagination.composable.ts'
import { useRouteQuery } from '@core/composables/route-query.composable.ts'
import { useSearchFilter } from '@core/composables/search-filter.composable.ts'
import { useTableState } from '@core/composables/table-state.composable.ts'
import { icon } from '@core/icons'
import { useSrColumns } from '@core/tables/column-sets/sr-columns.ts'
import { type SrScope } from '@core/types/storage-repository.type.ts'
import { shouldShowTargetCount } from '@core/utils/sr.utils.ts'
import { computed } from 'vue'
import { computed, ref } from 'vue'
import { useI18n } from 'vue-i18n'
const {
@@ -62,7 +61,17 @@ const { isReady, hasError, isDefaultSr } = useSrStore().subscribe()
const selectedSrId = useRouteQuery('id')
const { items: filteredSrs, searchBindings } = useSearchFilter(() => rawSrs)
const searchQuery = ref('')
const filteredSrs = computed(() => {
const searchTerm = searchQuery.value.trim().toLocaleLowerCase()
if (!searchTerm) {
return rawSrs
}
return rawSrs.filter(sr => Object.values(sr).some(value => String(value).toLocaleLowerCase().includes(searchTerm)))
})
const state = useTableState({
busy: () => busy ?? !isReady.value,

View File

@@ -3,7 +3,7 @@
<UiTitle>
{{ t('vdis') }}
</UiTitle>
<UiQuerySearchBar v-bind="searchBindings" />
<UiQuerySearchBar @search="(value: string) => (searchQuery = value)" />
<div class="container">
<VtsTable :state :pagination-bindings sticky="right">
<thead>
@@ -30,11 +30,10 @@ import UiQuerySearchBar from '@core/components/ui/query-search-bar/UiQuerySearch
import UiTitle from '@core/components/ui/title/UiTitle.vue'
import { usePagination } from '@core/composables/pagination.composable.ts'
import { useRouteQuery } from '@core/composables/route-query.composable.ts'
import { useSearchFilter } from '@core/composables/search-filter.composable.ts'
import { useTableState } from '@core/composables/table-state.composable.ts'
import { useVdiColumns } from '@core/tables/column-sets/vdi-columns.ts'
import { formatSizeRaw } from '@core/utils/size.util.ts'
import { computed } from 'vue'
import { computed, ref } from 'vue'
import { useI18n } from 'vue-i18n'
const { vdis, vbds, busy, error } = defineProps<{
vdis: XenApiVdi[]
@@ -44,7 +43,14 @@ const { vdis, vbds, busy, error } = defineProps<{
}>()
const { t } = useI18n()
const selectedVdiId = useRouteQuery('id')
const { items: filteredVdis, searchBindings } = useSearchFilter(() => vdis)
const searchQuery = ref('')
const filteredVdis = computed(() => {
const searchTerm = searchQuery.value.trim().toLocaleLowerCase()
if (!searchTerm) {
return vdis
}
return vdis.filter(vdi => Object.values(vdi).some(value => String(value).toLocaleLowerCase().includes(searchTerm)))
})
const state = useTableState({
busy: () => busy,
error: () => error,

View File

@@ -6,7 +6,7 @@
<slot name="title-actions" />
</template>
</UiTitle>
<UiQuerySearchBar v-bind="searchBindings" />
<UiQuerySearchBar @search="(value: string) => (searchQuery = value)" />
<VtsTable :state :pagination-bindings sticky="right">
<thead>
<tr>
@@ -35,7 +35,6 @@ import UiQuerySearchBar from '@core/components/ui/query-search-bar/UiQuerySearch
import UiTitle from '@core/components/ui/title/UiTitle.vue'
import { usePagination } from '@core/composables/pagination.composable.ts'
import { useRouteQuery } from '@core/composables/route-query.composable.ts'
import { useSearchFilter } from '@core/composables/search-filter.composable.ts'
import { useTableState } from '@core/composables/table-state.composable.ts'
import { useMapper } from '@core/packages/mapper'
import { type ActionItem } from '@core/tables/column-definitions/action-column.ts'
@@ -43,7 +42,7 @@ import { useVifColumns } from '@core/tables/column-sets/vif-columns.ts'
import { CONNECTION_ACTION } from '@core/types/connection.ts'
import { getUniqueIpAddressesForDevice } from '@core/utils/ip-address.utils.ts'
import { logicNot } from '@vueuse/math'
import { computed } from 'vue'
import { computed, ref } from 'vue'
import { useI18n } from 'vue-i18n'
const { vifs, vm } = defineProps<{
@@ -73,10 +72,21 @@ const getIpAddresses = (vif: XenApiVif) => {
return getUniqueIpAddressesForDevice(networks, vif.device)
}
const { items: filteredVifs, searchBindings } = useSearchFilter(
() => vifs,
vif => [...Object.values(vif), getNetworkName(vif.network)]
)
const searchQuery = ref('')
const filteredVifs = computed(() => {
const searchTerm = searchQuery.value.trim().toLocaleLowerCase()
if (!searchTerm) {
return vifs
}
return vifs.filter(vif =>
[...Object.values(vif), getNetworkName(vif.network)].some(value =>
String(value).toLocaleLowerCase().includes(searchTerm)
)
)
})
const state = useTableState({
busy: logicNot(isReady),

View File

@@ -70,7 +70,7 @@ const selectedNetwork = useRouteQuery<XenApiNetwork | undefined>('id', {
}
.new-network-link {
flex-grow: 1;
padding-block: 1.2rem;
height: 100%;
width: 100%;
}
</style>

View File

@@ -1,11 +1,7 @@
<template>
<ComponentStory
v-slot="{ properties }"
:params="[
prop('label').str().widget().preset('Tabs'),
prop('disabled').bool().widget(),
slot().help('Contains <RouterTab> or <UiTabItem>'),
]"
:params="[prop('disabled').bool().widget(), slot().help('Contains <RouterTab> or <UiTabItem>')]"
>
<TabList v-bind="properties">
<UiTabItem>Foo</UiTabItem>

View File

@@ -7,10 +7,7 @@
prop('size').required().enum('small', 'medium', 'large').preset('medium').widget(),
prop('disabled').bool().widget(),
prop('selected').bool().widget(),
prop('counter')
.type('CounterValue | { value: CounterValue; accent: CounterAccent }')
.widget(object())
.help('Info accent by default'),
prop('dot').bool().widget(),
prop('targetScale')
.type('number | { x: number; y: number }')
.default(1)
@@ -18,32 +15,6 @@
.help('Meant to increase click target size if needed')
.widget(),
]"
:presets="{
'No counter': {
props: {
icon: 'fa:bars-progress',
counter: undefined,
},
},
'Number counter': {
props: {
icon: 'fa:bars-progress',
counter: 6,
},
},
'Percentage (warning)': {
props: {
icon: 'fa:bars-progress',
counter: { value: '42%', accent: 'warning' },
},
},
'Exclamation mark (danger)': {
props: {
icon: 'fa:bars-progress',
counter: { value: '!', accent: 'danger' },
},
},
}"
>
<UiButtonIcon v-bind="properties" />
</ComponentStory>
@@ -52,6 +23,5 @@
<script lang="ts" setup>
import ComponentStory from '@/components/component-story/ComponentStory.vue'
import { iconProp, prop } from '@/libs/story/story-param.ts'
import { object } from '@/libs/story/story-widget.ts'
import UiButtonIcon from '@core/components/ui/button-icon/UiButtonIcon.vue'
</script>

View File

@@ -13,7 +13,6 @@
choice({ label: 'Search', value: 'fa:magnifying-glass' }, { label: 'AngleDown', value: 'fa:angle-down' })
),
prop('clearable').bool().widget(),
prop('busy').bool().widget(),
prop('prefix').str().widget(),
prop('suffix').str().widget(),
prop('disabled').bool().widget(),

View File

@@ -1,9 +1,6 @@
<template>
<ComponentStory
v-slot="{ properties }"
:params="[model().type('string').required(), prop('busy').bool().widget(), event('search')]"
>
<UiQuerySearchBar id="search-bar" v-bind="properties" v-model="filter" :busy="properties.busy || isSearching" />
<ComponentStory v-slot="{ properties }" :params="[event('search').args({ value: 'string' })]">
<UiQuerySearchBar id="search-bar" v-bind="properties" @search="(value: string) => (filter = value)" />
<p class="text">Example data:</p>
<ul class="data-list">
@@ -14,7 +11,7 @@
<script lang="ts" setup>
import ComponentStory from '@/components/component-story/ComponentStory.vue'
import { event, model, prop } from '@/libs/story/story-param.ts'
import { event } from '@/libs/story/story-param.ts'
import UiQuerySearchBar from '@core/components/ui/query-search-bar/UiQuerySearchBar.vue'
import { useTreeFilter } from '@core/composables/tree-filter.composable.ts'
import { defineTree } from '@core/packages/tree/define-tree.ts'
@@ -123,7 +120,7 @@ const data = [
},
]
const { filter, predicate, isSearching } = useTreeFilter()
const { filter, predicate } = useTreeFilter()
const definitions = defineTree('vms', data, {
getLabel: 'name_label',

View File

@@ -423,19 +423,6 @@ export default class Backups {
},
},
],
purgeVmBackupsJournal: [
// `before` is computed by the caller: the horizon is the one of XO, whatever the clock of this proxy
({ remote, before }) =>
Disposable.use(this.getAdapter(remote), adapter => adapter.purgeBackupJournal(before)),
{
description: 'remove the days of the backup journal of a remote before the one of a date',
params: {
remote: { type: 'object' },
// timestamp in ms
before: { type: 'number' },
},
},
],
restoreMetadataBackup: [
({ backupId, remote, xapi: xapiOptions }) =>
Disposable.use(app.remotes.getHandler(remote), xapiOptions && this.getXapi(xapiOptions), (handler, xapi) =>

View File

@@ -53,16 +53,6 @@ The following are required only for mirror backup tests (`qa:mirror`):
| `MIRROR_DESTINATION_REPOSITORY_NAME` | Mirror destination repository name | `Test mirror QA` |
| `MIRROR_DESTINATION_REPOSITORY_URL` | `@xen-orchestra/fs` URL for the mirror destination. Same backend flexibility as `BACKUP_REPOSITORY_URL`. | `file:///tmp/xo-test-mirror` |
The following are optional, for the VM folder lock tests (`qa:backup:lock`), which skip a backend whose URL is unset.
The machine running the suite must reach these repositories as XO does.
| Variable | Description | Example |
| ------------------------------ | --------------------------------------------- | --------------------------------------------------------------------------------- |
| `S3_BACKUP_REPOSITORY_NAME` | S3 backup repository name in XO | `Test backup QA S3` |
| `S3_BACKUP_REPOSITORY_URL` | `@xen-orchestra/fs` URL of an S3 bucket | `s3://<access key>:<secret key>@<host>/<bucket>/<directory>` |
| `AZURE_BACKUP_REPOSITORY_NAME` | Azure backup repository name in XO | `Test backup QA Azure` |
| `AZURE_BACKUP_REPOSITORY_URL` | `@xen-orchestra/fs` URL of an Azure container | `azure://<account>:<key>@<account>.blob.core.windows.net/<container>/<directory>` |
The following are optional, for load tests (disk churn via SSH). Leave `TEST_VM_SSH_KEY` unset
to let `ssh` fall back to its own default identity files / `ssh-agent`:
@@ -96,7 +86,6 @@ Log namespaces follow the pattern `qa:<suite>[:<variant>]`:
| `qa:backup:base` | `tests/backup.test.js` |
| `qa:backup:nbd` | `tests/backup.nbd.test.js` |
| `qa:backup:combined` | `tests/backup-replication-combined.test.js` |
| `qa:backup:lock` | `tests/backup.lock.test.js` |
| `qa:mirror` | `tests/backup-mirror.test.js` |
| `qa:export` | `tests/export.vhd.test.js` |
| `qa:load:backup:delta` | `scripts/backup-load-delta.mjs` |
@@ -117,15 +106,9 @@ yarn workspace @xen-orchestra/qa-test qa:vm # VM lifecycle (clone
yarn workspace @xen-orchestra/qa-test qa:backup # Full and delta backup
yarn workspace @xen-orchestra/qa-test qa:backup:nbd # Backup with NBD protocol
yarn workspace @xen-orchestra/qa-test qa:backup:combined # Advanced scenarios (replication + backup)
yarn workspace @xen-orchestra/qa-test qa:backup:lock # VM backup folder lock (S3 and Azure only)
yarn workspace @xen-orchestra/qa-test qa:export # VHD/XVA export and restoration
```
`qa:backup:lock` locks the backup folder of its test VM itself, from the machine running the suite, and checks that
a backup of the VM fails while the folder is locked, and that XO releases its own lock at the end of a backup. It runs
once per repository set in `S3_BACKUP_REPOSITORY_URL` and `AZURE_BACKUP_REPOSITORY_URL` (see above), and skips on an
S3 bucket which XO does not lock (Object Lock).
### Test subsets
```bash

View File

@@ -31,19 +31,6 @@ BACKUP_REPOSITORY_URL="file:///tmp/xo-test-backups"
MIRROR_DESTINATION_REPOSITORY_NAME=Test mirror QA
MIRROR_DESTINATION_REPOSITORY_URL="file:///tmp/xo-test-mirror"
# ===========================================
# S3 AND AZURE BACKUP REPOSITORY CONFIGURATION
# ===========================================
# Optional repositories for the VM folder lock tests (qa:backup:lock), which skip
# a backend whose URL is unset. The suite locks a VM's backup folder itself, so
# the machine running it must reach these repositories as XO does.
# use " around the url to handle # escaping
S3_BACKUP_REPOSITORY_NAME=Test backup QA S3
S3_BACKUP_REPOSITORY_URL= # e.g. "s3://<access key>:<secret key>@<host>/<bucket>/<directory>"
AZURE_BACKUP_REPOSITORY_NAME=Test backup QA Azure
AZURE_BACKUP_REPOSITORY_URL= # e.g. "azure://<account>:<key>@<account>.blob.core.windows.net/<container>/<directory>"
# ===========================================
# REPLICATION TEST CONFIGURATION
# ===========================================

View File

@@ -61,16 +61,6 @@ The following are required only for mirror backup tests (`qa:mirror`):
| `MIRROR_DESTINATION_REPOSITORY_NAME` | Mirror destination repository name | `Test mirror QA` |
| `MIRROR_DESTINATION_REPOSITORY_URL` | `@xen-orchestra/fs` URL for the mirror destination. Same backend flexibility as `BACKUP_REPOSITORY_URL`. | `file:///tmp/xo-test-mirror` |
The following are optional, for the VM folder lock tests (`qa:backup:lock`), which skip a backend whose URL is unset.
The machine running the suite must reach these repositories as XO does.
| Variable | Description | Example |
| ------------------------------ | --------------------------------------------- | --------------------------------------------------------------------------------- |
| `S3_BACKUP_REPOSITORY_NAME` | S3 backup repository name in XO | `Test backup QA S3` |
| `S3_BACKUP_REPOSITORY_URL` | `@xen-orchestra/fs` URL of an S3 bucket | `s3://<access key>:<secret key>@<host>/<bucket>/<directory>` |
| `AZURE_BACKUP_REPOSITORY_NAME` | Azure backup repository name in XO | `Test backup QA Azure` |
| `AZURE_BACKUP_REPOSITORY_URL` | `@xen-orchestra/fs` URL of an Azure container | `azure://<account>:<key>@<account>.blob.core.windows.net/<container>/<directory>` |
The following are optional, for load tests (disk churn via SSH). Leave `TEST_VM_SSH_KEY` unset
to let `ssh` fall back to its own default identity files / `ssh-agent`:
@@ -104,7 +94,6 @@ Log namespaces follow the pattern `qa:<suite>[:<variant>]`:
| `qa:backup:base` | `tests/backup.test.js` |
| `qa:backup:nbd` | `tests/backup.nbd.test.js` |
| `qa:backup:combined` | `tests/backup-replication-combined.test.js` |
| `qa:backup:lock` | `tests/backup.lock.test.js` |
| `qa:mirror` | `tests/backup-mirror.test.js` |
| `qa:export` | `tests/export.vhd.test.js` |
| `qa:load:backup:delta` | `scripts/backup-load-delta.mjs` |
@@ -125,15 +114,9 @@ yarn workspace @xen-orchestra/qa-test qa:vm # VM lifecycle (clone
yarn workspace @xen-orchestra/qa-test qa:backup # Full and delta backup
yarn workspace @xen-orchestra/qa-test qa:backup:nbd # Backup with NBD protocol
yarn workspace @xen-orchestra/qa-test qa:backup:combined # Advanced scenarios (replication + backup)
yarn workspace @xen-orchestra/qa-test qa:backup:lock # VM backup folder lock (S3 and Azure only)
yarn workspace @xen-orchestra/qa-test qa:export # VHD/XVA export and restoration
```
`qa:backup:lock` locks the backup folder of its test VM itself, from the machine running the suite, and checks that
a backup of the VM fails while the folder is locked, and that XO releases its own lock at the end of a backup. It runs
once per repository set in `S3_BACKUP_REPOSITORY_URL` and `AZURE_BACKUP_REPOSITORY_URL` (see above), and skips on an
S3 bucket which XO does not lock (Object Lock).
### Test subsets
```bash

View File

@@ -39,7 +39,6 @@
"qa:backup:combined": "node --env-file-if-exists=.env --test tests/backup-replication-combined.test.js",
"qa:backup:combined:cycle": "node --env-file-if-exists=.env --test tests/backup-replication-combined.test.js --test-name-pattern='Full Cycle'",
"qa:backup:sync": "node --env-file-if-exists=.env --test tests/backup.synchronized.test.js --test-concurrency=1",
"qa:backup:lock": "node --env-file-if-exists=.env --test tests/backup.lock.test.js",
"qa:mirror:cr": "node --env-file-if-exists=.env --test tests/backup-replication-combined.test.js --test-name-pattern='CR Mode'",
"qa:mirror": "node --env-file-if-exists=.env --test tests/backup-mirror.test.js",
"qa:replication": "node --env-file-if-exists=.env --test --test-concurrency=1 tests/replication.test.js",

View File

@@ -1,145 +0,0 @@
import assert from 'node:assert'
import { after, before, describe, it } from 'node:test'
import { createLogger } from '@xen-orchestra/log'
import { getSyncedHandler } from '@xen-orchestra/fs'
import { getVmBackupDir } from '@xen-orchestra/backups/_getVmBackupDir.mjs'
import { backupConfig } from '../backup.config.js'
import {
findTaskByMessage,
generateBackupJobName,
getDefaultSchedule,
getRequiredEnv,
getScheduleKey,
} from '../utils/index.js'
import { assertBackupSuccess, extractBackupErrors, resolveOrCreateBackupRepository } from '../utils/backupUtils.js'
import { setup, teardown } from './setup.js'
const log = createLogger('qa:backup:lock')
// The suite locks the backup folder of a VM itself, from the machine it runs on, and checks that XO honours that
// lock: it needs a repository which this machine reaches as XO reaches it, hence S3 or Azure. A local, NFS or SMB
// repository is a directory of XO's host.
const BACKENDS = [
{ label: 'S3', envPrefix: 'S3' },
{ label: 'Azure', envPrefix: 'AZURE' },
]
const isConfigured = ({ envPrefix }) => Boolean(process.env[`${envPrefix}_BACKUP_REPOSITORY_URL`])
describe(
'Backup VM folder lock',
{ skip: !BACKENDS.some(isConfigured) && 'neither S3_BACKUP_REPOSITORY_URL nor AZURE_BACKUP_REPOSITORY_URL is set' },
() => {
let dispatchClient
let tracker
let vm
before(async () => {
let vms
;({ dispatchClient, tracker, vms } = await setup())
vm = vms[0]
})
for (const backend of BACKENDS) {
const { label, envPrefix } = backend
describe(label, { skip: !isConfigured(backend) && `${envPrefix}_BACKUP_REPOSITORY_URL is not set` }, () => {
let jobId
let scheduleId
let handler
let disposeHandler
let skipReason
before(async () => {
const url = getRequiredEnv(`${envPrefix}_BACKUP_REPOSITORY_URL`)
// not tracked for cleanup: the tracker holds a single repository, the one setup() may have created, and
// the next run reuses this one
const backupRepository = await resolveOrCreateBackupRepository(dispatchClient, undefined, {
name: getRequiredEnv(`${envPrefix}_BACKUP_REPOSITORY_NAME`),
url,
})
const config = backupConfig(generateBackupJobName(), getDefaultSchedule(), vm, backupRepository)
jobId = await dispatchClient.backup.createBackupJob(config)
tracker.trackResource('backupJob', jobId, { name: config.name, mode: config.mode })
scheduleId = getScheduleKey(await dispatchClient.backup.details(jobId))
tracker.trackResource('schedule', scheduleId, { name: config.name, backupJobId: jobId })
const { value, dispose } = await getSyncedHandler({ url })
handler = value
disposeHandler = dispose
// A second lock of the same folder must be refused. On S3, nothing is locked when the bucket has Object
// Lock: XO does not lock either, and there is nothing to test.
const dir = getVmBackupDir(vm.uuid)
const lock = await handler.lock(dir)
try {
const secondLock = await handler.lock(dir)
await secondLock.dispose()
skipReason =
'the repository is not locked: its S3 bucket has Object Lock, or its Object Lock configuration ' +
'cannot be read (see the xo:fs:s3 warnings in the debug log)'
log.warn('VM folder lock pre-check failed', { backend: label, skipReason })
} catch (error) {
if (error.code !== 'ELOCKED') {
throw error
}
} finally {
await lock.dispose()
}
})
it('fails the backup of a VM whose folder is locked', async t => {
if (skipReason !== undefined) {
return t.skip(skipReason)
}
const lock = await handler.lock(getVmBackupDir(vm.uuid))
let result
try {
result = await dispatchClient.backup.runJobAndGetLog(jobId, scheduleId)
} finally {
await lock.dispose()
}
// the folder is locked before the snapshot is taken: the task of the VM fails at once
const vmTask = findTaskByMessage(result, 'backup VM')
assert.strictEqual(
vmTask?.status,
'failure',
'the backup should fail while the folder of the VM is locked: XO did not lock it (see the xo:fs warnings in its log)'
)
assert.strictEqual(
vmTask.result?.code,
'ELOCKED',
`the backup should fail on the lock, failed with: ${extractBackupErrors(result).join(' | ')}`
)
})
it('releases the lock at the end of the backup', async t => {
if (skipReason !== undefined) {
return t.skip(skipReason)
}
const result = await dispatchClient.backup.runJobAndGetLog(jobId, scheduleId)
assertBackupSuccess(result, `Backup to ${label} of a VM whose folder is not locked`)
// a lock left behind would fail the next backups of the VM until it goes stale: 3 minutes on S3, the 60
// seconds of its lease on Azure
const lock = await handler.lock(getVmBackupDir(vm.uuid))
await lock.dispose()
})
after(async () => {
await disposeHandler?.()
})
})
}
after(async () => {
await teardown(dispatchClient, tracker)
})
}
)

View File

@@ -29,6 +29,7 @@
"@types/express": "^5.0.0",
"@types/swagger-ui-express": "^4.1.7",
"@xen-orchestra/disk-transform": "^1.3.4",
"compression": "^1.7.3",
"openapi-types": "^12.1.3",
"rimraf": "^6.0.1",
"typescript": "~5.6.3",

View File

@@ -0,0 +1,403 @@
import {
Delete,
Example,
Extension,
Get,
Middlewares,
Path,
Post,
Query,
Request,
Response,
Route,
Security,
SuccessResponse,
Tags,
} from 'tsoa'
import type { Request as ExRequest } from 'express'
import { inject } from 'inversify'
import { provide } from 'inversify-binding-decorators'
import type { XoDockerContainer, XoDockerContainerAction, XoDockerContainerStats, XoDockerLogs } from '@vates/types'
import { DockerContainerService } from './docker-container.service.mjs'
import {
asynchronousActionResp,
badGatewayResp,
badRequestResp,
featureUnauthorized,
gatewayTimeoutResp,
incorrectStateResp,
invalidParameters,
noContentResp,
notFoundResp,
serviceUnavailableResp,
unauthorizedResp,
type Unbrand,
} from '../open-api/common/response.common.mjs'
import {
dockerContainer,
dockerContainerIds,
dockerContainerLogs,
dockerContainerStats,
partialDockerContainers,
} from '../open-api/oa-examples/docker-container.oa-example.mjs'
import { taskLocation } from '../open-api/oa-examples/task.oa-example.mjs'
import type { SendObjects } from '../helpers/helper.type.mjs'
import { withDockerErrors } from '../helpers/docker.helper.mjs'
import { dockerFeatureMiddleware } from '../middlewares/docker-feature.middleware.mjs'
import { XoController } from '../abstract-classes/xo-controller.mjs'
import type { CreateActionReturnType } from '../abstract-classes/base-controller.mjs'
import { RestApi } from '../rest-api/rest-api.mjs'
/**
* Header of the scoped listing which reports the engines which failed (JSON
* array of `{ engine, code }`), only present when there are some
*/
const DOCKER_ERRORS_HEADER = 'x-docker-errors'
// v1: no `acl` middleware, so every route is admin-only (see the README's
// ACLs section). The `// ACLs v2:` comments give the middleware to add with the
// `docker-container` ACL resource.
@Route('docker-containers')
@Security('*')
@Middlewares(dockerFeatureMiddleware)
@Response(badRequestResp.status, badRequestResp.description)
@Response(unauthorizedResp.status, unauthorizedResp.description)
@Response(featureUnauthorized.status, featureUnauthorized.description)
@Response(serviceUnavailableResp.status, 'Too many busy SSH connections, see the Retry-After header')
@Tags('docker-containers')
@provide(DockerContainerController)
export class DockerContainerController extends XoController<XoDockerContainer> {
#dockerContainerService: DockerContainerService
constructor(
@inject(RestApi) restApi: RestApi,
@inject(DockerContainerService) dockerContainerService: DockerContainerService
) {
super('docker-container', restApi)
this.#dockerContainerService = dockerContainerService
}
// --- abstract methods
// there is no unscoped listing: requires a filter designating the engines
async getAllCollectionObjects({ filter }: { filter?: string }): Promise<XoDockerContainer[]> {
return (await this.#dockerContainerService.list({ filter })).containers
}
getCollectionObject(id: XoDockerContainer['id']): Promise<XoDockerContainer> {
return this.restApi.xoApp.getDockerContainer(id)
}
/**
* Last lines of the logs of a container, bounded: at most `tail` lines
* (default 100, max `docker.maxLogsTail`), and cut at `docker.maxLogsSize`
* (`truncated: true`).
*
* Logs routinely contain secrets.
*
* Required privilege:
* - admin (v2: resource: docker-container, action: read-logs)
*
* @example id "8d834412-eb40-4328-a815-3fcc0989bd07_1b5d79f4a1c9275c5f9e1fc50629ea85ca807fe1c70f03e528e35f4b6ce1963e"
* @example tail 100
* @example since "2026-09-24T12:00:00Z"
* @example until "1790265600000"
* @example stdout true
* @example stderr true
* @example timestamps true
*/
// ACLs v2: acl({ resource: 'docker-container', action: 'read-logs', objectId: 'params.id', getObject: ({ restApi }) => restApi.xoApp.getDockerContainer })
@Example(dockerContainerLogs)
@Extension('x-mcp-exposure', 'deny')
@Get('{id}/logs')
@Response(notFoundResp.status, notFoundResp.description)
@Response(invalidParameters.status, invalidParameters.description)
@Response(badGatewayResp.status, 'SSH or Docker failure (see data.code)')
@Response(gatewayTimeoutResp.status, gatewayTimeoutResp.description)
async getDockerContainerLogs(
@Path() id: string,
/** number of lines from the end */
@Query() tail?: number,
/** ms since the epoch or a date string */
@Query() since?: string,
/** ms since the epoch or a date string */
@Query() until?: string,
@Query() stdout?: boolean,
@Query() stderr?: boolean,
@Query() timestamps?: boolean
): Promise<XoDockerLogs> {
return this.#dockerContainerService.getLogs(id as XoDockerContainer['id'], {
tail,
since,
until,
stdout,
stderr,
timestamps,
})
}
/**
* CPU, memory, network, block I/O and PIDs of a container, like `docker
* stats`: `cpuPercent` is 100 for one full CPU (up to `100 * onlineCpus`),
* `memoryUsage` excludes the reclaimable page cache.
*
* The latest sample of the engine's stats sampler when it streams this
* container (see `stats=true` on the listing), else one call to dockerd
* (~1-2 s). Does not start the sampler.
*
* Required privilege:
* - admin (v2: resource: docker-container, action: read)
*
* @example id "8d834412-eb40-4328-a815-3fcc0989bd07_1b5d79f4a1c9275c5f9e1fc50629ea85ca807fe1c70f03e528e35f4b6ce1963e"
*/
// ACLs v2: acl({ resource: 'docker-container', action: 'read', objectId: 'params.id', getObject: ({ restApi }) => restApi.xoApp.getDockerContainer })
@Example(dockerContainerStats)
@Extension('x-mcp-exposure', 'allow')
@Get('{id}/stats')
@Response(notFoundResp.status, notFoundResp.description)
@Response(badGatewayResp.status, 'SSH or Docker failure (see data.code)')
@Response(gatewayTimeoutResp.status, gatewayTimeoutResp.description)
async getDockerContainerStats(@Path() id: string): Promise<XoDockerContainerStats> {
const containerId = id as XoDockerContainer['id']
// 404 without connecting on a malformed id or an unknown engine
await this.#dockerContainerService.assertContainerId(containerId)
return this.restApi.xoApp.getDockerContainerStats(containerId)
}
/**
* The container, inspected (served from the listing cache when possible).
*
* Required privilege:
* - admin (v2: resource: docker-container, action: read)
*
* @example id "8d834412-eb40-4328-a815-3fcc0989bd07_1b5d79f4a1c9275c5f9e1fc50629ea85ca807fe1c70f03e528e35f4b6ce1963e"
*/
// ACLs v2: acl({ resource: 'docker-container', action: 'read', objectId: 'params.id', getObject: ({ restApi }) => restApi.xoApp.getDockerContainer })
@Example(dockerContainer)
@Extension('x-mcp-exposure', 'allow')
@Get('{id}')
@Response(notFoundResp.status, notFoundResp.description)
@Response(badGatewayResp.status, 'SSH or Docker failure (see data.code)')
@Response(gatewayTimeoutResp.status, gatewayTimeoutResp.description)
async getDockerContainer(@Path() id: string): Promise<Unbrand<XoDockerContainer>> {
return this.getObject(id as XoDockerContainer['id'])
}
/**
* Containers of the Docker engines designated by `filter`: it must contain
* a term with a value on `$engine`, `$VM` or `$pool` (e.g. `$VM:<uuid>`,
* `$engine:|(<id1> <id2>)`, matched like the rest of the filter, so a
* partial id works: `$VM:c7b3b4bc`) resolving to at most
* `docker.maxListedEngines` engines (default 10), else 422. The whole
* filter is then applied to the containers.
*
* Connects to the engines (results cached `docker.cacheExpiresIn`,
* `force_refresh=true` bypasses the cache). The response is a plain array,
* like every collection (`fields`, `limit`, `ndjson` and `markdown` behave
* as usual). An engine which fails does not fail the request: its
* containers are missing, and it is reported in the `x-docker-errors`
* response header, a JSON array of `{ engine, code }` (e.g.
* `[{"engine":"39a3cb1f-…","code":"SSH_AUTH_FAILED"}]`), only present when
* some engines failed. The details are in `GET /docker-engines/{id}/info`
* and in the engine's `connectionStatus` and `error`.
*
* `stats=true` starts the engine's stats sampler (one Docker stats stream
* per running container, at most `docker.maxStatsContainers`, stopped after
* `docker.statsIdleTimeout` without reader) and merges its latest samples
* into the running and paused containers (`stats`, see
* `GET /docker-containers/{id}/stats`). It never waits for a sample: the
* containers whose samples are not there yet have `statsPending: true`
* (the CPU usage needs two samples, one second apart).
*
* Required privilege:
* - admin (v2: resource: docker-container, action: read, per container)
*
* @example fields "id,name,state,status,image"
* @example filter "$engine:8d834412-eb40-4328-a815-3fcc0989bd07 state:running"
* @example limit 42
* @example all true
* @example stats true
* @example force_refresh false
*/
// ACLs v2: @Security('*', ['acl']) + sendObjects(…, { privilege: { action: 'read', resource: 'docker-container' } })
@Example(dockerContainerIds)
@Example(partialDockerContainers)
@Extension('x-mcp-exposure', 'allow')
@Get('')
@Response(invalidParameters.status, 'The filter does not designate engines, or too many')
async getDockerContainers(
@Request() req: ExRequest,
@Query() filter?: string,
@Query() fields?: string,
@Query() ndjson?: boolean,
@Query() markdown?: boolean,
@Query() limit?: number,
/** include stopped containers, default true */
@Query() all?: boolean,
/** merge the latest stats of the running and paused containers (`stats`), never blocks: `statsPending: true` while the first samples are not there (~2 s) */
@Query() stats?: boolean,
/** bypass the cache of the container lists */
@Query() force_refresh?: boolean
): SendObjects<Partial<Unbrand<XoDockerContainer>>> {
const { containers, errors } = await this.#dockerContainerService.list({
filter,
all,
stats,
forceRefresh: force_refresh,
})
if (errors.length !== 0) {
// set on the response itself: also sent with ndjson and markdown
req.res?.setHeader(
DOCKER_ERRORS_HEADER,
JSON.stringify(errors.map(({ $engine, code }) => ({ engine: $engine, code })))
)
}
return this.sendObjects(containers, req, { limit })
}
/**
* Required privilege:
* - admin (v2: resource: docker-container, action: start)
*
* @example id "8d834412-eb40-4328-a815-3fcc0989bd07_1b5d79f4a1c9275c5f9e1fc50629ea85ca807fe1c70f03e528e35f4b6ce1963e"
*/
// ACLs v2: acl({ resource: 'docker-container', action: 'start', objectId: 'params.id', getObject: ({ restApi }) => restApi.xoApp.getDockerContainer })
@Example(taskLocation)
@Extension('x-mcp-exposure', 'confirm')
@Post('{id}/actions/start')
@SuccessResponse(asynchronousActionResp.status, asynchronousActionResp.description)
@Response(noContentResp.status, 'Started, or already running (synchronous call)')
@Response(notFoundResp.status, notFoundResp.description)
@Response(badGatewayResp.status, 'SSH or Docker failure (see data.code, synchronous call)')
@Response(gatewayTimeoutResp.status, gatewayTimeoutResp.description)
startDockerContainer(@Path() id: string, @Query() sync?: boolean): CreateActionReturnType<void> {
return this.#action(id, 'start', sync)
}
/**
* Required privilege:
* - admin (v2: resource: docker-container, action: stop)
*
* @example id "8d834412-eb40-4328-a815-3fcc0989bd07_1b5d79f4a1c9275c5f9e1fc50629ea85ca807fe1c70f03e528e35f4b6ce1963e"
*/
// ACLs v2: acl({ resource: 'docker-container', action: 'stop', objectId: 'params.id', getObject: ({ restApi }) => restApi.xoApp.getDockerContainer })
@Example(taskLocation)
@Extension('x-mcp-exposure', 'confirm')
@Post('{id}/actions/stop')
@SuccessResponse(asynchronousActionResp.status, asynchronousActionResp.description)
@Response(noContentResp.status, 'Stopped, or already stopped (synchronous call)')
@Response(notFoundResp.status, notFoundResp.description)
@Response(badGatewayResp.status, 'SSH or Docker failure (see data.code, synchronous call)')
@Response(gatewayTimeoutResp.status, gatewayTimeoutResp.description)
stopDockerContainer(@Path() id: string, @Query() sync?: boolean): CreateActionReturnType<void> {
return this.#action(id, 'stop', sync)
}
/**
* Required privilege:
* - admin (v2: resource: docker-container, action: restart)
*
* @example id "8d834412-eb40-4328-a815-3fcc0989bd07_1b5d79f4a1c9275c5f9e1fc50629ea85ca807fe1c70f03e528e35f4b6ce1963e"
*/
// ACLs v2: acl({ resource: 'docker-container', action: 'restart', objectId: 'params.id', getObject: ({ restApi }) => restApi.xoApp.getDockerContainer })
@Example(taskLocation)
@Extension('x-mcp-exposure', 'confirm')
@Post('{id}/actions/restart')
@SuccessResponse(asynchronousActionResp.status, asynchronousActionResp.description)
@Response(noContentResp.status, 'Restarted (synchronous call)')
@Response(notFoundResp.status, notFoundResp.description)
@Response(badGatewayResp.status, 'SSH or Docker failure (see data.code, synchronous call)')
@Response(gatewayTimeoutResp.status, gatewayTimeoutResp.description)
restartDockerContainer(@Path() id: string, @Query() sync?: boolean): CreateActionReturnType<void> {
return this.#action(id, 'restart', sync)
}
/**
* Required privilege:
* - admin (v2: resource: docker-container, action: pause)
*
* @example id "8d834412-eb40-4328-a815-3fcc0989bd07_1b5d79f4a1c9275c5f9e1fc50629ea85ca807fe1c70f03e528e35f4b6ce1963e"
*/
// ACLs v2: acl({ resource: 'docker-container', action: 'pause', objectId: 'params.id', getObject: ({ restApi }) => restApi.xoApp.getDockerContainer })
@Example(taskLocation)
@Extension('x-mcp-exposure', 'confirm')
@Post('{id}/actions/pause')
@SuccessResponse(asynchronousActionResp.status, asynchronousActionResp.description)
@Response(noContentResp.status, 'Paused (synchronous call)')
@Response(notFoundResp.status, notFoundResp.description)
@Response(incorrectStateResp.status, 'Not running, or already paused (synchronous call)')
@Response(badGatewayResp.status, 'SSH or Docker failure (see data.code, synchronous call)')
@Response(gatewayTimeoutResp.status, gatewayTimeoutResp.description)
pauseDockerContainer(@Path() id: string, @Query() sync?: boolean): CreateActionReturnType<void> {
return this.#action(id, 'pause', sync)
}
/**
* Required privilege:
* - admin (v2: resource: docker-container, action: unpause)
*
* @example id "8d834412-eb40-4328-a815-3fcc0989bd07_1b5d79f4a1c9275c5f9e1fc50629ea85ca807fe1c70f03e528e35f4b6ce1963e"
*/
// ACLs v2: acl({ resource: 'docker-container', action: 'unpause', objectId: 'params.id', getObject: ({ restApi }) => restApi.xoApp.getDockerContainer })
@Example(taskLocation)
@Extension('x-mcp-exposure', 'confirm')
@Post('{id}/actions/unpause')
@SuccessResponse(asynchronousActionResp.status, asynchronousActionResp.description)
@Response(noContentResp.status, 'Unpaused (synchronous call)')
@Response(notFoundResp.status, notFoundResp.description)
@Response(incorrectStateResp.status, 'Not paused (synchronous call)')
@Response(badGatewayResp.status, 'SSH or Docker failure (see data.code, synchronous call)')
@Response(gatewayTimeoutResp.status, gatewayTimeoutResp.description)
unpauseDockerContainer(@Path() id: string, @Query() sync?: boolean): CreateActionReturnType<void> {
return this.#action(id, 'unpause', sync)
}
/**
* Remove the container from its Docker host.
*
* Always synchronous.
*
* Required privilege:
* - admin (v2: resource: docker-container, action: delete)
*
* @example id "8d834412-eb40-4328-a815-3fcc0989bd07_1b5d79f4a1c9275c5f9e1fc50629ea85ca807fe1c70f03e528e35f4b6ce1963e"
* @example force false
* @example removeVolumes false
*/
// ACLs v2: acl({ resource: 'docker-container', action: 'delete', objectId: 'params.id', getObject: ({ restApi }) => restApi.xoApp.getDockerContainer })
@Extension('x-mcp-exposure', 'confirm')
@Delete('{id}')
@SuccessResponse(noContentResp.status, noContentResp.description)
@Response(notFoundResp.status, notFoundResp.description)
@Response(incorrectStateResp.status, 'The container is running and force is not set')
@Response(badGatewayResp.status, 'SSH or Docker failure (see data.code)')
@Response(gatewayTimeoutResp.status, gatewayTimeoutResp.description)
async deleteDockerContainer(
@Path() id: string,
/** kill the container first if it is running */
@Query() force?: boolean,
/** also remove its anonymous volumes */
@Query() removeVolumes?: boolean
): Promise<void> {
const containerId = id as XoDockerContainer['id']
await this.#dockerContainerService.assertContainerId(containerId)
// no task: always synchronous, like the engine routes
await this.restApi.xoApp.deleteDockerContainer(containerId, { force, removeVolumes })
}
async #action(id: string, action: XoDockerContainerAction, sync?: boolean): CreateActionReturnType<void> {
const containerId = id as XoDockerContainer['id']
// 404 before creating a task: the id and the engine without connecting,
// then the container (from the listing cache when possible)
await this.#dockerContainerService.assertContainerId(containerId)
await this.getObject(containerId)
return this.createAction<void>(
() => withDockerErrors(() => this.restApi.xoApp.runDockerContainerAction(containerId, action)),
{
sync,
statusCode: noContentResp.status,
taskProperties: { name: `${action} Docker container`, objectId: containerId },
}
)
}
}

View File

@@ -0,0 +1,404 @@
import assert from 'node:assert/strict'
import { describe, it } from 'node:test'
import { serializeError } from '@vates/task'
import { invalidParameters, noSuchObject } from 'xo-common/api-errors.js'
import { DockerContainerController } from './docker-container.controller.mjs'
import { DockerContainerService, getEngineScope } from './docker-container.service.mjs'
import { ApiError } from '../helpers/error.helper.mjs'
import { safeParseComplexMatcher } from '../helpers/utils.helper.mjs'
import type { RestApi } from '../rest-api/rest-api.mjs'
const VM_1 = 'c7b3b4bc-0000-4000-8000-000000000001'
const VM_2 = 'c7b3b4bc-0000-4000-8000-000000000002'
const POOL = 'b7569d99-30f8-178a-7d94-801de3e29b5b'
const DOCKER_ID = 'ab'.repeat(32)
const engines = [
{ id: 'engine-1', $VM: VM_1, $pool: POOL },
{ id: 'engine-2', $VM: VM_2, $pool: POOL },
{ id: 'engine-3', host: '192.0.2.3' },
]
const containers = [
{ id: `engine-1_${DOCKER_ID}`, $engine: 'engine-1', $VM: VM_1, $pool: POOL, name: 'web', state: 'running' },
{ id: `engine-1_${'cd'.repeat(32)}`, $engine: 'engine-1', $VM: VM_1, $pool: POOL, name: 'db', state: 'exited' },
]
function setup({ maxListedEngines }: { maxListedEngines?: number } = {}) {
const calls: { method: string; args: unknown[] }[] = []
const tasks: Record<string, unknown>[] = []
const xoApp = {
config: { getOptional: (path: string) => (path === 'docker.maxListedEngines' ? maxListedEngines : undefined) },
getAllDockerEngines: async () => engines,
getDockerEngine: async (id: string) => {
const engine = engines.find(_ => _.id === id)
if (engine === undefined) {
throw noSuchObject(id, 'docker-engine')
}
return engine
},
getDockerContainers: async (opts: unknown) => {
calls.push({ method: 'getDockerContainers', args: [opts] })
return {
containers,
errors: [{ $engine: 'engine-2', $VM: VM_2, code: 'SSH_AUTH_FAILED', message: 'SSH authentication failed' }],
asOf: 42,
}
},
getDockerContainer: async (id: string) => {
const container = containers.find(_ => _.id === id)
if (container === undefined) {
throw noSuchObject(id, 'docker-container')
}
return container
},
getDockerContainerStats: async (...args: unknown[]) => {
calls.push({ method: 'getDockerContainerStats', args })
return { sampledAt: 1, cpuPercent: 3.1, memoryUsage: 42 }
},
runDockerContainerAction: async (...args: unknown[]) => {
calls.push({ method: 'runDockerContainerAction', args })
},
deleteDockerContainer: async (...args: unknown[]) => {
calls.push({ method: 'deleteDockerContainer', args })
},
}
const restApi = {
xoApp,
getCurrentUser: () => ({ id: 'admin', permission: 'admin' }),
tasks: {
create: (properties: Record<string, unknown>) => {
tasks.push(properties)
return {
id: 'task-1',
set() {},
run: async (fn: () => unknown) => {
try {
return await fn()
} catch (error) {
// what the Tasks mixin of xo-server records (`@vates/task`)
properties.result = error instanceof Error && !('toJSON' in error) ? serializeError(error) : error
throw error
}
},
}
},
},
} as unknown as RestApi
const service = new DockerContainerService(restApi)
const controller = new DockerContainerController(restApi, service)
return { calls, controller, service, tasks }
}
const scopeOf = (filter: string) => {
const scope = getEngineScope(safeParseComplexMatcher(filter))
return scope && engines.filter(scope as never).map(_ => _.id)
}
describe('getEngineScope()', () => {
it('value terms on $engine, $VM and $pool', () => {
assert.deepEqual(scopeOf('$engine:engine-3'), ['engine-3'])
assert.deepEqual(scopeOf(`$VM:${VM_2}`), ['engine-2'])
assert.deepEqual(scopeOf(`$VM:"${VM_2.toUpperCase()}"`), ['engine-2'])
assert.deepEqual(scopeOf(`$pool:${POOL}`), ['engine-1', 'engine-2'])
})
it('the semantics of complex-matcher, like the filter itself: partial ids (case-insensitive substring)', () => {
assert.deepEqual(scopeOf('$VM:c7b3b4bc'), ['engine-1', 'engine-2'])
assert.deepEqual(scopeOf('$VM:C7B3B4BC-0000-4000-8000-000000000001'), ['engine-1'])
assert.deepEqual(scopeOf('$engine:engine'), ['engine-1', 'engine-2', 'engine-3'])
assert.deepEqual(scopeOf('$pool:b7569d99 $engine:2'), ['engine-2'])
assert.deepEqual(scopeOf('$VM:dead'), [])
})
it('conjunctions, disjunctions', () => {
assert.deepEqual(scopeOf(`$pool:${POOL} name:web`), ['engine-1', 'engine-2'])
assert.deepEqual(scopeOf(`$pool:${POOL} $VM:${VM_1}`), ['engine-1'])
assert.deepEqual(scopeOf('$engine:|(engine-1 engine-3)'), ['engine-1', 'engine-3'])
assert.deepEqual(scopeOf(`|($engine:engine-3 $VM:${VM_1})`), ['engine-1', 'engine-3'])
// uninterpretable terms are ignored in a conjunction
assert.deepEqual(scopeOf('$engine:engine-3 !$VM:foo'), ['engine-3'])
})
it('unscoped', () => {
for (const filter of [
'name:web',
'$engine:engine-*',
'$VM:/^c7b3/',
'!$engine:engine-1',
'|($engine:engine-1 name:web)',
'$engine:|(engine-1 /x/)',
'engine-1',
]) {
assert.equal(scopeOf(filter), undefined, filter)
}
})
})
const makeReq = (query: Record<string, string>, headers: Record<string, string> = {}) =>
({
query,
path: '/rest/v0/docker-containers',
res: { setHeader: (name: string, value: string) => (headers[name] = value) },
}) as never
describe('DockerContainerController', () => {
describe('scoped listing', () => {
it('422 without a filter designating engines, before any connection', async () => {
const { calls, controller } = setup()
const req = { query: {}, path: '/rest/v0/docker-containers' } as never
for (const filter of [undefined, 'name:web', '$engine:engine-*']) {
await assert.rejects(controller.getDockerContainers(req, filter), invalidParameters.is)
}
assert.deepEqual(calls, [])
})
it('a partial id designates the engines, like the filter matches the containers', async () => {
const { calls, controller } = setup()
const req = makeReq({ fields: 'name' })
assert.deepEqual(await controller.getDockerContainers(req, '$VM:c7b3b4bc name:web', 'name'), [
{ name: 'web', href: `/rest/v0/docker-containers/engine-1_${DOCKER_ID}` },
])
assert.deepEqual((calls[0].args[0] as { engines: string[] }).engines, ['engine-1', 'engine-2'])
})
it('422 above maxListedEngines', async () => {
const { calls, controller } = setup({ maxListedEngines: 1 })
const req = { query: {}, path: '/rest/v0/docker-containers' } as never
await assert.rejects(controller.getDockerContainers(req, `$pool:${POOL}`), invalidParameters.is)
assert.deepEqual(calls, [])
})
it('a plain array; applies the whole filter; failed engines in the x-docker-errors header (fixes)', async () => {
const { calls, controller } = setup()
const filter = `$pool:${POOL} state:running`
const headers: Record<string, string> = {}
const req = makeReq({ fields: 'name,state', filter }, headers)
assert.deepEqual(await controller.getDockerContainers(req, filter), [
{ name: 'web', state: 'running', href: `/rest/v0/docker-containers/engine-1_${DOCKER_ID}` },
])
assert.deepEqual(JSON.parse(headers['x-docker-errors']), [{ engine: 'engine-2', code: 'SSH_AUTH_FAILED' }])
assert.deepEqual(calls, [
{
method: 'getDockerContainers',
args: [{ engines: ['engine-1', 'engine-2'], all: true, stats: false, forceRefresh: false }],
},
])
})
it('hrefs by default, limit, force_refresh (fixes)', async () => {
const { calls, controller } = setup()
const filter = `$VM:${VM_1}`
const req = makeReq({ filter })
assert.deepEqual(await controller.getDockerContainers(req, filter, undefined, undefined, undefined, 1), [
`/rest/v0/docker-containers/engine-1_${DOCKER_ID}`,
])
await controller.getDockerContainers(
req,
filter,
undefined,
undefined,
undefined,
undefined,
undefined,
undefined,
true
)
assert.equal((calls[1].args[0] as { forceRefresh: boolean }).forceRefresh, true)
})
it('no x-docker-errors header without failures; a scope designating no engines is valid', async () => {
const { calls, controller } = setup()
// eslint-disable-next-line @typescript-eslint/no-explicit-any
;(controller as any).restApi.xoApp.getDockerContainers = async (opts: unknown) => {
calls.push({ method: 'getDockerContainers', args: [opts] })
return { containers: [], errors: [], asOf: 42 }
}
const headers: Record<string, string> = {}
const req = makeReq({}, headers)
assert.deepEqual(await controller.getDockerContainers(req, '$VM:c7b3b4bc-0000-4000-8000-00000000dead'), [])
assert.deepEqual(headers, {})
assert.deepEqual(calls, [
{ method: 'getDockerContainers', args: [{ engines: [], all: true, stats: false, forceRefresh: false }] },
])
})
it('markdown: a table, the header is still set', async () => {
const { controller } = setup()
const headers: Record<string, string> = {}
const req = makeReq({ markdown: 'true', fields: 'name,state' }, headers)
const stream = (await controller.getDockerContainers(req, `$VM:${VM_1}`, 'name,state')) as AsyncIterable<unknown>
let text = ''
for await (const chunk of stream) {
text += String(chunk)
}
assert.match(text, /\| web +\| running +\|/)
assert.equal(headers['Content-Type'], 'text/markdown; charset=utf-8')
assert.ok('x-docker-errors' in headers)
})
it('ndjson: the containers, the header is still set', async () => {
const { controller } = setup()
const filter = `$VM:${VM_1}`
const headers: Record<string, string> = {}
const req = {
query: { ndjson: 'true', fields: 'name' },
path: '/rest/v0/docker-containers',
res: { setHeader: (name: string, value: string) => (headers[name] = value) },
} as never
const stream = (await controller.getDockerContainers(req, filter, 'name', true)) as AsyncIterable<unknown>
const chunks: string[] = []
for await (const chunk of stream) {
chunks.push(String(chunk))
}
assert.equal(headers['Content-Type'], 'application/x-ndjson')
assert.ok('x-docker-errors' in headers)
assert.deepEqual(
chunks
.join('')
.split('\n')
.filter(Boolean)
.map(line => JSON.parse(line).name),
['web', 'db']
)
})
})
describe('stats (phase 4)', () => {
it('stats=true is passed to the mixin, the stats and statsPending of the containers are kept', async () => {
const { calls, controller } = setup()
containers[0] = { ...containers[0], stats: { cpuPercent: 3.1 }, statsPending: true } as never
try {
const filter = `$VM:${VM_1}`
const req = makeReq({ filter, fields: 'name,stats,statsPending' })
const result = await controller.getDockerContainers(
req,
filter,
'name,stats,statsPending',
undefined,
undefined,
undefined,
undefined,
true
)
assert.equal((calls[0].args[0] as { stats: boolean }).stats, true)
assert.deepEqual((result as unknown[])[0], {
name: 'web',
stats: { cpuPercent: 3.1 },
statsPending: true,
href: `/rest/v0/docker-containers/engine-1_${DOCKER_ID}`,
})
} finally {
const { stats: _stats, statsPending: _pending, ...rest } = containers[0] as never as Record<string, unknown>
containers[0] = rest as never
}
})
it('GET /docker-containers/{id}/stats: 404 without connecting, then the mixin', async () => {
const { calls, controller } = setup()
for (const id of ['nope', `engine-9_${DOCKER_ID}`]) {
await assert.rejects(controller.getDockerContainerStats(id), noSuchObject.is, id)
}
assert.deepEqual(calls, [])
const id = `engine-1_${DOCKER_ID}`
assert.deepEqual(await controller.getDockerContainerStats(id), { sampledAt: 1, cpuPercent: 3.1, memoryUsage: 42 })
assert.deepEqual(calls, [{ method: 'getDockerContainerStats', args: [id] }])
})
})
describe('actions and removal', () => {
it('404 before creating a task, without connecting', async () => {
const { calls, controller, tasks } = setup()
for (const id of ['nope', `engine-1_${'z'.repeat(64)}`, `engine-9_${DOCKER_ID}`, `engine-1${DOCKER_ID}`]) {
await assert.rejects(controller.startDockerContainer(id, true), noSuchObject.is, id)
await assert.rejects(controller.deleteDockerContainer(id), noSuchObject.is, id)
}
assert.deepEqual(calls, [])
assert.deepEqual(tasks, [])
})
it('an unknown container of a known engine: 404 before creating a task', async () => {
const { calls, controller, tasks } = setup()
await assert.rejects(controller.startDockerContainer(`engine-1_${'ef'.repeat(32)}`), noSuchObject.is)
assert.deepEqual(calls, [])
assert.deepEqual(tasks, [])
})
it('five explicit actions', async () => {
const { calls, controller, tasks } = setup()
const id = `engine-1_${DOCKER_ID}`
await controller.startDockerContainer(id, true)
await controller.stopDockerContainer(id, true)
await controller.restartDockerContainer(id, true)
await controller.pauseDockerContainer(id, true)
await controller.unpauseDockerContainer(id, true)
assert.deepEqual(
calls.map(_ => _.args),
['start', 'stop', 'restart', 'pause', 'unpause'].map(action => [id, action])
)
assert.deepEqual(
tasks.map(_ => [_.name, _.objectId, _.objectType]),
['start', 'stop', 'restart', 'pause', 'unpause'].map(action => [
`REST API: ${action} Docker container`,
id,
'docker-container',
])
)
})
it('delete, with force and removeVolumes, without a task', async () => {
const { calls, controller, tasks } = setup()
const id = `engine-1_${DOCKER_ID}`
await controller.deleteDockerContainer(id, true, false)
assert.deepEqual(calls, [{ method: 'deleteDockerContainer', args: [id, { force: true, removeVolumes: false }] }])
// no task: its record would be readable by every user with task:read
assert.deepEqual(tasks, [])
})
it('Docker errors are mapped', async () => {
const { controller } = setup()
const error = Object.assign(new Error('Container is already paused'), {
name: 'DockerError',
code: 'DOCKER_API_ERROR',
data: { statusCode: 409 },
})
// eslint-disable-next-line @typescript-eslint/no-explicit-any
;(controller as any).restApi.xoApp.runDockerContainerAction = async () => {
throw error
}
await assert.rejects(controller.pauseDockerContainer(`engine-1_${DOCKER_ID}`, true), e => {
assert.ok(e instanceof ApiError)
assert.equal(e.status, 409)
return true
})
})
it('the record of a failed action holds the mapped error, without connection context nor raw error', async () => {
const { controller, tasks } = setup()
// eslint-disable-next-line @typescript-eslint/no-explicit-any
;(controller as any).restApi.xoApp.runDockerContainerAction = async () => {
throw Object.assign(new Error('Container is already paused'), {
name: 'DockerError',
code: 'DOCKER_API_ERROR',
data: {
host: '192.0.2.1',
port: 2222,
socketPath: '/run/user/1000/docker.sock',
path: '/containers/abc/pause',
statusCode: 409,
message: 'Container is already paused',
},
})
}
await assert.rejects(controller.pauseDockerContainer(`engine-1_${DOCKER_ID}`, true), ApiError)
const record = JSON.stringify(tasks)
assert.doesNotMatch(record, /192\.0\.2\.1|2222|docker\.sock|"cause"|"stack"/)
assert.deepEqual(JSON.parse(record)[0].result, {
code: 'DOCKER_API_ERROR',
statusCode: 409,
message: 'Container is already paused',
})
})
})
})

View File

@@ -0,0 +1,158 @@
import * as CM from 'complex-matcher'
import { inject } from 'inversify'
import { invalidParameters, noSuchObject } from 'xo-common/api-errors.js'
import type { XoDockerContainer, XoDockerContainerListError, XoDockerEngine, XoDockerLogs } from '@vates/types'
import { RestApi } from '../rest-api/rest-api.mjs'
import { safeParseComplexMatcher } from '../helpers/utils.helper.mjs'
const DEFAULT_MAX_LISTED_ENGINES = 10
// properties of the containers which designate their engine(s)
const SCOPE_PROPERTIES = ['$engine', '$VM', '$pool'] as const
type ScopeProperty = (typeof SCOPE_PROPERTIES)[number]
type EnginePredicate = (engine: XoDockerEngine) => boolean
// the scope properties of the containers of an engine
const getScopeObject = (engine: XoDockerEngine): Record<ScopeProperty, string | undefined> => ({
$engine: engine.id,
$VM: engine.$VM,
$pool: engine.$pool,
})
// a value (`foo`, `"foo"`) or a disjunction of values (`|(foo bar)`)
const isValueTerm = (node: CM.Node): boolean =>
node instanceof CM.StringNode ||
node instanceof CM.NumberOrStringNode ||
(node instanceof CM.Or && node.children.every(isValueTerm))
/**
* Engines designated by the value terms on `$engine`, `$VM` or `$pool` of a
* filter, as a predicate.
*
* The designated engines are a superset of the engines of the containers
* matching the filter (which is applied afterwards anyway): terms which cannot
* be interpreted (patterns, negations…) are ignored in a conjunction, and make
* a disjunction unscoped.
*
* @returns `undefined` if the filter does not designate engines
*/
export function getEngineScope(node: CM.Node): EnginePredicate | undefined {
if (node instanceof CM.Property) {
if (!(SCOPE_PROPERTIES as readonly string[]).includes(node.name) || !isValueTerm(node.child)) {
return
}
// complex-matcher's own semantics (case-insensitive substring), like the
// filter applied to the containers afterwards: `$VM:c7b3b4bc` works too
return engine => node.match(getScopeObject(engine))
}
if (node instanceof CM.And) {
const predicates = node.children.map(getEngineScope).filter(_ => _ !== undefined)
return predicates.length === 0 ? undefined : engine => predicates.every(predicate => predicate(engine))
}
if (node instanceof CM.Or) {
const predicates = node.children.map(getEngineScope)
return predicates.some(_ => _ === undefined)
? undefined
: engine => predicates.some(predicate => predicate!(engine))
}
}
/**
* Containers of the Docker engines, fetched live through xo-server's pool
* (and cached there, see `docker.cacheExpiresIn`: not cached again here).
*/
export class DockerContainerService {
#restApi: RestApi
constructor(@inject(RestApi) restApi: RestApi) {
this.#restApi = restApi
}
get #maxListedEngines(): number {
return this.#restApi.xoApp.config.getOptional<number>('docker.maxListedEngines') ?? DEFAULT_MAX_LISTED_ENGINES
}
/**
* Engines designated by a filter, without any connection.
*
* @throws invalidParameters if the filter does not designate engines, or too many
*/
async resolveEngines(filter: string | undefined): Promise<XoDockerEngine['id'][]> {
const scope = filter === undefined ? undefined : getEngineScope(safeParseComplexMatcher(filter))
if (scope === undefined) {
throw invalidParameters('filter on $engine, $VM or $pool is required (e.g. filter=$VM:<VM uuid>)')
}
const engines = (await this.#restApi.xoApp.getAllDockerEngines()).filter(scope).map(engine => engine.id)
const max = this.#maxListedEngines
if (engines.length > max) {
throw invalidParameters(
`the filter designates ${engines.length} Docker engines, at most ${max} are allowed (docker.maxListedEngines)`
)
}
return engines
}
/**
* Scoped listing: the engines designated by the filter are listed
* concurrently, then the whole filter is applied.
*
* An engine which fails does not fail the list: see `errors`.
*/
async list({
filter,
all = true,
stats = false,
forceRefresh = false,
}: {
filter?: string
all?: boolean
stats?: boolean
forceRefresh?: boolean
}): Promise<{ containers: XoDockerContainer[]; errors: XoDockerContainerListError[] }> {
const engines = await this.resolveEngines(filter)
const { containers, errors } = await this.#restApi.xoApp.getDockerContainers({ engines, all, stats, forceRefresh })
const predicate = safeParseComplexMatcher(filter!).createPredicate()
return { containers: containers.filter(predicate), errors }
}
/**
* Check the composite id and the existence of its engine, without any
* connection.
*
* @throws noSuchObject
*/
async assertContainerId(id: XoDockerContainer['id']): Promise<void> {
const index = id.indexOf('_')
if (index === -1 || !/^[0-9a-f]{64}$/.test(id.slice(index + 1))) {
throw noSuchObject(id, 'docker-container')
}
try {
await this.#restApi.xoApp.getDockerEngine(id.slice(0, index) as XoDockerEngine['id'])
} catch (error) {
throw noSuchObject.is(error) ? noSuchObject(id, 'docker-container') : error
}
}
getLogs(
id: XoDockerContainer['id'],
opts: {
tail?: number
since?: string
until?: string
stdout?: boolean
stderr?: boolean
timestamps?: boolean
}
): Promise<XoDockerLogs> {
// a number of milliseconds or a date string
const toDate = (value: string | undefined) =>
value !== undefined && /^\d+(?:\.\d+)?$/.test(value) ? Number(value) : value
return this.#restApi.xoApp.getDockerContainerLogs(id, {
...opts,
since: toDate(opts.since),
until: toDate(opts.until),
})
}
}

View File

@@ -0,0 +1,219 @@
// Raw Docker Engine API passthrough: /rest/v0/docker-engines/{id}/_raw/<Docker API path>
//
// Not a tsoa controller (a wildcard path): mounted with the external router
// (`mountExternalRoute`), which runs `expressAuthentication` first. Without an
// `acl` middleware, it already refuses non-admin users, but the admin check is
// repeated here, explicitly, because nothing else protects this route: it
// grants unrestricted access to the Docker daemon of the guest, which is
// root-equivalent on that guest.
//
// Handler order (the plan, §7): allowRawApi (501) → admin (403) → DOCKER
// feature → engine exists (404) → no connection hijacking (501) → path checks
// (400) → inbound header allowlist → audit log → response streamed with an
// outbound header allowlist, capped at docker.maxRawResponseSize → errors
// thrown, i.e. passed to `next()` by the external router.
import { pipeline } from 'node:stream/promises'
import type { Request, Response } from 'express'
import { createLogger } from '@xen-orchestra/log'
import type { OpenAPIV3 } from 'openapi-types'
import type { XoDockerEngine } from '@vates/types'
import { unauthorized } from 'xo-common/api-errors.js'
import { ApiError } from '../helpers/error.helper.mjs'
import type { RestApi } from '../rest-api/rest-api.mjs'
import type { RouteDefinition } from '../router/types.mjs'
const log = createLogger('xo:rest-api:docker-raw')
/** express path of the passthrough (relative to /rest/v0) */
export const DOCKER_RAW_ENDPOINT = '/docker-engines/:id/_raw/*'
const RAW_SEPARATOR = '/_raw/'
// the only request headers forwarded to dockerd: never `cookie`,
// `authorization`, `x-xo-*`, `upgrade`…
const INBOUND_HEADERS = ['accept', 'content-length', 'content-type'] as const
// the only response headers sent back
const OUTBOUND_HEADERS = ['api-version', 'content-length', 'content-type', 'docker-experimental', 'ostype']
// endpoints which hijack the connection (bidirectional streams): not supported
// the name may contain `/` (legacy link aliases, e.g. `web/db`): dockerd routes
// these endpoints with `{name:.*}`
const HIJACK_PATHS = [/^containers\/.+\/attach(?:\/ws)?$/, /^exec\/.+\/start$/, /^session$/, /^grpc$/]
const VERSION_SEGMENT = /^v\d+(?:\.\d+)?$/
/**
* Decoded segments of the Docker path, `undefined` if it is not acceptable:
* empty segments, `.` and `..`, encoded `/` or `\`, NUL, or invalid encoding.
* The decoded form matters: dockerd routes on the decoded path.
*/
export function getRawPathSegments(pathname: string): string[] | undefined {
if (pathname === '' || /%(?:2f|5c|00)/i.test(pathname)) {
return
}
const segments: string[] = []
for (const segment of pathname.split('/')) {
let decoded: string
try {
decoded = decodeURIComponent(segment)
} catch {
return
}
if (decoded === '' || decoded === '.' || decoded === '..' || /[\\/\0]/.test(decoded)) {
return
}
segments.push(decoded)
}
return segments
}
function isHijack(req: Request, segments: string[] | undefined): boolean {
if (req.headers.upgrade !== undefined || /\bupgrade\b/i.test(String(req.headers.connection ?? ''))) {
return true
}
if (segments === undefined) {
return false
}
const path = (VERSION_SEGMENT.test(segments[0]) ? segments.slice(1) : segments).join('/')
return HIJACK_PATHS.some(re => re.test(path))
}
export async function dockerRawHandler({ req, res, restApi }: { req: Request; res: Response; restApi: RestApi }) {
const { xoApp } = restApi
// 1. disabled by default: 501 rather than 404 so that an admin knows why
if (!(xoApp.config.getOptional<boolean>('docker.allowRawApi') ?? false)) {
throw new ApiError('the raw Docker API passthrough is disabled (docker.allowRawApi)', 501)
}
// 2. admin only, explicitly: this route is not protected by tsoa
const user = restApi.getCurrentUser()
if (user.permission !== 'admin') {
throw unauthorized()
}
// 3.
await xoApp.checkFeatureAuthorization('DOCKER')
// 4. 404 before any work
const engineId = req.params.id as XoDockerEngine['id']
const engine = await xoApp.getDockerEngine(engineId)
// the raw tail, not `req.params[0]` which is decoded and has no query string
const url = req.originalUrl
const index = url.indexOf(RAW_SEPARATOR)
const tail = index === -1 ? '' : url.slice(index + RAW_SEPARATOR.length)
const queryIndex = tail.indexOf('?')
const pathname = queryIndex === -1 ? tail : tail.slice(0, queryIndex)
const segments = getRawPathSegments(pathname)
// 5.
if (isHijack(req, segments)) {
throw new ApiError('attach, exec start and connection upgrades are not supported by the raw passthrough', 501)
}
// 6.
if (segments === undefined) {
throw new ApiError('invalid Docker API path', 400)
}
// 7. (a body already consumed by xo-server's urlencoded parser cannot be forwarded)
if ((req as Request & { _body?: boolean })._body === true) {
throw new ApiError('form-encoded bodies are not supported by the raw passthrough', 415)
}
const headers: Record<string, string> = {}
for (const name of INBOUND_HEADERS) {
const value = req.headers[name]
if (typeof value === 'string') {
headers[name] = value
}
}
const method = req.method
const hasBody =
method !== 'GET' &&
method !== 'HEAD' &&
(req.headers['transfer-encoding'] !== undefined ||
(req.headers['content-length'] !== undefined && req.headers['content-length'] !== '0'))
const path = '/' + tail
// 8. audit every call
log.info('docker raw', {
user: user.id,
userEmail: user.email,
engine: engineId,
vm: engine.$VM,
method,
path,
})
// 9. the request and the response are aborted when the client goes away
const controller = new AbortController()
const onClose = () => controller.abort()
res.once('close', onClose)
try {
const upstream = await xoApp.callDockerEngineRawApi(engineId, {
method,
path,
headers,
body: hasBody ? req : undefined,
signal: controller.signal,
})
// a 401/407 from the daemon (or a proxy in front of it) must not look like
// an XO authentication failure, nor make a browser prompt for credentials
if (upstream.statusCode === 401 || upstream.statusCode === 407) {
upstream.body.destroy()
throw new ApiError(`Docker API error ${upstream.statusCode}`, 502, {
data: { code: 'DOCKER_API_ERROR', statusCode: upstream.statusCode },
})
}
res.status(upstream.statusCode)
// streamed responses (events, logs?follow=1…) must reach the client as they
// come: xo-server's `compression()` (and any proxy) would buffer them
res.setHeader('Cache-Control', 'no-transform')
for (const name of OUTBOUND_HEADERS) {
const value = upstream.headers[name]
if (value !== undefined) {
res.setHeader(name, value)
}
}
try {
await pipeline(upstream.body, res)
} catch (error) {
// the status and headers are gone: the only way to report the failure
// (e.g. RAW_RESPONSE_TOO_LARGE) is to cut the response
if (!controller.signal.aborted) {
log.warn('docker raw: response interrupted', { engine: engineId, method, path, error })
}
res.destroy()
}
} finally {
res.off('close', onClose)
}
}
const dockerRawRoutes: RouteDefinition[] = (['get', 'post', 'put', 'patch', 'delete'] as const).map(method => ({
method,
endpoint: DOCKER_RAW_ENDPOINT,
tags: ['docker-engines'],
// writes the response itself, the external router does not send anything else
callback: ({ req, res, restApi }) => dockerRawHandler({ req, res, restApi }),
}))
/**
* Mount the passthrough on the external router, and remove the wildcard path
* it inserted in the OpenAPI spec: the hand-written entry,
* `/docker-engines/{id}/_raw/{path}`, is in `tsoa.json`.
*/
export function mountDockerRawRoutes(
mountExternalRoute: (route: RouteDefinition) => () => void,
swaggerOpenApiSpec: OpenAPIV3.Document
): void {
for (const route of dockerRawRoutes) {
mountExternalRoute(route)
}
delete swaggerOpenApiSpec.paths[DOCKER_RAW_ENDPOINT]
}

View File

@@ -0,0 +1,488 @@
import assert from 'node:assert/strict'
import { createServer, request as httpRequest, type Server } from 'node:http'
import { createRequire } from 'node:module'
import { Readable } from 'node:stream'
import { after, before, beforeEach, describe, it } from 'node:test'
import express, { type NextFunction, type Request, type Response } from 'express'
import type { OpenAPIV3 } from 'openapi-types'
import { featureUnauthorized, noSuchObject } from 'xo-common/api-errors.js'
import type { XoApp } from '@vates/types'
// the IoC container cannot be initialized on its own because of circular
// imports between the services: load the generated routes first, like
// `index.mts` does
import '../open-api/routes/routes.js'
import {
DOCKER_RAW_ENDPOINT,
dockerRawHandler,
getRawPathSegments,
mountDockerRawRoutes,
} from './docker-engine-raw.routes.mjs'
import genericErrorHandler from '../middlewares/generic-error-handler.middleware.mjs'
import { setupContainer } from '../ioc/ioc.mjs'
import type { RestApi } from '../rest-api/rest-api.mjs'
import { createExternalRouter } from '../router/external-router.mjs'
// xo-server compresses every response (`app.use(compression())`), no types
// eslint-disable-next-line @typescript-eslint/no-require-imports
const compression = createRequire(import.meta.url)('compression') as () => express.RequestHandler
const ENGINE_ID = 'a1ea0bb5-f67d-4406-8d9b-6a4c2fa8c6ac'
const VM_ID = 'c7b3b4bc-0000-4000-8000-000000000001'
type RawCall = { id: string; method: string; path: string; headers: Record<string, string>; body?: string }
type Upstream = { statusCode: number; headers: Record<string, string>; body: Readable }
// state of the fake xo-server, reset before each test
const state = {
allowRawApi: true as boolean | undefined,
licensed: true,
user: { id: 'admin-id', email: 'admin@example.org', permission: 'admin' } as {
id: string
email: string
permission: string
},
calls: [] as RawCall[],
upstream: (): Upstream => ({
statusCode: 200,
headers: { 'content-type': 'application/json', 'api-version': '1.43', server: 'Docker/29', 'x-secret': 'no' },
body: Readable.from(['[]']),
}),
error: undefined as Error | undefined,
signal: undefined as AbortSignal | undefined,
}
const restApi = {
getCurrentUser: () => state.user,
xoApp: {
// for the IoC container's RestApi, used by the external router
get apiContext() {
return { user: state.user }
},
config: {
getOptional: (path: string) => (path === 'docker.allowRawApi' ? state.allowRawApi : undefined),
},
checkFeatureAuthorization: async () => {
if (!state.licensed) {
throw featureUnauthorized({ featureCode: 'DOCKER' })
}
},
getDockerEngine: async (id: string) => {
if (id !== ENGINE_ID) {
throw noSuchObject(id, 'docker-engine')
}
return { id, $VM: VM_ID }
},
callDockerEngineRawApi: async (
id: string,
{
method,
path,
headers,
body,
signal,
}: { method: string; path: string; headers: Record<string, string>; body?: Readable; signal: AbortSignal }
) => {
const call: RawCall = { id, method, path, headers }
state.calls.push(call)
state.signal = signal
if (body !== undefined) {
const chunks: Buffer[] = []
for await (const chunk of body) {
chunks.push(chunk)
}
call.body = Buffer.concat(chunks).toString()
}
if (state.error !== undefined) {
throw state.error
}
return state.upstream()
},
},
} as unknown as RestApi
let server: Server
let port: number
before(async () => {
const app = express()
app.use(compression())
// like xo-server: a form-encoded body is consumed before the route
app.use(express.urlencoded({ extended: false }))
app.all(`/rest/v0${DOCKER_RAW_ENDPOINT}`, (req: Request, res: Response, next: NextFunction) => {
// what the external router does with the callback's errors
dockerRawHandler({ req, res, restApi }).catch(next)
})
app.use(genericErrorHandler)
server = createServer(app)
await new Promise<void>(resolve => server.listen(0, '127.0.0.1', resolve))
port = (server.address() as { port: number }).port
})
after(() => new Promise<void>(resolve => server.close(() => resolve())))
beforeEach(() => {
state.allowRawApi = true
state.licensed = true
state.user = { id: 'admin-id', email: 'admin@example.org', permission: 'admin' }
state.calls = []
state.error = undefined
state.signal = undefined
state.upstream = () => ({
statusCode: 200,
headers: { 'content-type': 'application/json', 'api-version': '1.43', server: 'Docker/29', 'x-secret': 'no' },
body: Readable.from(['[]']),
})
})
// raw HTTP request: fetch() would normalize the path (`..`) and forbid some headers
function send(
path: string,
{ method = 'GET', headers = {}, body }: { method?: string; headers?: Record<string, string>; body?: string } = {}
): Promise<{ status: number; headers: Record<string, unknown>; body: string; error?: Error }> {
return new Promise(resolve => {
const req = httpRequest({ host: '127.0.0.1', port, method, path: `/rest/v0/docker-engines/${path}`, headers })
req.on('response', res => {
const chunks: Buffer[] = []
res.on('data', chunk => chunks.push(chunk))
const done = (error?: Error) =>
resolve({ status: res.statusCode!, headers: res.headers, body: Buffer.concat(chunks).toString(), error })
res.on('end', () => done())
res.on('error', done)
res.on('aborted', () => done(new Error('aborted')))
})
req.on('error', error => resolve({ status: 0, headers: {}, body: '', error }))
req.end(body)
})
}
describe('raw Docker API passthrough', () => {
it('501 when disabled (the default), before anything else', async () => {
for (const value of [undefined, false]) {
state.allowRawApi = value
state.user = { id: 'u', email: 'u@example.org', permission: 'none' }
const res = await send(`${ENGINE_ID}/_raw/version`)
assert.equal(res.status, 501)
assert.match(res.body, /docker\.allowRawApi/)
}
assert.deepEqual(state.calls, [])
})
it('403 for a non-admin user, before any other check (the manual admin check)', async () => {
for (const permission of ['none', 'viewer', 'operator']) {
state.user = { id: 'u', email: 'u@example.org', permission }
state.licensed = false
// even with an unknown engine: nothing is disclosed
for (const id of [ENGINE_ID, 'unknown']) {
const res = await send(`${id}/_raw/version`)
assert.equal(res.status, 403, `${permission} ${id}`)
}
}
assert.deepEqual(state.calls, [])
})
it('the DOCKER feature, then 404 on an unknown engine', async () => {
state.licensed = false
assert.equal((await send(`${ENGINE_ID}/_raw/version`)).status, 403)
state.licensed = true
assert.equal((await send('unknown/_raw/version')).status, 404)
assert.deepEqual(state.calls, [])
})
it('attach, exec start and upgrades are refused (501), even encoded or versioned', async () => {
for (const path of [
'containers/abc/attach?stream=1',
'containers/abc/attach/ws',
'v1.43/containers/abc/attach',
'containers/abc/%61ttach',
'exec/123/start',
'v1.41/exec/123/start',
'session',
'grpc',
// names with a `/` (legacy link aliases like `web/db`), which dockerd
// routes with `{name:.*}` (review 3)
'containers/web/db/attach',
'containers/web/db/attach?stream=1&stdin=1',
'containers/web/db/attach/ws',
'v1.43/containers/web/db/attach',
'containers/a/b/c/attach',
'exec/a/b/start',
'v1.43/exec/web/db/start',
]) {
const res = await send(`${ENGINE_ID}/_raw/${path}`, { method: 'POST' })
assert.equal(res.status, 501, path)
}
const upgrade = await send(`${ENGINE_ID}/_raw/containers/json`, {
headers: { connection: 'Upgrade', upgrade: 'tcp' },
})
assert.equal(upgrade.status, 501)
assert.deepEqual(state.calls, [])
})
it('`..`, `.`, empty segments and encoded slashes are refused (400)', async () => {
for (const path of [
'../../info',
'containers/../../info',
'containers/%2e%2e/info',
'containers/%2E%2e/info',
'containers/./json',
'containers%2fjson',
'containers%2Fjson',
'containers%5cjson',
'containers//json',
'containers/%00/json',
'',
]) {
const res = await send(`${ENGINE_ID}/_raw/${path}`)
assert.equal(res.status, 400, path)
}
assert.deepEqual(state.calls, [])
})
it('forwards the path and query verbatim, only allowlisted headers both ways', async () => {
const res = await send(`${ENGINE_ID}/_raw/images/json?all=1&filters=%7B%22dangling%22%3A%5B%22true%22%5D%7D`, {
headers: {
accept: 'application/json',
cookie: 'authenticationToken=secret-token',
authorization: 'Basic c2VjcmV0OnNlY3JldA==',
'x-xo-client': 'mcp',
'x-registry-auth': 'secret',
'x-forwarded-for': '1.2.3.4',
},
})
assert.equal(res.status, 200)
assert.equal(res.body, '[]')
assert.deepEqual(state.calls, [
{
id: ENGINE_ID,
method: 'GET',
path: '/images/json?all=1&filters=%7B%22dangling%22%3A%5B%22true%22%5D%7D',
headers: { accept: 'application/json' },
},
])
assert.equal(res.headers['api-version'], '1.43')
assert.match(String(res.headers['content-type']), /^application\/json/)
assert.equal(res.headers.server, undefined)
assert.equal(res.headers['x-secret'], undefined)
})
it('forwards bodies with their content type, and the upstream status', async () => {
state.upstream = () => ({
statusCode: 404,
headers: { 'content-type': 'application/json' },
body: Readable.from(['{"message":"No such image"}']),
})
const body = JSON.stringify({ Image: 'alpine' })
const res = await send(`${ENGINE_ID}/_raw/containers/create?name=foo`, {
method: 'POST',
headers: { 'content-type': 'application/json', 'content-length': String(body.length), cookie: 'token=x' },
body,
})
assert.equal(res.status, 404)
assert.equal(res.body, '{"message":"No such image"}')
assert.deepEqual(state.calls, [
{
id: ENGINE_ID,
method: 'POST',
path: '/containers/create?name=foo',
headers: { 'content-type': 'application/json', 'content-length': String(body.length) },
body,
},
])
})
it('size caps: 413 for the request body, 502 for an announced response, cut when streamed', async () => {
const dockerError = (code: string) =>
Object.assign(new Error(code), { name: 'DockerError', code, data: { maxSize: 10 } })
state.error = dockerError('RAW_REQUEST_TOO_LARGE')
let res = await send(`${ENGINE_ID}/_raw/build`, { method: 'POST', body: 'x'.repeat(100) })
assert.equal(res.status, 413)
assert.equal(JSON.parse(res.body).data.code, 'RAW_REQUEST_TOO_LARGE')
state.error = dockerError('RAW_RESPONSE_TOO_LARGE')
res = await send(`${ENGINE_ID}/_raw/images/json`)
assert.equal(res.status, 502)
assert.equal(JSON.parse(res.body).data.code, 'RAW_RESPONSE_TOO_LARGE')
// the body fails after the headers: the response is cut
state.error = undefined
state.upstream = () => ({
statusCode: 200,
headers: { 'content-type': 'application/json' },
body: Readable.from(
(async function* () {
yield '[{"Id":"a"},'
await new Promise(resolve => setTimeout(resolve, 10))
throw dockerError('RAW_RESPONSE_TOO_LARGE')
})()
),
})
res = await send(`${ENGINE_ID}/_raw/containers/json`)
assert.equal(res.status, 200)
assert.ok(res.error !== undefined, 'the response is not complete')
assert.equal(res.body, '[{"Id":"a"},')
})
it('streamed responses are not buffered by compression (review 3)', async () => {
let push: ((chunk: string | null) => void) | undefined
state.upstream = () => {
const body = new Readable({ read() {} })
push = chunk => body.push(chunk)
return { statusCode: 200, headers: { 'content-type': 'application/json' }, body }
}
const first = await new Promise<{ headers: Record<string, unknown>; chunk: string }>((resolve, reject) => {
const req = httpRequest({
host: '127.0.0.1',
port,
path: `/rest/v0/docker-engines/${ENGINE_ID}/_raw/events`,
headers: { 'accept-encoding': 'gzip' },
})
req.on('response', res => {
const timer = setTimeout(() => {
req.destroy()
reject(new Error('no chunk within 1 s: the response is buffered'))
}, 1e3)
res.once('data', chunk => {
clearTimeout(timer)
resolve({ headers: res.headers, chunk: chunk.toString() })
req.destroy()
})
})
req.on('error', () => {})
req.end()
// one small event, the stream stays open
setTimeout(() => push!('{"status":"restart"}\n'), 50)
})
assert.equal(first.headers['content-encoding'], undefined)
assert.match(String(first.headers['cache-control']), /no-transform/)
assert.equal(first.chunk, '{"status":"restart"}\n')
})
it("the daemon's 401 and 407 are not passed through (review 3)", async () => {
for (const statusCode of [401, 407]) {
state.upstream = () => ({
statusCode,
headers: { 'content-type': 'application/json', 'www-authenticate': 'Basic realm="docker"' },
body: Readable.from(['{"message":"authentication required"}']),
})
const res = await send(`${ENGINE_ID}/_raw/images/json`)
assert.equal(res.status, 502, String(statusCode))
assert.equal(res.headers['www-authenticate'], undefined)
assert.deepEqual(JSON.parse(res.body).data, { code: 'DOCKER_API_ERROR', statusCode })
}
})
it('415 when the body was already consumed (form-encoded)', async () => {
const res = await send(`${ENGINE_ID}/_raw/containers/create`, {
method: 'POST',
headers: { 'content-type': 'application/x-www-form-urlencoded' },
body: 'Image=alpine',
})
assert.equal(res.status, 415)
assert.deepEqual(state.calls, [])
})
it('the upstream signal is aborted when the client disconnects mid-stream', async () => {
let push: ((chunk: string) => void) | undefined
state.upstream = () => {
const body = new Readable({ read() {} })
push = chunk => body.push(chunk)
return { statusCode: 200, headers: { 'content-type': 'application/json' }, body }
}
await new Promise<void>((resolve, reject) => {
const req = httpRequest({ host: '127.0.0.1', port, path: `/rest/v0/docker-engines/${ENGINE_ID}/_raw/events` })
req.on('response', res => {
res.once('data', () => {
// the client goes away while the stream is open
req.destroy()
resolve()
})
})
req.on('error', () => {})
req.end()
setTimeout(() => (push === undefined ? reject(new Error('no upstream call')) : push('{"status":"start"}\n')), 50)
})
const { signal } = state
assert.ok(signal !== undefined)
if (!signal.aborted) {
await new Promise((resolve, reject) => {
signal.addEventListener('abort', resolve)
setTimeout(() => reject(new Error('the upstream signal is not aborted')), 1e3)
})
}
})
it('SSH/Docker errors are mapped', async () => {
state.error = Object.assign(new Error('SSH authentication failed'), {
name: 'DockerError',
code: 'SSH_AUTH_FAILED',
})
const res = await send(`${ENGINE_ID}/_raw/version`)
assert.equal(res.status, 502)
assert.equal(JSON.parse(res.body).data.code, 'SSH_AUTH_FAILED')
})
})
describe('getRawPathSegments()', () => {
it('decodes the segments', () => {
assert.deepEqual(getRawPathSegments('images/foo%3Alatest/json'), ['images', 'foo:latest', 'json'])
assert.equal(getRawPathSegments('a/%2E'), undefined)
// (through express, an invalid encoding is already refused when decoding the route params)
assert.equal(getRawPathSegments('a/%zz'), undefined)
})
})
describe('through the external router, with the static OpenAPI spec', () => {
// eslint-disable-next-line @typescript-eslint/no-require-imports
const staticSpec = createRequire(import.meta.url)('../../open-api/spec/swagger.json') as OpenAPIV3.Document
const spec = structuredClone(staticSpec)
let routerServer: Server
let routerPort: number
before(async () => {
setupContainer(restApi.xoApp as unknown as XoApp)
const { mountExternalRoute, externalRouter } = createExternalRouter(spec)
mountDockerRawRoutes(mountExternalRoute, spec)
const app = express()
app.use('/rest/v0', externalRouter)
app.use(genericErrorHandler)
routerServer = createServer(app)
await new Promise<void>(resolve => routerServer.listen(0, '127.0.0.1', resolve))
routerPort = (routerServer.address() as { port: number }).port
})
after(() => new Promise<void>(resolve => routerServer.close(() => resolve())))
const get = async (path: string) =>
(await fetch(`http://127.0.0.1:${routerPort}/rest/v0/docker-engines/${path}`)).status
it('403 for a non-admin user, even with allowRawApi on', async () => {
state.allowRawApi = true
for (const permission of ['none', 'viewer', 'operator']) {
state.user = { id: 'u', email: 'u@example.org', permission }
assert.equal(await get(`${ENGINE_ID}/_raw/version`), 403, permission)
}
assert.deepEqual(state.calls, [])
state.user = { id: 'admin-id', email: 'admin@example.org', permission: 'admin' }
assert.equal(await get(`${ENGINE_ID}/_raw/version`), 200)
assert.equal(state.calls.length, 1)
})
it('the hand-written entry of tsoa.json (x-mcp-exposure deny) replaces the wildcard path', () => {
assert.equal(spec.paths[DOCKER_RAW_ENDPOINT], undefined)
const pathItem = spec.paths['/docker-engines/{id}/_raw/{path}'] as Record<string, Record<string, unknown>>
assert.deepEqual(Object.keys(pathItem), ['get', 'post', 'put', 'patch', 'delete'])
for (const operation of Object.values(pathItem)) {
assert.equal(operation['x-mcp-exposure'], 'deny')
assert.match(String(operation.operationId), /^DockerEngineRaw/)
assert.match(String(operation.description), /admin \(ACL v2 will add an acl check in addition/)
}
assert.deepEqual(
spec.paths['/docker-engines/{id}/_raw/{path}'],
staticSpec.paths['/docker-engines/{id}/_raw/{path}']
)
})
})

View File

@@ -0,0 +1,331 @@
import {
Body,
Delete,
Example,
Extension,
Get,
Middlewares,
Patch,
Path,
Post,
Query,
Request,
Response,
Route,
Security,
SuccessResponse,
Tags,
} from 'tsoa'
import { type Request as ExRequest, json } from 'express'
import { inject } from 'inversify'
import { provide } from 'inversify-binding-decorators'
import type {
XoDockerEngine,
XoDockerEngineInfo,
XoDockerEngineProperties,
XoDockerEngineTestResult,
} from '@vates/types'
import type { CreateDockerEngineBody, UpdateDockerEngineBody } from './docker-engine.type.mjs'
import {
asynchronousActionResp,
badGatewayResp,
badRequestResp,
createdResp,
featureUnauthorized,
gatewayTimeoutResp,
invalidParameters,
noContentResp,
notFoundResp,
serviceUnavailableResp,
tooManyRequestsResp,
unauthorizedResp,
type Unbrand,
} from '../open-api/common/response.common.mjs'
import {
dockerEngine,
dockerEngineId,
dockerEngineIds,
dockerEngineHostKeyUnknown,
dockerEngineInfo,
dockerEngineInfoAuthFailed,
dockerEngineTestFailure,
dockerEngineTestResult,
partialDockerEngines,
} from '../open-api/oa-examples/docker-engine.oa-example.mjs'
import { taskLocation } from '../open-api/oa-examples/task.oa-example.mjs'
import type { SendObjects } from '../helpers/helper.type.mjs'
import { withDockerErrors } from '../helpers/docker.helper.mjs'
import { dockerFeatureMiddleware } from '../middlewares/docker-feature.middleware.mjs'
import { XoController } from '../abstract-classes/xo-controller.mjs'
import type { CreateActionReturnType } from '../abstract-classes/base-controller.mjs'
import { RestApi } from '../rest-api/rest-api.mjs'
// v1: no `acl` middleware, so every route is admin-only (see the README's
// ACLs section): the stored credentials give root-equivalent access to the
// Docker hosts. The `// ACLs v2:` comments give the middleware to add with the
// `docker-engine` ACL resource.
@Route('docker-engines')
@Security('*')
@Middlewares(dockerFeatureMiddleware)
@Response(badRequestResp.status, badRequestResp.description)
@Response(unauthorizedResp.status, unauthorizedResp.description)
@Response(featureUnauthorized.status, featureUnauthorized.description)
@Tags('docker-engines')
@provide(DockerEngineController)
export class DockerEngineController extends XoController<XoDockerEngine> {
constructor(@inject(RestApi) restApi: RestApi) {
super('docker-engine', restApi)
}
// --- abstract methods
getAllCollectionObjects(): Promise<XoDockerEngine[]> {
return this.restApi.xoApp.getAllDockerEngines()
}
getCollectionObject(id: XoDockerEngine['id']): Promise<XoDockerEngine> {
return this.restApi.xoApp.getDockerEngine(id)
}
/**
* Configured Docker engines, without their secrets.
*
* Never connects: `connectionStatus` and `error` report the state of the
* pooled SSH connection. Filter on `$VM` to find the engine of a VM (an empty
* list means it has none).
*
* Required privilege:
* - admin (v2: resource: docker-engine, action: read)
*
* @example fields "id,$VM,label,connectionStatus"
* @example filter "$VM:c7b3b4bc-0000-4000-8000-00000000cafe"
* @example limit 42
*/
// ACLs v2: @Security('*', ['acl']) + sendObjects(…, { privilege: { action: 'read', resource: 'docker-engine' } })
@Example(dockerEngineIds)
@Example(partialDockerEngines)
@Extension('x-mcp-exposure', 'allow')
@Get('')
async getDockerEngines(
@Request() req: ExRequest,
@Query() fields?: string,
@Query() ndjson?: boolean,
@Query() markdown?: boolean,
@Query() filter?: string,
@Query() limit?: number
): Promise<SendObjects<Partial<Unbrand<XoDockerEngine>>>> {
return this.sendObjects(Object.values(await this.getObjects({ filter })), req, { limit })
}
/**
* Live information about the engine: connects (through the connection pool).
*
* Always answers 200 when the engine exists: `status` is `connected`, or
* `unreachable`, `auth-failed` or `host-key-mismatch` with an `error`.
*
* Required privilege:
* - admin (v2: resource: docker-engine, action: read)
*
* @example id "8d834412-eb40-4328-a815-3fcc0989bd07"
*/
// ACLs v2: acl({ resource: 'docker-engine', action: 'read', objectId: 'params.id', getObject: ({ restApi }) => restApi.xoApp.getDockerEngine })
@Example(dockerEngineInfo)
@Example(dockerEngineInfoAuthFailed)
@Extension('x-mcp-exposure', 'allow')
@Get('{id}/info')
@Response(notFoundResp.status, notFoundResp.description)
@Response(badGatewayResp.status, 'Docker API error of the daemon')
@Response(serviceUnavailableResp.status, 'Too many busy SSH connections, see the Retry-After header')
async getDockerEngineInfo(@Path() id: string): Promise<XoDockerEngineInfo> {
// not cached: three requests on the pooled connection, and an unreachable
// engine fails fast thanks to the pool's negative cache
return this.restApi.xoApp.getDockerEngineInfo(id as XoDockerEngine['id'])
}
/**
* The engine, without its secrets (`hasPassword` and `hasPrivateKey` tell
* which ones are set). Never connects.
*
* Required privilege:
* - admin (v2: resource: docker-engine, action: read)
*
* @example id "8d834412-eb40-4328-a815-3fcc0989bd07"
*/
// ACLs v2: acl({ resource: 'docker-engine', action: 'read', objectId: 'params.id', getObject: ({ restApi }) => restApi.xoApp.getDockerEngine })
@Example(dockerEngine)
@Extension('x-mcp-exposure', 'allow')
@Get('{id}')
@Response(notFoundResp.status, notFoundResp.description)
async getDockerEngine(@Path() id: string): Promise<Unbrand<XoDockerEngine>> {
return this.getObject(id as XoDockerEngine['id'])
}
/**
* Register a Docker engine reached through SSH.
*
* Connects first and saves nothing on failure.
*
* Host key: send the `hostKeyFingerprint` of the Docker host (`ssh-keygen -lf
* /etc/ssh/ssh_host_ed25519_key.pub` on it). Without it, answers 409 with the
* observed host key in `data` (`code: HOST_KEY_UNKNOWN`, `fingerprint`,
* `algorithm`) and saves nothing: once the user has checked it, send the
* same body again with `hostKeyFingerprint` set to that `fingerprint`. It is
* verified on connection, so a key which changed in between is refused (409
* `HOST_KEY_MISMATCH`).
*
* `acceptUnknownHostKey: true` (without `hostKeyFingerprint`) trusts and
* pins whatever key is presented: only for automation which cannot check it.
*
* After an SSH authentication failure, a refused host key or an aborted
* handshake, the same parameters are refused for `docker.authFailureCooldown`
* (default 10 s): 429 `SSH_COOLDOWN` with `Retry-After`, without connecting.
* Changed parameters are tried right away. `SSH_REFUSED_PENALTY` (502) means
* that the SSH server closed the connection before the handshake soon after
* failures: it may be temporarily refusing XO's address (OpenSSH
* PerSourcePenalties).
*
* The credentials are stored in the XO database, encrypted only if
* `redis.encryptCredentialDatabase` is enabled. Access to the Docker socket
* is equivalent to root on the Docker host.
*
* Always synchronous: the result (or the error) is the response.
*
* Required privilege:
* - admin (v2: resource: docker-engine, action: create)
*
* @example body {
* "$VM": "c7b3b4bc-0000-4000-8000-00000000cafe",
* "label": "Web server",
* "host": "192.168.1.42",
* "username": "xo",
* "privateKey": "-----BEGIN OPENSSH PRIVATE KEY-----\n…\n-----END OPENSSH PRIVATE KEY-----\n",
* "hostKeyFingerprint": "SHA256:G+4RawxzV+6SGkxauQY8Vqmu2KZ4ENCQu/YuxBIARDA"
* }
*/
// ACLs v2: acl({ resource: 'docker-engine', action: 'create', object: ({ req }) => req.body })
@Example(dockerEngineId)
@Extension('x-mcp-exposure', 'confirm')
@Post('')
@Middlewares(json())
@SuccessResponse(createdResp.status, createdResp.description)
@Response(notFoundResp.status, 'The VM does not exist')
@Response<{ error: string; data: Record<string, unknown> }>(
409,
'Unknown or mismatching SSH host key (see data.fingerprint), or the VM already has an engine',
dockerEngineHostKeyUnknown
)
@Response(invalidParameters.status, invalidParameters.description)
@Response(tooManyRequestsResp.status, 'SSH_COOLDOWN: the same parameters failed recently, see Retry-After')
@Response(badGatewayResp.status, 'SSH or Docker socket failure (see data.code, data.diagnostic)')
@Response(gatewayTimeoutResp.status, gatewayTimeoutResp.description)
async createDockerEngine(@Body() body: CreateDockerEngineBody): Promise<{ id: string }> {
// no task: its record (params, error) would be readable by every user with
// `task:read`
const engine = await this.restApi.xoApp.createDockerEngine(body as XoDockerEngineProperties)
return { id: engine.id }
}
/**
* Partial update: omitted properties are kept, `null` or `''` clears them
* (clearing `privateKey` also clears `passphrase`).
*
* Changing how to connect (host, port, username, password, privateKey,
* passphrase, socketPath, hostKeyFingerprint, or the VM when the address
* is resolved from it) connects first, verifying the host key with the new
* or the stored pin, and saves nothing on failure, with the errors of the
* creation: 409 `HOST_KEY_MISMATCH` (e.g. a wrong new `hostKeyFingerprint`),
* 502 `SSH_AUTH_FAILED` (e.g. a wrong new key), 502
* `DOCKER_SOCKET_UNREACHABLE` with `data.diagnostic`, 429 `SSH_COOLDOWN`…
* On success, the pooled connection is closed. Clearing
* `hostKeyFingerprint` (`null`) checks the host key like on creation: 409
* `HOST_KEY_UNKNOWN` with the observed `fingerprint`, to send back as
* `hostKeyFingerprint` (or `acceptUnknownHostKey: true`).
*
* Other changes (e.g. `label`) do not connect.
*
* Always synchronous.
*
* Required privilege:
* - admin (v2: resource: docker-engine, action: update)
*
* @example id "8d834412-eb40-4328-a815-3fcc0989bd07"
* @example body { "label": "Web server (prod)" }
*/
// ACLs v2: acl({ resource: 'docker-engine', action: 'update', objectId: 'params.id', getObject: ({ restApi }) => restApi.xoApp.getDockerEngine })
@Extension('x-mcp-exposure', 'confirm')
@Patch('{id}')
@Middlewares(json())
@SuccessResponse(noContentResp.status, noContentResp.description)
@Response(notFoundResp.status, notFoundResp.description)
@Response(409, 'Unknown or mismatching SSH host key (see data.fingerprint), or the VM already has an engine')
@Response(invalidParameters.status, invalidParameters.description)
@Response(tooManyRequestsResp.status, 'SSH_COOLDOWN: the same parameters failed recently, see Retry-After')
@Response(badGatewayResp.status, 'SSH or Docker socket failure (see data.code, data.diagnostic)')
@Response(gatewayTimeoutResp.status, gatewayTimeoutResp.description)
async updateDockerEngine(@Path() id: string, @Body() body: UpdateDockerEngineBody): Promise<void> {
// no task, see createDockerEngine()
await this.restApi.xoApp.updateDockerEngine(id as XoDockerEngine['id'], body as XoDockerEngineProperties)
}
/**
* Remove the engine from XO (nothing is changed on the Docker host), and
* close its connection.
*
* Required privilege:
* - admin (v2: resource: docker-engine, action: delete)
*
* @example id "8d834412-eb40-4328-a815-3fcc0989bd07"
*/
// ACLs v2: acl({ resource: 'docker-engine', action: 'delete', objectId: 'params.id', getObject: ({ restApi }) => restApi.xoApp.getDockerEngine })
@Extension('x-mcp-exposure', 'confirm')
@Delete('{id}')
@SuccessResponse(noContentResp.status, noContentResp.description)
@Response(notFoundResp.status, notFoundResp.description)
async deleteDockerEngine(@Path() id: string): Promise<void> {
// no task, see createDockerEngine()
await this.restApi.xoApp.deleteDockerEngine(id as XoDockerEngine['id'])
}
/**
* Check the connection with a new, non pooled, SSH connection.
*
* The result is never an error for connection problems: see `ok`, `error`,
* and `diagnostic` which tells apart the causes of a Docker socket which
* cannot be opened (missing socket, permission, forwarding disabled).
*
* Shortly after an authentication, host key or handshake failure of the
* engine, it is refused without connecting: 429 `SSH_COOLDOWN` with
* `Retry-After` (synchronous call).
*
* Required privilege:
* - admin (v2: resource: docker-engine, action: test)
*
* @example id "8d834412-eb40-4328-a815-3fcc0989bd07"
*/
// ACLs v2: acl({ resource: 'docker-engine', action: 'test', objectId: 'params.id', getObject: ({ restApi }) => restApi.xoApp.getDockerEngine })
@Example(taskLocation)
@Example(dockerEngineTestResult)
@Example(dockerEngineTestFailure)
@Extension('x-mcp-exposure', 'confirm')
@Post('{id}/actions/test')
@SuccessResponse(asynchronousActionResp.status, asynchronousActionResp.description)
@Response(200, 'Result of the test (synchronous call)')
@Response(notFoundResp.status, notFoundResp.description)
@Response(tooManyRequestsResp.status, 'SSH_COOLDOWN: a recent attempt failed, see Retry-After (synchronous call)')
async testDockerEngine(
@Path() id: string,
@Query() sync?: boolean
): CreateActionReturnType<XoDockerEngineTestResult> {
const engineId = id as XoDockerEngine['id']
// 404 before creating a task
await this.getObject(engineId)
return this.createAction<XoDockerEngineTestResult>(
() => withDockerErrors(() => this.restApi.xoApp.testDockerEngine(engineId)),
{
sync,
statusCode: 200,
// no body, so no params: the credentials are read from the database
taskProperties: { name: 'test Docker engine', objectId: engineId },
}
)
}
}

View File

@@ -0,0 +1,408 @@
import assert from 'node:assert/strict'
import { describe, it } from 'node:test'
import { serializeError } from '@vates/task'
import { noSuchObject } from 'xo-common/api-errors.js'
import { DockerEngineController } from './docker-engine.controller.mjs'
import { ApiError } from '../helpers/error.helper.mjs'
import { toDockerApiError } from '../helpers/docker.helper.mjs'
import genericErrorHandler from '../middlewares/generic-error-handler.middleware.mjs'
import type { RestApi } from '../rest-api/rest-api.mjs'
const ENGINE_ID = 'a1ea0bb5-f67d-4406-8d9b-6a4c2fa8c6ac'
const SECRETS = {
password: 'secret-password-value',
privateKey: '-----BEGIN OPENSSH PRIVATE KEY-----\nsecret-private-key-value\n-----END OPENSSH PRIVATE KEY-----\n',
passphrase: 'secret-passphrase-value',
}
class DockerError extends Error {
code: string
data?: Record<string, unknown>
constructor(code: string, message: string, data?: Record<string, unknown>) {
super(message)
this.name = 'DockerError'
this.code = code
this.data = data
}
}
const engine = {
id: ENGINE_ID,
port: 22,
username: 'xo',
socketPath: '/var/run/docker.sock',
hasPassword: true,
hasPrivateKey: true,
connectionStatus: 'idle',
}
type Task = { id: string; properties: Record<string, unknown>; result?: unknown }
// what the Tasks mixin of xo-server records on failure (`@vates/task`): the
// error itself if it has a `toJSON()`, otherwise `serializeError(error)`
const recordError = (error: unknown) => (error instanceof Error && !('toJSON' in error) ? serializeError(error) : error)
function setup({ xoApp: xoAppOverrides = {} }: { xoApp?: object } = {}) {
const calls: { method: string; args: unknown[] }[] = []
const tasks: Task[] = []
const record =
(method: string, result: (...args: unknown[]) => unknown) =>
async (...args: unknown[]) => {
calls.push({ method, args })
return result(...args)
}
const xoApp = {
getAllDockerEngines: record('getAllDockerEngines', () => [engine]),
getDockerEngine: record('getDockerEngine', id => {
if (id !== ENGINE_ID) {
throw noSuchObject(id, 'docker-engine')
}
return engine
}),
createDockerEngine: record('createDockerEngine', () => engine),
updateDockerEngine: record('updateDockerEngine', () => engine),
deleteDockerEngine: record('deleteDockerEngine', () => undefined),
getDockerEngineInfo: record('getDockerEngineInfo', () => ({ status: 'connected', asOf: 0 })),
testDockerEngine: record('testDockerEngine', () => ({ ok: true, fingerprint: 'SHA256:x' })),
...xoAppOverrides,
}
const restApi = {
xoApp,
getCurrentUser: () => ({ id: 'admin', permission: 'admin' }),
tasks: {
create: (properties: Record<string, unknown>) => {
const task: Task = { id: `task-${tasks.length}`, properties }
tasks.push(task)
return {
id: task.id,
set: (name: string, value: unknown) => {
properties[name] = value
},
run: async (fn: () => unknown) => {
try {
return (task.result = await fn())
} catch (error) {
task.result = recordError(error)
throw error
}
},
}
},
},
} as unknown as RestApi
const controller = new DockerEngineController(restApi)
return { calls, controller, tasks }
}
const CONNECTION_CONTEXT = { host: '192.0.2.1', port: 2222, socketPath: '/run/user/1000/docker.sock' }
// everything a task record could persist, readable with task:read
const assertNoSecrets = (tasks: Task[]) => {
assert.ok(tasks.length > 0)
const serialized = JSON.stringify(tasks.map(({ properties, result }) => ({ properties, result })))
for (const [name, value] of Object.entries(SECRETS)) {
assert.equal(serialized.includes(value), false, `${name} found in a task record`)
}
// not even a fragment
assert.equal(serialized.includes('secret-'), false, 'a fragment of a secret found in a task record')
for (const [name, value] of Object.entries(CONNECTION_CONTEXT)) {
assert.equal(serialized.includes(String(value)), false, `${name} found in a task record`)
}
assert.equal(serialized.includes('"cause"'), false, 'the raw error found in a task record')
}
// what the client receives, through the generic error handler
function respond(error: unknown) {
const res = {
status: 0,
headers: {} as Record<string, string>,
body: undefined as unknown,
}
const fakeRes = {
headersSent: false,
setHeader: (name: string, value: string) => (res.headers[name] = value),
status: (code: number) => {
res.status = code
return fakeRes
},
json: (value: unknown) => (res.body = value),
}
genericErrorHandler(error, { method: 'POST', path: '/docker-engines' } as never, fakeRes as never, () => {})
return res
}
describe('DockerEngineController', () => {
describe('create, update and delete: no task, whose record would be readable with task:read', () => {
it('create', async () => {
const { calls, controller, tasks } = setup()
const body = { host: '192.0.2.1', username: 'xo', ...SECRETS, hostKeyFingerprint: 'SHA256:x' }
assert.deepEqual(await controller.createDockerEngine(body), { id: ENGINE_ID })
// the mixin gets the real secrets
assert.deepEqual(calls, [{ method: 'createDockerEngine', args: [body] }])
assert.deepEqual(tasks, [])
})
it('create which fails: the HTTP answer is the error (TOFU 409 with the observed fingerprint)', async () => {
const error = new DockerError('HOST_KEY_UNKNOWN', 'unknown host key', {
host: '192.0.2.1',
port: 22,
fingerprint: 'SHA256:x',
algorithm: 'ssh-ed25519',
})
const { controller, tasks } = setup({
xoApp: {
createDockerEngine: async () => {
throw error
},
},
})
await assert.rejects(controller.createDockerEngine({ username: 'xo', host: 'h', ...SECRETS }), _ => _ === error)
assert.deepEqual(tasks, [])
assert.deepEqual(respond(error), {
status: 409,
headers: {},
body: {
error: 'unknown host key',
data: { code: 'HOST_KEY_UNKNOWN', fingerprint: 'SHA256:x', algorithm: 'ssh-ed25519' },
},
})
})
it('create or update with a VM which does not exist: 404', async () => {
const vmId = 'c7b3b4bc-0000-4000-8000-00000000dead'
const throwNoSuchVm = async () => noSuchObject(vmId, 'VM')
const { controller } = setup({ xoApp: { createDockerEngine: throwNoSuchVm, updateDockerEngine: throwNoSuchVm } })
for (const call of [
() => controller.createDockerEngine({ $VM: vmId, username: 'xo' }),
() => controller.updateDockerEngine(ENGINE_ID, { $VM: vmId }),
]) {
await assert.rejects(call(), error => {
assert.equal(respond(error).status, 404)
return true
})
}
})
it('update', async () => {
const { calls, controller, tasks } = setup()
const body = { privateKey: SECRETS.privateKey, passphrase: SECRETS.passphrase, password: null }
await controller.updateDockerEngine(ENGINE_ID, body)
assert.deepEqual(calls, [{ method: 'updateDockerEngine', args: [ENGINE_ID, body] }])
assert.deepEqual(tasks, [])
})
it('update which fails to connect: the error of the creation', async () => {
for (const [code, status] of [
['SSH_AUTH_FAILED', 502],
['HOST_KEY_MISMATCH', 409],
['SSH_COOLDOWN', 429],
] as const) {
const error = new DockerError(code, code, { retryAfter: 3 })
const { controller, tasks } = setup({
xoApp: {
updateDockerEngine: async () => {
throw error
},
},
})
await assert.rejects(
controller.updateDockerEngine(ENGINE_ID, { privateKey: SECRETS.privateKey }),
_ => _ === error
)
assert.deepEqual(tasks, [])
const res = respond(error)
assert.equal(res.status, status, code)
assert.equal((res.body as { data: { code: string } }).data.code, code)
}
})
it('delete', async () => {
const { calls, controller, tasks } = setup()
await controller.deleteDockerEngine(ENGINE_ID)
assert.deepEqual(calls, [{ method: 'deleteDockerEngine', args: [ENGINE_ID] }])
assert.deepEqual(tasks, [])
})
})
it('test which fails: the task record holds the mapped error, without connection context', async () => {
const { controller, tasks } = setup({
xoApp: {
testDockerEngine: async () => {
throw new DockerError('TIMEOUT', 'timed out', { ...CONNECTION_CONTEXT, timeout: 30e3 })
},
},
})
await assert.rejects(controller.testDockerEngine(ENGINE_ID, true), ApiError)
assertNoSecrets(tasks)
assert.deepEqual(JSON.parse(JSON.stringify(tasks[0].result)), {
code: 'TIMEOUT',
timeout: 30e3,
message: 'timed out',
})
})
it('test: no secrets in the task record', async () => {
const { controller, tasks } = setup()
assert.deepEqual(await controller.testDockerEngine(ENGINE_ID, true), { ok: true, fingerprint: 'SHA256:x' })
assertNoSecrets(tasks)
assert.equal(tasks[0].properties.params, undefined)
})
it('test: 404 before creating a task', async () => {
const { controller, tasks } = setup()
await assert.rejects(controller.testDockerEngine('nope'), noSuchObject.is)
assert.deepEqual(tasks, [])
})
it('info: connection problems are a status, not an HTTP error', async () => {
const info = { status: 'auth-failed', asOf: 1, error: { code: 'SSH_AUTH_FAILED', message: 'x' } }
const { controller } = setup({ xoApp: { getDockerEngineInfo: async () => info } })
assert.deepEqual(await controller.getDockerEngineInfo(ENGINE_ID), info)
})
})
describe('toDockerApiError()', () => {
const statusOf = (code: string, data?: Record<string, unknown>) =>
(toDockerApiError(new DockerError(code, 'message', data)) as ApiError).status
it('maps the DockerError codes to HTTP statuses', () => {
assert.equal(statusOf('HOST_KEY_UNKNOWN'), 409)
assert.equal(statusOf('HOST_KEY_MISMATCH'), 409)
// never 401: it would make the browser prompt for XO credentials
assert.equal(statusOf('SSH_AUTH_FAILED'), 502)
assert.equal(statusOf('SSH_UNREACHABLE'), 502)
assert.equal(statusOf('SSH_ERROR'), 502)
assert.equal(statusOf('SSH_REFUSED_PENALTY'), 502)
assert.equal(statusOf('SSH_COOLDOWN', { retryAfter: 7 }), 429)
assert.equal(statusOf('DOCKER_SOCKET_UNREACHABLE'), 502)
assert.equal(statusOf('STREAM_LOCAL_UNSUPPORTED'), 502)
assert.equal(statusOf('DOCKER_API_VERSION_UNSUPPORTED'), 502)
assert.equal(statusOf('TIMEOUT'), 504)
assert.equal(statusOf('POOL_EXHAUSTED'), 503)
assert.equal(statusOf('CONNECTION_CLOSED'), 503)
assert.equal(statusOf('DOCKER_API_ERROR', { statusCode: 409 }), 409)
assert.equal(statusOf('DOCKER_API_ERROR', { statusCode: 500 }), 502)
assert.equal(statusOf('DOCKER_API_ERROR'), 502)
})
it("never passes the daemon's authentication errors through, only an allowlist of 4xx (review 3)", () => {
for (const statusCode of [400, 404, 409]) {
assert.equal(statusOf('DOCKER_API_ERROR', { statusCode }), statusCode)
}
// 401/407 would make a browser or a proxy prompt for credentials, 403
// would look like a missing XO permission
for (const statusCode of [401, 403, 405, 406, 407, 413, 418, 429, 451, 499]) {
const error = toDockerApiError(new DockerError('DOCKER_API_ERROR', 'nope', { statusCode })) as ApiError
assert.equal(error.status, 502, String(statusCode))
assert.equal(error.data?.statusCode, statusCode, 'the upstream status is kept in data')
}
})
it('DOCKER_API_ERROR: only code, statusCode and a truncated message reach the client (review 3)', () => {
const message = 'x'.repeat(10e3)
const error = toDockerApiError(
new DockerError('DOCKER_API_ERROR', message, {
host: '192.0.2.1',
port: 2222,
socketPath: '/run/user/1000/docker.sock',
path: '/containers/abc/json',
statusCode: 404,
message,
})
) as ApiError
assert.equal(error.status, 404)
assert.deepEqual(Object.keys(error.data!).sort(), ['code', 'message', 'statusCode'])
assert.equal(error.data!.code, 'DOCKER_API_ERROR')
assert.equal(error.data!.statusCode, 404)
assert.ok((error.data!.message as string).length <= 1024)
assert.ok(error.message.length <= 1024)
assert.doesNotMatch(JSON.stringify({ message: error.message, data: error.data }), /192\.0\.2\.1|2222|docker\.sock/)
})
it('other errors: the connection context (host, port, socketPath, path) is not copied (review 3)', () => {
const error = toDockerApiError(
new DockerError('TIMEOUT', 'timed out', {
host: '192.0.2.1',
port: 2222,
socketPath: '/run/user/1000/docker.sock',
path: '/containers/abc/json',
timeout: 30e3,
})
) as ApiError
assert.deepEqual(error.data, { code: 'TIMEOUT', timeout: 30e3 })
const hostKey = toDockerApiError(
new DockerError('HOST_KEY_UNKNOWN', 'unknown', {
host: '192.0.2.1',
port: 22,
fingerprint: 'SHA256:x',
algorithm: 'ssh-ed25519',
})
) as ApiError
assert.deepEqual(hostKey.data, { code: 'HOST_KEY_UNKNOWN', fingerprint: 'SHA256:x', algorithm: 'ssh-ed25519' })
})
it('keeps the data, with the code', () => {
const error = toDockerApiError(
new DockerError('DOCKER_SOCKET_UNREACHABLE', 'message', { diagnostic: { code: 'socket-missing' } })
) as ApiError
assert.equal(error.message, 'message')
assert.deepEqual(error.data, { code: 'DOCKER_SOCKET_UNREACHABLE', diagnostic: { code: 'socket-missing' } })
})
it('other errors are returned as is', () => {
let error: unknown
try {
// xo-common's factories throw
noSuchObject('x', 'docker-engine')
} catch (_error) {
error = _error
}
assert.ok(noSuchObject.is(error))
assert.equal(toDockerApiError(error), error)
const plain = Object.assign(new Error('x'), { code: 'SSH_AUTH_FAILED' })
assert.equal(toDockerApiError(plain), plain)
})
it('POOL_EXHAUSTED: 503 with a Retry-After header', () => {
const headers: Record<string, string> = {}
let status: number | undefined
let body: unknown
const res = {
headersSent: false,
setHeader: (name: string, value: string) => (headers[name] = value),
status: (code: number) => {
status = code
return res
},
json: (value: unknown) => (body = value),
}
// mapped by the generic error handler itself
genericErrorHandler(
new DockerError('POOL_EXHAUSTED', 'too many connections'),
{ method: 'GET', path: '/docker-engines/x/info' } as never,
res as never,
() => {}
)
assert.equal(status, 503)
assert.deepEqual(headers, { 'Retry-After': '5' })
assert.deepEqual(body, { error: 'too many connections', data: { code: 'POOL_EXHAUSTED' } })
})
it('SSH_COOLDOWN: 429 with Retry-After from data.retryAfter (fixes)', () => {
const error = toDockerApiError(
new DockerError('SSH_COOLDOWN', 'retry in 7 s', { retryAfter: 7, lastCode: 'SSH_AUTH_FAILED' })
) as ApiError & { headers?: Record<string, string> }
assert.equal(error.status, 429)
assert.deepEqual(error.data, { code: 'SSH_COOLDOWN', retryAfter: 7, lastCode: 'SSH_AUTH_FAILED' })
const headers: Record<string, string> = {}
const res = {
headersSent: false,
setHeader: (name: string, value: string) => (headers[name] = value),
status: () => res,
json: () => {},
}
genericErrorHandler(error, { method: 'POST', path: '/docker-engines' } as never, res as never, () => {})
assert.deepEqual(headers, { 'Retry-After': '7' })
})
})

View File

@@ -0,0 +1,57 @@
/**
* SSH connection to a Docker host
*
* The SSH user must be able to read and write the Docker socket (e.g. be in
* the `docker` group): this is equivalent to root access on the Docker host.
*/
export interface CreateDockerEngineBody {
/** VM running the engine, required without `host` */
$VM?: string
label?: string
/** SSH host, without it the address is resolved from the VM's reported addresses */
host?: string
/** SSH port, default 22 */
port?: number
username: string
/** a password or a private key is required */
password?: string
/** OpenSSH or PEM private key */
privateKey?: string
passphrase?: string
/** default `/var/run/docker.sock` (rootless Docker: `/run/user/<uid>/docker.sock`) */
socketPath?: string
/**
* `SHA256:…` as printed by `ssh-keygen -lf /etc/ssh/ssh_host_ed25519_key.pub`
* on the Docker host, or the `fingerprint` of a 409 `HOST_KEY_UNKNOWN` answer
* once checked. Verified on connection.
*/
hostKeyFingerprint?: string
/**
* without `hostKeyFingerprint`: trust and pin whatever host key is presented
* (never stored). Prefer sending the checked fingerprint.
*/
acceptUnknownHostKey?: boolean
}
/**
* Omitted properties are kept, `null` or `''` clears them (`port` and
* `socketPath` are reset to their defaults)
*/
export interface UpdateDockerEngineBody {
$VM?: string | null
label?: string | null
host?: string | null
port?: number | null
username?: string
password?: string | null
privateKey?: string | null
passphrase?: string | null
socketPath?: string | null
/**
* replaces the pinned key, verified by connecting before saving; `null`
* clears it: the host key is then checked like on creation
*/
hostKeyFingerprint?: string | null
/** see the creation */
acceptUnknownHostKey?: boolean
}

View File

@@ -0,0 +1,146 @@
import { createLogger } from '@xen-orchestra/log'
import type { HttpStatusCodeLiteral } from 'tsoa'
import { ApiError } from './error.helper.mjs'
const log = createLogger('xo:rest-api:docker')
/**
* Shape of the `DockerError`s thrown by xo-server's Docker transport
* (`@xen-orchestra/docker-ssh`, which is not a dependency of this package):
* they are recognized by their name and string code.
*/
type DockerErrorLike = Error & { code: string; data?: Record<string, unknown> }
const isDockerError = (error: unknown): error is DockerErrorLike =>
error instanceof Error && error.name === 'DockerError' && typeof (error as { code?: unknown }).code === 'string'
function getRetryAfter(error: DockerErrorLike): string | undefined {
switch (error.code) {
case 'POOL_EXHAUSTED':
// the pool is full of busy connections: the client should retry soon
return '5'
case 'SSH_COOLDOWN': {
const retryAfter = error.data?.retryAfter
return String(typeof retryAfter === 'number' && retryAfter > 0 ? Math.ceil(retryAfter) : 1)
}
}
}
// Docker Engine API statuses of errors of the request: 400 bad parameter,
// 404 no such object, 409 conflict (e.g. already paused, in use)
const PASSED_THROUGH_STATUSES = new Set([400, 404, 409])
// the connection context added by xo-server to its errors: logged here, never
// sent to the client
const CONTEXT_FIELDS = new Set(['host', 'port', 'socketPath', 'path'])
// same as xo-server's `MAX_ERROR_MESSAGE_LENGTH`
const MAX_MESSAGE_LENGTH = 512
function truncateMessage(message: string): string {
return message.length > MAX_MESSAGE_LENGTH ? message.slice(0, MAX_MESSAGE_LENGTH) + '…' : message
}
function getClientData(error: DockerErrorLike): Record<string, unknown> {
const data = error.data ?? {}
if (error.code === 'DOCKER_API_ERROR') {
// written by the daemon: only what the client needs
const { statusCode, message } = data
return {
code: error.code,
statusCode: typeof statusCode === 'number' ? statusCode : undefined,
message: typeof message === 'string' ? truncateMessage(message) : undefined,
}
}
return { ...Object.fromEntries(Object.entries(data).filter(([key]) => !CONTEXT_FIELDS.has(key))), code: error.code }
}
function getStatus(error: DockerErrorLike): HttpStatusCodeLiteral {
switch (error.code) {
case 'HOST_KEY_UNKNOWN':
case 'HOST_KEY_MISMATCH':
return 409
case 'TIMEOUT':
return 504
case 'SSH_COOLDOWN':
// refused locally: a recent attempt with the same parameters failed
return 429
case 'POOL_EXHAUSTED':
case 'CONNECTION_CLOSED':
return 503
case 'RAW_REQUEST_TOO_LARGE':
// raw passthrough, docker.maxRawRequestSize
return 413
case 'DOCKER_API_ERROR': {
const statusCode = error.data?.statusCode
// errors of the request (e.g. 409 pausing a paused container) are passed
// through, only the ones in the allowlist: a 401/407 from the daemon (or
// a proxy in front of it) would make the browser prompt for credentials
// and a 403 would look like a missing XO permission. Every other status
// is the upstream's fault, `data.statusCode` keeps it.
return typeof statusCode === 'number' && PASSED_THROUGH_STATUSES.has(statusCode)
? (statusCode as HttpStatusCodeLiteral)
: 502
}
default:
// SSH_* (including SSH_REFUSED_PENALTY), STREAM_LOCAL_*, DOCKER_SOCKET_UNREACHABLE,
// DOCKER_API_VERSION_UNSUPPORTED…
//
// never 401 (`invalidCredentials`): the credentials rejected are the
// Docker host's, not the XO user's, and a 401 would make the browser
// prompt for XO credentials
return 502
}
}
/**
* Convert a `DockerError` to an `ApiError` with the right HTTP status, other
* errors are returned as is.
*
* `data.code` is the Docker error code. For `DOCKER_API_ERROR`, only the
* upstream `statusCode` and the (truncated) `message` are added; for the
* others, the properties of its `data` (e.g. the observed `fingerprint` of
* `HOST_KEY_UNKNOWN`, the socket `diagnostic`) are kept, except the connection
* context (`host`, `port`, `socketPath`, `path`), which is only logged. They
* never contain secrets: xo-server scrubs them.
*/
export function toDockerApiError(error: unknown): unknown {
if (!isDockerError(error)) {
return error
}
const status = getStatus(error)
const retryAfter = getRetryAfter(error)
// the full error, with its context, stays in the server logs
if (status >= 500) {
log.warn(error.message, { error })
} else {
log.debug(error.message, { error })
}
const message = truncateMessage(error.message)
const data = getClientData(error)
const apiError = new ApiError(message, status, {
data,
headers: retryAfter === undefined ? undefined : { 'Retry-After': retryAfter },
})
// no `cause`, and a `toJSON()`: the record of a failed task (`@vates/task`
// serializes an error without `toJSON()` with its `cause` and enumerable
// properties, the data of an ApiError is private) is readable with
// `task:read`, it gets what the client would get, never the raw error and its
// connection context
return Object.assign(apiError, { toJSON: () => ({ ...data, message }) })
}
/**
* Run `fn`, converting the `DockerError`s it throws, see `toDockerApiError()`.
*
* Only needed in the actions of tasks: their records keep the error as thrown,
* whereas the other errors are converted by the generic error handler.
*/
export async function withDockerErrors<T>(fn: () => Promise<T>): Promise<T> {
try {
return await fn()
} catch (error) {
throw toDockerApiError(error)
}
}

View File

@@ -3,11 +3,20 @@ import { HttpStatusCodeLiteral } from 'tsoa'
export class ApiError extends Error {
#status: HttpStatusCodeLiteral
#data?: Record<string, unknown>
#headers?: Record<string, string>
constructor(message: string, status: HttpStatusCodeLiteral, opts: { data?: Record<string, unknown> } = {}) {
/**
* @param opts.headers response headers, e.g. `Retry-After`
*/
constructor(
message: string,
status: HttpStatusCodeLiteral,
opts: { data?: Record<string, unknown>; headers?: Record<string, string> } = {}
) {
super(message)
this.#status = status
this.#data = opts.data
this.#headers = opts.headers
}
get status() {
@@ -17,4 +26,8 @@ export class ApiError extends Error {
get data() {
return this.#data
}
get headers() {
return this.#headers
}
}

View File

@@ -13,6 +13,7 @@ import { mcpGateMiddleware } from './middlewares/mcp-gate.middleware.mjs'
import { type OpenAPIV3 } from 'openapi-types'
import { createExternalRouter, sendObjects } from './router/external-router.mjs'
import { BASE_URL } from './helpers/utils.helper.mjs'
import { mountDockerRawRoutes } from './docker-engines/docker-engine-raw.routes.mjs'
export { sendObjects }
@@ -60,6 +61,10 @@ export default function setupRestApi(express: Express, xoApp: XoApp) {
express.use(BASE_URL, externalRouter)
// raw Docker Engine API passthrough (admin only, disabled by default), a
// wildcard route: not a tsoa controller
mountDockerRawRoutes(mountExternalRoute, swaggerOpenApiSpec)
express.get(`${BASE_URL}/docs/swagger.json`, (_req, res) => {
res.setHeader('Content-Type', 'application/json')
res.json(swaggerOpenApiSpec)

View File

@@ -19,6 +19,7 @@ import { SrService } from '../srs/sr.service.mjs'
import { LicenseService } from '../licenses/license.service.mjs'
import { BackupRepositoryService } from '../backup-repositories/backup-repository.service.mjs'
import { V2vService } from '../v2v/v2v.service.mjs'
import { DockerContainerService } from '../docker-containers/docker-container.service.mjs'
const iocContainer = new Container()
@@ -154,6 +155,14 @@ export function setupContainer(xoApp: XoApp) {
return new V2vService(restApi)
})
.inSingletonScope()
iocContainer
.bind(DockerContainerService)
.toDynamicValue(ctx => {
const restApi = ctx.container.get(RestApi)
return new DockerContainerService(restApi)
})
.inSingletonScope()
}
export { iocContainer }

View File

@@ -0,0 +1,16 @@
import type { NextFunction, Request, Response } from 'express'
import { iocContainer } from '../ioc/ioc.mjs'
import { RestApi } from '../rest-api/rest-api.mjs'
/**
* Class-level middleware of the Docker controllers, before the handler and the
* route middlewares (body parsing, acl): an unlicensed XOA must not store
* credentials nor open SSH sessions.
*/
export function dockerFeatureMiddleware(_req: Request, _res: Response, next: NextFunction): void {
iocContainer
.get(RestApi)
.xoApp.checkFeatureAuthorization('DOCKER')
.then(() => next(), next)
}

View File

@@ -0,0 +1,94 @@
import assert from 'node:assert/strict'
import { createServer, type Server } from 'node:http'
import { after, before, describe, it } from 'node:test'
import express from 'express'
import { featureUnauthorized } from 'xo-common/api-errors.js'
import type { XoApp } from '@vates/types'
import { RegisterRoutes } from '../open-api/routes/routes.js'
import { setupContainer } from '../ioc/ioc.mjs'
import genericErrorHandler from './generic-error-handler.middleware.mjs'
const state = { licensed: false, dockerCalls: [] as string[] }
// records every access to a Docker method of xo-server
const xoApp = new Proxy(
{
apiContext: { user: { id: 'admin', permission: 'admin' } },
config: { getOptional: () => undefined },
checkFeatureAuthorization: async (feature: string) => {
assert.equal(feature, 'DOCKER')
if (!state.licensed) {
throw featureUnauthorized({ featureCode: feature })
}
},
getAllDockerEngines: async () => [],
},
{
get(target, name) {
if (typeof name === 'string' && name.includes('Docker')) {
state.dockerCalls.push(name)
}
return target[name as keyof typeof target]
},
}
) as unknown as XoApp
let server: Server
let baseUrl: string
before(async () => {
setupContainer(xoApp)
const app = express()
RegisterRoutes(app)
app.use(genericErrorHandler)
server = createServer(app)
await new Promise<void>(resolve => server.listen(0, '127.0.0.1', resolve))
baseUrl = `http://127.0.0.1:${(server.address() as { port: number }).port}/rest/v0`
})
after(() => new Promise<void>(resolve => server.close(() => resolve())))
const ENGINE_ID = 'a1ea0bb5-f67d-4406-8d9b-6a4c2fa8c6ac'
const CONTAINER_ID = `${ENGINE_ID}_${'ab'.repeat(32)}`
describe('dockerFeatureMiddleware', () => {
it('unlicensed: 403 on every Docker route, before any Docker method of xo-server', async () => {
state.licensed = false
state.dockerCalls = []
for (const [method, path, body] of [
['GET', '/docker-engines'],
['GET', `/docker-engines/${ENGINE_ID}`],
['GET', `/docker-engines/${ENGINE_ID}/info`],
// before the body is even parsed or validated
['POST', '/docker-engines', { host: 'h', username: 'xo', password: 'secret' }],
['PATCH', `/docker-engines/${ENGINE_ID}`, { label: 'x' }],
['DELETE', `/docker-engines/${ENGINE_ID}`],
['POST', `/docker-engines/${ENGINE_ID}/actions/test?sync=true`],
['GET', `/docker-containers?filter=${encodeURIComponent('$VM:x')}`],
['GET', `/docker-containers/${CONTAINER_ID}`],
['GET', `/docker-containers/${CONTAINER_ID}/logs`],
['GET', `/docker-containers/${CONTAINER_ID}/stats`],
['POST', `/docker-containers/${CONTAINER_ID}/actions/start`],
['DELETE', `/docker-containers/${CONTAINER_ID}`],
] as const) {
const res = await fetch(baseUrl + path, {
method,
headers: body === undefined ? {} : { 'content-type': 'application/json' },
body: body === undefined ? undefined : JSON.stringify(body),
})
assert.equal(res.status, 403, `${method} ${path}`)
assert.equal(((await res.json()) as { data: { featureCode: string } }).data.featureCode, 'DOCKER')
}
assert.deepEqual(state.dockerCalls, [])
})
it('licensed: the handler is reached', async () => {
state.licensed = true
state.dockerCalls = []
const res = await fetch(`${baseUrl}/docker-engines`)
assert.equal(res.status, 200)
assert.deepEqual(await res.json(), [])
assert.deepEqual(state.dockerCalls, ['getAllDockerEngines'])
})
})

View File

@@ -15,6 +15,7 @@ import type { HttpStatusCodeLiteral } from 'tsoa'
import { NextFunction, Request, Response } from 'express'
import { ApiError } from '../helpers/error.helper.mjs'
import { toDockerApiError } from '../helpers/docker.helper.mjs'
import type { XoError } from '../helpers/helper.type.mjs'
const log = createLogger('xo:rest-api:error-handler')
@@ -22,6 +23,9 @@ const log = createLogger('xo:rest-api:error-handler')
// must have 4 parameters to be recognized as an error middleware by express
// eslint-disable-next-line @typescript-eslint/no-unused-vars
export default function genericErrorHandler(error: unknown, req: Request, res: Response, _next: NextFunction) {
// DockerErrors of xo-server's Docker transport to ApiErrors
error = toDockerApiError(error)
if (!(error instanceof Error)) {
log.error(JSON.stringify(error))
res.status(500).json({ error })
@@ -36,6 +40,11 @@ export default function genericErrorHandler(error: unknown, req: Request, res: R
if (error instanceof ApiError) {
statusCode = error.status
if (error.headers !== undefined && !res.headersSent) {
for (const [name, value] of Object.entries(error.headers)) {
res.setHeader(name, value)
}
}
} else if (noSuchObject.is(error)) {
statusCode = 404
} else if (unauthorized.is(error) || forbiddenOperation.is(error)) {

View File

@@ -81,3 +81,23 @@ export const incorrectStateResp = {
status: 409,
description: 'Incorrect state',
} as const
export const badGatewayResp = {
status: 502,
description: 'Bad gateway, a remote system (e.g. a Docker host) failed or cannot be reached',
} as const
export const serviceUnavailableResp = {
status: 503,
description: 'Service unavailable, retry later',
} as const
export const tooManyRequestsResp = {
status: 429,
description: 'Too many requests, see the Retry-After header',
} as const
export const gatewayTimeoutResp = {
status: 504,
description: 'Gateway timeout, a remote system (e.g. a Docker host) did not answer in time',
} as const

View File

@@ -0,0 +1,123 @@
// Real payloads, captured from xo-server run from the sources against a rootless
// dockerd 29.8.1 reached through OpenSSH 10.0 (phase 3 end-to-end run of the
// Docker integration, rerun after the review fixes). Lists are shortened.
export const dockerContainerIds = [
'/rest/v0/docker-containers/8d834412-eb40-4328-a815-3fcc0989bd07_40ce479c34637ad31b8ecd460d7d14aa0e2ed90dd73187afa6b284170418f1d5',
'/rest/v0/docker-containers/8d834412-eb40-4328-a815-3fcc0989bd07_e35120a9e4facc5f42d55f464be996b1f47cdaa7c433d6a045857aab28d45c4d',
]
export const partialDockerContainers = [
{
name: 'xo-redis',
state: 'running',
status: 'Up 3 hours',
image: 'redis:alpine',
href: '/rest/v0/docker-containers/8d834412-eb40-4328-a815-3fcc0989bd07_40ce479c34637ad31b8ecd460d7d14aa0e2ed90dd73187afa6b284170418f1d5',
},
{
name: 'demo-web-1',
state: 'running',
status: 'Up 4 hours',
image: 'nginx:alpine',
href: '/rest/v0/docker-containers/8d834412-eb40-4328-a815-3fcc0989bd07_e35120a9e4facc5f42d55f464be996b1f47cdaa7c433d6a045857aab28d45c4d',
},
{
name: 'demo-cache-1',
state: 'running',
status: 'Up 4 hours (healthy)',
image: 'redis:alpine',
href: '/rest/v0/docker-containers/8d834412-eb40-4328-a815-3fcc0989bd07_21c685423c29ddad1a7ba038fdc57f89f12a922310f65cd0f4fe2f2b245db8fa',
},
]
export const dockerContainer = {
id: '8d834412-eb40-4328-a815-3fcc0989bd07_1b5d79f4a1c9275c5f9e1fc50629ea85ca807fe1c70f03e528e35f4b6ce1963e',
$engine: '8d834412-eb40-4328-a815-3fcc0989bd07',
dockerId: '1b5d79f4a1c9275c5f9e1fc50629ea85ca807fe1c70f03e528e35f4b6ce1963e',
name: 'xo-nginx',
image: 'nginx:alpine',
imageId: 'sha256:1ed1b0e1d7652937d6cbdaf4018c7b6fc009a7dd6c3047351e2eddda745de43f',
command: "/docker-entrypoint.sh nginx -g 'daemon off;'",
createdAt: 1790269461978,
state: 'running',
status: 'Up 2 hours',
ports: [
{
privatePort: 80,
protocol: 'tcp',
publicPort: 8080,
ip: '0.0.0.0',
},
],
labels: {
maintainer: 'NGINX Docker Maintainers <docker-maint@nginx.com>',
'xo-test': 'fixture',
},
networks: [
{
name: 'bridge',
ipAddress: '172.17.0.2',
},
],
mounts: [],
startedAt: 1790277033015,
finishedAt: 1790277031960,
oomKilled: false,
restartPolicy: {
name: 'no',
maximumRetryCount: 0,
},
restartCount: 0,
tty: false,
hostname: '1b5d79f4a1c9',
workingDir: '/',
}
export const dockerContainerLogs = {
entries: [
{
stream: 'stderr',
timestamp: '2026-09-24T19:10:33.469963395Z',
message: '2026/09/24 19:10:33 [notice] 1#1: start worker process 25',
},
{
stream: 'stderr',
timestamp: '2026-09-24T19:10:33.471748246Z',
message: '2026/09/24 19:10:33 [notice] 1#1: start worker process 26',
},
{
stream: 'stderr',
timestamp: '2026-09-24T19:10:33.471765867Z',
message: '2026/09/24 19:10:33 [notice] 1#1: start worker process 27',
},
{
stream: 'stdout',
timestamp: '2026-09-24T19:10:35.422548641Z',
message: '172.17.0.1 - - [24/Sep/2026:19:10:35 +0000] "GET / HTTP/1.1" 200 896 "-" "curl/8.14.1" "-"',
},
{
stream: 'stdout',
timestamp: '2026-09-24T21:29:31.366260426Z',
message: '172.17.0.1 - - [24/Sep/2026:21:29:31 +0000] "GET / HTTP/1.1" 200 896 "-" "curl/8.14.1" "-"',
},
],
truncated: false,
timedOut: false,
asOf: 1790285371392,
}
// xo-nginx running a busy loop, phase 4 end-to-end run (one full CPU = 100)
export const dockerContainerStats = {
sampledAt: 1790299585403,
cpuPercent: 101.81180487804878,
onlineCpus: 6,
memoryUsage: 6746112,
memoryLimit: 5157838848,
memoryPercent: 0.1307933845706689,
networkRx: 816,
networkTx: 126,
blockRead: null,
blockWrite: null,
pids: 9,
}

View File

@@ -0,0 +1,120 @@
// Real payloads, captured from xo-server run from the sources against a rootless
// dockerd 29.8.1 reached through OpenSSH 10.0 (phase 3 end-to-end run of the
// Docker integration, rerun after the review fixes). Lists are shortened.
export const dockerEngineId = {
id: '8d834412-eb40-4328-a815-3fcc0989bd07',
}
export const dockerEngineIds = ['/rest/v0/docker-engines/8d834412-eb40-4328-a815-3fcc0989bd07']
export const partialDockerEngines = [
{
id: '8d834412-eb40-4328-a815-3fcc0989bd07',
label: 'local rootless',
connectionStatus: 'idle',
href: '/rest/v0/docker-engines/8d834412-eb40-4328-a815-3fcc0989bd07',
},
]
export const dockerEngine = {
id: '8d834412-eb40-4328-a815-3fcc0989bd07',
label: 'local rootless',
host: '127.0.0.1',
port: 2298,
username: 'docker',
socketPath: '/run/user/1000/docker.sock',
hostKeyFingerprint: 'SHA256:G+4RawxzV+6SGkxauQY8Vqmu2KZ4ENCQu/YuxBIARDA',
hostKeyAlgorithm: 'ssh-ed25519',
resolvedHost: '127.0.0.1',
hasPassword: false,
hasPrivateKey: true,
kind: 'docker',
connectionStatus: 'idle',
}
export const dockerEngineInfo = {
status: 'connected',
kind: 'docker',
asOf: 1790285367714,
daemonId: '00000000-0000-4000-8000-000000000000',
name: 'docker-host',
engineVersion: '29.8.1',
apiVersion: '1.43',
minApiVersion: '1.40',
operatingSystem: 'Debian GNU/Linux 13 (trixie)',
osType: 'linux',
kernelVersion: '6.12.101+deb13-amd64',
architecture: 'x86_64',
cpus: 6,
memory: 5157838848,
storageDriver: 'overlayfs',
loggingDriver: 'json-file',
cgroupDriver: 'systemd',
cgroupVersion: '2',
rootless: true,
containers: {
total: 9,
running: 6,
paused: 1,
stopped: 2,
},
images: 3,
warnings: ['WARNING: No cpuset support', 'WARNING: No io.weight support'],
daemonApiVersion: '1.56',
compose: {
projects: [
{
name: 'demo',
containers: 2,
running: 2,
},
],
},
}
export const dockerEngineInfoAuthFailed = {
status: 'auth-failed',
asOf: 1790285380191,
error: {
code: 'SSH_AUTH_FAILED',
message: 'SSH authentication failed',
data: {
host: '127.0.0.1',
port: 2298,
socketPath: '/run/user/1000/docker.sock',
},
},
}
export const dockerEngineTestResult = {
ok: true,
apiVersion: '1.43',
engineVersion: '29.8.1',
fingerprint: 'SHA256:G+4RawxzV+6SGkxauQY8Vqmu2KZ4ENCQu/YuxBIARDA',
algorithm: 'ssh-ed25519',
}
export const dockerEngineTestFailure = {
ok: false,
fingerprint: 'SHA256:G+4RawxzV+6SGkxauQY8Vqmu2KZ4ENCQu/YuxBIARDA',
algorithm: 'ssh-ed25519',
error: {
code: 'SSH_AUTH_FAILED',
message: 'SSH authentication failed',
data: {
host: '127.0.0.1',
port: 2298,
socketPath: '/run/user/1000/docker.sock',
},
},
}
export const dockerEngineHostKeyUnknown = {
error: 'the SSH host key is unknown',
data: {
fingerprint: 'SHA256:G+4RawxzV+6SGkxauQY8Vqmu2KZ4ENCQu/YuxBIARDA',
algorithm: 'ssh-ed25519',
code: 'HOST_KEY_UNKNOWN',
},
}

View File

@@ -77,6 +77,361 @@
"tags": ["docs"],
"x-mcp-exposure": "deny"
}
},
"/docker-engines/{id}/_raw/{path}": {
"get": {
"operationId": "DockerEngineRawGet",
"description": "Raw Docker Engine API passthrough (`{path}` is the Docker API path, which may contain `/` and a query string, e.g. `images/json?all=1`; it is prefixed with the negotiated API version unless it starts with `v<version>/`). Docker's answer is returned as is (status and body), with only the `api-version`, `content-length`, `content-type`, `docker-experimental` and `ostype` headers.\n\nThe whole request, response included, is limited to `docker.rawRequestTimeout` (default 5 minutes, 504 before the response, otherwise the response is cut). Responses are never compressed (`Cache-Control: no-transform`), so that streams (e.g. `events`) arrive as they come. A 401 or 407 from the daemon is answered with a 502 (`data.statusCode`), never passed through.\n\nDisabled by default (501): `[docker] allowRawApi = true` in xo-server's configuration. It grants unrestricted access to the Docker daemon of the guest, which is equivalent to root on that guest: every call is logged.\n\nOnly the `accept`, `content-type` and `content-length` request headers are forwarded. The request body is limited to `docker.maxRawRequestSize` (413) and the response to `docker.maxRawResponseSize` (502 when announced by `content-length`, otherwise the response is cut). Attach, exec start and connection upgrades are refused (501), as are `.`/`..` segments and encoded slashes (400). HEAD is supported through GET.\n\nRequired privilege:\n- admin (ACL v2 will add an acl check in addition to the admin check)",
"tags": ["docker-engines"],
"security": [
{
"*": []
}
],
"parameters": [
{
"in": "path",
"name": "id",
"required": true,
"schema": {
"type": "string"
},
"example": "8d834412-eb40-4328-a815-3fcc0989bd07"
},
{
"in": "path",
"name": "path",
"required": true,
"description": "Docker Engine API path (may contain `/`)",
"schema": {
"type": "string"
},
"example": "images/json"
}
],
"responses": {
"200": {
"description": "Docker's answer (any status is passed through, except 401 and 407: 502)"
},
"400": {
"description": "Invalid Docker API path"
},
"401": {
"description": "Authentication required"
},
"403": {
"description": "Not an administrator, or DOCKER feature not authorized"
},
"404": {
"description": "Unknown engine"
},
"413": {
"description": "Request body larger than docker.maxRawRequestSize"
},
"501": {
"description": "Disabled (docker.allowRawApi), or attach/exec start/upgrade"
},
"502": {
"description": "SSH or Docker failure (see data.code), or response larger than docker.maxRawResponseSize"
},
"503": {
"description": "Too many busy SSH connections or streams"
},
"504": {
"description": "No response within docker.rawRequestTimeout"
}
},
"x-mcp-exposure": "deny"
},
"post": {
"operationId": "DockerEngineRawPost",
"description": "Raw Docker Engine API passthrough (`{path}` is the Docker API path, which may contain `/` and a query string, e.g. `images/json?all=1`; it is prefixed with the negotiated API version unless it starts with `v<version>/`). Docker's answer is returned as is (status and body), with only the `api-version`, `content-length`, `content-type`, `docker-experimental` and `ostype` headers.\n\nThe whole request, response included, is limited to `docker.rawRequestTimeout` (default 5 minutes, 504 before the response, otherwise the response is cut). Responses are never compressed (`Cache-Control: no-transform`), so that streams (e.g. `events`) arrive as they come. A 401 or 407 from the daemon is answered with a 502 (`data.statusCode`), never passed through.\n\nDisabled by default (501): `[docker] allowRawApi = true` in xo-server's configuration. It grants unrestricted access to the Docker daemon of the guest, which is equivalent to root on that guest: every call is logged.\n\nOnly the `accept`, `content-type` and `content-length` request headers are forwarded. The request body is limited to `docker.maxRawRequestSize` (413) and the response to `docker.maxRawResponseSize` (502 when announced by `content-length`, otherwise the response is cut). Attach, exec start and connection upgrades are refused (501), as are `.`/`..` segments and encoded slashes (400). HEAD is supported through GET.\n\nRequired privilege:\n- admin (ACL v2 will add an acl check in addition to the admin check)",
"tags": ["docker-engines"],
"security": [
{
"*": []
}
],
"parameters": [
{
"in": "path",
"name": "id",
"required": true,
"schema": {
"type": "string"
},
"example": "8d834412-eb40-4328-a815-3fcc0989bd07"
},
{
"in": "path",
"name": "path",
"required": true,
"description": "Docker Engine API path (may contain `/`)",
"schema": {
"type": "string"
},
"example": "images/json"
}
],
"requestBody": {
"required": false,
"content": {
"application/json": {
"schema": {}
},
"application/octet-stream": {
"schema": {}
}
}
},
"responses": {
"200": {
"description": "Docker's answer (any status is passed through, except 401 and 407: 502)"
},
"400": {
"description": "Invalid Docker API path"
},
"401": {
"description": "Authentication required"
},
"403": {
"description": "Not an administrator, or DOCKER feature not authorized"
},
"404": {
"description": "Unknown engine"
},
"413": {
"description": "Request body larger than docker.maxRawRequestSize"
},
"501": {
"description": "Disabled (docker.allowRawApi), or attach/exec start/upgrade"
},
"502": {
"description": "SSH or Docker failure (see data.code), or response larger than docker.maxRawResponseSize"
},
"503": {
"description": "Too many busy SSH connections or streams"
},
"504": {
"description": "No response within docker.rawRequestTimeout"
}
},
"x-mcp-exposure": "deny"
},
"put": {
"operationId": "DockerEngineRawPut",
"description": "Raw Docker Engine API passthrough (`{path}` is the Docker API path, which may contain `/` and a query string, e.g. `images/json?all=1`; it is prefixed with the negotiated API version unless it starts with `v<version>/`). Docker's answer is returned as is (status and body), with only the `api-version`, `content-length`, `content-type`, `docker-experimental` and `ostype` headers.\n\nThe whole request, response included, is limited to `docker.rawRequestTimeout` (default 5 minutes, 504 before the response, otherwise the response is cut). Responses are never compressed (`Cache-Control: no-transform`), so that streams (e.g. `events`) arrive as they come. A 401 or 407 from the daemon is answered with a 502 (`data.statusCode`), never passed through.\n\nDisabled by default (501): `[docker] allowRawApi = true` in xo-server's configuration. It grants unrestricted access to the Docker daemon of the guest, which is equivalent to root on that guest: every call is logged.\n\nOnly the `accept`, `content-type` and `content-length` request headers are forwarded. The request body is limited to `docker.maxRawRequestSize` (413) and the response to `docker.maxRawResponseSize` (502 when announced by `content-length`, otherwise the response is cut). Attach, exec start and connection upgrades are refused (501), as are `.`/`..` segments and encoded slashes (400). HEAD is supported through GET.\n\nRequired privilege:\n- admin (ACL v2 will add an acl check in addition to the admin check)",
"tags": ["docker-engines"],
"security": [
{
"*": []
}
],
"parameters": [
{
"in": "path",
"name": "id",
"required": true,
"schema": {
"type": "string"
},
"example": "8d834412-eb40-4328-a815-3fcc0989bd07"
},
{
"in": "path",
"name": "path",
"required": true,
"description": "Docker Engine API path (may contain `/`)",
"schema": {
"type": "string"
},
"example": "images/json"
}
],
"requestBody": {
"required": false,
"content": {
"application/json": {
"schema": {}
},
"application/octet-stream": {
"schema": {}
}
}
},
"responses": {
"200": {
"description": "Docker's answer (any status is passed through, except 401 and 407: 502)"
},
"400": {
"description": "Invalid Docker API path"
},
"401": {
"description": "Authentication required"
},
"403": {
"description": "Not an administrator, or DOCKER feature not authorized"
},
"404": {
"description": "Unknown engine"
},
"413": {
"description": "Request body larger than docker.maxRawRequestSize"
},
"501": {
"description": "Disabled (docker.allowRawApi), or attach/exec start/upgrade"
},
"502": {
"description": "SSH or Docker failure (see data.code), or response larger than docker.maxRawResponseSize"
},
"503": {
"description": "Too many busy SSH connections or streams"
},
"504": {
"description": "No response within docker.rawRequestTimeout"
}
},
"x-mcp-exposure": "deny"
},
"patch": {
"operationId": "DockerEngineRawPatch",
"description": "Raw Docker Engine API passthrough (`{path}` is the Docker API path, which may contain `/` and a query string, e.g. `images/json?all=1`; it is prefixed with the negotiated API version unless it starts with `v<version>/`). Docker's answer is returned as is (status and body), with only the `api-version`, `content-length`, `content-type`, `docker-experimental` and `ostype` headers.\n\nThe whole request, response included, is limited to `docker.rawRequestTimeout` (default 5 minutes, 504 before the response, otherwise the response is cut). Responses are never compressed (`Cache-Control: no-transform`), so that streams (e.g. `events`) arrive as they come. A 401 or 407 from the daemon is answered with a 502 (`data.statusCode`), never passed through.\n\nDisabled by default (501): `[docker] allowRawApi = true` in xo-server's configuration. It grants unrestricted access to the Docker daemon of the guest, which is equivalent to root on that guest: every call is logged.\n\nOnly the `accept`, `content-type` and `content-length` request headers are forwarded. The request body is limited to `docker.maxRawRequestSize` (413) and the response to `docker.maxRawResponseSize` (502 when announced by `content-length`, otherwise the response is cut). Attach, exec start and connection upgrades are refused (501), as are `.`/`..` segments and encoded slashes (400). HEAD is supported through GET.\n\nRequired privilege:\n- admin (ACL v2 will add an acl check in addition to the admin check)",
"tags": ["docker-engines"],
"security": [
{
"*": []
}
],
"parameters": [
{
"in": "path",
"name": "id",
"required": true,
"schema": {
"type": "string"
},
"example": "8d834412-eb40-4328-a815-3fcc0989bd07"
},
{
"in": "path",
"name": "path",
"required": true,
"description": "Docker Engine API path (may contain `/`)",
"schema": {
"type": "string"
},
"example": "images/json"
}
],
"requestBody": {
"required": false,
"content": {
"application/json": {
"schema": {}
},
"application/octet-stream": {
"schema": {}
}
}
},
"responses": {
"200": {
"description": "Docker's answer (any status is passed through, except 401 and 407: 502)"
},
"400": {
"description": "Invalid Docker API path"
},
"401": {
"description": "Authentication required"
},
"403": {
"description": "Not an administrator, or DOCKER feature not authorized"
},
"404": {
"description": "Unknown engine"
},
"413": {
"description": "Request body larger than docker.maxRawRequestSize"
},
"501": {
"description": "Disabled (docker.allowRawApi), or attach/exec start/upgrade"
},
"502": {
"description": "SSH or Docker failure (see data.code), or response larger than docker.maxRawResponseSize"
},
"503": {
"description": "Too many busy SSH connections or streams"
},
"504": {
"description": "No response within docker.rawRequestTimeout"
}
},
"x-mcp-exposure": "deny"
},
"delete": {
"operationId": "DockerEngineRawDelete",
"description": "Raw Docker Engine API passthrough (`{path}` is the Docker API path, which may contain `/` and a query string, e.g. `images/json?all=1`; it is prefixed with the negotiated API version unless it starts with `v<version>/`). Docker's answer is returned as is (status and body), with only the `api-version`, `content-length`, `content-type`, `docker-experimental` and `ostype` headers.\n\nThe whole request, response included, is limited to `docker.rawRequestTimeout` (default 5 minutes, 504 before the response, otherwise the response is cut). Responses are never compressed (`Cache-Control: no-transform`), so that streams (e.g. `events`) arrive as they come. A 401 or 407 from the daemon is answered with a 502 (`data.statusCode`), never passed through.\n\nDisabled by default (501): `[docker] allowRawApi = true` in xo-server's configuration. It grants unrestricted access to the Docker daemon of the guest, which is equivalent to root on that guest: every call is logged.\n\nOnly the `accept`, `content-type` and `content-length` request headers are forwarded. The request body is limited to `docker.maxRawRequestSize` (413) and the response to `docker.maxRawResponseSize` (502 when announced by `content-length`, otherwise the response is cut). Attach, exec start and connection upgrades are refused (501), as are `.`/`..` segments and encoded slashes (400). HEAD is supported through GET.\n\nRequired privilege:\n- admin (ACL v2 will add an acl check in addition to the admin check)",
"tags": ["docker-engines"],
"security": [
{
"*": []
}
],
"parameters": [
{
"in": "path",
"name": "id",
"required": true,
"schema": {
"type": "string"
},
"example": "8d834412-eb40-4328-a815-3fcc0989bd07"
},
{
"in": "path",
"name": "path",
"required": true,
"description": "Docker Engine API path (may contain `/`)",
"schema": {
"type": "string"
},
"example": "images/json"
}
],
"responses": {
"200": {
"description": "Docker's answer (any status is passed through, except 401 and 407: 502)"
},
"400": {
"description": "Invalid Docker API path"
},
"401": {
"description": "Authentication required"
},
"403": {
"description": "Not an administrator, or DOCKER feature not authorized"
},
"404": {
"description": "Unknown engine"
},
"413": {
"description": "Request body larger than docker.maxRawRequestSize"
},
"501": {
"description": "Disabled (docker.allowRawApi), or attach/exec start/upgrade"
},
"502": {
"description": "SSH or Docker failure (see data.code), or response larger than docker.maxRawResponseSize"
},
"503": {
"description": "Too many busy SSH connections or streams"
},
"504": {
"description": "No response within docker.rawRequestTimeout"
}
},
"x-mcp-exposure": "deny"
}
}
}
}

View File

@@ -1,17 +1,7 @@
<template>
<MenuList :placement>
<template #trigger="{ open }">
<UiButton
v-if="isInPanel"
variant="tertiary"
accent="brand"
size="medium"
left-icon="action:change-state"
@click="open($event)"
>
{{ t('action:change-state') }}
</UiButton>
<UiDropdownButton v-else variant="secondary" size="medium" icon="action:change-state" @click="open($event)">
<UiDropdownButton variant="secondary" size="medium" icon="action:change-state" @click="open($event)">
{{ t('action:change-state') }}
</UiDropdownButton>
</template>
@@ -21,11 +11,8 @@
<script lang="ts" setup>
import MenuList from '@core/components/menu/MenuList.vue'
import UiButton from '@core/components/ui/button/UiButton.vue'
import UiDropdownButton from '@core/components/ui/dropdown-button/UiDropdownButton.vue'
import { IK_PANEL_ACTIONS } from '@core/utils/injection-keys.util.ts'
import type { Options } from 'placement.js'
import { inject } from 'vue'
import { useI18n } from 'vue-i18n'
const { placement = 'bottom-end' } = defineProps<{
@@ -37,6 +24,4 @@ defineSlots<{
}>()
const { t } = useI18n()
const isInPanel = inject(IK_PANEL_ACTIONS, undefined) !== undefined
</script>

View File

@@ -1,21 +1,14 @@
<template>
<UiModal :accent :icon @confirm="isConfirmed && emit('confirm')" @dismiss="emit('cancel')">
<UiModal :accent :icon @confirm="emit('confirm')" @dismiss="emit('cancel')">
<template #title>
<span>{{ modalTexts.title }}</span>
</template>
<template #content>
<div class="vts-action-modal">
<p v-if="modalTexts.message">{{ modalTexts.message }}</p>
<VtsTypeToConfirmInput
v-if="confirmationText !== undefined"
v-model="isTypedTextConfirmed"
:confirmation-text
/>
</div>
<span v-if="modalTexts.message">{{ modalTexts.message }}</span>
</template>
<template #buttons>
<VtsOverlayCancelButton @click="emit('cancel')">{{ t('action:go-back') }}</VtsOverlayCancelButton>
<VtsOverlayConfirmButton :disabled="!isConfirmed">
<VtsOverlayConfirmButton>
{{ modalTexts.action }}
</VtsOverlayConfirmButton>
</template>
@@ -25,13 +18,11 @@
<script lang="ts" setup>
import VtsOverlayCancelButton from '@core/components/overlay/VtsOverlayCancelButton.vue'
import VtsOverlayConfirmButton from '@core/components/overlay/VtsOverlayConfirmButton.vue'
import VtsTypeToConfirmInput from '@core/components/type-to-confirm-input/VtsTypeToConfirmInput.vue'
import type { ModalAccent } from '@core/components/ui/modal/UiModal.vue'
import UiModal from '@core/components/ui/modal/UiModal.vue'
import type { IconName } from '@core/icons'
import { useMapper } from '@core/packages/mapper/use-mapper.ts'
import type { ActionsByObject, HostActions, ObjectType, VmActions } from '@core/types/object.type.ts'
import { computed, ref } from 'vue'
import { useI18n } from 'vue-i18n'
type ActionTexts = {
@@ -47,28 +38,21 @@ type TextMappingByObject = {
type VtsActionModalVmProps = {
object: 'vm'
action: VmActions
vmCount: number
vmName: string
hostName?: never
}
type VtsActionModalHostProps = {
object: 'host'
action: HostActions
vmCount?: never
vmName?: never
hostName: string
}
const {
action,
object,
vmCount = 1,
hostName,
confirmationText,
} = defineProps<
const { action, object, vmName, hostName } = defineProps<
(VtsActionModalVmProps | VtsActionModalHostProps) & {
accent: ModalAccent
icon: IconName
confirmationText?: string
}
>()
@@ -87,24 +71,24 @@ const { t } = useI18n()
const textMappingsByObject: TextMappingByObject = {
vm: {
'force-reboot': {
title: t('modal:vm-force-reboot-title', { n: vmCount }),
message: t('modal:vm-force-reboot-message', { n: vmCount }),
action: t('action:force-reboot-n-vms', { n: vmCount }),
title: t('modal:confirm-vm-force-reboot?', { vm: vmName }),
message: t('modal:vm-force-reboot-message'),
action: t('modal:action:vm-force-reboot'),
},
'force-shutdown': {
title: t('modal:vm-force-shutdown-title', { n: vmCount }),
message: t('modal:vm-force-shutdown-message', { n: vmCount }),
action: t('action:force-shutdown-n-vms', { n: vmCount }),
title: t('modal:confirm-vm-force-shutdown?', { vm: vmName }),
message: t('modal:vm-force-shutdown-message'),
action: t('modal:action:vm-force-shutdown'),
},
reboot: {
title: t('modal:vm-reboot-title', { n: vmCount }),
message: t('modal:vm-reboot-message', { n: vmCount }),
action: t('action:reboot-n-vms', { n: vmCount }),
title: t('modal:confirm-vm-reboot?', { vm: vmName }),
message: t('modal:vm-reboot-message'),
action: t('modal:action:vm-reboot'),
},
shutdown: {
title: t('modal:vm-shutdown-title', { n: vmCount }),
message: t('modal:vm-shutdown-message', { n: vmCount }),
action: t('action:shutdown-n-vms', { n: vmCount }),
title: t('modal:confirm-vm-shutdown?', { vm: vmName }),
message: t('modal:vm-shutdown-message'),
action: t('modal:action:vm-shutdown'),
},
},
host: {
@@ -175,16 +159,4 @@ const modalTexts = useMapper(
() => textMappingsByObject[object] as Record<ActionsByObject[ObjectType], ActionTexts>,
() => defaultActionByObject[object]
)
const isTypedTextConfirmed = ref(false)
const isConfirmed = computed(() => confirmationText === undefined || isTypedTextConfirmed.value)
</script>
<style lang="postcss" scoped>
.vts-action-modal {
display: flex;
flex-direction: column;
gap: 2.4rem;
}
</style>

View File

@@ -7,7 +7,9 @@
<template #content>
<div class="vts-type-to-confirm-modal">
<p v-if="description">{{ description }}</p>
<VtsTypeToConfirmInput v-model="isConfirmed" :confirmation-text />
<p class="instruction">{{ t('type-below-to-continue') }}</p>
<UiTag :accent class="confirmation-text" variant="primary">{{ displayedConfirmationText }}</UiTag>
<UiInput v-model="typedText" accent="brand" />
</div>
</template>
@@ -23,14 +25,15 @@
<script lang="ts" setup>
import VtsOverlayCancelButton from '@core/components/overlay/VtsOverlayCancelButton.vue'
import VtsOverlayConfirmButton from '@core/components/overlay/VtsOverlayConfirmButton.vue'
import VtsTypeToConfirmInput from '@core/components/type-to-confirm-input/VtsTypeToConfirmInput.vue'
import UiInput from '@core/components/ui/input/UiInput.vue'
import type { ModalAccent } from '@core/components/ui/modal/UiModal.vue'
import UiModal from '@core/components/ui/modal/UiModal.vue'
import UiTag from '@core/components/ui/tag/UiTag.vue'
import type { IconName } from '@core/icons'
import { ref } from 'vue'
import { computed, ref } from 'vue'
import { useI18n } from 'vue-i18n'
defineProps<{
const { confirmationText } = defineProps<{
accent: ModalAccent
title: string
confirmationText: string
@@ -46,7 +49,11 @@ const emit = defineEmits<{
const { t } = useI18n()
const isConfirmed = ref(false)
const typedText = ref('')
const displayedConfirmationText = computed(() => `[${confirmationText}]`)
const isConfirmed = computed(() => typedText.value === confirmationText)
</script>
<style lang="postcss" scoped>
@@ -54,5 +61,13 @@ const isConfirmed = ref(false)
display: flex;
flex-direction: column;
gap: 2.4rem;
.instruction {
color: var(--color-neutral-txt-secondary);
}
.confirmation-text {
align-self: center;
}
}
</style>

View File

@@ -8,15 +8,30 @@
:id
v-model="filter"
:accent="isUsable ? 'brand' : 'danger'"
:busy
:aria-label="uiStore.isSmall ? t('query-builder:label') : undefined"
:placeholder="t('query-builder:placeholder')"
enterkeyhint="search"
clearable
@clear="emit('search', '')"
@keydown.enter="handleEnterKey($event)"
/>
</div>
<UiButtonIcon
v-if="uiStore.isSmallOrMedium"
icon="fa:magnifying-glass"
size="medium"
accent="brand"
@click="search()"
/>
<template v-else>
<UiButton size="medium" accent="brand" variant="secondary" @click="search()">
{{ t('action:search') }}
</UiButton>
<VtsDivider type="stretch" />
</template>
<VtsQueryBuilderButton
v-model="rootGroup"
:small="uiStore.isSmallOrMedium"
@@ -28,7 +43,10 @@
</template>
<script setup lang="ts">
import VtsDivider from '@core/components/divider/VtsDivider.vue'
import VtsQueryBuilderButton from '@core/components/query-builder/VtsQueryBuilderButton.vue'
import UiButton from '@core/components/ui/button/UiButton.vue'
import UiButtonIcon from '@core/components/ui/button-icon/UiButtonIcon.vue'
import UiInput from '@core/components/ui/input/UiInput.vue'
import type { QueryBuilderSchema } from '@core/packages/query-builder/types.ts'
import { useQueryBuilder } from '@core/packages/query-builder/use-query-builder.ts'
@@ -38,11 +56,10 @@ import { useI18n } from 'vue-i18n'
const { schema } = defineProps<{
schema: QueryBuilderSchema
busy?: boolean
}>()
const emit = defineEmits<{
search: []
search: [filter: string]
}>()
const filter = defineModel<string>({ required: true })
@@ -55,9 +72,13 @@ const id = useId()
const { rootGroup, isUsable, updateFilter, resetFilter } = useQueryBuilder(filter, () => schema)
function search() {
emit('search', filter.value)
}
function confirmQueryBuilder() {
updateFilter()
emit('search')
emit('search', rootGroup.value.rawFilter)
}
function handleEnterKey(event: KeyboardEvent) {
@@ -67,7 +88,7 @@ function handleEnterKey(event: KeyboardEvent) {
}
event.preventDefault()
emit('search')
search()
}
</script>
@@ -85,10 +106,6 @@ function handleEnterKey(event: KeyboardEvent) {
}
}
.label {
color: var(--color-neutral-txt-secondary);
}
.input-container {
flex: 1;
min-width: 0;

View File

@@ -1,17 +0,0 @@
<template>
<p class="vts-required-hint typo-body-regular-small">{{ t('field:required') }}</p>
</template>
<script lang="ts" setup>
import { useI18n } from 'vue-i18n'
const { t } = useI18n()
</script>
<style lang="postcss" scoped>
.vts-required-hint::before {
content: '*';
margin-right: 0.4rem;
color: var(--color-info-txt-base);
}
</style>

View File

@@ -1,91 +0,0 @@
<template>
<div ref="rootRef" class="vts-filter-select">
<UiDropdownButton ref="triggerRef" :disabled="isDisabled" :icon :selected="isOpen" size="small" variant="primary">
<slot />
</UiDropdownButton>
<template v-if="isOpen">
<VtsBackdrop />
<UiDropdownList ref="dropdownRef" :style="floatingStyles" class="dropdown-list">
<template #before>
<div class="select-all-buttons">
<UiButton accent="brand" size="small" variant="tertiary" @click="toggleSelectAll(true)">
{{ t('action:select-all') }}
</UiButton>
<UiButton accent="brand" size="small" variant="tertiary" @click="toggleSelectAll(false)">
{{ t('action:deselect-all') }}
</UiButton>
</div>
</template>
<template v-for="option of options" :key="option.id">
<slot name="option" :option="option as FormSelectIdToOption<TSelectId>">
<VtsOption :option />
</slot>
</template>
</UiDropdownList>
</template>
</div>
</template>
<script generic="TSelectId extends FormSelectId" lang="ts" setup>
import VtsBackdrop from '@core/components/backdrop/VtsBackdrop.vue'
import VtsOption from '@core/components/select/VtsOption.vue'
import UiButton from '@core/components/ui/button/UiButton.vue'
import UiDropdownList from '@core/components/ui/dropdown/UiDropdownList.vue'
import UiDropdownButton from '@core/components/ui/dropdown-button/UiDropdownButton.vue'
import type { IconName } from '@core/icons'
import {
type FormSelect,
type FormSelectId,
type FormSelectIdToOption,
useFormSelectController,
} from '@core/packages/form-select'
import { inject } from 'vue'
import { useI18n } from 'vue-i18n'
const { id } = defineProps<{
id: TSelectId
icon?: IconName
}>()
defineSlots<{
default(): any
option?(props: { option: FormSelectIdToOption<TSelectId> }): any
}>()
const { t } = useI18n()
const select = inject(id)
if (!select) {
throw new Error(`No select configuration has been found for this ID`)
}
const { options, isDisabled } = select as FormSelect
const { rootRef, triggerRef, dropdownRef, isOpen, floatingStyles } = useFormSelectController(select as FormSelect)
function toggleSelectAll(value: boolean) {
options.value.filter(option => !option.properties.disabled).forEach(option => option.toggleFlag('selected', value))
}
</script>
<style lang="postcss" scoped>
.vts-filter-select {
display: inline-block;
}
.dropdown-list {
max-height: 36.2rem;
overflow: auto;
z-index: 1020;
.select-all-buttons {
display: flex;
gap: 0.8rem;
padding: 0.4rem;
background: var(--color-neutral-background-secondary);
}
}
</style>

View File

@@ -1,127 +1,29 @@
<!-- v2 -->
<!-- v1.0 -->
<template>
<div class="tab-list">
<div ref="list" class="list">
<div ref="tabs" class="tabs" role="tablist" :aria-label="label">
<slot />
</div>
</div>
<template v-for="direction in SCROLL_DIRECTIONS" :key="direction">
<div v-if="canScroll[direction]" :class="direction" class="scroll-button-container">
<UiButtonIcon
class="scroll-button"
accent="brand"
:icon="`fa:angle-${direction}`"
size="small"
:target-scale="1"
tabindex="-1"
aria-hidden="true"
@click="scrollTabs(direction)"
/>
</div>
</template>
<slot />
</div>
</template>
<script lang="ts" setup>
import UiButtonIcon from '@core/components/ui/button-icon/UiButtonIcon.vue'
import { useDisabled } from '@core/composables/disabled.composable.ts'
import { useTabListNavigation } from '@core/composables/tab-list-navigation.composable.ts'
import { useResizeObserver, useScroll } from '@vueuse/core'
import { computed, useTemplateRef } from 'vue'
const { label, disabled } = defineProps<{
label?: string
const props = defineProps<{
disabled?: boolean
}>()
const SCROLL_DIRECTIONS = ['left', 'right'] as const
const SCROLL_STEP_RATIO = 0.8
useDisabled(() => disabled)
const list = useTemplateRef('list')
const tabs = useTemplateRef('tabs')
const { arrivedState, measure } = useScroll(list)
useResizeObserver([list, tabs], () => measure())
useTabListNavigation(list)
const canScroll = computed(() => ({ left: !arrivedState.left, right: !arrivedState.right }))
function scrollTabs(direction: (typeof SCROLL_DIRECTIONS)[number]) {
if (list.value === null) {
return
}
const step = list.value.clientWidth * SCROLL_STEP_RATIO
list.value.scrollBy({ left: direction === 'left' ? -step : step })
}
useDisabled(() => props.disabled)
</script>
<style lang="postcss" scoped>
.tab-list {
position: relative;
display: flex;
align-items: stretch;
height: 5rem;
border-bottom: 1px solid var(--color-neutral-border);
background-color: var(--color-neutral-background-primary);
max-width: 100%;
overflow: auto;
flex-shrink: 0;
.list {
display: flex;
align-items: stretch;
flex: 1;
min-width: 0;
overflow-x: auto;
overflow-y: hidden;
scroll-behavior: smooth;
overscroll-behavior-x: contain;
scrollbar-width: none;
&::-webkit-scrollbar {
display: none;
}
@media (prefers-reduced-motion: reduce) {
scroll-behavior: auto;
}
}
.tabs {
display: flex;
align-items: stretch;
flex-shrink: 0;
}
.scroll-button-container {
position: absolute;
inset-block: 0;
z-index: 1;
display: flex;
width: 2.8rem;
padding: 0.2rem;
background-color: var(--color-neutral-background-primary);
&.left {
inset-inline-start: 0;
}
&.right {
inset-inline-end: 0;
}
.scroll-button {
width: 100%;
height: 100%;
}
}
}
</style>

Some files were not shown because too many files have changed in this diff Show More