✨ feat(triggers): backend-driven update queue with per-trigger concurrency limit

- Add 'queued' status and phase to container update operation model
- API handler creates operation as 'queued' immediately on update request
- Docker trigger uses pLimit(1) semaphore to serialize concurrent updates
- Executor transitions queued→in-progress instead of inserting duplicate
- Container list API attaches both queued and in-progress operations
- UI recognizes backend 'queued' status for "Queued" display

Author: s-b-e-n-s-o-n

app/api/container-actions.test.ts

@@ -56,6 +56,17 @@ vi.mock('../configuration', () => ({
   getVersion: vi.fn(() => 'test-version'),
 }));
 
+vi.mock('../store/update-operation', () => ({
+  insertOperation: vi.fn((op) => ({ id: op.id || 'op-mock', ...op })),
+  updateOperation: vi.fn(),
+  getOperationById: vi.fn(),
+  getOperationsByContainerName: vi.fn(() => []),
+  getInProgressOperationByContainerName: vi.fn(),
+  getInProgressOperationByContainerId: vi.fn(),
+  getActiveOperationByContainerName: vi.fn(),
+  getActiveOperationByContainerId: vi.fn(),
+}));
+
 vi.mock('../log', () => ({
   default: { child: vi.fn(() => ({ info: vi.fn(), warn: vi.fn(), debug: vi.fn() })) },
 }));

app/api/container-actions.ts

@@ -9,6 +9,7 @@ import { type Container, clearDetectedUpdateState } from '../model/container.js'
 import { getContainerActionsCounter } from '../prometheus/container-actions.js';
 import * as registry from '../registry/index.js';
 import * as storeContainer from '../store/container.js';
+import * as updateOperationStore from '../store/update-operation.js';
 import Trigger from '../triggers/providers/Trigger.js';
 import { recordAuditEvent } from './audit-events.js';
 import { findDockerTriggerForContainer, NO_DOCKER_TRIGGER_FOUND_ERROR } from './docker-trigger.js';
