@shipfox/api-workspaces 10.0.0 → 10.2.0

package/src/core/admin-workspaces.ts

@@ -1,9 +1,111 @@
+import {type AdministrationRole, createAdministrationActionEvent} from '@shipfox/api-common-dto';
 import type {ProjectsModuleClient} from '@shipfox/api-projects-dto/inter-module';
 import type {RunnersInterModuleClient} from '@shipfox/api-runners-dto/inter-module';
 import type {StringIdCursor} from '@shipfox/node-drizzle';
 import {logger} from '@shipfox/node-opentelemetry';
+import {hashOpaqueToken} from '@shipfox/node-tokens';
+import {
+  reactivateWorkspaceWithAudit,
+  suspendWorkspaceWithAudit,
+} from '#db/admin-workspace-commands.js';
 import {listAdminWorkspaces as listAdminWorkspaceRows} from '#db/workspaces.js';
 
+const ADMIN_OPERATOR_ROLE: AdministrationRole = 'admin-operator';
+const SUSPEND_COMMAND = 'workspace.suspend';
+const REACTIVATE_COMMAND = 'workspace.reactivate';
+
+export interface WorkspaceAdministrationMutationContext {
+  actorId: string;
+  actorRole: AdministrationRole;
+  idempotencyKey: string;
+  correlationId: string;
+  workspaceId: string;
+  reason: string;
+}
+
+export interface WorkspaceAdministrationMutationResult {
+  workspaceId: string;
+  status: 'active' | 'suspended';
+  correlationId: string;
+}
+
+function commandFingerprint(
+  command: string,
+  params: WorkspaceAdministrationMutationContext,
+): string {
+  return hashOpaqueToken(
+    `${command}:${JSON.stringify({workspaceId: params.workspaceId, reason: params.reason})}`,
+  );
+}
+
+function administrationEvent(params: {
+  actorId: string;
+  actorRole: AdministrationRole;
+  command: string;
+  workspaceId: string;
+  reason: string;
+  correlationId: string;
+  idempotencyKeyFingerprint: string;
+}) {
+  return createAdministrationActionEvent({
+    actorId: params.actorId,
+    actorRole: params.actorRole,
+    requiredRole: ADMIN_OPERATOR_ROLE,
+    command: params.command,
+    targetType: 'workspace',
+    targetId: params.workspaceId,
+    reason: params.reason,
+    result: 'succeeded',
+    correlationId: params.correlationId,
+    idempotencyKeyFingerprint: params.idempotencyKeyFingerprint,
+    occurredAt: new Date().toISOString(),
+  });
+}
+
+async function runWorkspaceAdministrationMutation(
+  params: WorkspaceAdministrationMutationContext,
+  command: string,
+  update: typeof suspendWorkspaceWithAudit,
+): Promise<WorkspaceAdministrationMutationResult> {
+  const idempotencyKeyFingerprint = hashOpaqueToken(params.idempotencyKey);
+  const result = await update({
+    actorId: params.actorId,
+    workspaceId: params.workspaceId,
+    idempotencyKeyFingerprint,
+    requestFingerprint: commandFingerprint(command, params),
+    event: administrationEvent({
+      actorId: params.actorId,
+      actorRole: params.actorRole,
+      command,
+      workspaceId: params.workspaceId,
+      reason: params.reason,
+      correlationId: params.correlationId,
+      idempotencyKeyFingerprint,
+    }),
+  });
+  return result;
+}
+
+export async function suspendWorkspace(
+  params: WorkspaceAdministrationMutationContext,
+): Promise<WorkspaceAdministrationMutationResult> {
+  return await runWorkspaceAdministrationMutation(
+    params,
+    SUSPEND_COMMAND,
+    suspendWorkspaceWithAudit,
+  );
+}
+
+export async function reactivateWorkspace(
+  params: WorkspaceAdministrationMutationContext,
+): Promise<WorkspaceAdministrationMutationResult> {
+  return await runWorkspaceAdministrationMutation(
+    params,
+    REACTIVATE_COMMAND,
+    reactivateWorkspaceWithAudit,
+  );
+}
+
 export interface WorkspaceAdministratorSummary {
   id: string;
   name: string;

package/src/core/errors.ts

@@ -12,6 +12,34 @@ export class WorkspaceInactiveError extends Error {
   }
 }
 
