@wopr-network/platform-core 1.0.10 → 1.1.0

package/dist/fleet/fleet-manager.js

@@ -0,0 +1,712 @@
+import { randomUUID } from "node:crypto";
+import { PassThrough } from "node:stream";
+import { logger } from "../config/logger.js";
+import { buildDiscoveryEnv } from "../discovery/discovery-config.js";
+import { getSharedVolumeConfig } from "./shared-volume-config.js";
+const CONTAINER_LABEL = "wopr.managed";
+const CONTAINER_ID_LABEL = "wopr.bot-id";
+export class FleetManager {
+    docker;
+    store;
+    platformDiscovery;
+    networkPolicy;
+    proxyManager;
+    commandBus;
+    instanceRepo;
+    botMetricsTracker;
+    eventEmitter;
+    locks = new Map();
+    async withLock(botId, fn) {
+        const prev = this.locks.get(botId) ?? Promise.resolve();
+        let resolve;
+        const next = new Promise((r) => {
+            resolve = r;
+        });
+        this.locks.set(botId, next);
+        try {
+            await prev;
+            return await fn();
+        }
+        finally {
+            resolve();
+            if (this.locks.get(botId) === next)
+                this.locks.delete(botId);
+        }
+    }
+    constructor(docker, store, platformDiscovery, networkPolicy, proxyManager, commandBus, instanceRepo, botMetricsTracker, eventEmitter) {
+        this.docker = docker;
+        this.store = store;
+        this.platformDiscovery = platformDiscovery;
+        this.networkPolicy = networkPolicy;
+        this.proxyManager = proxyManager;
+        this.commandBus = commandBus;
+        this.instanceRepo = instanceRepo;
+        this.botMetricsTracker = botMetricsTracker;
+        this.eventEmitter = eventEmitter;
+    }
+    emitEvent(type, botId, tenantId) {
+        if (!this.eventEmitter)
+            return;
+        if (!tenantId)
+            return; // skip — event with no tenant would be invisible to all subscribers
+        this.eventEmitter.emit({ type, botId, tenantId, timestamp: new Date().toISOString() });
+    }
+    /**
+     * Look up which node a bot is assigned to.
+     * Returns { nodeId, commandBus } when the bot has a remote assignment,
+     * or null when it should be handled locally.
+     * Callers use the returned commandBus reference directly, avoiding the need
+     * to re-check this.commandBus after the call.
+     */
+    async resolveNodeId(botId) {
+        if (!this.commandBus || !this.instanceRepo)
+            return null;
+        const instance = await this.instanceRepo.getById(botId);
+        if (!instance?.nodeId)
+            return null;
+        return { nodeId: instance.nodeId, commandBus: this.commandBus };
+    }
+    /**
+     * Create a new bot: persist profile, pull image, create container.
+     * Rolls back profile on container creation failure.
+     *
+     * @param params - Bot profile fields (without id)
+     * @param resourceLimits - Optional Docker resource constraints (from tier)
+     */
+    async create(params, resourceLimits) {
+        const id = params.id ?? randomUUID();
+        const hasExplicitId = "id" in params && params.id !== undefined;
+        const doCreate = async () => {
+            const profile = { ...params, id };
+            if (hasExplicitId && (await this.store.get(id))) {
+                throw new Error(`Bot with id ${id} already exists`);
+            }
+            await this.store.save(profile);
+            try {
+                const remote = await this.resolveNodeId(id);
+                if (remote) {
+                    // Dispatch to remote node agent — it handles pull + create + start
+                    await remote.commandBus.send(remote.nodeId, {
+                        type: "bot.start",
+                        payload: {
+                            name: profile.name,
+                            image: profile.image,
+                            env: profile.env,
+                            restart: profile.restartPolicy,
+                        },
+                    });
+                }
+                else {
+                    // Local dockerode fallback
+                    await this.pullImage(profile.image);
+                    await this.createContainer(profile, resourceLimits);
+                }
+            }
+            catch (err) {
+                logger.error(`Failed to create container for bot ${profile.id}, rolling back profile`, {
+                    err,
+                });
+                await this.store.delete(profile.id);
+                throw err;
+            }
+            // Register proxy route for tenant subdomain routing (non-fatal)
+            if (this.proxyManager) {
+                try {
+                    const subdomain = profile.name.toLowerCase().replace(/_/g, "-");
+                    await this.proxyManager.addRoute({
+                        instanceId: profile.id,
+                        subdomain,
+                        upstreamHost: `wopr-${subdomain}`,
+                        upstreamPort: 7437,
+                        healthy: true,
+                    });
+                }
+                catch (err) {
+                    logger.warn("Proxy route registration failed (non-fatal)", { botId: profile.id, err });
+                }
+            }
+            this.emitEvent("bot.created", profile.id, profile.tenantId);
+            return profile;
+        };
+        return hasExplicitId ? this.withLock(id, doCreate) : doCreate();
+    }
+    /**
+     * Start a stopped bot container.
+     * Valid from: stopped, created, exited, dead, error states.
+     * Throws InvalidStateTransitionError if the container is already running.
+     */
+    async start(id) {
+        return this.withLock(id, async () => {
+            this.botMetricsTracker?.reset(id);
+            const remote = await this.resolveNodeId(id);
+            if (remote) {
+                const profile = await this.store.get(id);
+                if (!profile)
+                    throw new BotNotFoundError(id);
+                await remote.commandBus.send(remote.nodeId, {
+                    type: "bot.start",
+                    payload: {
+                        name: profile.name,
+                        image: profile.image,
+                        env: profile.env,
+                        restart: profile.restartPolicy,
+                    },
+                });
+            }
+            else {
+                const container = await this.findContainer(id);
+                if (!container)
+                    throw new BotNotFoundError(id);
+                const info = await container.inspect();
+                const validStartStates = new Set(["stopped", "created", "exited", "dead", "error"]);
+                this.assertValidState(id, info.State.Status, "start", validStartStates);
+                await container.start();
+            }
+            if (this.proxyManager) {
+                this.proxyManager.updateHealth(id, true);
+            }
+            logger.info(`Started bot ${id}`);
+            let startedTenantId;
+            try {
+                startedTenantId = (await this.store.get(id))?.tenantId;
+            }
+            catch (err) {
+                logger.warn(`Failed to fetch profile after starting bot ${id}`, { err });
+            }
+            this.emitEvent("bot.started", id, startedTenantId);
+        });
+    }
+    /**
+     * Stop a running bot container.
+     * Valid from: running, starting, restarting states.
+     * Throws InvalidStateTransitionError if the container is not running.
+     */
+    async stop(id) {
+        return this.withLock(id, async () => {
+            const remote = await this.resolveNodeId(id);
+            if (remote) {
+                const profile = await this.store.get(id);
+                if (!profile)
+                    throw new BotNotFoundError(id);
+                await remote.commandBus.send(remote.nodeId, {
+                    type: "bot.stop",
+                    payload: { name: profile.name },
+                });
+            }
+            else {
+                const container = await this.findContainer(id);
+                if (!container)
+                    throw new BotNotFoundError(id);
+                const info = await container.inspect();
+                const validStopStates = new Set(["running", "starting", "restarting"]);
+                this.assertValidState(id, info.State.Status, "stop", validStopStates);
+                await container.stop();
+            }
+            if (this.proxyManager) {
+                this.proxyManager.updateHealth(id, false);
+            }
+            logger.info(`Stopped bot ${id}`);
+            let stoppedTenantId;
+            try {
+                stoppedTenantId = (await this.store.get(id))?.tenantId;
+            }
+            catch (err) {
+                logger.warn(`Failed to fetch profile after stopping bot ${id}`, { err });
+            }
+            this.emitEvent("bot.stopped", id, stoppedTenantId);
+        });
+    }
+    /**
+     * Restart: pull new image BEFORE restarting container to avoid downtime on pull failure.
+     * Valid from: running, stopped, exited, dead states.
+     * Throws InvalidStateTransitionError if the container is in an invalid state (e.g. paused).
+     * For remote bots, delegates to the node agent via NodeCommandBus.
+     */
+    async restart(id) {
+        return this.withLock(id, async () => {
+            this.botMetricsTracker?.reset(id);
+            const profile = await this.store.get(id);
+            if (!profile)
+                throw new BotNotFoundError(id);
+            const remote = await this.resolveNodeId(id);
+            if (remote) {
+                await remote.commandBus.send(remote.nodeId, {
+                    type: "bot.restart",
+                    payload: { name: profile.name },
+                });
+            }
+            else {
+                // Pull new image first — if this fails, old container is unchanged
+                await this.pullImage(profile.image);
+                const container = await this.findContainer(id);
+                if (!container)
+                    throw new BotNotFoundError(id);
+                const info = await container.inspect();
+                const validRestartStates = new Set(["running", "stopped", "exited", "dead"]);
+                this.assertValidState(id, info.State.Status, "restart", validRestartStates);
+                await container.restart();
+            }
+            logger.info(`Restarted bot ${id}`);
+            this.emitEvent("bot.restarted", id, profile.tenantId);
+        });
+    }
+    /**
+     * Remove a bot: stop container, remove it, optionally remove volumes, delete profile.
+     * For remote bots, delegates stop+remove to the node agent via NodeCommandBus.
+     */
+    async remove(id, removeVolumes = false) {
+        return this.withLock(id, async () => {
+            const profile = await this.store.get(id);
+            if (!profile)
+                throw new BotNotFoundError(id);
+            const remote = await this.resolveNodeId(id);
+            if (remote) {
+                await remote.commandBus.send(remote.nodeId, {
+                    type: "bot.remove",
+                    payload: { name: profile.name, removeVolumes },
+                });
+            }
+            else {
+                const container = await this.findContainer(id);
+                if (container) {
+                    const info = await container.inspect();
+                    if (info.State.Running) {
+                        await container.stop();
+                    }
+                    await container.remove({ v: removeVolumes });
+                }
+            }
+            // Clean up tenant network if no more containers remain
+            if (this.networkPolicy) {
+                await this.networkPolicy.cleanupAfterRemoval(profile.tenantId);
+            }
+            await this.store.delete(id);
+            if (this.proxyManager) {
+                this.proxyManager.removeRoute(id);
+            }
+            logger.info(`Removed bot ${id}`);
+            this.emitEvent("bot.removed", id, profile.tenantId);
+        });
+    }
+    /**
+     * Get live status of a single bot.
+     */
+    async status(id) {
+        const profile = await this.store.get(id);
+        if (!profile)
+            throw new BotNotFoundError(id);
+        const container = await this.findContainer(id);
+        if (!container) {
+            return this.offlineStatus(profile);
+        }
+        return this.buildStatus(profile, container);
+    }
+    /**
+     * List all bots with live status.
+     */
+    async listAll() {
+        const profiles = await this.store.list();
+        return Promise.all(profiles.map((p) => this.statusForProfile(p)));
+    }
+    /**
+     * List bots belonging to a specific tenant with live status.
+     */
+    async listByTenant(tenantId) {
+        const profiles = await this.store.list();
+        const tenantProfiles = profiles.filter((p) => p.tenantId === tenantId);
+        return Promise.all(tenantProfiles.map((p) => this.statusForProfile(p)));
+    }
+    /**
+     * Get container logs.
+     */
+    async logs(id, tail = 100) {
+        const container = await this.findContainer(id);
+        if (!container)
+            throw new BotNotFoundError(id);
+        const logBuffer = await container.logs({
+            stdout: true,
+            stderr: true,
+            tail,
+            timestamps: true,
+        });
+        // Docker returns multiplexed binary frames when Tty is false (the default).
+        // Demultiplex by stripping the 8-byte header from each frame so callers
+        // receive plain text instead of binary garbage interleaved with log lines.
+        const buf = Buffer.isBuffer(logBuffer) ? logBuffer : Buffer.from(logBuffer, "binary");
+        const chunks = [];
+        let offset = 0;
+        while (offset + 8 <= buf.length) {
+            const frameSize = buf.readUInt32BE(offset + 4);
+            const end = offset + 8 + frameSize;
+            if (end > buf.length)
+                break;
+            chunks.push(buf.subarray(offset + 8, end));
+            offset = end;
+        }
+        // If demux produced nothing (e.g. TTY container), fall back to raw string
+        return chunks.length > 0 ? Buffer.concat(chunks).toString("utf-8") : buf.toString("utf-8");
+    }
+    /**
+     * Stream container logs in real-time (follow mode).
+     * Returns a Node.js ReadableStream that emits plain-text log chunks (already demultiplexed).
+     * For remote bots, proxies via node-agent bot.logs command and returns a one-shot stream.
+     * Caller is responsible for destroying the stream when done.
+     */
+    async logStream(id, opts) {
+        // Check for remote node assignment first (mirrors start/stop/restart pattern)
+        const remote = await this.resolveNodeId(id);
+        if (remote) {
+            const profile = await this.store.get(id);
+            if (!profile)
+                throw new BotNotFoundError(id);
+            const result = await remote.commandBus.send(remote.nodeId, {
+                type: "bot.logs",
+                payload: { name: profile.name, tail: opts.tail ?? 100 },
+            });
+            const logData = typeof result.data === "string" ? result.data : "";
+            const pt = new PassThrough();
+            pt.end(logData);
+            return pt;
+        }
+        const container = await this.findContainer(id);
+        if (!container)
+            throw new BotNotFoundError(id);
+        const logOpts = {
+            stdout: true,
+            stderr: true,
+            follow: true,
+            tail: opts.tail ?? 100,
+            timestamps: true,
+        };
+        if (opts.since) {
+            logOpts.since = opts.since;
+        }
+        // Docker returns a multiplexed binary stream when Tty is false (the default for
+        // containers created by createContainer without Tty:true). Demultiplex it so
+        // callers receive plain text without 8-byte binary frame headers.
+        const multiplexed = (await container.logs(logOpts));
+        const pt = new PassThrough();
+        this.docker.modem.demuxStream(multiplexed, pt, pt);
+        return pt;
+    }
+    /** Fields that require container recreation when changed. */
+    static CONTAINER_FIELDS = new Set([
+        "image",
+        "env",
+        "restartPolicy",
+        "volumeName",
+        "name",
+        "discovery",
+    ]);
+    /**
+     * Update a bot profile. Only recreates the container if container-relevant
+     * fields changed. Rolls back the profile if container recreation fails.
+     */
+    async update(id, updates) {
+        return this.withLock(id, async () => {
+            const existing = await this.store.get(id);
+            if (!existing)
+                throw new BotNotFoundError(id);
+            const updated = { ...existing, ...updates };
+            const needsRecreate = Object.keys(updates).some((k) => FleetManager.CONTAINER_FIELDS.has(k));
+            const container = await this.findContainer(id);
+            if (container && needsRecreate) {
+                const info = await container.inspect();
+                const wasRunning = info.State.Running;
+                // Save the updated profile only after pre-checks succeed
+                if (updates.image) {
+                    await this.pullImage(updated.image);
+                }
+                await this.store.save(updated);
+                try {
+                    if (wasRunning) {
+                        try {
+                            await container.stop();
+                        }
+                        catch (err) {
+                            logger.warn(`Failed to stop container ${id} during update`, { botId: id, err });
+                            throw err;
+                        }
+                    }
+                    try {
+                        await container.remove();
+                    }
+                    catch (err) {
+                        logger.warn(`Failed to remove container ${id} during update`, { botId: id, err });
+                        throw err;
+                    }
+                    await this.createContainer(updated);
+                    if (wasRunning) {
+                        const newContainer = await this.findContainer(id);
+                        if (newContainer)
+                            await newContainer.start();
+                    }
+                }
+                catch (err) {
+                    // Rollback profile to the previous state
+                    logger.error(`Failed to recreate container for bot ${id}, rolling back profile`, { err });
+                    await this.store.save(existing);
+                    throw err;
+                }
+            }
+            else {
+                // Metadata-only change or no container — just save the profile
+                await this.store.save(updated);
+            }
+            return updated;
+        });
+    }
+    /**
+     * Get disk usage for a bot's /data volume.
+     * Returns null if the container is not running or exec fails.
+     */
+    async getVolumeUsage(id) {
+        const container = await this.findContainer(id);
+        if (!container)
+            return null;
+        try {
+            const info = await container.inspect();
+            if (!info.State.Running)
+                return null;
+            const exec = await container.exec({
+                Cmd: ["df", "-B1", "/data"],
+                AttachStdout: true,
+                AttachStderr: false,
+            });
+            const output = await new Promise((resolve, reject) => {
+                exec.start({}, (err, stream) => {
+                    if (err)
+                        return reject(err);
+                    if (!stream)
+                        return reject(new Error("No stream from exec"));
+                    let data = "";
+                    stream.on("data", (chunk) => {
+                        data += chunk.toString();
+                    });
+                    stream.on("end", () => resolve(data));
+                    stream.on("error", reject);
+                });
+            });
+            // Parse df output — second line has the numbers
+            const lines = output.trim().split("\n");
+            if (lines.length < 2)
+                return null;
+            const parts = lines[lines.length - 1].split(/\s+/);
+            if (parts.length < 4)
+                return null;
+            const totalBytes = parseInt(parts[1], 10);
+            const usedBytes = parseInt(parts[2], 10);
+            const availableBytes = parseInt(parts[3], 10);
+            if (Number.isNaN(totalBytes) || Number.isNaN(usedBytes) || Number.isNaN(availableBytes))
+                return null;
+            return { usedBytes, totalBytes, availableBytes };
+        }
+        catch {
+            logger.warn(`Failed to get volume usage for bot ${id}`);
+            return null;
+        }
+    }
+    /** Get the underlying profile store */
+    get profiles() {
+        return this.store;
+    }
+    // --- Private helpers ---
+    /**
+     * Assert that a container's current state is valid for the requested operation.
+     * Guards against undefined/null Status values from Docker (uses "unknown" as fallback).
+     * Throws InvalidStateTransitionError when the state is not in validStates.
+     */
+    assertValidState(id, rawStatus, operation, validStates) {
+        const currentState = typeof rawStatus === "string" && rawStatus ? rawStatus : "unknown";
+        if (!validStates.has(currentState)) {
+            throw new InvalidStateTransitionError(id, operation, currentState, [...validStates]);
+        }
+    }
+    async pullImage(image) {
+        logger.info(`Pulling image ${image}`);
+        // Build authconfig from environment variables if present.
+        // REGISTRY_USERNAME / REGISTRY_PASSWORD / REGISTRY_SERVER are optional;
+        // when set they allow pulling from private registries (e.g. ghcr.io).
+        const username = process.env.REGISTRY_USERNAME;
+        const password = process.env.REGISTRY_PASSWORD;
+        const server = process.env.REGISTRY_SERVER;
+        const authconfig = username && password ? { username, password, serveraddress: server ?? "ghcr.io" } : undefined;
+        const stream = await this.docker.pull(image, authconfig ? { authconfig } : {});
+        await new Promise((resolve, reject) => {
+            this.docker.modem.followProgress(stream, (err) => {
+                if (err)
+                    reject(err);
+                else
+                    resolve();
+            });
+        });
+    }
+    async createContainer(profile, resourceLimits) {
+        const restartPolicyMap = {
+            no: "no",
+            always: "always",
+            "on-failure": "on-failure",
+            "unless-stopped": "unless-stopped",
+        };
+        const binds = [];
+        if (profile.volumeName) {
+            binds.push(`${profile.volumeName}:/data`);
+        }
+        // Mount shared node_modules volume read-only (WOP-973)
+        const sharedVolConfig = getSharedVolumeConfig();
+        if (sharedVolConfig.enabled) {
+            binds.push(`${sharedVolConfig.volumeName}:${sharedVolConfig.mountPath}:ro`);
+        }
+        const hostConfig = {
+            RestartPolicy: {
+                Name: restartPolicyMap[profile.restartPolicy] || "",
+            },
+            Binds: binds.length > 0 ? binds : undefined,
+            SecurityOpt: ["no-new-privileges"],
+            CapDrop: ["ALL"],
+            CapAdd: ["NET_BIND_SERVICE"],
+            ReadonlyRootfs: true,
+            Tmpfs: {
+                "/tmp": "rw,noexec,nosuid,size=64m",
+                "/var/tmp": "rw,noexec,nosuid,size=64m",
+            },
+        };
+        // Set tenant network isolation if NetworkPolicy is configured
+        if (this.networkPolicy) {
+            const networkMode = await this.networkPolicy.prepareForContainer(profile.tenantId);
+            hostConfig.NetworkMode = networkMode;
+        }
+        // Apply resource limits from tier if provided
+        if (resourceLimits) {
+            hostConfig.Memory = resourceLimits.Memory;
+            hostConfig.CpuQuota = resourceLimits.CpuQuota;
+            hostConfig.PidsLimit = resourceLimits.PidsLimit;
+        }
+        // Merge discovery env vars into the container environment.
+        // discoveryEnv overrides profile.env (spread order matters).
+        // Empty-string values mean "explicitly remove" — filter them out.
+        const discoveryEnv = buildDiscoveryEnv(profile.discovery, this.platformDiscovery);
+        const sharedNodePath = sharedVolConfig.enabled ? { NODE_PATH: sharedVolConfig.mountPath } : {};
+        const mergedEnv = { ...profile.env, ...sharedNodePath, ...discoveryEnv };
+        const container = await this.docker.createContainer({
+            Image: profile.image,
+            name: `wopr-${profile.name.replace(/_/g, "-")}`,
+            Env: Object.entries(mergedEnv)
+                .filter(([, v]) => v !== "")
+                .map(([k, v]) => `${k}=${v}`),
+            Labels: {
+                [CONTAINER_LABEL]: "true",
+                [CONTAINER_ID_LABEL]: profile.id,
+            },
+            HostConfig: hostConfig,
+            Healthcheck: {
+                Test: ["CMD-SHELL", "node -e 'process.exit(0)'"],
+                Interval: 30_000_000_000, // 30s in nanoseconds
+                Timeout: 10_000_000_000,
+                Retries: 3,
+                StartPeriod: 15_000_000_000,
+            },
+        });
+        logger.info(`Created container ${container.id} for bot ${profile.id}`);
+        return container;
+    }
+    async findContainer(botId) {
+        const containers = await this.docker.listContainers({
+            all: true,
+            filters: {
+                label: [`${CONTAINER_ID_LABEL}=${botId}`],
+            },
+        });
+        if (containers.length === 0)
+            return null;
+        return this.docker.getContainer(containers[0].Id);
+    }
+    async statusForProfile(profile) {
+        const container = await this.findContainer(profile.id);
+        if (!container)
+            return this.offlineStatus(profile);
+        return this.buildStatus(profile, container);
+    }
+    async buildStatus(profile, container) {
+        const info = await container.inspect();
+        let stats = null;
+        if (info.State.Running) {
+            try {
+                stats = await this.getStats(container);
+            }
+            catch {
+                // stats not available
+            }
+        }
+        const now = new Date().toISOString();
+        return {
+            id: profile.id,
+            name: profile.name,
+            description: profile.description,
+            image: profile.image,
+            containerId: info.Id,
+            state: info.State.Status,
+            health: info.State.Health?.Status ?? null,
+            uptime: info.State.Running && info.State.StartedAt ? info.State.StartedAt : null,
+            startedAt: info.State.StartedAt || null,
+            createdAt: info.Created || now,
+            updatedAt: now,
+            stats,
+            applicationMetrics: this.botMetricsTracker?.getMetrics(profile.id) ?? null,
+        };
+    }
+    offlineStatus(profile) {
+        const now = new Date().toISOString();
+        return {
+            id: profile.id,
+            name: profile.name,
+            description: profile.description,
+            image: profile.image,
+            containerId: null,
+            state: "stopped",
+            health: null,
+            uptime: null,
+            startedAt: null,
+            createdAt: now,
+            updatedAt: now,
+            stats: null,
+            applicationMetrics: null,
+        };
+    }
+    async getStats(container) {
+        const raw = await container.stats({ stream: false });
+        const cpuDelta = raw.cpu_stats.cpu_usage.total_usage - raw.precpu_stats.cpu_usage.total_usage;
+        const systemDelta = raw.cpu_stats.system_cpu_usage - raw.precpu_stats.system_cpu_usage;
+        const numCpus = raw.cpu_stats.online_cpus || 1;
+        const cpuPercent = systemDelta > 0 ? (cpuDelta / systemDelta) * numCpus * 100 : 0;
+        const memUsage = raw.memory_stats.usage || 0;
+        const memLimit = raw.memory_stats.limit || 1;
+        return {
+            cpuPercent: Math.round(cpuPercent * 100) / 100,
+            memoryUsageMb: Math.round(memUsage / 1024 / 1024),
+            memoryLimitMb: Math.round(memLimit / 1024 / 1024),
+            memoryPercent: Math.round((memUsage / memLimit) * 100 * 100) / 100,
+        };
+    }
+}
+export class BotNotFoundError extends Error {
+    constructor(id) {
+        super(`Bot not found: ${id}`);
+        this.name = "BotNotFoundError";
+    }
+}
+export class InvalidStateTransitionError extends Error {
+    botId;
+    operation;
+    currentState;
+    validStates;
+    constructor(botId, operation, currentState, validStates) {
+        super(`Cannot ${operation} bot ${botId}: container is in state "${currentState}". ` +
+            `Valid states for ${operation}: ${validStates.join(", ")}.`);
+        this.name = "InvalidStateTransitionError";
+        this.botId = botId;
+        this.operation = operation;
+        this.currentState = currentState;
+        this.validStates = validStates;
+    }
+}