feat(api): idle container reaper (MS22-P1k) (#614)

Co-authored-by: Jason Woltje <jason@diversecanvas.com>
Co-committed-by: Jason Woltje <jason@diversecanvas.com>

apps/api/src/app.module.ts

@@ -2,6 +2,7 @@ import { Module } from "@nestjs/common";
 import { APP_INTERCEPTOR, APP_GUARD } from "@nestjs/core";
 import { ThrottlerModule } from "@nestjs/throttler";
 import { BullModule } from "@nestjs/bullmq";
+import { ScheduleModule } from "@nestjs/schedule";
 import { ThrottlerValkeyStorageService, ThrottlerApiKeyGuard } from "./common/throttler";
 import { CsrfGuard } from "./common/guards/csrf.guard";
 import { CsrfService } from "./common/services/csrf.service";
@@ -53,6 +54,7 @@ import { ConversationArchiveModule } from "./conversation-archive/conversation-a
 import { RlsContextInterceptor } from "./common/interceptors/rls-context.interceptor";
 import { AgentConfigModule } from "./agent-config/agent-config.module";
 import { ContainerLifecycleModule } from "./container-lifecycle/container-lifecycle.module";
+import { ContainerReaperModule } from "./container-reaper/container-reaper.module";
 import { FleetSettingsModule } from "./fleet-settings/fleet-settings.module";
 import { OnboardingModule } from "./onboarding/onboarding.module";
 
@@ -85,6 +87,7 @@ import { OnboardingModule } from "./onboarding/onboarding.module";
         };
       })(),
     }),
+    ScheduleModule.forRoot(),
     TelemetryModule,
     PrismaModule,
     DatabaseModule,
@@ -129,6 +132,7 @@ import { OnboardingModule } from "./onboarding/onboarding.module";
     ConversationArchiveModule,
     AgentConfigModule,
     ContainerLifecycleModule,
+    ContainerReaperModule,
     FleetSettingsModule,
     OnboardingModule,
   ],

apps/api/src/container-reaper/container-reaper.module.ts

@@ -0,0 +1,10 @@
+import { Module } from "@nestjs/common";
+import { ScheduleModule } from "@nestjs/schedule";
+import { ContainerLifecycleModule } from "../container-lifecycle/container-lifecycle.module";
+import { ContainerReaperService } from "./container-reaper.service";
+
+@Module({
+  imports: [ScheduleModule, ContainerLifecycleModule],
+  providers: [ContainerReaperService],
+})
+export class ContainerReaperModule {}

apps/api/src/container-reaper/container-reaper.service.spec.ts

@@ -0,0 +1,45 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import type { ContainerLifecycleService } from "../container-lifecycle/container-lifecycle.service";
+import { ContainerReaperService } from "./container-reaper.service";
+
+describe("ContainerReaperService", () => {
+  let service: ContainerReaperService;
+  let containerLifecycle: Pick<ContainerLifecycleService, "reapIdle">;
+
+  beforeEach(() => {
+    containerLifecycle = {
+      reapIdle: vi.fn(),
+    };
+    service = new ContainerReaperService(containerLifecycle as ContainerLifecycleService);
+  });
+
+  it("reapIdleContainers calls containerLifecycle.reapIdle()", async () => {
+    vi.mocked(containerLifecycle.reapIdle).mockResolvedValue({ stopped: [] });
+
+    await service.reapIdleContainers();
+
+    expect(containerLifecycle.reapIdle).toHaveBeenCalledTimes(1);
+  });
+
+  it("reapIdleContainers handles errors gracefully", async () => {
+    const error = new Error("reap failure");
+    vi.mocked(containerLifecycle.reapIdle).mockRejectedValue(error);
+    const loggerError = vi.spyOn(service["logger"], "error").mockImplementation(() => {});
+
+    await expect(service.reapIdleContainers()).resolves.toBeUndefined();
+
+    expect(loggerError).toHaveBeenCalledWith(
+      "Failed to reap idle containers",
+      expect.stringContaining("reap failure")
+    );
+  });
+
+  it("reapIdleContainers logs stopped container count", async () => {
+    vi.mocked(containerLifecycle.reapIdle).mockResolvedValue({ stopped: ["user-1", "user-2"] });
+    const loggerLog = vi.spyOn(service["logger"], "log").mockImplementation(() => {});
+
+    await service.reapIdleContainers();
+
+    expect(loggerLog).toHaveBeenCalledWith("Stopped 2 idle containers: user-1, user-2");
+  });
+});

apps/api/src/container-reaper/container-reaper.service.ts

@@ -0,0 +1,30 @@
+import { Injectable, Logger } from "@nestjs/common";
+import { Cron, CronExpression } from "@nestjs/schedule";
+import { ContainerLifecycleService } from "../container-lifecycle/container-lifecycle.service";
+
+@Injectable()
+export class ContainerReaperService {
+  private readonly logger = new Logger(ContainerReaperService.name);
+
+  constructor(private readonly containerLifecycle: ContainerLifecycleService) {}
+
+  @Cron(CronExpression.EVERY_5_MINUTES)
+  async reapIdleContainers(): Promise<void> {
+    this.logger.log("Running idle container reap cycle...");
+    try {
+      const result = await this.containerLifecycle.reapIdle();
+      if (result.stopped.length > 0) {
+        this.logger.log(
+          `Stopped ${String(result.stopped.length)} idle containers: ${result.stopped.join(", ")}`
+        );
+      } else {
+        this.logger.debug("No idle containers to stop");
+      }
+    } catch (error) {
+      this.logger.error(
+        "Failed to reap idle containers",
+        error instanceof Error ? error.stack : String(error)
+      );
+    }
+  }
+}