@openmdm/core 0.2.0 → 0.3.0

package/src/queue.ts

@@ -0,0 +1,161 @@
+/**
+ * OpenMDM Message Queue Manager
+ *
+ * Provides persistent message queue management for the MDM system.
+ * Ensures reliable message delivery with retry and expiration handling.
+ */
+
+import type {
+  MessageQueueManager,
+  QueuedMessage,
+  EnqueueMessageInput,
+  QueueStats,
+  DatabaseAdapter,
+} from './types';
+
+/**
+ * Default maximum attempts for message delivery
+ */
+const DEFAULT_MAX_ATTEMPTS = 3;
+
+/**
+ * Default TTL in seconds (24 hours)
+ */
+const DEFAULT_TTL_SECONDS = 86400;
+
+/**
+ * Create a MessageQueueManager instance
+ */
+export function createMessageQueueManager(db: DatabaseAdapter): MessageQueueManager {
+  return {
+    async enqueue(message: EnqueueMessageInput): Promise<QueuedMessage> {
+      if (!db.enqueueMessage) {
+        throw new Error('Database adapter does not support message queue');
+      }
+
+      // Set defaults
+      const enrichedMessage: EnqueueMessageInput = {
+        ...message,
+        priority: message.priority ?? 'normal',
+        maxAttempts: message.maxAttempts ?? DEFAULT_MAX_ATTEMPTS,
+        ttlSeconds: message.ttlSeconds ?? DEFAULT_TTL_SECONDS,
+      };
+
+      return db.enqueueMessage(enrichedMessage);
+    },
+
+    async enqueueBatch(messages: EnqueueMessageInput[]): Promise<QueuedMessage[]> {
+      if (!db.enqueueMessage) {
+        throw new Error('Database adapter does not support message queue');
+      }
+
+      const results: QueuedMessage[] = [];
+
+      for (const message of messages) {
+        const enrichedMessage: EnqueueMessageInput = {
+          ...message,
+          priority: message.priority ?? 'normal',
+          maxAttempts: message.maxAttempts ?? DEFAULT_MAX_ATTEMPTS,
+          ttlSeconds: message.ttlSeconds ?? DEFAULT_TTL_SECONDS,
+        };
+
+        const queued = await db.enqueueMessage(enrichedMessage);
+        results.push(queued);
+      }
+
+      return results;
+    },
+
+    async dequeue(deviceId: string, limit: number = 10): Promise<QueuedMessage[]> {
+      if (!db.dequeueMessages) {
+        throw new Error('Database adapter does not support message queue');
+      }
+      return db.dequeueMessages(deviceId, limit);
+    },
+
+    async acknowledge(messageId: string): Promise<void> {
+      if (!db.acknowledgeMessage) {
+        throw new Error('Database adapter does not support message queue');
+      }
+      await db.acknowledgeMessage(messageId);
+    },
+
+    async fail(messageId: string, error: string): Promise<void> {
+      if (!db.failMessage) {
+        throw new Error('Database adapter does not support message queue');
+      }
+      await db.failMessage(messageId, error);
+    },
+
+    async retryFailed(maxAttempts: number = DEFAULT_MAX_ATTEMPTS): Promise<number> {
+      if (!db.retryFailedMessages) {
+        throw new Error('Database adapter does not support message queue');
+      }
+      return db.retryFailedMessages(maxAttempts);
+    },
+
+    async purgeExpired(): Promise<number> {
+      if (!db.purgeExpiredMessages) {
+        throw new Error('Database adapter does not support message queue');
+      }
+      return db.purgeExpiredMessages();
+    },
+
+    async getStats(tenantId?: string): Promise<QueueStats> {
+      if (!db.getQueueStats) {
+        throw new Error('Database adapter does not support message queue');
+      }
+      return db.getQueueStats(tenantId);
+    },
+
+    async peek(deviceId: string, limit: number = 10): Promise<QueuedMessage[]> {
+      if (!db.peekMessages) {
+        throw new Error('Database adapter does not support message queue');
+      }
+      return db.peekMessages(deviceId, limit);
+    },
+  };
+}
+
+/**
+ * Message priority weights for sorting
+ */
+export const PRIORITY_WEIGHTS = {
+  high: 3,
+  normal: 2,
+  low: 1,
+} as const;
+
+/**
+ * Compare messages by priority (higher priority first)
+ */
+export function compareByPriority(a: QueuedMessage, b: QueuedMessage): number {
+  return PRIORITY_WEIGHTS[b.priority] - PRIORITY_WEIGHTS[a.priority];
+}
+
+/**
+ * Check if a message has expired
+ */
+export function isMessageExpired(message: QueuedMessage): boolean {
+  if (!message.expiresAt) return false;
+  return new Date(message.expiresAt) < new Date();
+}
+
+/**
+ * Check if a message can be retried
+ */
+export function canRetryMessage(message: QueuedMessage): boolean {
+  return message.status === 'failed' && message.attempts < message.maxAttempts;
+}
+
+/**
+ * Calculate exponential backoff delay for retries
+ */
+export function calculateBackoffDelay(
+  attempts: number,
+  baseDelayMs: number = 1000,
+  maxDelayMs: number = 300000 // 5 minutes
+): number {
+  const delay = baseDelayMs * Math.pow(2, attempts - 1);
+  return Math.min(delay, maxDelayMs);
+}

