chore: initial commit for phase07

apps/api/src/lib/schedule-utils.ts

@@ -0,0 +1,103 @@
+/**
+ * Compute the next run time for a scheduled task.
+ */
+export function computeNextRun(
+  scheduleType: string,
+  scheduleData: Record<string, unknown>,
+): Date {
+  const now = new Date();
+
+  switch (scheduleType) {
+    case 'interval': {
+      const minutes = Number(scheduleData.minutes) || 60;
+      return new Date(now.getTime() + minutes * 60_000);
+    }
+
+    case 'daily': {
+      const hour = Number(scheduleData.hour ?? 0);
+      const minute = Number(scheduleData.minute ?? 0);
+      const next = new Date(now);
+      next.setHours(hour, minute, 0, 0);
+      if (next <= now) next.setDate(next.getDate() + 1);
+      return next;
+    }
+
+    case 'weekly': {
+      const dayOfWeek = Number(scheduleData.dayOfWeek ?? 0); // 0=Sunday
+      const hour = Number(scheduleData.hour ?? 0);
+      const minute = Number(scheduleData.minute ?? 0);
+      const next = new Date(now);
+      next.setHours(hour, minute, 0, 0);
+      const currentDay = next.getDay();
+      let daysAhead = dayOfWeek - currentDay;
+      if (daysAhead < 0 || (daysAhead === 0 && next <= now)) {
+        daysAhead += 7;
+      }
+      next.setDate(next.getDate() + daysAhead);
+      return next;
+    }
+
+    case 'cron': {
+      // Simple cron parser for: minute hour dayOfMonth month dayOfWeek
+      const expression = String(scheduleData.expression || '0 * * * *');
+      return parseCronNextRun(expression, now);
+    }
+
+    default:
+      return new Date(now.getTime() + 3600_000); // fallback: 1 hour
+  }
+}
+
+function parseCronNextRun(expression: string, from: Date): Date {
+  const parts = expression.trim().split(/\s+/);
+  const cronMinute = parts[0] ?? '*';
+  const cronHour = parts[1] ?? '*';
+  const cronDom = parts[2] ?? '*';
+  const cronMonth = parts[3] ?? '*';
+  const cronDow = parts[4] ?? '*';
+
+  // Brute force: check next 1440 minutes (24 hours)
+  const candidate = new Date(from);
+  candidate.setSeconds(0, 0);
+  candidate.setMinutes(candidate.getMinutes() + 1);
+
+  for (let i = 0; i < 1440 * 31; i++) {
+    if (
+      matchesCronField(cronMinute, candidate.getMinutes()) &&
+      matchesCronField(cronHour, candidate.getHours()) &&
+      matchesCronField(cronDom, candidate.getDate()) &&
+      matchesCronField(cronMonth, candidate.getMonth() + 1) &&
+      matchesCronField(cronDow, candidate.getDay())
+    ) {
+      return candidate;
+    }
+    candidate.setMinutes(candidate.getMinutes() + 1);
+  }
+
+  // Fallback if no match found
+  return new Date(from.getTime() + 3600_000);
+}
+
+function matchesCronField(field: string, value: number): boolean {
+  if (field === '*') return true;
+
+  // Handle step values: */5
+  if (field.startsWith('*/')) {
+    const step = parseInt(field.slice(2), 10);
+    return step > 0 && value % step === 0;
+  }
+
+  // Handle ranges: 1-5
+  if (field.includes('-')) {
+    const [min, max] = field.split('-').map(Number);
+    return min !== undefined && max !== undefined && value >= min && value <= max;
+  }
+
+  // Handle lists: 1,3,5
+  if (field.includes(',')) {
+    return field.split(',').map(Number).includes(value);
+  }
+
+  // Exact match
+  return parseInt(field, 10) === value;
+}

apps/api/src/routes/servers/backups.ts