+export class WorkspaceAlreadySuspendedError extends Error {
+  constructor(workspaceId: string) {
+    super(`Workspace is already suspended: ${workspaceId}`);
+    this.name = 'WorkspaceAlreadySuspendedError';
+  }
+}
+
+export class WorkspaceNotSuspendedError extends Error {
+  constructor(workspaceId: string) {
+    super(`Workspace is not suspended: ${workspaceId}`);
+    this.name = 'WorkspaceNotSuspendedError';
+  }
+}
+
+export class WorkspaceDeletedError extends Error {
+  constructor(workspaceId: string) {
+    super(`Workspace is deleted: ${workspaceId}`);
+    this.name = 'WorkspaceDeletedError';
+  }
+}
+
+export class WorkspaceAdminIdempotencyKeyReuseError extends Error {
+  constructor() {
+    super('Idempotency key was already used for a different workspace command');
+    this.name = 'WorkspaceAdminIdempotencyKeyReuseError';
+  }
+}
+
 export class InvitationNotFoundError extends Error {
   constructor(id: string) {
     super(`Invitation not found: ${id}`);

package/src/core/index.ts

@@ -2,6 +2,10 @@ export {
   type ListWorkspaceAdministratorSummariesParams,
   type ListWorkspaceAdministratorSummariesResult,
   listWorkspaceAdministratorSummaries,
+  reactivateWorkspace,
+  suspendWorkspace,
+  type WorkspaceAdministrationMutationContext,
+  type WorkspaceAdministrationMutationResult,
   type WorkspaceAdministratorSummary,
 } from './admin-workspaces.js';
 export type {Invitation} from './entities/invitation.js';
@@ -18,7 +22,11 @@ export {
   SelfRemovalNotAllowedError,
   TokenAlreadyUsedError,
   TokenExpiredError,
+  WorkspaceAdminIdempotencyKeyReuseError,
+  WorkspaceAlreadySuspendedError,
+  WorkspaceDeletedError,
   WorkspaceNotFoundError,
+  WorkspaceNotSuspendedError,
 } from './errors.js';
 export {
   acceptWorkspaceInvitation,

package/src/db/admin-workspace-commands.ts

@@ -0,0 +1,169 @@
+import type {
+  AdministrationActionEvent,
+  AdministrationActionEventMap,
+} from '@shipfox/api-common-dto';
+import {writeOutboxEvent} from '@shipfox/node-outbox';
+import {and, eq, sql} from 'drizzle-orm';
+import {
+  WorkspaceAdminIdempotencyKeyReuseError,
+  WorkspaceAlreadySuspendedError,
+  WorkspaceDeletedError,
+  WorkspaceNotFoundError,
+  WorkspaceNotSuspendedError,
+} from '#core/errors.js';
+import {db} from './db.js';
+import {
+  type WorkspaceAdminCommandResultDb,
+  workspacesAdminCommandResults,
+} from './schema/admin-command-results.js';
+import {workspacesOutbox} from './schema/outbox.js';
+import {workspaces} from './schema/workspaces.js';
+
+type Tx = Parameters<Parameters<ReturnType<typeof db>['transaction']>[0]>[0];
+
+export interface WorkspaceAdministrationResult {
+  workspaceId: string;
+  status: 'active' | 'suspended';
+  correlationId: string;
+}
+
+interface AuditedWorkspaceCommandParams {
+  actorId: string;
+  idempotencyKeyFingerprint: string;
+  requestFingerprint: string;
+  event: AdministrationActionEvent;
+  workspaceId: string;
+}
+
+async function loadCommandResult(
+  tx: Tx,
+  params: Pick<AuditedWorkspaceCommandParams, 'actorId' | 'idempotencyKeyFingerprint'> & {
+    command: string;
+    requestFingerprint: string;
+  },
+): Promise<WorkspaceAdministrationResult | undefined> {
+  const rows = await tx
+    .select()
+    .from(workspacesAdminCommandResults)
+    .where(
+      and(
+        eq(workspacesAdminCommandResults.actorId, params.actorId),
+        eq(
+          workspacesAdminCommandResults.idempotencyKeyFingerprint,
+          params.idempotencyKeyFingerprint,
+        ),
+      ),
+    )
+    .limit(1);
+  const result: WorkspaceAdminCommandResultDb | undefined = rows[0];
+  if (!result) return undefined;
+  if (
+    result.command !== params.command ||
+    result.requestFingerprint !== params.requestFingerprint
+  ) {
+    throw new WorkspaceAdminIdempotencyKeyReuseError();
+  }
+  return result.result;
+}
+
+async function storeCommandResult(
+  tx: Tx,
+  params: AuditedWorkspaceCommandParams,
+  result: WorkspaceAdministrationResult,
+): Promise<void> {
+  await tx.insert(workspacesAdminCommandResults).values({
+    actorId: params.actorId,
+    idempotencyKeyFingerprint: params.idempotencyKeyFingerprint,
+    command: params.event.command,
+    requestFingerprint: params.requestFingerprint,
+    result,
+  });
+}
+
+async function writeAdministrationAction(tx: Tx, event: AdministrationActionEvent): Promise<void> {
+  await writeOutboxEvent<AdministrationActionEventMap>(tx, workspacesOutbox, {
+    type: 'administration.action.performed',
+    payload: event,
+  });
+}
+
+async function lockAdminCommand(
+  tx: Tx,
+  params: {actorId: string; idempotencyKeyFingerprint: string},
+): Promise<void> {
+  await tx.execute(
+    sql`select pg_advisory_xact_lock(hashtext(${`workspaces_admin_command:${params.actorId}:${params.idempotencyKeyFingerprint}`}))`,
+  );
+}
+
+async function updateWorkspaceStatusWithAudit(
+  params: AuditedWorkspaceCommandParams & {
+    expectedStatus: 'active' | 'suspended';
+    nextStatus: 'active' | 'suspended';
+  },
+): Promise<WorkspaceAdministrationResult> {
+  return await db().transaction(async (tx) => {
+    await lockAdminCommand(tx, params);
+
+    const existing = await loadCommandResult(tx, {
+      actorId: params.actorId,
+      idempotencyKeyFingerprint: params.idempotencyKeyFingerprint,
+      command: params.event.command,
+      requestFingerprint: params.requestFingerprint,
+    });
+    if (existing) return existing;
+
+    const rows = await tx
+      .select()
+      .from(workspaces)
+      .where(eq(workspaces.id, params.workspaceId))
+      .for('update')
+      .limit(1);
+    const workspaceRow = rows[0];
+    if (!workspaceRow) throw new WorkspaceNotFoundError(params.workspaceId);
+    if (workspaceRow.status === 'deleted') throw new WorkspaceDeletedError(params.workspaceId);
+    if (workspaceRow.status !== params.expectedStatus) {
+      if (params.nextStatus === 'suspended') {
+        throw new WorkspaceAlreadySuspendedError(params.workspaceId);
+      }
+      throw new WorkspaceNotSuspendedError(params.workspaceId);
+    }
+
+    const updatedRows = await tx
+      .update(workspaces)
+      .set({status: params.nextStatus, updatedAt: new Date()})
+      .where(eq(workspaces.id, params.workspaceId))
+      .returning();
+    const updatedRow = updatedRows[0];
+    if (!updatedRow) throw new WorkspaceNotFoundError(params.workspaceId);
+
+    const result = {
+      workspaceId: updatedRow.id,
+      status: updatedRow.status as 'active' | 'suspended',
+      correlationId: params.event.correlationId,
+    } satisfies WorkspaceAdministrationResult;
+    await writeAdministrationAction(tx, params.event);
+    await storeCommandResult(tx, params, result);
+    return result;
+  });
+}
+
+export async function suspendWorkspaceWithAudit(
+  params: AuditedWorkspaceCommandParams,
+): Promise<WorkspaceAdministrationResult> {
+  return await updateWorkspaceStatusWithAudit({
+    ...params,
+    expectedStatus: 'active',
+    nextStatus: 'suspended',
+  });
+}
+
+export async function reactivateWorkspaceWithAudit(
+  params: AuditedWorkspaceCommandParams,
+): Promise<WorkspaceAdministrationResult> {
+  return await updateWorkspaceStatusWithAudit({
+    ...params,
+    expectedStatus: 'suspended',
+    nextStatus: 'active',
+  });
+}

package/src/db/db.ts

@@ -1,11 +1,13 @@
 import {drizzle, type NodePgDatabase} from '@shipfox/node-drizzle';
 import {pgClient} from '@shipfox/node-postgres';
+import {workspacesAdminCommandResults} from './schema/admin-command-results.js';
 import {invitations} from './schema/invitations.js';
 import {memberships} from './schema/memberships.js';
 import {workspacesOutbox} from './schema/outbox.js';
 import {workspaces} from './schema/workspaces.js';
 
 export const schema = {
+  workspacesAdminCommandResults,
   workspaces,
   memberships,
   invitations,

package/src/db/index.ts

@@ -22,6 +22,7 @@ export {
   listMembershipsByWorkspace,
   removeMembership,
 } from './memberships.js';
+export {workspacesAdminCommandResults} from './schema/admin-command-results.js';
 export {workspacesOutbox} from './schema/outbox.js';
 export type {
   AdminWorkspaceRow,

package/src/db/schema/admin-command-results.ts

@@ -0,0 +1,30 @@
+import {uuidv7PrimaryKey} from '@shipfox/node-drizzle';
+import {jsonb, text, timestamp, uniqueIndex, uuid} from 'drizzle-orm/pg-core';
+import {pgTable} from './common.js';
+
+export interface StoredWorkspaceAdministrationResult {
+  workspaceId: string;
+  status: 'active' | 'suspended';
+  correlationId: string;
+}
+
+export const workspacesAdminCommandResults = pgTable(
+  'admin_command_results',
+  {
+    id: uuidv7PrimaryKey(),
+    actorId: uuid('actor_id').notNull(),
+    idempotencyKeyFingerprint: text('idempotency_key_fingerprint').notNull(),
+    command: text('command').notNull(),
+    requestFingerprint: text('request_fingerprint').notNull(),
+    result: jsonb('result').$type<StoredWorkspaceAdministrationResult>().notNull(),
+    createdAt: timestamp('created_at', {withTimezone: true}).notNull().defaultNow(),
+  },
+  (table) => [
+    uniqueIndex('workspaces_admin_command_results_actor_key_unique').on(
+      table.actorId,
+      table.idempotencyKeyFingerprint,
+    ),
+  ],
+);
+
+export type WorkspaceAdminCommandResultDb = typeof workspacesAdminCommandResults.$inferSelect;

package/src/index.test.ts

@@ -1,3 +1,4 @@
+import {ADMINISTRATION_ACTION_PERFORMED} from '@shipfox/api-common-dto';
 import {
   WORKSPACES_INVITATION_SEND_REQUESTED,
   WORKSPACES_MEMBER_INVITED,
@@ -22,12 +23,13 @@ describe('workspacesModule', () => {
     const publisher = workspacesModule.publishers?.find((pub) => pub.name === 'workspaces');
     const events = workspacesModule.subscribers?.map((subscriber) => subscriber.event);
 
-    expect(publisher?.eventSchemas).toBe(workspacesEventSchemas);
+    expect(publisher?.eventSchemas).not.toBe(workspacesEventSchemas);
     expect(Object.keys(publisher?.eventSchemas ?? {})).toEqual([
       WORKSPACES_INVITATION_SEND_REQUESTED,
       WORKSPACES_WORKSPACE_CREATED,
       WORKSPACES_MEMBER_INVITED,
       WORKSPACES_MEMBER_JOINED,
+      ADMINISTRATION_ACTION_PERFORMED,
     ]);
     expect(events).toContain(WORKSPACES_INVITATION_SEND_REQUESTED);
   });

package/src/index.ts

@@ -1,4 +1,5 @@
 import type {AuthInterModuleClient} from '@shipfox/api-auth-dto/inter-module';
+import {administrationActionEventSchemas} from '@shipfox/api-common-dto';
 import type {ProjectsModuleClient} from '@shipfox/api-projects-dto/inter-module';
 import type {RunnersInterModuleClient} from '@shipfox/api-runners-dto/inter-module';
 import {
@@ -38,6 +39,10 @@ export {listMembershipsByUser} from '#db/memberships.js';
 export {createWorkspacesRoutes, workspacesRoutes as routes} from '#presentation/routes/index.js';
 
 const subscriber = subscriberFactory<WorkspacesEventMap>();
+const workspacesPublisherEventSchemas = {
+  ...workspacesEventSchemas,
+  ...administrationActionEventSchemas,
+};
 
 export interface WorkspacesModuleOptions {
   auth: AuthInterModuleClient;
@@ -52,7 +57,12 @@ export function createWorkspacesModule(options: WorkspacesModuleOptions): Shipfo
     routes: createWorkspacesRoutes(options),
     e2eRoutes: [workspacesE2eRoutes],
     publishers: [
-      {name: 'workspaces', table: workspacesOutbox, db, eventSchemas: workspacesEventSchemas},
+      {
+        name: 'workspaces',
+        table: workspacesOutbox,
+        db,
+        eventSchemas: workspacesPublisherEventSchemas,
+      },
     ],
     subscribers: [subscriber(WORKSPACES_INVITATION_SEND_REQUESTED, onInvitationSendRequested)],
     metrics: registerWorkspacesServiceMetrics,
@@ -67,7 +77,12 @@ export const workspacesModule: ShipfoxModule = {
   routes: workspacesRoutes,
   e2eRoutes: [workspacesE2eRoutes],
   publishers: [
-    {name: 'workspaces', table: workspacesOutbox, db, eventSchemas: workspacesEventSchemas},
+    {
+      name: 'workspaces',
+      table: workspacesOutbox,
+      db,
+      eventSchemas: workspacesPublisherEventSchemas,
+    },
   ],
   subscribers: [subscriber(WORKSPACES_INVITATION_SEND_REQUESTED, onInvitationSendRequested)],
   metrics: registerWorkspacesServiceMetrics,