✨ feat(containers): add container action operations and dashboard updates

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

app/api/container-actions.test.ts

@@ -491,6 +491,42 @@ describe('Container Actions Router', () => {
       expect(contractValidation.errors).toStrictEqual([]);
     });
 
+    test('should persist provided batch queue metadata on accepted updates', async () => {
+      const container = {
+        id: 'c1',
+        name: 'nginx',
+        image: { name: 'nginx' },
+        updateAvailable: true,
+      };
+      mockGetContainer.mockReturnValue(container);
+      const mockTriggerFn = vi.fn().mockResolvedValue(undefined);
+      const trigger = { type: 'docker', trigger: mockTriggerFn };
+      mockGetState.mockReturnValue({ trigger: { 'docker.default': trigger } });
+      const updateOperationStore = await import('../store/update-operation');
+
+      const handler = getHandler('post', '/:id/update');
+      const req = createMockRequest({
+        params: { id: 'c1' },
+        body: {
+          batchId: 'batch-1',
+          queuePosition: 2,
+          queueTotal: 4,
+        },
+      });
+      const res = createMockResponse();
+      await handler(req, res);
+
+      expect(updateOperationStore.insertOperation).toHaveBeenCalledWith(
+        expect.objectContaining({
+          batchId: 'batch-1',
+          queuePosition: 2,
+          queueTotal: 4,
+          status: 'queued',
+          phase: 'queued',
+        }),
+      );
+    });
+
     test('should accept update immediately with a dockercompose trigger', async () => {
       const container = {
         id: 'c1',

app/api/container-actions.ts

@@ -48,6 +48,45 @@ type DockerWatcher = {
   };
 };
 
+type UpdateQueueBatchMetadata = {
+  batchId: string;
+  queuePosition: number;
+  queueTotal: number;
+};
+
+function parsePositiveInteger(value: unknown): number | undefined {
+  if (typeof value === 'number') {
+    return Number.isSafeInteger(value) && value > 0 ? value : undefined;
+  }
+  if (typeof value !== 'string' || !/^\d+$/.test(value)) {
+    return undefined;
+  }
+
+  const parsed = Number.parseInt(value, 10);
+  return Number.isSafeInteger(parsed) && parsed > 0 ? parsed : undefined;
+}
+
+function parseUpdateQueueBatchMetadata(body: unknown): UpdateQueueBatchMetadata | undefined {
+  if (!body || typeof body !== 'object') {
+    return undefined;
+  }
+
+  const candidate = body as Record<string, unknown>;
+  const batchId = typeof candidate.batchId === 'string' ? candidate.batchId.trim() : '';
+  const queuePosition = parsePositiveInteger(candidate.queuePosition);
+  const queueTotal = parsePositiveInteger(candidate.queueTotal);
+
+  if (!batchId || !queuePosition || !queueTotal || queuePosition > queueTotal) {
+    return undefined;
+  }
+
+  return {
+    batchId,
+    queuePosition,
+    queueTotal,
+  };
+}
+
 function clearManualUpdateDetectionState(id: string) {
   const containerAfterTrigger = storeContainer.getContainer(id);
   if (
@@ -227,6 +266,7 @@ async function updateContainer(req: Request, res: Response) {
   }
 
   const operationId = crypto.randomUUID();
+  const batchMetadata = parseUpdateQueueBatchMetadata(req.body);
   getContainerActionsCounter()?.inc({ action: 'container-update' });
 
   updateOperationStore.insertOperation({
@@ -235,6 +275,7 @@ async function updateContainer(req: Request, res: Response) {
     containerName: container.name,
     status: 'queued',
     phase: 'queued',
+    ...batchMetadata,
   });
 
   void (async () => {

app/api/container/crud.test.ts

@@ -2379,6 +2379,9 @@ describe('api/container/crud', () => {
         updatedAt: '2026-04-01T12:00:00.000Z',
         fromVersion: '1.0.0',
         toVersion: '1.1.0',
+        batchId: 'batch-1',
+        queuePosition: 1,
+        queueTotal: 3,
       });
 
       const listRes = callGetContainers(harness.handlers);
@@ -2397,6 +2400,9 @@ describe('api/container/crud', () => {
                 phase: 'old-stopped',
                 fromVersion: '1.0.0',
                 toVersion: '1.1.0',
+                batchId: 'batch-1',
+                queuePosition: 1,
+                queueTotal: 3,
               }),
             }),
           ],
@@ -2408,6 +2414,9 @@ describe('api/container/crud', () => {
             id: 'op-1',
             status: 'in-progress',
             phase: 'old-stopped',
+            batchId: 'batch-1',
+            queuePosition: 1,
+            queueTotal: 3,
           }),
         }),
       );

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

@@ -96,6 +96,32 @@ describe('attachInProgressUpdateOperation', () => {
     });
   });
 