@@ -0,0 +1,177 @@
+import type { FastifyInstance } from 'fastify';
+import { eq, and } from 'drizzle-orm';
+import { Type } from '@sinclair/typebox';
+import { servers, backups } from '@source/database';
+import { AppError } from '../../lib/errors.js';
+import { requirePermission } from '../../lib/permissions.js';
+import { createAuditLog } from '../../lib/audit.js';
+
+const ParamSchema = {
+  params: Type.Object({
+    orgId: Type.String({ format: 'uuid' }),
+    serverId: Type.String({ format: 'uuid' }),
+  }),
+};
+
+const BackupParamSchema = {
+  params: Type.Object({
+    orgId: Type.String({ format: 'uuid' }),
+    serverId: Type.String({ format: 'uuid' }),
+    backupId: Type.String({ format: 'uuid' }),
+  }),
+};
+
+const CreateBackupBody = Type.Object({
+  name: Type.String({ minLength: 1, maxLength: 255 }),
+  isLocked: Type.Optional(Type.Boolean({ default: false })),
+});
+
+export default async function backupRoutes(app: FastifyInstance) {
+  app.addHook('onRequest', app.authenticate);
+
+  // GET /backups — list all backups for a server
+  app.get('/', { schema: ParamSchema }, async (request) => {
+    const { orgId, serverId } = request.params as { orgId: string; serverId: string };
+    await requirePermission(request, orgId, 'backup.read');
+
+    const server = await app.db.query.servers.findFirst({
+      where: and(eq(servers.id, serverId), eq(servers.organizationId, orgId)),
+    });
+    if (!server) throw AppError.notFound('Server not found');
+
+    const backupList = await app.db.query.backups.findMany({
+      where: eq(backups.serverId, serverId),
+      orderBy: (b, { desc }) => [desc(b.createdAt)],
+    });
+
+    return { backups: backupList };
+  });
+
+  // POST /backups — create a backup
+  app.post('/', { schema: { ...ParamSchema, body: CreateBackupBody } }, async (request, reply) => {
+    const { orgId, serverId } = request.params as { orgId: string; serverId: string };
+    await requirePermission(request, orgId, 'backup.create');
+
+    const body = request.body as { name: string; isLocked?: boolean };
+
+    const server = await app.db.query.servers.findFirst({
+      where: and(eq(servers.id, serverId), eq(servers.organizationId, orgId)),
+    });
+    if (!server) throw AppError.notFound('Server not found');
+
+    // Create backup record (pending — daemon will update when complete)
+    const [backup] = await app.db
+      .insert(backups)
+      .values({
+        serverId,
+        name: body.name,
+        isLocked: body.isLocked ?? false,
+      })
+      .returning();
+
+    // TODO: Send gRPC CreateBackup to daemon
+    // Daemon will:
+    //   1. tar+gz the server directory
+    //   2. Upload to @source/cdn
+    //   3. Callback to API with cdnPath, sizeBytes, checksum
+    //   4. API updates backup record with completedAt
+
+    await createAuditLog(app.db, request, {
+      organizationId: orgId,
+      serverId,
+      action: 'backup.create',
+      metadata: { name: body.name },
+    });
+
+    return reply.code(201).send(backup);
+  });
+
+  // POST /backups/:backupId/restore — restore a backup
+  app.post('/:backupId/restore', { schema: BackupParamSchema }, async (request) => {
+    const { orgId, serverId, backupId } = request.params as {
+      orgId: string;
+      serverId: string;
+      backupId: string;
+    };
+    await requirePermission(request, orgId, 'backup.restore');
+
+    const server = await app.db.query.servers.findFirst({
+      where: and(eq(servers.id, serverId), eq(servers.organizationId, orgId)),
+    });
+    if (!server) throw AppError.notFound('Server not found');
+
+    const backup = await app.db.query.backups.findFirst({
+      where: and(eq(backups.id, backupId), eq(backups.serverId, serverId)),
+    });
+    if (!backup) throw AppError.notFound('Backup not found');
+    if (!backup.completedAt) throw AppError.badRequest('Backup is not yet completed');
+
+    // TODO: Send gRPC RestoreBackup to daemon
+    // Daemon will:
+    //   1. Stop the server
+    //   2. Download backup from @source/cdn
+    //   3. Extract tar.gz over server directory
+    //   4. Start the server
+
+    await createAuditLog(app.db, request, {
+      organizationId: orgId,
+      serverId,
+      action: 'backup.restore',
+      metadata: { backupName: backup.name, backupId },
+    });
+
+    return { success: true, message: 'Restore initiated' };
+  });
+
+  // PATCH /backups/:backupId/lock — toggle backup lock
+  app.patch('/:backupId/lock', { schema: BackupParamSchema }, async (request) => {
+    const { orgId, serverId, backupId } = request.params as {
+      orgId: string;
+      serverId: string;
+      backupId: string;
+    };
+    await requirePermission(request, orgId, 'backup.manage');
+
+    const backup = await app.db.query.backups.findFirst({
+      where: and(eq(backups.id, backupId), eq(backups.serverId, serverId)),
+    });
+    if (!backup) throw AppError.notFound('Backup not found');
+
+    const [updated] = await app.db
+      .update(backups)
+      .set({ isLocked: !backup.isLocked })
+      .where(eq(backups.id, backupId))
+      .returning();
+
+    return updated;
+  });
+
+  // DELETE /backups/:backupId — delete a backup
+  app.delete('/:backupId', { schema: BackupParamSchema }, async (request, reply) => {
+    const { orgId, serverId, backupId } = request.params as {
+      orgId: string;
+      serverId: string;
+      backupId: string;
+    };
+    await requirePermission(request, orgId, 'backup.delete');
+
+    const backup = await app.db.query.backups.findFirst({
+      where: and(eq(backups.id, backupId), eq(backups.serverId, serverId)),
+    });
+    if (!backup) throw AppError.notFound('Backup not found');
+    if (backup.isLocked) throw AppError.badRequest('Cannot delete a locked backup');
+
+    // TODO: Send gRPC DeleteBackup to daemon to remove from CDN
+
+    await app.db.delete(backups).where(eq(backups.id, backupId));
+
+    await createAuditLog(app.db, request, {
+      organizationId: orgId,
+      serverId,
+      action: 'backup.delete',
+      metadata: { name: backup.name },
+    });
+
+    return reply.code(204).send();
+  });
+}