@@ -215,6 +216,14 @@ async function updateContainer(req: Request, res: Response) {
   const operationId = crypto.randomUUID();
   getContainerActionsCounter()?.inc({ action: 'container-update' });
 
+  updateOperationStore.insertOperation({
+    id: operationId,
+    containerId: container.id,
+    containerName: container.name,
+    status: 'queued',
+    phase: 'queued',
+  });
+
   void (async () => {
     try {
       await trigger.trigger(container, { operationId });

app/api/container.test.ts

@@ -62,8 +62,11 @@ vi.mock('../store/audit', () => ({
 
 vi.mock('../store/update-operation', () => ({
   getOperationsByContainerName: (...args: unknown[]) => mockGetOperationsByContainerName(...args),
+  getOperationById: vi.fn(() => undefined),
   getInProgressOperationByContainerName: vi.fn(() => undefined),
   getInProgressOperationByContainerId: vi.fn(() => undefined),
+  getActiveOperationByContainerName: vi.fn(() => undefined),
+  getActiveOperationByContainerId: vi.fn(() => undefined),
 }));
 
 vi.mock('../registry', () => ({
@@ -1432,6 +1435,8 @@ describe('Container Router', () => {
             getOperationsByContainerName: vi.fn(() => []),
             getInProgressOperationByContainerName: vi.fn(() => undefined),
             getInProgressOperationByContainerId: vi.fn(() => undefined),
+            getActiveOperationByContainerName: vi.fn(() => undefined),
+            getActiveOperationByContainerId: vi.fn(() => undefined),
           },
         },
         agentApi: {

app/api/container/crud-context.ts

@@ -29,6 +29,8 @@ export interface UpdateOperationStoreApi {
   getOperationsByContainerName: (containerName: string) => unknown[];
   getInProgressOperationByContainerName: (containerName: string) => unknown | undefined;
   getInProgressOperationByContainerId: (containerId: string) => unknown | undefined;
+  getActiveOperationByContainerName: (containerName: string) => unknown | undefined;
+  getActiveOperationByContainerId: (containerId: string) => unknown | undefined;
 }
 
 export interface ServerConfiguration {

app/api/container/crud.test.ts

@@ -158,6 +158,8 @@ function createHarness(options: { containers?: any[] } = {}) {
       getOperationsByContainerName: vi.fn(() => []),
       getInProgressOperationByContainerName: vi.fn(() => undefined),
       getInProgressOperationByContainerId: vi.fn(() => undefined),
+      getActiveOperationByContainerName: vi.fn(() => undefined),
+      getActiveOperationByContainerId: vi.fn(() => undefined),
     },
     getServerConfiguration: vi.fn(() => ({ feature: { delete: true } })),
     getAgent: vi.fn(),
@@ -2370,7 +2372,7 @@ describe('api/container/crud', () => {
       const harness = createHarness({
         containers: [createContainer({ id: 'c1', name: 'edge-api' })],
       });
-      harness.deps.updateOperationStore.getInProgressOperationByContainerName.mockReturnValue({
+      harness.deps.updateOperationStore.getActiveOperationByContainerName.mockReturnValue({
         id: 'op-1',
         status: 'in-progress',
         phase: 'old-stopped',
@@ -2383,7 +2385,7 @@ describe('api/container/crud', () => {
       const singleRes = callGetContainer(harness.handlers, 'c1');
 
       expect(
-        harness.deps.updateOperationStore.getInProgressOperationByContainerName,
+        harness.deps.updateOperationStore.getActiveOperationByContainerName,
       ).toHaveBeenCalledWith('edge-api');
       expect(listRes.json).toHaveBeenCalledWith(
         expect.objectContaining({
@@ -2415,7 +2417,7 @@ describe('api/container/crud', () => {
       const harness = createHarness({
         containers: [createContainer({ id: 'new-c1', name: 'edge-api' })],
       });
-      harness.deps.updateOperationStore.getInProgressOperationByContainerId.mockImplementation(
+      harness.deps.updateOperationStore.getActiveOperationByContainerId.mockImplementation(
         (id: string) =>
           id === 'new-c1'
             ? {
@@ -2435,10 +2437,10 @@ describe('api/container/crud', () => {
       const singleRes = callGetContainer(harness.handlers, 'new-c1');
 
       expect(
-        harness.deps.updateOperationStore.getInProgressOperationByContainerId,
+        harness.deps.updateOperationStore.getActiveOperationByContainerId,
       ).toHaveBeenCalledWith('new-c1');
       expect(
-        harness.deps.updateOperationStore.getInProgressOperationByContainerName,
+        harness.deps.updateOperationStore.getActiveOperationByContainerName,
       ).not.toHaveBeenCalled();
       expect(listRes.json).toHaveBeenCalledWith(
         expect.objectContaining({
@@ -2470,7 +2472,7 @@ describe('api/container/crud', () => {
       const harness = createHarness({
         containers: [createContainer({ id: 'c1', name: 'edge-api' })],
       });
-      harness.deps.updateOperationStore.getInProgressOperationByContainerName.mockReturnValue({
+      harness.deps.updateOperationStore.getActiveOperationByContainerName.mockReturnValue({
         id: 'op-1',
         status: 'success',
         phase: 'complete',

app/api/container/handlers/list.test.ts

@@ -11,6 +11,8 @@ function createMockContext(operation?: unknown): CrudHandlerContext {
       getOperationsByContainerName: vi.fn(),
       getInProgressOperationByContainerName: vi.fn().mockReturnValue(operation),
       getInProgressOperationByContainerId: vi.fn(),
+      getActiveOperationByContainerName: vi.fn().mockReturnValue(operation),
+      getActiveOperationByContainerId: vi.fn(),
     },
     getServerConfiguration: vi.fn(),
     getAgent: vi.fn(),
@@ -112,21 +114,17 @@ describe('attachInProgressUpdateOperation', () => {
     };
     const context = createMockContext();
     (
-      context.updateOperationStore.getInProgressOperationByContainerId as ReturnType<typeof vi.fn>
+      context.updateOperationStore.getActiveOperationByContainerId as ReturnType<typeof vi.fn>
     ).mockReturnValue(byIdResult);
     (
-      context.updateOperationStore.getInProgressOperationByContainerName as ReturnType<typeof vi.fn>
+      context.updateOperationStore.getActiveOperationByContainerName as ReturnType<typeof vi.fn>
     ).mockReturnValue(byNameResult);
 
     const result = attachInProgressUpdateOperation(context, container);
 
     expect(result.updateOperation?.id).toBe('op-by-id');
-    expect(context.updateOperationStore.getInProgressOperationByContainerId).toHaveBeenCalledWith(
-      'c1',
-    );
-    expect(
-      context.updateOperationStore.getInProgressOperationByContainerName,
-    ).not.toHaveBeenCalled();
+    expect(context.updateOperationStore.getActiveOperationByContainerId).toHaveBeenCalledWith('c1');
+    expect(context.updateOperationStore.getActiveOperationByContainerName).not.toHaveBeenCalled();
   });
 
   test('does not attach name-matched operation that belongs to a different container ID (#256)', () => {
@@ -142,10 +140,10 @@ describe('attachInProgressUpdateOperation', () => {
     };
     const context = createMockContext();
     (
-      context.updateOperationStore.getInProgressOperationByContainerId as ReturnType<typeof vi.fn>
+      context.updateOperationStore.getActiveOperationByContainerId as ReturnType<typeof vi.fn>
     ).mockImplementation((id: string) => (id === 'host1-abc' ? operationForA : undefined));
     (
-      context.updateOperationStore.getInProgressOperationByContainerName as ReturnType<typeof vi.fn>
+      context.updateOperationStore.getActiveOperationByContainerName as ReturnType<typeof vi.fn>
     ).mockReturnValue(operationForA);
 
     const resultA = attachInProgressUpdateOperation(context, containerA);
@@ -166,10 +164,10 @@ describe('attachInProgressUpdateOperation', () => {
     };
     const context = createMockContext();
     (
-      context.updateOperationStore.getInProgressOperationByContainerId as ReturnType<typeof vi.fn>
+      context.updateOperationStore.getActiveOperationByContainerId as ReturnType<typeof vi.fn>
     ).mockReturnValue(undefined);
     (
-      context.updateOperationStore.getInProgressOperationByContainerName as ReturnType<typeof vi.fn>
+      context.updateOperationStore.getActiveOperationByContainerName as ReturnType<typeof vi.fn>
     ).mockReturnValue(legacyOperation);
 
     const result = attachInProgressUpdateOperation(context, container);

app/api/container/handlers/list.ts

@@ -83,11 +83,11 @@ export function attachInProgressUpdateOperation(
   context: CrudHandlerContext,
   container: Container,
 ): Container {
-  const byId = context.updateOperationStore.getInProgressOperationByContainerId(container.id);
+  const byId = context.updateOperationStore.getActiveOperationByContainerId(container.id);
   // Name-based fallback only for legacy operations that predate the containerId field.
   const byName = byId
     ? undefined
-    : context.updateOperationStore.getInProgressOperationByContainerName(container.name);
+    : context.updateOperationStore.getActiveOperationByContainerName(container.name);
   const isLegacyOperation =
     byName && typeof byName === 'object' && !('containerId' in (byName as Record<string, unknown>));
   const matched = byId ?? (isLegacyOperation ? byName : undefined);

app/api/container/handlers/release-notes.test.ts

@@ -35,6 +35,8 @@ function createMockContext(overrides: Partial<CrudHandlerContext> = {}): CrudHan
       getOperationsByContainerName: vi.fn(),
       getInProgressOperationByContainerName: vi.fn(),
       getInProgressOperationByContainerId: vi.fn(),
+      getActiveOperationByContainerName: vi.fn(),
+      getActiveOperationByContainerId: vi.fn(),
     },
     getServerConfiguration: vi.fn(),
     getAgent: vi.fn(),

app/model/container-update-operation.ts

@@ -1,4 +1,5 @@
 export const CONTAINER_UPDATE_OPERATION_STATUSES = [
+  'queued',
   'in-progress',
   'succeeded',
   'rolled-back',
@@ -8,6 +9,7 @@ export const CONTAINER_UPDATE_OPERATION_STATUSES = [
 export type ContainerUpdateOperationStatus = (typeof CONTAINER_UPDATE_OPERATION_STATUSES)[number];
 
 export const CONTAINER_UPDATE_OPERATION_PHASES = [
+  'queued',
   'pulling',
   'pull-failed',
   'prepare',

app/store/update-operation.ts

@@ -44,7 +44,9 @@ type UpdateOperationQuery =
   | { 'data.id': string }
   | { 'data.containerName': string }
   | { 'data.containerName': string; 'data.status': ContainerUpdateOperationStatus }
+  | { 'data.containerId': string }
   | { 'data.containerId': string; 'data.status': ContainerUpdateOperationStatus }
+  | { 'data.newContainerId': string }
   | { 'data.newContainerId': string; 'data.status': ContainerUpdateOperationStatus };
 
 interface UpdateOperationCollection {
@@ -170,6 +172,17 @@ export function insertOperation(operation: InsertUpdateOperationInput): UpdateOp
   return operationToSave;
 }
 
+/**
+ * Return a single operation by its unique ID.
+ */
+export function getOperationById(id: string): UpdateOperation | undefined {
+  if (!updateOperationCollection || !id) {
+    return undefined;
+  }
+
+  return updateOperationCollection.findOne({ 'data.id': id })?.data;
+}
+
 /**
  * Update an operation by id.
  */
@@ -254,6 +267,58 @@ export function getInProgressOperationByContainerId(
   return operations.at(0);
 }
 
+const ACTIVE_STATUSES = ['in-progress', 'queued'] as const;
+
+/**
+ * Return the latest active (in-progress OR queued) operation for a container name.
+ */
+export function getActiveOperationByContainerName(
+  containerName: string,
+): UpdateOperation | undefined {
+  if (!updateOperationCollection) {
+    return undefined;
+  }
+
+  const operations = updateOperationCollection
+    .find({ 'data.containerName': containerName })
+    .filter((item) => (ACTIVE_STATUSES as readonly string[]).includes(item.data.status))
+    .map((item) => item.data)
+    .sort((a, b) => getOperationTimestamp(b) - getOperationTimestamp(a));
+
+  return operations.at(0);
+}
+
+/**
+ * Return the latest active (in-progress OR queued) operation for a container ID.
+ */
+export function getActiveOperationByContainerId(containerId: string): UpdateOperation | undefined {
+  if (!updateOperationCollection || !containerId) {
+    return undefined;
+  }
+
+  const operationsById = new Map<string, UpdateOperation>();
+
+  for (const document of updateOperationCollection.find({ 'data.containerId': containerId })) {
+    if ((ACTIVE_STATUSES as readonly string[]).includes(document.data.status)) {
+      operationsById.set(document.data.id, document.data);
+    }
+  }
+
+  for (const document of updateOperationCollection.find({
+    'data.newContainerId': containerId,
+  })) {
+    if ((ACTIVE_STATUSES as readonly string[]).includes(document.data.status)) {
+      operationsById.set(document.data.id, document.data);
+    }
+  }
+
+  const operations = [...operationsById.values()].sort(
+    (a, b) => getOperationTimestamp(b) - getOperationTimestamp(a),
+  );
+
+  return operations.at(0);
+}
+
 export function getOperationsByContainerName(containerName: string): UpdateOperation[] {
   if (!updateOperationCollection) {
     return [];