package/src/schedule.ts

@@ -0,0 +1,325 @@
+/**
+ * OpenMDM Schedule Manager
+ *
+ * Provides scheduled task management for the MDM system.
+ * Enables scheduling of recurring operations, maintenance windows, and one-time tasks.
+ */
+
+import type {
+  ScheduleManager,
+  ScheduledTask,
+  ScheduledTaskFilter,
+  ScheduledTaskListResult,
+  CreateScheduledTaskInput,
+  UpdateScheduledTaskInput,
+  TaskSchedule,
+  TaskExecution,
+  DatabaseAdapter,
+} from './types';
+
+/**
+ * Parse cron expression and calculate next run time
+ * Supports: minute hour dayOfMonth month dayOfWeek
+ */
+function parseCronNextRun(cron: string, from: Date = new Date()): Date | null {
+  try {
+    const parts = cron.trim().split(/\s+/);
+    if (parts.length !== 5) return null;
+
+    const [minute, hour, dayOfMonth, month, dayOfWeek] = parts;
+
+    // Simple cron parsing - handles basic patterns
+    const now = new Date(from);
+    const next = new Date(now);
+
+    // Start from the next minute
+    next.setSeconds(0);
+    next.setMilliseconds(0);
+    next.setMinutes(next.getMinutes() + 1);
+
+    // Try to find next valid time (up to 1 year)
+    const maxIterations = 365 * 24 * 60; // 1 year in minutes
+    for (let i = 0; i < maxIterations; i++) {
+      const matches =
+        matchesCronField(minute, next.getMinutes()) &&
+        matchesCronField(hour, next.getHours()) &&
+        matchesCronField(dayOfMonth, next.getDate()) &&
+        matchesCronField(month, next.getMonth() + 1) &&
+        matchesCronField(dayOfWeek, next.getDay());
+
+      if (matches) {
+        return next;
+      }
+
+      next.setMinutes(next.getMinutes() + 1);
+    }
+
+    return null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Check if a value matches a cron field pattern
+ */
+function matchesCronField(pattern: string, value: number): boolean {
+  if (pattern === '*') return true;
+
+  // Handle step values: */5, */15, etc.
+  if (pattern.startsWith('*/')) {
+    const step = parseInt(pattern.slice(2), 10);
+    return value % step === 0;
+  }
+
+  // Handle ranges: 1-5
+  if (pattern.includes('-')) {
+    const [start, end] = pattern.split('-').map((n) => parseInt(n, 10));
+    return value >= start && value <= end;
+  }
+
+  // Handle lists: 1,3,5
+  if (pattern.includes(',')) {
+    const values = pattern.split(',').map((n) => parseInt(n, 10));
+    return values.includes(value);
+  }
+
+  // Simple number
+  return parseInt(pattern, 10) === value;
+}
+
+/**
+ * Check if current time is within a maintenance window
+ */
+function isInMaintenanceWindow(
+  window: TaskSchedule['window'],
+  now: Date = new Date()
+): boolean {
+  if (!window) return false;
+
+  const dayOfWeek = now.getDay();
+  if (!window.daysOfWeek.includes(dayOfWeek)) return false;
+
+  // Parse times
+  const [startHour, startMin] = window.startTime.split(':').map(Number);
+  const [endHour, endMin] = window.endTime.split(':').map(Number);
+
+  const currentMinutes = now.getHours() * 60 + now.getMinutes();
+  const startMinutes = startHour * 60 + startMin;
+  const endMinutes = endHour * 60 + endMin;
+
+  // Handle overnight windows
+  if (endMinutes < startMinutes) {
+    return currentMinutes >= startMinutes || currentMinutes < endMinutes;
+  }
+
+  return currentMinutes >= startMinutes && currentMinutes < endMinutes;
+}
+
+/**
+ * Calculate next run time for a maintenance window
+ */
+function calculateNextWindowRun(
+  window: TaskSchedule['window'],
+  from: Date = new Date()
+): Date | null {
+  if (!window) return null;
+
+  const [startHour, startMin] = window.startTime.split(':').map(Number);
+
+  // Try each day for the next 7 days
+  for (let dayOffset = 0; dayOffset <= 7; dayOffset++) {
+    const candidate = new Date(from);
+    candidate.setDate(candidate.getDate() + dayOffset);
+    candidate.setHours(startHour, startMin, 0, 0);
+
+    // Skip if in the past
+    if (candidate <= from) continue;
+
+    // Check if day matches
+    if (window.daysOfWeek.includes(candidate.getDay())) {
+      return candidate;
+    }
+  }
+
+  return null;
+}
+
+/**
+ * Create a ScheduleManager instance
+ */
+export function createScheduleManager(db: DatabaseAdapter): ScheduleManager {
+  /**
+   * Calculate the next run time for a schedule
+   */
+  function calculateNextRun(schedule: TaskSchedule): Date | null {
+    const now = new Date();
+
+    switch (schedule.type) {
+      case 'once':
+        // For one-time tasks, return the scheduled time if it's in the future
+        if (schedule.executeAt && new Date(schedule.executeAt) > now) {
+          return new Date(schedule.executeAt);
+        }
+        return null;
+
+      case 'recurring':
+        // Parse cron expression
+        if (schedule.cron) {
+          return parseCronNextRun(schedule.cron, now);
+        }
+        return null;
+
+      case 'window':
+        // Calculate next maintenance window start
+        if (schedule.window) {
+          return calculateNextWindowRun(schedule.window, now);
+        }
+        return null;
+
+      default:
+        return null;
+    }
+  }
+
+  return {
+    async get(id: string): Promise<ScheduledTask | null> {
+      if (!db.findScheduledTask) {
+        throw new Error('Database adapter does not support task scheduling');
+      }
+      return db.findScheduledTask(id);
+    },
+
+    async list(filter?: ScheduledTaskFilter): Promise<ScheduledTaskListResult> {
+      if (!db.listScheduledTasks) {
+        throw new Error('Database adapter does not support task scheduling');
+      }
+      return db.listScheduledTasks(filter);
+    },
+
+    async create(data: CreateScheduledTaskInput): Promise<ScheduledTask> {
+      if (!db.createScheduledTask) {
+        throw new Error('Database adapter does not support task scheduling');
+      }
+
+      // Calculate initial next run time
+      const nextRunAt = calculateNextRun(data.schedule);
+
+      // Create task with calculated next run
+      const task = await db.createScheduledTask({
+        ...data,
+        // Note: nextRunAt is set by the database adapter based on schedule
+      });
+
+      // Update next run time if needed
+      if (nextRunAt && db.updateScheduledTask) {
+        return db.updateScheduledTask(task.id, {
+          ...data,
+        });
+      }
+
+      return task;
+    },
+
+    async update(id: string, data: UpdateScheduledTaskInput): Promise<ScheduledTask> {
+      if (!db.updateScheduledTask || !db.findScheduledTask) {
+        throw new Error('Database adapter does not support task scheduling');
+      }
+
+      const existing = await db.findScheduledTask(id);
+      if (!existing) {
+        throw new Error(`Scheduled task not found: ${id}`);
+      }
+
+      return db.updateScheduledTask(id, data);
+    },
+
+    async delete(id: string): Promise<void> {
+      if (!db.deleteScheduledTask) {
+        throw new Error('Database adapter does not support task scheduling');
+      }
+      await db.deleteScheduledTask(id);
+    },
+
+    async pause(id: string): Promise<ScheduledTask> {
+      if (!db.updateScheduledTask || !db.findScheduledTask) {
+        throw new Error('Database adapter does not support task scheduling');
+      }
+
+      const task = await db.findScheduledTask(id);
+      if (!task) {
+        throw new Error(`Scheduled task not found: ${id}`);
+      }
+
+      if (task.status === 'paused') {
+        return task;
+      }
+
+      return db.updateScheduledTask(id, { status: 'paused' });
+    },
+
+    async resume(id: string): Promise<ScheduledTask> {
+      if (!db.updateScheduledTask || !db.findScheduledTask) {
+        throw new Error('Database adapter does not support task scheduling');
+      }
+
+      const task = await db.findScheduledTask(id);
+      if (!task) {
+        throw new Error(`Scheduled task not found: ${id}`);
+      }
+
+      if (task.status !== 'paused') {
+        return task;
+      }
+
+      // Recalculate next run time
+      const nextRunAt = calculateNextRun(task.schedule);
+
+      return db.updateScheduledTask(id, { status: 'active' });
+    },
+
+    async runNow(id: string): Promise<TaskExecution> {
+      if (
+        !db.findScheduledTask ||
+        !db.createTaskExecution ||
+        !db.updateScheduledTask
+      ) {
+        throw new Error('Database adapter does not support task scheduling');
+      }
+
+      const task = await db.findScheduledTask(id);
+      if (!task) {
+        throw new Error(`Scheduled task not found: ${id}`);
+      }
+
+      // Create execution record
+      const execution = await db.createTaskExecution({ taskId: id });
+
+      // Update task last run time
+      await db.updateScheduledTask(id, {});
+
+      return execution;
+    },
+
+    async getUpcoming(hours: number): Promise<ScheduledTask[]> {
+      if (!db.getUpcomingTasks) {
+        throw new Error('Database adapter does not support task scheduling');
+      }
+      return db.getUpcomingTasks(hours);
+    },
+
+    async getExecutions(taskId: string, limit: number = 10): Promise<TaskExecution[]> {
+      if (!db.listTaskExecutions) {
+        throw new Error('Database adapter does not support task scheduling');
+      }
+      return db.listTaskExecutions(taskId, limit);
+    },
+
+    calculateNextRun,
+  };
+}
+
+/**
+ * Export utility functions
+ */
+export { parseCronNextRun, isInMaintenanceWindow, calculateNextWindowRun };