mirror of
https://github.com/vatesfr/xen-orchestra.git
synced 2026-11-16 12:03:40 -06:00
Compare commits
72 Commits
docs/body-
...
docker-exp
| Author | SHA1 | Date | |
|---|---|---|---|
|
|
1a6563decf | ||
|
|
cf6f18b433 | ||
|
|
4baccb916a | ||
|
|
910e9a520b | ||
|
|
9e23b86361 | ||
|
|
3afb4d7db6 | ||
|
|
e06e88dc42 | ||
|
|
bb8d061f8a | ||
|
|
b828ac2cc7 | ||
|
|
a6d1e1f146 | ||
|
|
28a61fa77e | ||
|
|
5300ad1e94 | ||
|
|
522f84381a | ||
|
|
5085390086 | ||
|
|
93e4af1459 | ||
|
|
f871c574a0 | ||
|
|
1746ac3ea3 | ||
|
|
881cabf0ac | ||
|
|
f75996f8bc | ||
|
|
e3bb023ffd | ||
|
|
1a63541fd2 | ||
|
|
30bf6d8fc0 | ||
|
|
522001551d | ||
|
|
49c0a8afe8 | ||
|
|
462b06c225 | ||
|
|
9098a9c183 | ||
|
|
b83569a6d2 | ||
|
|
e447ffa725 | ||
|
|
c037b9a2ec | ||
|
|
a6288fef97 | ||
|
|
eb302273e5 | ||
|
|
6c40bd0f71 | ||
|
|
9d3bd23296 | ||
|
|
588ee7c9b5 | ||
|
|
32b0dd8eba | ||
|
|
640b82b14e | ||
|
|
8e29220966 | ||
|
|
2bbca2e868 | ||
|
|
d130c8b88a | ||
|
|
b1cf44e109 | ||
|
|
8d7c41b0ab | ||
|
|
abfa163afb | ||
|
|
8914dd96d3 | ||
|
|
3c2ddd1755 | ||
|
|
145533b850 | ||
|
|
a912f52803 | ||
|
|
7d30f5b75f | ||
|
|
f6685ad05c | ||
|
|
f6f0820853 | ||
|
|
a2c9daeb10 | ||
|
|
158975ed99 | ||
|
|
a6344a4c3e | ||
|
|
1ef7d651e0 | ||
|
|
191dc72d18 | ||
|
|
dc2232d590 | ||
|
|
77ecba566e | ||
|
|
e3eed972a2 | ||
|
|
0d70b3ed07 | ||
|
|
915568bd9a | ||
|
|
0bdd147b86 | ||
|
|
12f68ef7f8 | ||
|
|
620fb0890d | ||
|
|
ab38e9ff9b | ||
|
|
548ede5afa | ||
|
|
b4c95eaf18 | ||
|
|
c96dd62e01 | ||
|
|
22448c94af | ||
|
|
a3a9cf898a | ||
|
|
4310594842 | ||
|
|
c2ca305fc5 | ||
|
|
d1091b5df1 | ||
|
|
8e16763df4 |
@@ -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)))
|
||||
|
||||
|
||||
57
@vates/obfuscate/index.test.js
Normal file
57
@vates/obfuscate/index.test.js
Normal 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' })
|
||||
})
|
||||
})
|
||||
@@ -18,6 +18,7 @@
|
||||
"node": ">=8.10"
|
||||
},
|
||||
"scripts": {
|
||||
"postversion": "npm publish --access public"
|
||||
"postversion": "npm publish --access public",
|
||||
"test": "node --test"
|
||||
}
|
||||
}
|
||||
|
||||
@@ -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'
|
||||
|
||||
173
@vates/types/src/lib/xen-orchestra-docker.mts
Normal file
173
@vates/types/src/lib/xen-orchestra-docker.mts
Normal 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
|
||||
}
|
||||
@@ -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: {
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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.
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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 })
|
||||
}
|
||||
}
|
||||
|
||||
@@ -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) {
|
||||
|
||||
@@ -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
|
||||
|
||||
42
@xen-orchestra/docker-ssh/.USAGE.md
Normal file
42
@xen-orchestra/docker-ssh/.USAGE.md
Normal 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()
|
||||
}
|
||||
```
|
||||
1
@xen-orchestra/docker-ssh/.gitattributes
vendored
Normal file
1
@xen-orchestra/docker-ssh/.gitattributes
vendored
Normal file
@@ -0,0 +1 @@
|
||||
src/docker-api.gen.mts linguist-generated=true
|
||||
1
@xen-orchestra/docker-ssh/.npmignore
Symbolic link
1
@xen-orchestra/docker-ssh/.npmignore
Symbolic link
@@ -0,0 +1 @@
|
||||
../../scripts/npmignore
|
||||
75
@xen-orchestra/docker-ssh/README.md
Normal file
75
@xen-orchestra/docker-ssh/README.md
Normal file
@@ -0,0 +1,75 @@
|
||||
<!-- DO NOT EDIT MANUALLY, THIS FILE HAS BEEN GENERATED -->
|
||||
|
||||
# @xen-orchestra/docker-ssh
|
||||
|
||||
[](https://npmjs.org/package/@xen-orchestra/docker-ssh)  [](https://bundlephobia.com/result?p=@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)
|
||||
6
@xen-orchestra/docker-ssh/eslint.config.mjs
Normal file
6
@xen-orchestra/docker-ssh/eslint.config.mjs
Normal 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)
|
||||
54
@xen-orchestra/docker-ssh/package.json
Normal file
54
@xen-orchestra/docker-ssh/package.json
Normal 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"
|
||||
}
|
||||
}
|
||||
140
@xen-orchestra/docker-ssh/scripts/generate-api-types.mjs
Normal file
140
@xen-orchestra/docker-ssh/scripts/generate-api-types.mjs
Normal 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 })
|
||||
}
|
||||
314
@xen-orchestra/docker-ssh/src/connection.integration.test.mts
Normal file
314
@xen-orchestra/docker-ssh/src/connection.integration.test.mts
Normal 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
|
||||
})
|
||||
}
|
||||
)
|
||||
})
|
||||
1217
@xen-orchestra/docker-ssh/src/connection.mts
Normal file
1217
@xen-orchestra/docker-ssh/src/connection.mts
Normal file
File diff suppressed because it is too large
Load Diff
967
@xen-orchestra/docker-ssh/src/connection.test.mts
Normal file
967
@xen-orchestra/docker-ssh/src/connection.test.mts
Normal 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)
|
||||
})
|
||||
})
|
||||
145
@xen-orchestra/docker-ssh/src/cooldown.mts
Normal file
145
@xen-orchestra/docker-ssh/src/cooldown.mts
Normal 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)
|
||||
}
|
||||
}
|
||||
}
|
||||
108
@xen-orchestra/docker-ssh/src/cooldown.test.mts
Normal file
108
@xen-orchestra/docker-ssh/src/cooldown.test.mts
Normal 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)
|
||||
})
|
||||
})
|
||||
3242
@xen-orchestra/docker-ssh/src/docker-api.gen.mts
generated
Normal file
3242
@xen-orchestra/docker-ssh/src/docker-api.gen.mts
generated
Normal file
File diff suppressed because it is too large
Load Diff
226
@xen-orchestra/docker-ssh/src/errors.mts
Normal file
226
@xen-orchestra/docker-ssh/src/errors.mts
Normal 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 })
|
||||
}
|
||||
118
@xen-orchestra/docker-ssh/src/errors.test.mts
Normal file
118
@xen-orchestra/docker-ssh/src/errors.test.mts
Normal 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)
|
||||
})
|
||||
})
|
||||
2525
@xen-orchestra/docker-ssh/src/fixtures/containers.mts
Normal file
2525
@xen-orchestra/docker-ssh/src/fixtures/containers.mts
Normal file
File diff suppressed because it is too large
Load Diff
189
@xen-orchestra/docker-ssh/src/fixtures/engine.mts
Normal file
189
@xen-orchestra/docker-ssh/src/fixtures/engine.mts
Normal 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
|
||||
22
@xen-orchestra/docker-ssh/src/fixtures/logs.mts
Normal file
22
@xen-orchestra/docker-ssh/src/fixtures/logs.mts
Normal 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×tamps=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',
|
||||
}
|
||||
560
@xen-orchestra/docker-ssh/src/fixtures/stats.mts
Normal file
560
@xen-orchestra/docker-ssh/src/fixtures/stats.mts
Normal 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[]
|
||||
21
@xen-orchestra/docker-ssh/src/index.mts
Normal file
21
@xen-orchestra/docker-ssh/src/index.mts
Normal 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'
|
||||
206
@xen-orchestra/docker-ssh/src/normalize.integration.test.mts
Normal file
206
@xen-orchestra/docker-ssh/src/normalize.integration.test.mts
Normal 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)
|
||||
})
|
||||
})
|
||||
599
@xen-orchestra/docker-ssh/src/normalize.mts
Normal file
599
@xen-orchestra/docker-ssh/src/normalize.mts
Normal 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 ?? [],
|
||||
}
|
||||
}
|
||||
687
@xen-orchestra/docker-ssh/src/normalize.test.mts
Normal file
687
@xen-orchestra/docker-ssh/src/normalize.test.mts
Normal 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')
|
||||
})
|
||||
})
|
||||
504
@xen-orchestra/docker-ssh/src/pool.mts
Normal file
504
@xen-orchestra/docker-ssh/src/pool.mts
Normal 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)))
|
||||
}
|
||||
}
|
||||
454
@xen-orchestra/docker-ssh/src/pool.test.mts
Normal file
454
@xen-orchestra/docker-ssh/src/pool.test.mts
Normal 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 }
|
||||
)
|
||||
})
|
||||
})
|
||||
313
@xen-orchestra/docker-ssh/src/requests.mts
Normal file
313
@xen-orchestra/docker-ssh/src/requests.mts
Normal 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
|
||||
}
|
||||
}
|
||||
241
@xen-orchestra/docker-ssh/src/requests.test.mts
Normal file
241
@xen-orchestra/docker-ssh/src/requests.test.mts
Normal 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
|
||||
})
|
||||
})
|
||||
207
@xen-orchestra/docker-ssh/src/ssh-http-agent.mts
Normal file
207
@xen-orchestra/docker-ssh/src/ssh-http-agent.mts
Normal 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)
|
||||
)
|
||||
}
|
||||
}
|
||||
356
@xen-orchestra/docker-ssh/src/stats-sampler.mts
Normal file
356
@xen-orchestra/docker-ssh/src/stats-sampler.mts
Normal 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))
|
||||
}
|
||||
}
|
||||
450
@xen-orchestra/docker-ssh/src/stats-sampler.test.mts
Normal file
450
@xen-orchestra/docker-ssh/src/stats-sampler.test.mts
Normal 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()
|
||||
}
|
||||
})
|
||||
})
|
||||
273
@xen-orchestra/docker-ssh/src/stdcopy.mts
Normal file
273
@xen-orchestra/docker-ssh/src/stdcopy.mts
Normal 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()
|
||||
},
|
||||
})
|
||||
}
|
||||
326
@xen-orchestra/docker-ssh/src/stdcopy.test.mts
Normal file
326
@xen-orchestra/docker-ssh/src/stdcopy.test.mts
Normal 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)
|
||||
})
|
||||
})
|
||||
106
@xen-orchestra/docker-ssh/src/ttl-cache.mts
Normal file
106
@xen-orchestra/docker-ssh/src/ttl-cache.mts
Normal 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)
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
68
@xen-orchestra/docker-ssh/src/ttl-cache.test.mts
Normal file
68
@xen-orchestra/docker-ssh/src/ttl-cache.test.mts
Normal 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)
|
||||
})
|
||||
})
|
||||
161
@xen-orchestra/docker-ssh/src/wire.mts
Normal file
161
@xen-orchestra/docker-ssh/src/wire.mts
Normal 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
|
||||
}
|
||||
16
@xen-orchestra/docker-ssh/tsconfig.json
Normal file
16
@xen-orchestra/docker-ssh/tsconfig.json
Normal 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"]
|
||||
}
|
||||
@@ -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 })
|
||||
}
|
||||
@@ -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 })
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
@@ -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)
|
||||
})
|
||||
}
|
||||
})
|
||||
})
|
||||
@@ -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 })
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
@@ -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)
|
||||
})
|
||||
})
|
||||
@@ -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)
|
||||
|
||||
|
||||
@@ -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);
|
||||
|
||||
@@ -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),
|
||||
|
||||
@@ -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)
|
||||
|
||||
|
||||
@@ -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)
|
||||
|
||||
|
||||
@@ -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),
|
||||
|
||||
@@ -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,
|
||||
|
||||
@@ -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,
|
||||
|
||||
@@ -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),
|
||||
|
||||
@@ -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>
|
||||
|
||||
@@ -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>
|
||||
|
||||
@@ -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>
|
||||
|
||||
@@ -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(),
|
||||
|
||||
@@ -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',
|
||||
|
||||
@@ -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) =>
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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
|
||||
# ===========================================
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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",
|
||||
|
||||
@@ -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)
|
||||
})
|
||||
}
|
||||
)
|
||||
@@ -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",
|
||||
|
||||
@@ -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 },
|
||||
}
|
||||
)
|
||||
}
|
||||
}
|
||||
@@ -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',
|
||||
})
|
||||
})
|
||||
})
|
||||
})
|
||||
@@ -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),
|
||||
})
|
||||
}
|
||||
}
|
||||
@@ -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]
|
||||
}
|
||||
@@ -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}']
|
||||
)
|
||||
})
|
||||
})
|
||||
@@ -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 },
|
||||
}
|
||||
)
|
||||
}
|
||||
}
|
||||
@@ -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' })
|
||||
})
|
||||
})
|
||||
@@ -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
|
||||
}
|
||||
146
@xen-orchestra/rest-api/src/helpers/docker.helper.mts
Normal file
146
@xen-orchestra/rest-api/src/helpers/docker.helper.mts
Normal 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)
|
||||
}
|
||||
}
|
||||
@@ -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
|
||||
}
|
||||
}
|
||||
|
||||
@@ -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)
|
||||
|
||||
@@ -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 }
|
||||
|
||||
@@ -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)
|
||||
}
|
||||
@@ -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'])
|
||||
})
|
||||
})
|
||||
@@ -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)) {
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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,
|
||||
}
|
||||
@@ -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',
|
||||
},
|
||||
}
|
||||
@@ -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"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
@@ -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>
|
||||
|
||||
@@ -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>
|
||||
|
||||
@@ -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>
|
||||
|
||||
@@ -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;
|
||||
|
||||
@@ -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>
|
||||
@@ -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>
|
||||
@@ -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
Reference in New Issue
Block a user