+  test('keeps valid batch queue metadata from active operations', () => {
+    const container = createContainer();
+    const context = createMockContext({
+      id: 'op-1',
+      status: 'queued',
+      phase: 'queued',
+      updatedAt: '2026-04-01T12:00:00.000Z',
+      batchId: 'batch-1',
+      queuePosition: 2,
+      queueTotal: 4,
+    });
+
+    expect(attachInProgressUpdateOperation(context, container)).toEqual({
+      ...container,
+      updateOperation: {
+        id: 'op-1',
+        status: 'queued',
+        phase: 'queued',
+        updatedAt: '2026-04-01T12:00:00.000Z',
+        batchId: 'batch-1',
+        queuePosition: 2,
+        queueTotal: 4,
+      },
+    });
+  });
+
   test('prefers container-ID lookup over name-based lookup', () => {
     const container = createContainer({ id: 'c1', name: 'portainer_agent' });
     const byIdResult = {

app/api/container/handlers/list.ts

@@ -26,6 +26,18 @@ import { parseBooleanQueryParam } from '../request-helpers.js';
 
 export type ContainerListBasePath = '/api/containers' | '/api/containers/watch';
 
+function parsePositiveInteger(value: unknown): number | undefined {
+  if (typeof value === 'number') {
+    return Number.isSafeInteger(value) && value > 0 ? value : undefined;
+  }
+  if (typeof value !== 'string' || !/^\d+$/.test(value)) {
+    return undefined;
+  }
+
+  const parsed = Number.parseInt(value, 10);
+  return Number.isSafeInteger(parsed) && parsed > 0 ? parsed : undefined;
+}
+
 function stripContainerVulnerabilityArrays(container: Container): Container {
   if (!container.security) {
     return container;
@@ -63,6 +75,9 @@ function sanitizeInProgressUpdateOperation(
   const status = isContainerUpdateOperationStatus(candidate.status) ? candidate.status : undefined;
   const phase = isContainerUpdateOperationPhase(candidate.phase) ? candidate.phase : undefined;
   const updatedAt = typeof candidate.updatedAt === 'string' ? candidate.updatedAt : undefined;
+  const batchId = typeof candidate.batchId === 'string' ? candidate.batchId : undefined;
+  const queuePosition = parsePositiveInteger(candidate.queuePosition);
+  const queueTotal = parsePositiveInteger(candidate.queueTotal);
 
   if (!id || !status || !phase || !updatedAt) {
     return undefined;
@@ -76,6 +91,13 @@ function sanitizeInProgressUpdateOperation(
     ...(typeof candidate.fromVersion === 'string' ? { fromVersion: candidate.fromVersion } : {}),
     ...(typeof candidate.toVersion === 'string' ? { toVersion: candidate.toVersion } : {}),
     ...(typeof candidate.targetImage === 'string' ? { targetImage: candidate.targetImage } : {}),
+    ...(batchId && queuePosition && queueTotal && queuePosition <= queueTotal
+      ? {
+          batchId,
+          queuePosition,
+          queueTotal,
+        }
+      : {}),
   };
 }
 

app/model/container.ts

@@ -128,6 +128,9 @@ export interface ContainerUpdateOperationState {
   status: ContainerUpdateOperationStatus;
   phase: ContainerUpdateOperationPhase;
   updatedAt: string;
+  batchId?: string;
+  queuePosition?: number;
+  queueTotal?: number;
   fromVersion?: string;
   toVersion?: string;
   targetImage?: string;

ui/src/services/container-actions.ts

@@ -1,3 +1,26 @@
+export interface UpdateContainerBatchMetadata {
+  batchId?: string;
+  queuePosition?: number;
+  queueTotal?: number;
+}
+
+function hasValidUpdateContainerBatchMetadata(
+  metadata?: UpdateContainerBatchMetadata,
+): metadata is {
+  batchId: string;
+  queuePosition: number;
+  queueTotal: number;
+} {
+  return (
+    !!metadata?.batchId &&
+    Number.isSafeInteger(metadata.queuePosition) &&
+    metadata.queuePosition > 0 &&
+    Number.isSafeInteger(metadata.queueTotal) &&
+    metadata.queueTotal > 0 &&
+    metadata.queuePosition <= metadata.queueTotal
+  );
+}
+
 async function startContainer(containerId: string) {
   const response = await fetch(`/api/v1/containers/${containerId}/start`, {
     method: 'POST',
@@ -34,10 +57,18 @@ async function restartContainer(containerId: string) {
   return response.json();
 }
 
-async function updateContainer(containerId: string) {
+async function updateContainer(containerId: string, metadata?: UpdateContainerBatchMetadata) {
   const response = await fetch(`/api/v1/containers/${containerId}/update`, {
     method: 'POST',
     credentials: 'include',
+    ...(hasValidUpdateContainerBatchMetadata(metadata)
+      ? {
+          headers: {
+            'Content-Type': 'application/json',
+          },
+          body: JSON.stringify(metadata),
+        }
+      : {}),
   });
   if (!response.ok) {
     const body = await response.json().catch(() => ({}));

ui/src/types/api.d.ts

@@ -72,6 +72,9 @@ export interface ApiContainerUpdateOperation {
   phase: ApiContainerUpdateOperationPhase;
   createdAt: string;
   updatedAt: string;
+  batchId?: string;
+  queuePosition?: number;
+  queueTotal?: number;
   containerId?: string;
   containerName?: string;
   triggerName?: string;

ui/src/types/container.d.ts

@@ -43,6 +43,9 @@ export interface ContainerUpdateOperation {
   status: ContainerUpdateOperationStatus;
   phase: ContainerUpdateOperationPhase;
   updatedAt: string;
+  batchId?: string;
+  queuePosition?: number;
+  queueTotal?: number;
   fromVersion?: string;
   toVersion?: string;
   targetImage?: string;

ui/src/utils/container-mapper.ts

@@ -162,6 +162,18 @@ function asNonEmptyString(value: unknown): string | undefined {
   return trimmed.length > 0 ? trimmed : undefined;
 }
 
+function asPositiveInteger(value: unknown): number | undefined {
+  if (typeof value === 'number') {
+    return Number.isSafeInteger(value) && value > 0 ? value : undefined;
+  }
+  if (typeof value !== 'string' || !/^\d+$/.test(value)) {
+    return undefined;
+  }
+
+  const parsed = Number.parseInt(value, 10);
+  return Number.isSafeInteger(parsed) && parsed > 0 ? parsed : undefined;
+}
+
 function asOptionalBoolean(value: unknown): boolean | undefined {
   return typeof value === 'boolean' ? value : undefined;
 }
@@ -590,6 +602,9 @@ function deriveUpdateOperation(
   const status = asContainerUpdateOperationStatus(operation.status);
   const phase = asContainerUpdateOperationPhase(operation.phase);
   const updatedAt = asNonEmptyString(operation.updatedAt);
+  const batchId = asNonEmptyString(operation.batchId);
+  const queuePosition = asPositiveInteger(operation.queuePosition);
+  const queueTotal = asPositiveInteger(operation.queueTotal);
 
   if (!id || !status || !phase || !updatedAt) {
     return undefined;
@@ -609,6 +624,9 @@ function deriveUpdateOperation(
     ...(asNonEmptyString(operation.targetImage)
       ? { targetImage: asNonEmptyString(operation.targetImage) }
       : {}),
+    ...(batchId && queuePosition && queueTotal && queuePosition <= queueTotal
+      ? { batchId, queuePosition, queueTotal }
+      : {}),
   };
 }