Enhance API with OIDC support, including login and callback endpoints. Update environment variables for OIDC configuration in .env.example. Add new features to the catalog service for listing software families, Minecraft versions, and deployment regions. Implement server management actions such as kill, delete, and update in the servers module. Integrate feature flags for maintenance mode in server operations. Update pnpm-lock.yaml with new dependencies and versions.

packages/server-state/package.json

@@ -0,0 +1,17 @@
+{
+  "name": "@hexahost/server-state",
+  "version": "0.0.0",
+  "private": true,
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "scripts": {
+    "build": "tsc",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run"
+  },
+  "devDependencies": {
+    "@hexahost/typescript-config": "workspace:*",
+    "typescript": "^5.7.3",
+    "vitest": "^3.0.5"
+  }
+}

packages/server-state/src/index.ts

@@ -0,0 +1,107 @@
+export type GameServerStatus =
+  | 'DRAFT'
+  | 'ALLOCATING'
+  | 'PROVISIONING'
+  | 'INSTALLING'
+  | 'STOPPED'
+  | 'QUEUED'
+  | 'STARTING'
+  | 'RUNNING'
+  | 'STOPPING'
+  | 'BACKING_UP'
+  | 'RESTORING'
+  | 'MIGRATING'
+  | 'SUSPENDED'
+  | 'MAINTENANCE'
+  | 'UNKNOWN'
+  | 'ERROR'
+  | 'DELETING'
+  | 'DELETED';
+
+export const ALLOWED_TRANSITIONS: Record<GameServerStatus, GameServerStatus[]> = {
+  DRAFT: ['ALLOCATING', 'PROVISIONING', 'DELETING'],
+  ALLOCATING: ['PROVISIONING', 'ERROR', 'DELETING'],
+  PROVISIONING: ['INSTALLING', 'ERROR', 'DELETING'],
+  INSTALLING: ['STOPPED', 'ERROR', 'DELETING'],
+  STOPPED: [
+    'STARTING',
+    'QUEUED',
+    'PROVISIONING',
+    'BACKING_UP',
+    'RESTORING',
+    'MIGRATING',
+    'SUSPENDED',
+    'MAINTENANCE',
+    'DELETING',
+  ],
+  QUEUED: ['STARTING', 'STOPPED', 'DELETING'],
+  STARTING: ['RUNNING', 'STOPPED', 'ERROR', 'UNKNOWN', 'DELETING'],
+  RUNNING: ['STOPPING', 'BACKING_UP', 'ERROR', 'UNKNOWN', 'DELETING'],
+  STOPPING: ['STOPPED', 'ERROR', 'UNKNOWN', 'DELETING'],
+  BACKING_UP: ['RUNNING', 'STOPPED', 'ERROR'],
+  RESTORING: ['STOPPED', 'ERROR'],
+  MIGRATING: ['STOPPED', 'ERROR'],
+  SUSPENDED: ['STOPPED', 'DELETING'],
+  MAINTENANCE: ['STOPPED', 'DELETING'],
+  UNKNOWN: ['STOPPED', 'STARTING', 'ERROR', 'DELETING'],
+  ERROR: ['STOPPED', 'STARTING', 'QUEUED', 'PROVISIONING', 'DELETING'],
+  DELETING: ['DELETED'],
+  DELETED: [],
+};
+
+export const IN_PROGRESS_STATUSES: GameServerStatus[] = [
+  'ALLOCATING',
+  'PROVISIONING',
+  'INSTALLING',
+  'STARTING',
+  'STOPPING',
+  'BACKING_UP',
+  'RESTORING',
+  'MIGRATING',
+  'DELETING',
+];
+
+export function assertTransition(
+  fromStatus: GameServerStatus,
+  toStatus: GameServerStatus,
+): void {
+  const allowed = ALLOWED_TRANSITIONS[fromStatus];
+
+  if (!allowed.includes(toStatus)) {
+    throw new Error(`Invalid state transition from ${fromStatus} to ${toStatus}`);
+  }
+}
+
+export function isInProgress(status: GameServerStatus): boolean {
+  return IN_PROGRESS_STATUSES.includes(status);
+}
+
+export function resolveStartTarget(status: GameServerStatus): GameServerStatus {
+  switch (status) {
+    case 'DRAFT':
+    case 'ERROR':
+      return 'PROVISIONING';
+    case 'STOPPED':
+    case 'UNKNOWN':
+    case 'QUEUED':
+      return 'STARTING';
+    default:
+      throw new Error(`Cannot start server while in status ${status}`);
+  }
+}
+
+export function resolveStopTarget(status: GameServerStatus): GameServerStatus {
+  if (status !== 'RUNNING') {
+    throw new Error(`Cannot stop server while in status ${status}`);
+  }
+
+  return 'STOPPING';
+}
+
+export function resolveKillTarget(status: GameServerStatus): GameServerStatus {
+  if (status !== 'RUNNING' && status !== 'STARTING' && status !== 'STOPPING') {
+    throw new Error(`Cannot kill server while in status ${status}`);
+  }
+
+  return 'STOPPED';
+}

packages/server-state/src/state.test.ts

@@ -0,0 +1,28 @@
+import { describe, expect, it } from 'vitest';
+
+import {
+  assertTransition,
+  isInProgress,
+  resolveKillTarget,
+  resolveStartTarget,
+} from './index';
+
+describe('server state machine', () => {
+  it('allows draft to provisioning', () => {
+    expect(() => assertTransition('DRAFT', 'PROVISIONING')).not.toThrow();
+  });
+
+  it('rejects invalid transition', () => {
+    expect(() => assertTransition('DELETED', 'RUNNING')).toThrow();
+  });
+
+  it('detects in-progress statuses', () => {
+    expect(isInProgress('STARTING')).toBe(true);
+    expect(isInProgress('STOPPED')).toBe(false);
+  });
+
+  it('resolves start and kill targets', () => {
+    expect(resolveStartTarget('STOPPED')).toBe('STARTING');
+    expect(resolveKillTarget('RUNNING')).toBe('STOPPED');
+  });
+});

packages/server-state/tsconfig.json

@@ -0,0 +1,8 @@
+{
+  "extends": "@hexahost/typescript-config/library.json",
+  "compilerOptions": {
+    "outDir": "./dist",
+    "rootDir": "./src"
+  },
+  "include": ["src/**/*"]
+}