Free, Open Source, Self-Hosted WhatsApp API Gateway
TypeScript apibotgatewayself-hostedwhatsappwhatsapp-apiwhatsapp-automationwhatsapp-botwhatsapp-gatewaywhatsapp-gateway-apiwhatsapp-webwhatsapp-web-api
import Docker from 'dockerode';
import { DockerService, prestartBuiltinDatabase } from './docker.service';
import { recordOsEnvKeys, recordPinnedEnvKeys } from '../../config/env-precedence';
import { HOST_SPELLINGS } from '../../../test/fixtures/builtin-mode-cases';
// Prevent actual Docker connections on module init during tests
jest.mock('dockerode');
// The auto-mocked constructor: initializeDocker does `new Docker(...)` internally, so the
// onModuleInit/isDockerAvailable tests steer the daemon by replacing its implementation.
const DockerMock = Docker as unknown as jest.Mock;
/** A daemon with no local copy of any image: inspect answers 404, so createService pulls. */
const imageNotCached = () => ({
inspect: jest.fn().mockRejectedValue(Object.assign(new Error('no such image'), { statusCode: 404 })),
});
describe('DockerService.getRunningBuiltinServices', () => {
const container = (name: string, service: string, state: string, labels: Record<string, string> = {}) => ({
id: name,
name,
state,
status: state,
labels: { 'com.openwa.service': service, 'com.openwa.builtin': 'true', ...labels },
});
it('reports a service built-in only when its labeled container is actually running', async () => {
const service = new DockerService();
jest
.spyOn(service, 'listContainers')
.mockResolvedValue([
container('openwa-postgres', 'database', 'running'),
container('openwa-redis', 'cache', 'exited'),
]);
expect(await service.getRunningBuiltinServices()).toEqual({ database: 'openwa', cache: false, storage: false });
});
it('names a running container Docker Compose created, by its project label', async () => {
const service = new DockerService();
jest
.spyOn(service, 'listContainers')
.mockResolvedValue([
container('openwa-postgres', 'database', 'running', { 'com.docker.compose.project': 'openwa' }),
container('openwa-redis', 'cache', 'running'),
container('openwa-minio', 'storage', 'exited', { 'com.docker.compose.project': 'openwa' }),
]);
expect(await service.getRunningBuiltinServices()).toEqual({ database: 'compose', cache: 'openwa', storage: false });
});
it('reports all false when a live inventory contains no bundled containers', async () => {
const service = new DockerService();
jest.spyOn(service, 'listContainers').mockResolvedValue([]);
expect(await service.getRunningBuiltinServices()).toEqual({ database: false, cache: false, storage: false });
});
});
describe('DockerService.buildDockerOptions', () => {
let service: DockerService;
const originalDockerHost = process.env.DOCKER_HOST;
beforeEach(() => {
service = new DockerService();
});
afterEach(() => {
if (originalDockerHost === undefined) {
delete process.env.DOCKER_HOST;
} else {
process.env.DOCKER_HOST = originalDockerHost;
}
});
it('returns TCP options when DOCKER_HOST is set to tcp://host:port', () => {
process.env.DOCKER_HOST = 'tcp://docker-proxy:2375';
expect(service.buildDockerOptions()).toEqual({
host: 'docker-proxy',
port: 2375,
protocol: 'http',
});
});
it('falls back to unix socket when DOCKER_HOST is not set', () => {
delete process.env.DOCKER_HOST;
expect(service.buildDockerOptions()).toEqual({
socketPath: '/var/run/docker.sock',
});
});
it('falls back to unix socket for unsupported DOCKER_HOST schemes', () => {
process.env.DOCKER_HOST = 'unix:///run/docker.sock';
expect(service.buildDockerOptions()).toEqual({
socketPath: '/var/run/docker.sock',
});
});
});
describe('DockerService.stopManagedService (stop-only teardown)', () => {
// Teardown is deliberately stop-only: the pinned docker-socket-proxy v0.5.0 never reads its
// DELETE env flag (deletion is admitted only as an undocumented side effect of its POST
// method gate), so the code must not depend on container.remove() at all.
const makeService = (container: unknown) => {
const service = new DockerService();
const getContainerByService = jest.spyOn(service, 'getContainerByService').mockResolvedValue(container as never);
return { service, getContainerByService };
};
it('maps the profile to its service label and stops a running container without removing it', async () => {
const container = {
inspect: jest.fn().mockResolvedValue({ State: { Running: true } }),
stop: jest.fn().mockResolvedValue(undefined),
remove: jest.fn(),
};
const { service, getContainerByService } = makeService(container);
await expect(service.stopManagedService('postgres')).resolves.toBe(true);
expect(getContainerByService).toHaveBeenCalledWith('database');
expect(container.stop).toHaveBeenCalledTimes(1);
expect(container.remove).not.toHaveBeenCalled();
});
it('leaves an already-stopped container alone (no stop, no remove)', async () => {
const container = {
inspect: jest.fn().mockResolvedValue({ State: { Running: false } }),
stop: jest.fn(),
remove: jest.fn(),
};
const { service } = makeService(container);
await expect(service.stopManagedService('redis')).resolves.toBe(true);
expect(container.stop).not.toHaveBeenCalled();
expect(container.remove).not.toHaveBeenCalled();
});
it('returns true when the container is already gone', async () => {
const { service } = makeService(null);
await expect(service.stopManagedService('minio')).resolves.toBe(true);
});
it('reports failure honestly when stop fails (and still never removes)', async () => {
const container = {
inspect: jest.fn().mockResolvedValue({ State: { Running: true } }),
stop: jest.fn().mockRejectedValue(new Error('daemon gone')),
remove: jest.fn(),
};
const { service } = makeService(container);
await expect(service.stopManagedService('postgres')).resolves.toBe(false);
expect(container.remove).not.toHaveBeenCalled();
});
});
describe('DockerService.getContainerByService exact-name fallback', () => {
// Label lookup returns nothing → exercises the name fallback. The fallback must match the exact
// OpenWA-managed container name, never a substring (a substring — and especially the empty string —
// would let an arbitrary container be resolved and torn down).
function withFakeDocker(containers: Array<{ Id: string; Names: string[] }>) {
const service = new DockerService();
const listContainers = jest
.fn()
.mockResolvedValueOnce([]) // label-filtered lookup: no match
.mockResolvedValueOnce(containers); // fallback: all containers
const getContainer = jest.fn((id: string) => ({ id }));
Object.assign(service as unknown as Record<string, unknown>, {
docker: { listContainers, getContainer },
isAvailable: true,
});
return { service, getContainer };
}
it('does not resolve any container for an empty service name', async () => {
const { service, getContainer } = withFakeDocker([{ Id: 'abc', Names: ['/openwa-postgres'] }]);
expect(await service.getContainerByService('')).toBeNull();
expect(getContainer).not.toHaveBeenCalled();
});
it('does not resolve a container by substring of its name', async () => {
const { service, getContainer } = withFakeDocker([{ Id: 'abc', Names: ['/openwa-postgres-primary'] }]);
// 'postgres' is a substring of 'openwa-postgres-primary' but not the exact managed name.
expect(await service.getContainerByService('postgres')).toBeNull();
expect(getContainer).not.toHaveBeenCalled();
});
it('resolves the exact openwa-<service> container', async () => {
const { service, getContainer } = withFakeDocker([
{ Id: 'p', Names: ['/openwa-postgres'] },
{ Id: 'r', Names: ['/openwa-redis'] },
]);
const result = await service.getContainerByService('redis');
expect(getContainer).toHaveBeenCalledWith('r');
expect(result).toEqual({ id: 'r' });
});
});
describe('DockerService.onModuleInit', () => {
// The probe runs against whatever buildDockerOptions() points at, but the dockerode
// constructor is the auto-mock — the "daemon" is whatever the test's fake says it is,
// so no real socket is ever touched.
const ENV_KEYS = [
'DOCKER_HOST',
'REDIS_BUILTIN',
'POSTGRES_BUILTIN',
'MINIO_BUILTIN',
'DATABASE_TYPE',
'STORAGE_TYPE',
'REDIS_ENABLED',
'QUEUE_ENABLED',
'CACHE_ENABLED',
'DATABASE_HOST',
'REDIS_HOST',
'S3_ENDPOINT',
];
let savedEnv: Record<string, string | undefined> = {};
const happyDocker = () => ({
ping: jest.fn().mockResolvedValue(undefined),
listContainers: jest.fn().mockResolvedValue([]),
getImage: imageNotCached,
pull: (_image: string, cb: (err: Error | null, stream: null) => void) => cb(null, null),
modem: { followProgress: (_stream: null, cb: (err: Error | null) => void) => cb(null) },
createVolume: jest.fn().mockResolvedValue({}),
createContainer: jest.fn().mockResolvedValue({ start: jest.fn().mockResolvedValue(undefined) }),
});
beforeEach(() => {
savedEnv = {};
for (const k of ENV_KEYS) {
savedEnv[k] = process.env[k];
delete process.env[k];
}
});
afterEach(() => {
for (const k of ENV_KEYS) {
if (savedEnv[k] === undefined) delete process.env[k];
else process.env[k] = savedEnv[k];
}
recordPinnedEnvKeys({});
DockerMock.mockReset();
});
it('does not throw when the Docker socket is absent — orchestration is disabled and bootstrap is skipped', async () => {
DockerMock.mockImplementation(() => ({
ping: jest.fn().mockRejectedValue(new Error('connect ENOENT /var/run/docker.sock')),
}));
const service = new DockerService();
await expect(service.onModuleInit()).resolves.toBeUndefined();
expect(service.isDockerAvailable()).toBe(false);
});
it('bootstraps the env-configured built-in profiles when the daemon is reachable', async () => {
process.env.REDIS_BUILTIN = 'true';
process.env.REDIS_ENABLED = 'true';
const docker = happyDocker();
DockerMock.mockImplementation(() => docker);
const service = new DockerService();
await expect(service.onModuleInit()).resolves.toBeUndefined();
expect(service.isDockerAvailable()).toBe(true);
expect(docker.createContainer).toHaveBeenCalledWith(expect.objectContaining({ name: 'openwa-redis' }));
});
it('logs a warning but still resolves when bootstrap orchestration fails', async () => {
process.env.REDIS_BUILTIN = 'true';
process.env.REDIS_ENABLED = 'true';
const docker = {
...happyDocker(),
pull: (_image: string, cb: (err: Error | null, stream: null) => void) => cb(new Error('pull denied'), null),
};
DockerMock.mockImplementation(() => docker);
const service = new DockerService();
const warn = jest
.spyOn((service as unknown as { logger: { warn: () => void } }).logger, 'warn')
.mockImplementation(() => undefined);
await expect(service.onModuleInit()).resolves.toBeUndefined();
expect(service.isDockerAvailable()).toBe(true);
expect(warn).toHaveBeenCalledWith(expect.stringContaining('[Bootstrap Orchestration] Issues'));
expect(docker.createContainer).not.toHaveBeenCalled();
});
// A built-in flag starts its container only for a datastore this boot uses: a flag left beside a SQLite database,
// local storage or a Redis nothing reaches would otherwise run a container on every boot that nothing dials.
// Redis is reached by the queue and the cache as well as by REDIS_ENABLED.
describe.each([
['openwa-postgres', 'POSTGRES_BUILTIN', [{ DATABASE_TYPE: 'postgres' }], [{}, { DATABASE_TYPE: 'sqlite' }]],
[
'openwa-redis',
'REDIS_BUILTIN',
[{ REDIS_ENABLED: 'true' }, { QUEUE_ENABLED: 'true' }, { CACHE_ENABLED: 'true' }],
[{}, { REDIS_ENABLED: 'false', QUEUE_ENABLED: 'false', CACHE_ENABLED: 'false' }],
],
['openwa-minio', 'MINIO_BUILTIN', [{ STORAGE_TYPE: 's3' }], [{}, { STORAGE_TYPE: 'local' }]],
] as const)('%s', (container, flag, used, unused) => {
const started = async (env: Record<string, string>): Promise<boolean> => {
Object.assign(process.env, { [flag]: 'true' }, env);
const docker = happyDocker();
DockerMock.mockImplementation(() => docker);
await new DockerService().onModuleInit();
return docker.createContainer.mock.calls.some(([spec]) => (spec as { name: string }).name === container);
};
it.each(used.map(env => [JSON.stringify(env), env]))('is started when %s', async (_label, env) => {
expect(await started(env)).toBe(true);
});
it.each(unused.map(env => [JSON.stringify(env), env]))('is not started when %s', async (_label, env) => {
expect(await started(env)).toBe(false);
});
});
// The host the environment pins outranks the saved file at boot, so a bundled container started for a host pinned
// elsewhere would run with nothing dialling it. A pinned host that reaches the container in any spelling still starts
// it: the next boot dials it.
describe.each([
['openwa-postgres', 'POSTGRES_BUILTIN', { DATABASE_TYPE: 'postgres' }, 'DATABASE_HOST', 'database'],
['openwa-redis', 'REDIS_BUILTIN', { REDIS_ENABLED: 'true' }, 'REDIS_HOST', 'redis'],
['openwa-minio', 'MINIO_BUILTIN', { STORAGE_TYPE: 's3' }, 'S3_ENDPOINT', 'storage'],
] as const)('%s with its host pinned', (container, flag, use, hostKey, service) => {
it.each([
...HOST_SPELLINGS[service].reach.map(host => [host, true] as const),
...HOST_SPELLINGS[service].elsewhere.map(host => [host, false] as const),
])('to %j is started: %s', async (host, expected) => {
Object.assign(process.env, { [flag]: 'true', [hostKey]: host }, use);
recordPinnedEnvKeys({ [hostKey]: host });
const docker = happyDocker();
DockerMock.mockImplementation(() => docker);
await new DockerService().onModuleInit();
const names = docker.createContainer.mock.calls.map(([spec]) => (spec as { name: string }).name);
expect(names.includes(container)).toBe(expected);
});
});
});
describe('prestartBuiltinDatabase', () => {
const builtin = { DATABASE_TYPE: 'postgres', POSTGRES_BUILTIN: 'true' };
afterEach(() => DockerMock.mockReset());
it('starts a stopped built-in postgres container through a real DockerService', async () => {
const container = {
inspect: jest.fn().mockResolvedValue({ State: { Running: false } }),
start: jest.fn().mockResolvedValue(undefined),
};
const docker = {
ping: jest.fn().mockResolvedValue(undefined),
listContainers: jest.fn().mockResolvedValue([{ Id: 'pg' }]),
getContainer: jest.fn().mockReturnValue(container),
};
DockerMock.mockImplementation(() => docker);
await prestartBuiltinDatabase(builtin, new DockerService());
expect(docker.listContainers).toHaveBeenCalledWith({
all: true,
filters: { label: ['com.openwa.service=database'] },
abortSignal: expect.any(AbortSignal) as unknown,
});
expect(container.start).toHaveBeenCalledTimes(1);
});
it.each([
['an sqlite deployment', { DATABASE_TYPE: 'sqlite', POSTGRES_BUILTIN: 'true' }],
['an external postgres', { DATABASE_TYPE: 'postgres', POSTGRES_BUILTIN: 'false' }],
['no built-in flag', { DATABASE_TYPE: 'postgres' }],
])('does nothing for %s', async (_label, env) => {
const service = { startBuiltinDatabase: jest.fn().mockResolvedValue(undefined) };
await prestartBuiltinDatabase(env, service);
expect(service.startBuiltinDatabase).not.toHaveBeenCalled();
});
it.each([
...HOST_SPELLINGS.database.reach.map(host => [host, 1] as const),
...HOST_SPELLINGS.database.elsewhere.map(host => [host, 0] as const),
])('with DATABASE_HOST pinned to %j starts the container %i times', async (host, calls) => {
recordPinnedEnvKeys({ DATABASE_HOST: host });
const service = { startBuiltinDatabase: jest.fn().mockResolvedValue(undefined) };
try {
await prestartBuiltinDatabase({ ...builtin, DATABASE_HOST: host }, service);
} finally {
recordPinnedEnvKeys({});
}
expect(service.startBuiltinDatabase).toHaveBeenCalledTimes(calls);
});
it('gives up after the timeout when the Docker endpoint never answers', async () => {
const service = { startBuiltinDatabase: () => new Promise<void>(() => undefined) };
await expect(prestartBuiltinDatabase(builtin, service, 10)).resolves.toBeUndefined();
});
it('never throws, so boot proceeds to the data connection as before', async () => {
const service = { startBuiltinDatabase: jest.fn().mockRejectedValue(new Error('boom')) };
await expect(prestartBuiltinDatabase(builtin, service)).resolves.toBeUndefined();
});
});
describe('DockerService.isDockerAvailable', () => {
const originalDockerHost = process.env.DOCKER_HOST;
afterEach(() => {
if (originalDockerHost === undefined) delete process.env.DOCKER_HOST;
else process.env.DOCKER_HOST = originalDockerHost;
DockerMock.mockReset();
});
it('returns the live availability flag', () => {
delete process.env.DOCKER_HOST; // no re-probe: the flag is reported as-is
const service = new DockerService();
expect(service.isDockerAvailable()).toBe(false);
Object.assign(service as unknown as Record<string, unknown>, { isAvailable: true });
expect(service.isDockerAvailable()).toBe(true);
});
it('re-probes once in the background when DOCKER_HOST is set and the first probe failed', async () => {
process.env.DOCKER_HOST = 'tcp://docker-proxy:2375';
const ping = jest.fn().mockResolvedValue(undefined);
DockerMock.mockImplementation(() => ({ ping }));
const service = new DockerService();
// The first call reports the stale false and kicks off the one-shot re-probe...
expect(service.isDockerAvailable()).toBe(false);
// ...and the in-flight guard stops a second probe from piling up.
expect(service.isDockerAvailable()).toBe(false);
expect(DockerMock).toHaveBeenCalledTimes(1);
await new Promise(resolve => setImmediate(resolve));
expect(ping).toHaveBeenCalledTimes(1);
expect(service.isDockerAvailable()).toBe(true);
});
});
describe('DockerService.listContainers', () => {
const makeService = (listContainers: jest.Mock) => {
const service = new DockerService();
Object.assign(service as unknown as Record<string, unknown>, {
docker: { listContainers },
isAvailable: true,
});
return service;
};
it('returns no live inventory when Docker is unavailable', async () => {
expect(await new DockerService().listContainers()).toBeNull();
});
it('maps only OpenWA containers (label or /openwa- name) to ContainerInfo', async () => {
const service = makeService(
jest.fn().mockResolvedValue([
{
Id: 'aabbccddeeff00112233',
Names: ['/openwa-postgres'],
State: 'running',
Status: 'Up 2 hours',
Labels: { 'com.openwa.service': 'database', 'com.openwa.builtin': 'true' },
},
{ Id: '11223344556677889900', Names: ['/openwa-redis'], State: 'exited', Status: 'Exited (0) yesterday' },
// Label-only match with sparse fields: falls back to 'unknown' placeholders.
{ Id: 'ffee0011223344556677', Labels: { 'com.openwa.service': 'cache' } },
{ Id: 'deadbeef0011', Names: ['/unrelated'], State: 'running', Status: 'Up', Labels: {} },
]),
);
expect(await service.listContainers()).toEqual([
{
id: 'aabbccddeeff',
name: 'openwa-postgres',
state: 'running',
status: 'Up 2 hours',
labels: { 'com.openwa.service': 'database', 'com.openwa.builtin': 'true' },
},
{ id: '112233445566', name: 'openwa-redis', state: 'exited', status: 'Exited (0) yesterday', labels: {} },
{
id: 'ffee00112233',
name: 'unknown',
state: 'unknown',
status: 'unknown',
labels: { 'com.openwa.service': 'cache' },
},
]);
});
it('returns no live inventory when the daemon listing fails', async () => {
const service = makeService(jest.fn().mockRejectedValue(new Error('daemon gone')));
expect(await service.listContainers()).toBeNull();
});
});
describe('DockerService.getContainerByService label match and guard rails', () => {
it('returns null when Docker is unavailable', async () => {
expect(await new DockerService().getContainerByService('database')).toBeNull();
});
it('resolves the container by its com.openwa.service label', async () => {
const service = new DockerService();
const listContainers = jest.fn().mockResolvedValue([{ Id: 'label-hit-1', Names: ['/openwa-postgres'] }]);
const getContainer = jest.fn((id: string) => ({ id }));
Object.assign(service as unknown as Record<string, unknown>, {
docker: { listContainers, getContainer },
isAvailable: true,
});
const result = await service.getContainerByService('database');
expect(listContainers).toHaveBeenCalledWith({
all: true,
filters: { label: ['com.openwa.service=database'] },
abortSignal: expect.any(AbortSignal) as unknown,
});
expect(getContainer).toHaveBeenCalledWith('label-hit-1');
expect(result).toEqual({ id: 'label-hit-1' });
});
it('returns null when the daemon lookup fails', async () => {
const service = new DockerService();
Object.assign(service as unknown as Record<string, unknown>, {
docker: { listContainers: jest.fn().mockRejectedValue(new Error('daemon gone')) },
isAvailable: true,
});
expect(await service.getContainerByService('database')).toBeNull();
});
});
describe('DockerService.createService', () => {
const withDocker = (docker: unknown) => {
const service = new DockerService();
Object.assign(service as unknown as Record<string, unknown>, { docker, isAvailable: true });
return service;
};
it('returns false when Docker is unavailable', async () => {
expect(await new DockerService().createService('redis')).toBe(false);
});
it('returns false for an unknown profile', async () => {
expect(await withDocker({}).createService('not-a-profile')).toBe(false);
});
it('returns true without pulling when the container already exists and is running', async () => {
const service = withDocker({});
const container = { inspect: jest.fn().mockResolvedValue({ State: { Running: true } }), start: jest.fn() };
jest.spyOn(service, 'getContainerByService').mockResolvedValue(container as never);
await expect(service.createService('postgres')).resolves.toBe(true);
expect(container.start).not.toHaveBeenCalled();
});
it('starts the retained container when it exists but is stopped', async () => {
const service = withDocker({});
const container = {
inspect: jest.fn().mockResolvedValue({ State: { Running: false } }),
start: jest.fn().mockResolvedValue(undefined),
};
jest.spyOn(service, 'getContainerByService').mockResolvedValue(container as never);
await expect(service.createService('redis')).resolves.toBe(true);
expect(container.start).toHaveBeenCalledTimes(1);
});
it('pulls, creates the volume and container, and starts it (a pre-existing volume is fine)', async () => {
const start = jest.fn().mockResolvedValue(undefined);
const docker = {
getImage: imageNotCached,
pull: (_image: string, cb: (err: Error | null, stream: null) => void) => cb(null, null),
modem: { followProgress: (_stream: null, cb: (err: Error | null) => void) => cb(null) },
// EEXIST races are normal — the volume may survive from an earlier run.
createVolume: jest.fn().mockRejectedValue(new Error('volume already exists')),
createContainer: jest.fn().mockResolvedValue({ start }),
};
const service = withDocker(docker);
jest.spyOn(service, 'getContainerByService').mockResolvedValue(null);
await expect(service.createService('redis')).resolves.toBe(true);
expect(docker.createVolume).toHaveBeenCalledWith({ Name: 'openwa_redis-data' });
expect(docker.createContainer).toHaveBeenCalledWith(
expect.objectContaining({ name: 'openwa-redis', Image: 'redis:7-alpine' }),
);
expect(start).toHaveBeenCalledTimes(1);
});
it('returns false when the daemon rejects the image pull', async () => {
const docker = {
modem: {},
getImage: imageNotCached,
pull: (_image: string, cb: (err: Error | null, stream: null) => void) =>
cb(new Error('pull access denied'), null),
};
const service = withDocker(docker);
jest.spyOn(service, 'getContainerByService').mockResolvedValue(null);
await expect(service.createService('redis')).resolves.toBe(false);
});
it('creates the container from a cached image without pulling it', async () => {
const start = jest.fn().mockResolvedValue(undefined);
const getImage = jest.fn(() => ({ inspect: jest.fn().mockResolvedValue({ Id: 'sha256:abc' }) }));
const docker = {
modem: {},
getImage,
pull: jest.fn(),
createVolume: jest.fn().mockResolvedValue({}),
createContainer: jest.fn().mockResolvedValue({ start }),
};
const service = withDocker(docker);
jest.spyOn(service, 'getContainerByService').mockResolvedValue(null);
await expect(service.createService('redis')).resolves.toBe(true);
expect(getImage).toHaveBeenCalledWith('redis:7-alpine');
expect(docker.pull).not.toHaveBeenCalled();
expect(start).toHaveBeenCalledTimes(1);
});
it('pulls the pinned image once when it is not on the host', async () => {
const pull = jest.fn((_image: string, cb: (err: Error | null, stream: null) => void) => cb(null, null));
const docker = {
getImage: imageNotCached,
pull,
modem: { followProgress: (_stream: null, cb: (err: Error | null) => void) => cb(null) },
createVolume: jest.fn().mockResolvedValue({}),
createContainer: jest.fn().mockResolvedValue({ start: jest.fn().mockResolvedValue(undefined) }),
};
const service = withDocker(docker);
jest.spyOn(service, 'getContainerByService').mockResolvedValue(null);
await expect(service.createService('redis')).resolves.toBe(true);
expect(pull).toHaveBeenCalledTimes(1);
expect(pull).toHaveBeenCalledWith('redis:7-alpine', expect.any(Function));
});
});
describe('DockerService.startService', () => {
it('creates the mapped profile when no container exists yet', async () => {
const service = new DockerService();
jest.spyOn(service, 'getContainerByService').mockResolvedValue(null);
const createService = jest.spyOn(service, 'createService').mockResolvedValue(true);
await expect(service.startService('database')).resolves.toBe(true);
expect(createService).toHaveBeenCalledWith('postgres');
});
it('passes an unmapped service name through as its own profile', async () => {
const service = new DockerService();
jest.spyOn(service, 'getContainerByService').mockResolvedValue(null);
const createService = jest.spyOn(service, 'createService').mockResolvedValue(false);
await expect(service.startService('custom-service')).resolves.toBe(false);
expect(createService).toHaveBeenCalledWith('custom-service');
});
it('returns true when the container is already running', async () => {
const service = new DockerService();
const container = { inspect: jest.fn().mockResolvedValue({ State: { Running: true } }), start: jest.fn() };
jest.spyOn(service, 'getContainerByService').mockResolvedValue(container as never);
await expect(service.startService('cache')).resolves.toBe(true);
expect(container.start).not.toHaveBeenCalled();
});
it('starts a stopped container', async () => {
const service = new DockerService();
const container = {
inspect: jest.fn().mockResolvedValue({ State: { Running: false } }),
start: jest.fn().mockResolvedValue(undefined),
};
jest.spyOn(service, 'getContainerByService').mockResolvedValue(container as never);
await expect(service.startService('cache')).resolves.toBe(true);
expect(container.start).toHaveBeenCalledTimes(1);
});
it('returns false when the daemon rejects the start', async () => {
const service = new DockerService();
const container = {
inspect: jest.fn().mockResolvedValue({ State: { Running: false } }),
start: jest.fn().mockRejectedValue(new Error('daemon gone')),
};
jest.spyOn(service, 'getContainerByService').mockResolvedValue(container as never);
await expect(service.startService('cache')).resolves.toBe(false);
});
});
describe('DockerService image drift warning', () => {
const OLD_IMAGE = 'minio/minio:RELEASE.2024-01-01T00-00-00Z';
const pinOf = (service: DockerService, profile: string): string =>
(service as unknown as { getContainerSpec(p: string): { image: string } }).getContainerSpec(profile).image;
const retained = (running: boolean, image?: string) => ({
inspect: jest.fn().mockResolvedValue({
Name: '/openwa-minio',
State: { Running: running },
...(image ? { Config: { Image: image } } : {}),
}),
start: jest.fn().mockResolvedValue(undefined),
});
const setup = (container: unknown) => {
const service = new DockerService();
Object.assign(service as unknown as Record<string, unknown>, { docker: {}, isAvailable: true });
jest.spyOn(service, 'getContainerByService').mockResolvedValue(container as never);
const warn = jest.spyOn((service as unknown as { logger: { warn: () => void } }).logger, 'warn');
warn.mockImplementation(() => undefined);
return { service, warn };
};
it('warns when a stopped retained container runs an older image, and still starts it', async () => {
const container = retained(false, OLD_IMAGE);
const { service, warn } = setup(container);
await expect(service.startService('storage')).resolves.toBe(true);
expect(container.start).toHaveBeenCalledTimes(1);
expect(warn).toHaveBeenCalledTimes(1);
const message = String((warn.mock.calls[0] as unknown[])[0]);
expect(message).toContain('openwa-minio');
expect(message).toContain(OLD_IMAGE);
expect(message).toContain(pinOf(service, 'minio'));
expect(message).toContain('docker rm -f openwa-minio');
expect(message).not.toContain('data migration');
});
it('adds the data-migration caveat for a drifted PostgreSQL container', async () => {
const container = {
inspect: jest.fn().mockResolvedValue({
Name: '/openwa-postgres',
State: { Running: false },
Config: { Image: 'postgres:15-alpine' },
}),
start: jest.fn().mockResolvedValue(undefined),
};
const { service, warn } = setup(container);
await expect(service.startService('database')).resolves.toBe(true);
expect(warn).toHaveBeenCalledTimes(1);
const message = String((warn.mock.calls[0] as unknown[])[0]);
expect(message).toContain('docker rm -f openwa-postgres');
expect(message).toContain('major version change needs a data migration');
});
it('warns for a running drifted container without starting it', async () => {
const container = retained(true, OLD_IMAGE);
const { service, warn } = setup(container);
await expect(service.startService('storage')).resolves.toBe(true);
expect(container.start).not.toHaveBeenCalled();
expect(warn).toHaveBeenCalledTimes(1);
});
it('stays quiet when the container runs the pinned image or reports no image', async () => {
const pinned = setup(null);
const onPin = retained(false, pinOf(pinned.service, 'minio'));
jest.spyOn(pinned.service, 'getContainerByService').mockResolvedValue(onPin as never);
await expect(pinned.service.startService('storage')).resolves.toBe(true);
expect(pinned.warn).not.toHaveBeenCalled();
const bare = setup(retained(false));
await expect(bare.service.startService('storage')).resolves.toBe(true);
expect(bare.warn).not.toHaveBeenCalled();
});
it('warns on the createService name-fallback branch too', async () => {
const { service, warn } = setup(retained(false, OLD_IMAGE));
await expect(service.createService('minio')).resolves.toBe(true);
expect(warn).toHaveBeenCalledWith(expect.stringContaining(OLD_IMAGE));
});
it('does not turn a drifted retained container into an orchestration failure', async () => {
const { service } = setup(retained(false, OLD_IMAGE));
const result = await service.orchestrateProfiles(['minio']);
expect(result.success).toBe(true);
expect(result.containersStarted).toEqual(['minio']);
});
});
describe('DockerService.stopService', () => {
const makeService = (container: unknown) => {
const service = new DockerService();
jest.spyOn(service, 'getContainerByService').mockResolvedValue(container as never);
return service;
};
it('stops a running container and retains it', async () => {
const container = {
inspect: jest.fn().mockResolvedValue({ State: { Running: true } }),
stop: jest.fn().mockResolvedValue(undefined),
};
await expect(makeService(container).stopService('database')).resolves.toBe(true);
expect(container.stop).toHaveBeenCalledTimes(1);
});
it('returns true when the container is already stopped', async () => {
const container = {
inspect: jest.fn().mockResolvedValue({ State: { Running: false } }),
stop: jest.fn(),
};
await expect(makeService(container).stopService('database')).resolves.toBe(true);
expect(container.stop).not.toHaveBeenCalled();
});
it('returns true when the container does not exist', async () => {
await expect(makeService(null).stopService('database')).resolves.toBe(true);
});
it('returns false when the daemon rejects the stop', async () => {
const container = {
inspect: jest.fn().mockResolvedValue({ State: { Running: true } }),
stop: jest.fn().mockRejectedValue(new Error('daemon gone')),
};
await expect(makeService(container).stopService('database')).resolves.toBe(false);
});
});
describe('DockerService.orchestrateProfiles', () => {
const availableService = () => {
const service = new DockerService();
Object.assign(service as unknown as Record<string, unknown>, { docker: {}, isAvailable: true });
return service;
};
it('fails fast when Docker is unavailable, keeping the estimated restart time', async () => {
const result = await new DockerService().orchestrateProfiles(['postgres', 'redis', 'minio']);
expect(result).toEqual({
success: false,
message: 'Docker is not available',
containersStarted: [],
containersStopped: [],
errors: [],
estimatedTime: 15 + 20 + 13 + 15,
});
});
it('starts each mapped profile in order and reports the success message', async () => {
const service = availableService();
const startService = jest.spyOn(service, 'startService').mockResolvedValue(true);
const result = await service.orchestrateProfiles(['postgres', 'redis']);
expect(startService).toHaveBeenNthCalledWith(1, 'database');
expect(startService).toHaveBeenNthCalledWith(2, 'cache');
expect(result).toEqual({
success: true,
message: 'Successfully orchestrated 2 service(s)',
containersStarted: ['postgres', 'redis'],
containersStopped: [],
errors: [],
estimatedTime: 15 + 20 + 13,
});
});
it('collects per-profile failures and still succeeds when at least one started', async () => {
const service = availableService();
jest.spyOn(service, 'startService').mockImplementation((svc: string) => Promise.resolve(svc === 'database'));
const result = await service.orchestrateProfiles(['postgres', 'redis']);
expect(result.success).toBe(true);
expect(result.containersStarted).toEqual(['postgres']);
expect(result.errors).toEqual([
"Failed to create or start the 'redis' container; see the server log for the Docker error.",
]);
expect(result.message).toBe(result.errors.join('; '));
});
it('captures a thrown start error instead of rejecting, and fails when nothing started', async () => {
const service = availableService();
jest.spyOn(service, 'startService').mockRejectedValue(new Error('boom'));
const result = await service.orchestrateProfiles(['postgres']);
expect(result.success).toBe(false);
expect(result.containersStarted).toEqual([]);
expect(result.errors).toEqual(['Failed to start postgres: boom']);
expect(result.message).toBe('Failed to start postgres: boom');
});
});
describe('DockerService availability recovery', () => {
const keys = [
'DOCKER_HOST',
'DATABASE_TYPE',
'STORAGE_TYPE',
'REDIS_ENABLED',
'QUEUE_ENABLED',
'CACHE_ENABLED',
'POSTGRES_BUILTIN',
'REDIS_BUILTIN',
'MINIO_BUILTIN',
'REDIS_HOST',
'DATABASE_PASSWORD',
'S3_ACCESS_KEY_ID',
'S3_SECRET_ACCESS_KEY',
'S3_ACCESS_KEY',
'S3_SECRET_KEY',
];
let saved: Record<string, string | undefined>;
beforeEach(() => {
saved = Object.fromEntries(keys.map(key => [key, process.env[key]]));
for (const key of keys) delete process.env[key];
Object.assign(process.env, {
DOCKER_HOST: 'tcp://proxy.invalid:2375',
DATABASE_TYPE: 'sqlite',
STORAGE_TYPE: 'local',
POSTGRES_BUILTIN: 'true',
REDIS_BUILTIN: 'true',
MINIO_BUILTIN: 'true',
REDIS_HOST: 'redis',
DATABASE_PASSWORD: '',
S3_ACCESS_KEY_ID: '',
S3_SECRET_ACCESS_KEY: '',
S3_ACCESS_KEY: '',
S3_SECRET_KEY: '',
});
recordPinnedEnvKeys({});
recordOsEnvKeys(process.env);
jest.useFakeTimers();
});
afterEach(() => {
for (const key of keys) {
if (saved[key] === undefined) delete process.env[key];
else process.env[key] = saved[key];
}
recordPinnedEnvKeys({});
recordOsEnvKeys(process.env);
DockerMock.mockReset();
jest.useRealTimers();
});
it.each([
[{ REDIS_ENABLED: 'true' }, false, ['openwa-redis']],
[{ QUEUE_ENABLED: 'true' }, false, ['openwa-redis']],
[{ CACHE_ENABLED: 'true' }, false, ['openwa-redis']],
[{ REDIS_ENABLED: 'true' }, true, []],
[{}, false, []],
] as const)(
'reconciles selected services once for %j with an external pin %s',
async (selection, external, expected) => {
Object.assign(process.env, selection);
if (external) {
process.env.REDIS_HOST = 'cache.external.invalid';
recordPinnedEnvKeys({ REDIS_HOST: 'cache.external.invalid' });
}
let reconnect: (() => void) | undefined;
let releaseStart: (() => void) | undefined;
const reconnecting = new Promise<void>(resolve => (reconnect = resolve));
const starting = new Promise<void>(resolve => (releaseStart = resolve));
const created: string[] = [];
const daemon = {
ping: jest
.fn()
.mockRejectedValueOnce(new Error('proxy not ready'))
.mockImplementation(() => reconnecting),
listContainers: jest.fn().mockResolvedValue([]),
getImage: () => ({ inspect: () => Promise.resolve({}) }),
modem: {},
createVolume: jest.fn().mockResolvedValue({}),
createContainer: jest.fn((config: { name: string }) => {
created.push(config.name);
return Promise.resolve({ start: () => starting });
}),
};
DockerMock.mockImplementation(() => daemon);
const service = new DockerService();
await service.onModuleInit();
for (let i = 0; i < 10; i++) service.isDockerAvailable();
expect(DockerMock).toHaveBeenCalledTimes(2);
reconnect!();
await jest.advanceTimersByTimeAsync(1);
expect(created).toEqual(expected);
for (let i = 0; i < 10; i++) service.isDockerAvailable();
expect(created).toEqual(expected);
expect(DockerMock).toHaveBeenCalledTimes(2);
releaseStart!();
await jest.advanceTimersByTimeAsync(1);
expect(created).toEqual(expected);
},
);
it('recovers a previously reachable local socket after its inventory fails', async () => {
delete process.env.DOCKER_HOST;
process.env.POSTGRES_BUILTIN = 'false';
process.env.REDIS_BUILTIN = 'false';
process.env.MINIO_BUILTIN = 'false';
const daemon = {
ping: jest.fn().mockResolvedValue(undefined),
listContainers: jest.fn().mockRejectedValueOnce(new Error('daemon restarted')).mockResolvedValue([]),
};
DockerMock.mockImplementation(() => daemon);
const service = new DockerService();
await service.onModuleInit();
await expect(service.listContainers()).resolves.toBeNull();
expect(service.isDockerAvailable()).toBe(false);
await jest.advanceTimersByTimeAsync(1);
expect(service.isDockerAvailable()).toBe(true);
await expect(service.listContainers()).resolves.toEqual([]);
});
});
describe('DockerService image inspection failures', () => {
function serviceFor(docker: unknown): DockerService {
const service = new DockerService();
service.callTimeoutMs = 40;
Object.assign(service as unknown as Record<string, unknown>, { docker, isAvailable: true });
jest.spyOn(service, 'getContainerByService').mockResolvedValue(null);
return service;
}
afterEach(() => {
jest.useRealTimers();
jest.restoreAllMocks();
});
it('aborts the real Dockerode image request without starting a pull after its deadline', async () => {
const RealDocker = jest.requireActual<typeof import('dockerode')>('dockerode');
let signal: AbortSignal | undefined;
const dial = jest.fn(
(options: { abortSignal?: AbortSignal }, callback: (error: Error | null, value?: unknown) => void) => {
signal = options.abortSignal;
signal?.addEventListener('abort', () => callback(new Error('inspection aborted')), { once: true });
},
);
const modem = { Promise, dial };
const pull = jest.fn();
const service = serviceFor({ modem, getImage: () => new RealDocker.Image(modem, 'redis:7-alpine'), pull });
jest.useFakeTimers();
const result = service.createService('redis');
await jest.advanceTimersByTimeAsync(80);
await expect(result).resolves.toBe(false);
expect(signal?.aborted).toBe(true);
expect(modem.dial).toBe(dial);
expect(pull).not.toHaveBeenCalled();
});
it.each([401, 500, undefined])('does not pull after an inspection error with status %s', async statusCode => {
const pull = jest.fn();
const error = Object.assign(new Error('inspection failed'), { statusCode });
const service = serviceFor({
modem: {},
getImage: () => ({ inspect: () => Promise.reject(error) }),
pull,
});
await expect(service.createService('redis')).resolves.toBe(false);
expect(pull).not.toHaveBeenCalled();
});
it('lets a missing image finish pulling after the short inspection deadline', async () => {
let finishPull: ((error: Error | null) => void) | undefined;
const start = jest.fn().mockResolvedValue(undefined);
const service = serviceFor({
modem: { followProgress: (_stream: unknown, callback: (error: Error | null) => void) => (finishPull = callback) },
getImage: imageNotCached,
pull: (_image: string, callback: (error: Error | null, stream: unknown) => void) => callback(null, {}),
createVolume: jest.fn().mockResolvedValue({}),
createContainer: jest.fn().mockResolvedValue({ start }),
});
jest.useFakeTimers();
let finished = false;
const result = service.createService('redis').then(value => {
finished = true;
return value;
});
await jest.advanceTimersByTimeAsync(160);
expect(finished).toBe(false);
expect(finishPull).toBeDefined();
finishPull!(null);
await expect(result).resolves.toBe(true);
expect(start).toHaveBeenCalledTimes(1);
});
});
describe('DockerService existing container inspection deadlines', () => {
afterEach(() => {
jest.useRealTimers();
jest.restoreAllMocks();
});
it.each(['create', 'start', 'stop'] as const)(
'aborts a stalled inspection before %s mutates a container',
async operation => {
const service = new DockerService();
service.callTimeoutMs = 40;
Object.assign(service as unknown as Record<string, unknown>, { docker: {}, isAvailable: true });
let signal: AbortSignal | undefined;
const container = {
inspect: jest.fn(
(options?: Docker.ContainerInspectOptions) =>
new Promise<never>((_resolve, reject) => {
signal = options?.abortSignal;
signal?.addEventListener('abort', () => reject(new Error('inspection aborted')), { once: true });
}),
),
start: jest.fn(),
stop: jest.fn(),
};
jest.spyOn(service, 'getContainerByService').mockResolvedValue(container as never);
jest.useFakeTimers();
let settled: boolean | undefined;
const action =
operation === 'create'
? service.createService('redis')
: operation === 'start'
? service.startService('cache')
: service.stopService('cache');
const work = action.then(value => {
settled = value;
return value;
});
await jest.advanceTimersByTimeAsync(80);
expect(settled).toBe(false);
expect(signal?.aborted).toBe(true);
expect(container.inspect).toHaveBeenCalledTimes(1);
expect(container.start).not.toHaveBeenCalled();
expect(container.stop).not.toHaveBeenCalled();
await expect(work).resolves.toBe(false);
},
);
});