@wopr-network/platform-core 1.37.0 → 1.39.0

package/src/fleet/fleet-manager.test.ts

@@ -2,7 +2,7 @@ import type Docker from "dockerode";
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 import type { NetworkPolicy } from "../network/network-policy.js";
 import type { IBotInstanceRepository } from "./bot-instance-repository.js";
-import { BotNotFoundError, FleetManager, InvalidStateTransitionError } from "./fleet-manager.js";
+import { BotNotFoundError, FleetManager } from "./fleet-manager.js";
 import type { INodeCommandBus } from "./node-command-bus.js";
 import type { ProfileStore } from "./profile-store.js";
 import type { BotInstance, NewBotInstance } from "./repository-types.js";
@@ -19,6 +19,7 @@ function mockContainer(overrides: Record<string, unknown> = {}) {
     remove: vi.fn().mockResolvedValue(undefined),
     inspect: vi.fn().mockResolvedValue({
       Id: "container-123",
+      Name: "/wopr-test-bot",
       Created: "2026-01-01T00:00:00Z",
       State: {
         Status: "running",
@@ -26,6 +27,7 @@ function mockContainer(overrides: Record<string, unknown> = {}) {
         StartedAt: "2026-01-01T00:00:00Z",
         Health: { Status: "healthy" },
       },
+      NetworkSettings: { Ports: {} },
     }),
     stats: vi.fn().mockResolvedValue({
       cpu_stats: { cpu_usage: { total_usage: 200 }, system_cpu_usage: 2000, online_cpus: 2 },
@@ -108,10 +110,10 @@ describe("FleetManager", () => {
 
   describe("create", () => {
     it("saves profile, pulls image, and creates container", async () => {
-      const profile = await fleet.create(PROFILE_PARAMS);
+      const instance = await fleet.create(PROFILE_PARAMS);
 
-      expect(profile.id).toEqual(expect.any(String));
-      expect(profile.name).toBe("test-bot");
+      expect(instance.id).toEqual(expect.any(String));
+      expect(instance.profile.name).toBe("test-bot");
       expect(store.save).toHaveBeenCalledWith(expect.objectContaining({ name: "test-bot" }));
       expect(docker.pull).toHaveBeenCalledWith("ghcr.io/wopr-network/wopr:stable", {});
       expect(docker.createContainer).toHaveBeenCalledWith(
@@ -140,94 +142,19 @@ describe("FleetManager", () => {
   });
 
   describe("start", () => {
-    it("starts an existing stopped container", async () => {
-      // Container must be in a stopped/created/exited state
-      container.inspect.mockResolvedValue({
-        Id: "container-123",
-        Created: "2026-01-01T00:00:00Z",
-        State: { Status: "stopped", Running: false, StartedAt: "", Health: { Status: "healthy" } },
-      });
-      docker.listContainers.mockResolvedValue([{ Id: "container-123" }]);
-
-      await fleet.start("bot-id");
-      expect(container.start).toHaveBeenCalled();
-    });
-
-    it("starts an exited container", async () => {
-      container.inspect.mockResolvedValue({
-        Id: "container-123",
-        Created: "2026-01-01T00:00:00Z",
-        State: { Status: "exited", Running: false, StartedAt: "", Health: null },
-      });
-      docker.listContainers.mockResolvedValue([{ Id: "container-123" }]);
-
-      await fleet.start("bot-id");
+    it("starts a created container via Instance.start()", async () => {
+      const instance = await fleet.create(PROFILE_PARAMS);
+      await instance.start();
       expect(container.start).toHaveBeenCalled();
     });
-
-    it("starts a dead container", async () => {
-      container.inspect.mockResolvedValue({
-        Id: "container-123",
-        Created: "2026-01-01T00:00:00Z",
-        State: { Status: "dead", Running: false, StartedAt: "", Health: null },
-      });
-      docker.listContainers.mockResolvedValue([{ Id: "container-123" }]);
-
-      await fleet.start("bot-id");
-      expect(container.start).toHaveBeenCalled();
-    });
-
-    it("throws InvalidStateTransitionError with 'unknown' when Status is missing/null", async () => {
-      container.inspect.mockResolvedValue({
-        Id: "container-123",
-        Created: "2026-01-01T00:00:00Z",
-        State: { Status: null, Running: false, StartedAt: "", Health: null },
-      });
-      docker.listContainers.mockResolvedValue([{ Id: "container-123" }]);
-
-      await expect(fleet.start("bot-id")).rejects.toThrow(InvalidStateTransitionError);
-      await expect(fleet.start("bot-id")).rejects.toThrow(/unknown/);
-    });
-
-    it("throws InvalidStateTransitionError when container is already running", async () => {
-      // Default mockContainer has state "running"
-      docker.listContainers.mockResolvedValue([{ Id: "container-123" }]);
-
-      await expect(fleet.start("bot-id")).rejects.toThrow(InvalidStateTransitionError);
-      await expect(fleet.start("bot-id")).rejects.toThrow(/Cannot start bot/);
-    });
-
-    it("throws BotNotFoundError when container not found", async () => {
-      docker.listContainers.mockResolvedValue([]);
-      await expect(fleet.start("missing")).rejects.toThrow(BotNotFoundError);
-    });
   });
 
   describe("stop", () => {
-    it("stops a running container", async () => {
-      // Default mockContainer has state "running" — valid for stop
-      docker.listContainers.mockResolvedValue([{ Id: "container-123" }]);
-
-      await fleet.stop("bot-id");
+    it("stops a running container via Instance.stop()", async () => {
+      const instance = await fleet.create(PROFILE_PARAMS);
+      await instance.stop();
       expect(container.stop).toHaveBeenCalled();
     });
-
-    it("throws InvalidStateTransitionError when container is already stopped", async () => {
-      container.inspect.mockResolvedValue({
-        Id: "container-123",
-        Created: "2026-01-01T00:00:00Z",
-        State: { Status: "exited", Running: false, StartedAt: "", Health: null },
-      });
-      docker.listContainers.mockResolvedValue([{ Id: "container-123" }]);
-
-      await expect(fleet.stop("bot-id")).rejects.toThrow(InvalidStateTransitionError);
-      await expect(fleet.stop("bot-id")).rejects.toThrow(/Cannot stop bot/);
-    });
-
-    it("throws BotNotFoundError when container not found", async () => {
-      docker.listContainers.mockResolvedValue([]);
-      await expect(fleet.stop("missing")).rejects.toThrow(BotNotFoundError);
-    });
   });
 
   describe("restart", () => {
@@ -521,10 +448,11 @@ describe("FleetManager", () => {
       );
     });
 
-    it("calls addRoute on create with correct subdomain and upstream", async () => {
-      const profile = await proxyFleet.create(PROFILE_PARAMS);
+    it("calls addRoute via setupProxy with correct subdomain and upstream", async () => {
+      const instance = await proxyFleet.create(PROFILE_PARAMS);
+      await instance.setupProxy();
       expect(proxyManager.addRoute).toHaveBeenCalledWith({
-        instanceId: profile.id,
+        instanceId: instance.id,
         subdomain: "test-bot",
         upstreamHost: "wopr-test-bot",
         upstreamPort: 7437,
@@ -532,11 +460,12 @@ describe("FleetManager", () => {
       });
     });
 
-    it("still returns profile when addRoute fails (non-fatal)", async () => {
+    it("still returns instance when setupProxy addRoute fails (non-fatal)", async () => {
+      const instance = await proxyFleet.create(PROFILE_PARAMS);
       proxyManager.addRoute.mockRejectedValueOnce(new Error("DNS fail"));
-      const profile = await proxyFleet.create(PROFILE_PARAMS);
-      expect(profile.id).toEqual(expect.any(String));
-      expect(profile.name).toBe("test-bot");
+      await instance.setupProxy();
+      expect(instance.id).toEqual(expect.any(String));
+      expect(instance.profile.name).toBe("test-bot");
     });
 
     it("calls removeRoute on remove", async () => {
@@ -546,36 +475,33 @@ describe("FleetManager", () => {
       expect(proxyManager.removeRoute).toHaveBeenCalledWith("bot-id");
     });
 
-    it("calls updateHealth(true) on start", async () => {
-      container.inspect.mockResolvedValue({
-        Id: "container-123",
-        Created: "2026-01-01T00:00:00Z",
-        State: { Status: "stopped", Running: false, StartedAt: "", Health: { Status: "healthy" } },
-      });
-      docker.listContainers.mockResolvedValue([{ Id: "container-123" }]);
-      await proxyFleet.start("bot-id");
-      expect(proxyManager.updateHealth).toHaveBeenCalledWith("bot-id", true);
+    it("starts via Instance.start()", async () => {
+      const instance = await proxyFleet.create(PROFILE_PARAMS);
+      await instance.start();
+      expect(container.start).toHaveBeenCalled();
     });
 
-    it("calls updateHealth(false) on stop", async () => {
-      docker.listContainers.mockResolvedValue([{ Id: "container-123" }]);
-      await proxyFleet.stop("bot-id");
-      expect(proxyManager.updateHealth).toHaveBeenCalledWith("bot-id", false);
+    it("stops via Instance.stop()", async () => {
+      const instance = await proxyFleet.create(PROFILE_PARAMS);
+      await instance.stop();
+      expect(container.stop).toHaveBeenCalled();
     });
 
     it("does not call proxy methods when no proxyManager is provided", async () => {
       // `fleet` from the outer beforeEach has no proxyManager
-      const profile = await fleet.create(PROFILE_PARAMS);
+      const instance = await fleet.create(PROFILE_PARAMS);
+      await instance.setupProxy(); // no-op since no proxyManager
       expect(proxyManager.addRoute).not.toHaveBeenCalled();
-      expect(profile.id).toEqual(expect.any(String));
+      expect(instance.id).toEqual(expect.any(String));
     });
 
     it("normalizes underscores to hyphens in subdomain", async () => {
-      await proxyFleet.create({ ...PROFILE_PARAMS, name: "my_cool_bot" });
+      const instance = await proxyFleet.create({ ...PROFILE_PARAMS, name: "my_cool_bot" });
+      await instance.setupProxy();
       expect(proxyManager.addRoute).toHaveBeenCalledWith(
         expect.objectContaining({
           subdomain: "my-cool-bot",
-          upstreamHost: "wopr-my-cool-bot",
+          upstreamHost: "wopr-test-bot",
         }),
       );
     });
@@ -646,76 +572,6 @@ describe("FleetManager", () => {
   });
 
   describe("per-bot mutex", () => {
-    it("serializes 5 concurrent startBot calls into exactly 1 start per call", async () => {
-      // Containers must be in stopped state so the state guard passes
-      container.inspect.mockResolvedValue({
-        Id: "container-123",
-        Created: "2026-01-01T00:00:00Z",
-        State: { Status: "stopped", Running: false, StartedAt: "", Health: null },
-      });
-      docker.listContainers.mockResolvedValue([{ Id: "container-123" }]);
-
-      let startCount = 0;
-      container.start.mockImplementation(async () => {
-        startCount++;
-        const current = startCount;
-        await new Promise((r) => setTimeout(r, 10));
-        expect(startCount).toBe(current);
-      });
-
-      const promises = Array.from({ length: 5 }, () => fleet.start("bot-id"));
-      await Promise.all(promises);
-
-      expect(container.start).toHaveBeenCalledTimes(5);
-    });
-
-    it("does not block operations on different bots (proves concurrency)", async () => {
-      // For this test: start needs stopped state, stop needs running state.
-      // Both bot-a and bot-b share the same mock container.
-      // Use a stopped state so start() passes, and mock stop() directly so it bypasses state check.
-      container.inspect.mockResolvedValue({
-        Id: "container-123",
-        Created: "2026-01-01T00:00:00Z",
-        State: { Status: "stopped", Running: false, StartedAt: "", Health: null },
-      });
-      docker.listContainers.mockResolvedValue([{ Id: "container-123" }]);
-
-      let releaseStart!: () => void;
-      container.start.mockImplementation(
-        () =>
-          new Promise<void>((resolve) => {
-            releaseStart = resolve;
-          }),
-      );
-      const stopSpy = vi.fn();
-      // Override inspect for the stop path to return "running" state
-      let callCount = 0;
-      container.inspect.mockImplementation(async () => {
-        callCount++;
-        // First call is for bot-a start, subsequent for bot-b stop
-        return callCount === 1
-          ? { Id: "container-123", State: { Status: "stopped", Running: false } }
-          : { Id: "container-123", State: { Status: "running", Running: true } };
-      });
-      container.stop.mockImplementation(async () => {
-        stopSpy();
-      });
-
-      const startPromise = fleet.start("bot-a");
-      await Promise.resolve(); // allow start lock acquisition
-      await expect(fleet.stop("bot-b")).resolves.toBeUndefined();
-      expect(stopSpy).toHaveBeenCalledTimes(1);
-      releaseStart();
-      await startPromise;
-    });
-
-    it("releases lock even when operation throws", async () => {
-      docker.listContainers.mockResolvedValue([]);
-
-      await expect(fleet.start("bot-id")).rejects.toThrow(BotNotFoundError);
-      await expect(fleet.start("bot-id")).rejects.toThrow(BotNotFoundError);
-    });
-
     it("serializes concurrent create calls with the same explicit ID (mutual exclusion)", async () => {
       // Add a delay to store.save so the race is observable: the mutex must ensure
       // the first save completes before the second call checks for the existing profile.
@@ -800,7 +656,7 @@ describe("FleetManager", () => {
         instanceRepo,
       );
 
-      const profile = await fleet.create({
+      const instance = await fleet.create({
         id: botId,
         tenantId: "t1",
         name: "test-bot",
@@ -812,7 +668,7 @@ describe("FleetManager", () => {
         updatePolicy: "manual",
       });
 
-      expect(profile.id).toBe(botId);
+      expect(instance.id).toBe(botId);
       expect(bus.send).toHaveBeenCalledWith("node-1", {
         type: "bot.start",
         payload: {
@@ -862,45 +718,6 @@ describe("FleetManager", () => {
       expect(docker.pull).toHaveBeenCalled();
     });
 
-    it("should dispatch stop via commandBus when bot has nodeId", async () => {
-      const container = mockContainer();
-      const docker = mockDocker(container);
-      const store = mockStore();
-      const bus = mockCommandBus();
-      const instanceRepo = mockInstanceRepo();
-
-      const botId = "bot-stop-1";
-      await instanceRepo.create({ id: botId, tenantId: "t1", name: "stop-bot", nodeId: "node-2" });
-
-      const fleet = new FleetManager(
-        docker as unknown as Docker,
-        store,
-        undefined,
-        undefined,
-        undefined,
-        bus,
-        instanceRepo,
-      );
-
-      await store.save({
-        id: botId,
-        tenantId: "t1",
-        name: "stop-bot",
-        description: "",
-        image: "ghcr.io/wopr-network/wopr:latest",
-        env: {},
-        restartPolicy: "unless-stopped",
-      } as BotProfile);
-
-      await fleet.stop(botId);
-
-      expect(bus.send).toHaveBeenCalledWith("node-2", {
-        type: "bot.stop",
-        payload: { name: "stop-bot" },
-      });
-      expect(container.stop).not.toHaveBeenCalled();
-    });
-
     it("should dispatch restart via commandBus when bot has nodeId", async () => {
       const container = mockContainer();
       const docker = mockDocker(container);

package/src/fleet/fleet-manager.ts

@@ -10,6 +10,7 @@ import type { NetworkPolicy } from "../network/network-policy.js";
 import type { ProxyManagerInterface } from "../proxy/types.js";
 import type { IBotInstanceRepository } from "./bot-instance-repository.js";
 import type { BotEventType, FleetEventEmitter } from "./fleet-event-emitter.js";
+import { Instance } from "./instance.js";
 import type { INodeCommandBus } from "./node-command-bus.js";
 import type { IProfileStore } from "./profile-store.js";
 import { getSharedVolumeConfig } from "./shared-volume-config.js";
@@ -98,10 +99,10 @@ export class FleetManager {
   async create(
     params: Omit<BotProfile, "id"> & { id?: string },
     resourceLimits?: ContainerResourceLimits,
-  ): Promise<BotProfile> {
+  ): Promise<Instance> {
     const id = params.id ?? randomUUID();
     const hasExplicitId = "id" in params && params.id !== undefined;
-    const doCreate = async () => {
+    const doCreate = async (): Promise<Instance> => {
       const profile: BotProfile = { ...params, id };
 
       if (hasExplicitId && (await this.store.get(id))) {
@@ -113,7 +114,6 @@ export class FleetManager {
       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: {
@@ -123,8 +123,21 @@ export class FleetManager {
               restart: profile.restartPolicy,
             },
           });
+          // Remote bots have no local container — return a remote Instance
+          const containerName = `wopr-${profile.name.replace(/_/g, "-")}`;
+          const remoteInstance = new Instance({
+            docker: this.docker,
+            profile,
+            containerId: `remote:${remote.nodeId}`,
+            containerName,
+            url: `remote://${remote.nodeId}/${containerName}`,
+            instanceRepo: this.instanceRepo,
+            proxyManager: this.proxyManager,
+            eventEmitter: this.eventEmitter,
+          });
+          remoteInstance.emitCreated();
+          return remoteInstance;
         } else {
-          // Local dockerode fallback
           await this.pullImage(profile.image);
           await this.createContainer(profile, resourceLimits);
         }
@@ -136,106 +149,60 @@ export class FleetManager {
         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;
+      const instance = await this.buildInstance(profile);
+      instance.emitCreated();
+      return instance;
     };
 
     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.
+   * Build an Instance from a profile after container creation.
+   * Inspects the Docker container to resolve container name and URL.
    */
-  async start(id: string): Promise<void> {
-    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: string | undefined;
-      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);
-    });
+  private resolvePort(profile: BotProfile): number {
+    const envPort = profile.env?.PORT;
+    return envPort ? Number.parseInt(envPort, 10) || 7437 : 7437;
   }
 
   /**
-   * Stop a running bot container.
-   * Valid from: running, starting, restarting states.
-   * Throws InvalidStateTransitionError if the container is not running.
+   * Get an Instance handle for an existing bot by ID.
+   * Looks up the profile and inspects the Docker container.
    */
-  async stop(id: string): Promise<void> {
-    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: string | undefined;
-      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);
+  async getInstance(id: string): Promise<Instance> {
+    const profile = await this.store.get(id);
+    if (!profile) throw new BotNotFoundError(id);
+    return this.buildInstance(profile);
+  }
+
+  private async buildInstance(profile: BotProfile): Promise<Instance> {
+    const dockerContainer = await this.findContainer(profile.id);
+    if (!dockerContainer) throw new Error(`Container for ${profile.id} not found after creation`);
+    const info = await dockerContainer.inspect();
+    const containerName = info.Name.replace(/^\//, "");
+    const containerId = info.Id;
+
+    // Resolve URL from network DNS or host port mapping
+    let url: string;
+    const port = this.resolvePort(profile);
+    if (profile.network) {
+      url = `http://${containerName}:${port}`;
+    } else {
+      const portBindings = info.NetworkSettings?.Ports?.[`${port}/tcp`];
+      const hostPort = portBindings?.[0]?.HostPort ?? String(port);
+      url = `http://localhost:${hostPort}`;
+    }
+
+    return new Instance({
+      docker: this.docker,
+      profile,
+      containerId,
+      containerName,
+      url,
+      instanceRepo: this.instanceRepo,
+      proxyManager: this.proxyManager,
+      eventEmitter: this.eventEmitter,
     });
   }
 
@@ -433,6 +400,8 @@ export class FleetManager {
     "volumeName",
     "name",
     "discovery",
+    "network",
+    "ephemeral",
   ]);
 
   /**
@@ -608,23 +577,29 @@ export class FleetManager {
       binds.push(`${sharedVolConfig.volumeName}:${sharedVolConfig.mountPath}:ro`);
     }
 
+    const isEphemeral = profile.ephemeral === true;
+
     const hostConfig: Docker.ContainerCreateOptions["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",
-      },
+      CapDrop: isEphemeral ? undefined : ["ALL"],
+      CapAdd: isEphemeral ? undefined : ["NET_BIND_SERVICE"],
+      ReadonlyRootfs: !isEphemeral,
+      Tmpfs: isEphemeral
+        ? undefined
+        : {
+            "/tmp": "rw,noexec,nosuid,size=64m",
+            "/var/tmp": "rw,noexec,nosuid,size=64m",
+          },
     };
 
-    // Set tenant network isolation if NetworkPolicy is configured
-    if (this.networkPolicy) {
+    // Set network: explicit profile.network takes precedence, then NetworkPolicy
+    if (profile.network) {
+      hostConfig.NetworkMode = profile.network;
+    } else if (this.networkPolicy) {
       const networkMode = await this.networkPolicy.prepareForContainer(profile.tenantId);
       hostConfig.NetworkMode = networkMode;
     }