apps/api/src/routes/servers/index.ts

@@ -15,13 +15,17 @@ import {
 } from './schemas.js';
 import configRoutes from './config.js';
 import pluginRoutes from './plugins.js';
+import scheduleRoutes from './schedules.js';
+import backupRoutes from './backups.js';
 
 export default async function serverRoutes(app: FastifyInstance) {
   app.addHook('onRequest', app.authenticate);
 
-  // Register sub-routes for config and plugins
+  // Register sub-routes
   await app.register(configRoutes, { prefix: '/:serverId/config' });
   await app.register(pluginRoutes, { prefix: '/:serverId/plugins' });
+  await app.register(scheduleRoutes, { prefix: '/:serverId/schedules' });
+  await app.register(backupRoutes, { prefix: '/:serverId/backups' });
 
   // GET /api/organizations/:orgId/servers
   app.get('/', { schema: { querystring: PaginationQuerySchema } }, async (request) => {

apps/api/src/routes/servers/schedules.ts

@@ -0,0 +1,208 @@
+import type { FastifyInstance } from 'fastify';
+import { eq, and } from 'drizzle-orm';
+import { Type } from '@sinclair/typebox';
+import { servers, scheduledTasks } from '@source/database';
+import { AppError } from '../../lib/errors.js';
+import { requirePermission } from '../../lib/permissions.js';
+import { createAuditLog } from '../../lib/audit.js';
+import { computeNextRun } from '../../lib/schedule-utils.js';
+
+const ParamSchema = {
+  params: Type.Object({
+    orgId: Type.String({ format: 'uuid' }),
+    serverId: Type.String({ format: 'uuid' }),
+  }),
+};
+
+const TaskParamSchema = {
+  params: Type.Object({
+    orgId: Type.String({ format: 'uuid' }),
+    serverId: Type.String({ format: 'uuid' }),
+    taskId: Type.String({ format: 'uuid' }),
+  }),
+};
+
+const CreateScheduleBody = Type.Object({
+  name: Type.String({ minLength: 1, maxLength: 255 }),
+  action: Type.Union([
+    Type.Literal('command'),
+    Type.Literal('power'),
+    Type.Literal('backup'),
+  ]),
+  payload: Type.String({ minLength: 1 }),
+  scheduleType: Type.Union([
+    Type.Literal('interval'),
+    Type.Literal('daily'),
+    Type.Literal('weekly'),
+    Type.Literal('cron'),
+  ]),
+  scheduleData: Type.Object({}, { additionalProperties: true }),
+  isActive: Type.Optional(Type.Boolean({ default: true })),
+});
+
+const UpdateScheduleBody = Type.Object({
+  name: Type.Optional(Type.String({ minLength: 1, maxLength: 255 })),
+  action: Type.Optional(
+    Type.Union([Type.Literal('command'), Type.Literal('power'), Type.Literal('backup')]),
+  ),
+  payload: Type.Optional(Type.String({ minLength: 1 })),
+  scheduleType: Type.Optional(
+    Type.Union([
+      Type.Literal('interval'),
+      Type.Literal('daily'),
+      Type.Literal('weekly'),
+      Type.Literal('cron'),
+    ]),
+  ),
+  scheduleData: Type.Optional(Type.Object({}, { additionalProperties: true })),
+  isActive: Type.Optional(Type.Boolean()),
+});
+
+export default async function scheduleRoutes(app: FastifyInstance) {
+  app.addHook('onRequest', app.authenticate);
+
+  // GET /schedules — list all scheduled tasks for a server
+  app.get('/', { schema: ParamSchema }, async (request) => {
+    const { orgId, serverId } = request.params as { orgId: string; serverId: string };
+    await requirePermission(request, orgId, 'schedule.read');
+
+    const server = await app.db.query.servers.findFirst({
+      where: and(eq(servers.id, serverId), eq(servers.organizationId, orgId)),
+    });
+    if (!server) throw AppError.notFound('Server not found');
+
+    const tasks = await app.db.query.scheduledTasks.findMany({
+      where: eq(scheduledTasks.serverId, serverId),
+      orderBy: (t, { desc }) => [desc(t.createdAt)],
+    });
+
+    return { tasks };
+  });
+
+  // POST /schedules — create a scheduled task
+  app.post('/', { schema: { ...ParamSchema, body: CreateScheduleBody } }, async (request) => {
+    const { orgId, serverId } = request.params as { orgId: string; serverId: string };
+    await requirePermission(request, orgId, 'schedule.manage');
+
+    const body = request.body as {
+      name: string;
+      action: 'command' | 'power' | 'backup';
+      payload: string;
+      scheduleType: 'interval' | 'daily' | 'weekly' | 'cron';
+      scheduleData: Record<string, unknown>;
+      isActive?: boolean;
+    };
+
+    const server = await app.db.query.servers.findFirst({
+      where: and(eq(servers.id, serverId), eq(servers.organizationId, orgId)),
+    });
+    if (!server) throw AppError.notFound('Server not found');
+
+    const nextRun = computeNextRun(body.scheduleType, body.scheduleData);
+
+    const [task] = await app.db
+      .insert(scheduledTasks)
+      .values({
+        serverId,
+        name: body.name,
+        action: body.action,
+        payload: body.payload,
+        scheduleType: body.scheduleType,
+        scheduleData: body.scheduleData,
+        isActive: body.isActive ?? true,
+        nextRunAt: nextRun,
+      })
+      .returning();
+
+    await createAuditLog(app.db, request, {
+      organizationId: orgId,
+      serverId,
+      action: 'schedule.create',
+      metadata: { name: body.name, action: body.action },
+    });
+
+    return task;
+  });
+
+  // PATCH /schedules/:taskId — update a scheduled task
+  app.patch('/:taskId', { schema: { ...TaskParamSchema, body: UpdateScheduleBody } }, async (request) => {
+    const { orgId, serverId, taskId } = request.params as {
+      orgId: string;
+      serverId: string;
+      taskId: string;
+    };
+    await requirePermission(request, orgId, 'schedule.manage');
+
+    const body = request.body as Record<string, unknown>;
+
+    const existing = await app.db.query.scheduledTasks.findFirst({
+      where: and(eq(scheduledTasks.id, taskId), eq(scheduledTasks.serverId, serverId)),
+    });
+    if (!existing) throw AppError.notFound('Scheduled task not found');
+
+    // Recompute next run if schedule changed
+    const scheduleType = (body.scheduleType as string) || existing.scheduleType;
+    const scheduleData = (body.scheduleData as Record<string, unknown>) || (existing.scheduleData as Record<string, unknown>);
+    const nextRun = computeNextRun(scheduleType, scheduleData);
+
+    const [updated] = await app.db
+      .update(scheduledTasks)
+      .set({ ...body, nextRunAt: nextRun, updatedAt: new Date() })
+      .where(eq(scheduledTasks.id, taskId))
+      .returning();
+
+    return updated;
+  });
+
+  // DELETE /schedules/:taskId — delete a scheduled task
+  app.delete('/:taskId', { schema: TaskParamSchema }, async (request, reply) => {
+    const { orgId, serverId, taskId } = request.params as {
+      orgId: string;
+      serverId: string;
+      taskId: string;
+    };
+    await requirePermission(request, orgId, 'schedule.manage');
+
+    const existing = await app.db.query.scheduledTasks.findFirst({
+      where: and(eq(scheduledTasks.id, taskId), eq(scheduledTasks.serverId, serverId)),
+    });
+    if (!existing) throw AppError.notFound('Scheduled task not found');
+
+    await app.db.delete(scheduledTasks).where(eq(scheduledTasks.id, taskId));
+
+    await createAuditLog(app.db, request, {
+      organizationId: orgId,
+      serverId,
+      action: 'schedule.delete',
+      metadata: { name: existing.name },
+    });
+
+    return reply.code(204).send();
+  });
+
+  // POST /schedules/:taskId/trigger — manually trigger a task
+  app.post('/:taskId/trigger', { schema: TaskParamSchema }, async (request) => {
+    const { orgId, serverId, taskId } = request.params as {
+      orgId: string;
+      serverId: string;
+      taskId: string;
+    };
+    await requirePermission(request, orgId, 'schedule.manage');
+
+    const task = await app.db.query.scheduledTasks.findFirst({
+      where: and(eq(scheduledTasks.id, taskId), eq(scheduledTasks.serverId, serverId)),
+    });
+    if (!task) throw AppError.notFound('Scheduled task not found');
+
+    // TODO: Execute task action (send to daemon via gRPC)
+    // For now, just update lastRunAt and nextRunAt
+    const nextRun = computeNextRun(task.scheduleType, task.scheduleData as Record<string, unknown>);
+
+    await app.db
+      .update(scheduledTasks)
+      .set({ lastRunAt: new Date(), nextRunAt: nextRun })
+      .where(eq(scheduledTasks.id, taskId));
+
+    return { success: true, triggered: task.name };
+  });
+}