feat: add timezone support for scheduled backups

adiologydev · adiologydev · commit d96d68e11316 · 2025-12-19T22:38:11.000Z
diff --git a/README.md b/README.md
@@ -29,7 +29,7 @@ Glob patterns • tar.gz compression • Local + S3 storage • Docker volumes 
 - 🔍 **Glob Patterns** — Include/exclude files using patterns (`**/*.ts`, `!**/node_modules/**`)
 - 🐳 **Docker Volumes** — Backup Docker volumes with Docker Compose integration
 - ☁️ **Dual Storage** — Store backups locally and/or in S3 (supports R2, MinIO, etc.)
-- ⏰ **Scheduled Backups** — Cron-based scheduling with independent retention policies
+- ⏰ **Scheduled Backups** — Cron-based scheduling with timezone support and independent retention policies
 - 🛡️ **Safe Cleanup** — Multi-layer validation before any deletion (checksums, path verification)
 - ✅ **Integrity Verification** — Verify backups exist and checksums match
 
@@ -106,9 +106,14 @@ s3:
   # accessKeyId: "key"                 # Or use S3_ACCESS_KEY_ID env var
   # secretAccessKey: "secret"          # Or use S3_SECRET_ACCESS_KEY env var
 
+# Optional: Set default timezone for all schedules
+# scheduler:
+#   timezone: "America/New_York"
+
 schedules:
   daily:
     cron: "0 2 * * *"        # Daily at 2 AM
+    # timezone: "Europe/London"  # Override global timezone
     retention:
       maxCount: 7            # Keep max 7 backups
       maxDays: 14            # Delete after 14 days
diff --git a/docs/configuration.md b/docs/configuration.md
@@ -221,19 +221,37 @@ S3-compatible storage (AWS S3, R2, MinIO, etc.).
 - `S3_REGION` (optional)
 - `S3_ENDPOINT` (optional)
 
+### `scheduler`
+
+Global scheduler settings.
+
+| Field      | Type   | Required | Description                                    |
+| ---------- | ------ | -------- | ---------------------------------------------- |
+| `timezone` | string | No       | Default timezone for all schedules (IANA name) |
+
+**Example:**
+
+```yaml
+scheduler:
+  timezone: "America/New_York"
+```
+
 ### `schedules`
 
 Named schedules with cron expressions and retention policies.
 
-| Field                | Type     | Required | Description                      |
-| -------------------- | -------- | -------- | -------------------------------- |
-| `cron`               | string   | Yes      | Cron expression (5 fields)       |
-| `retention.maxCount` | number   | No       | Maximum backups to keep          |
-| `retention.maxDays`  | number   | No       | Delete backups older than N days |
-| `sources`            | string[] | No       | Limit to specific sources        |
+| Field                | Type     | Required | Description                                   |
+| -------------------- | -------- | -------- | --------------------------------------------- |
+| `cron`               | string   | Yes      | Cron expression (5 fields)                    |
+| `retention.maxCount` | number   | No       | Maximum backups to keep                       |
+| `retention.maxDays`  | number   | No       | Delete backups older than N days              |
+| `sources`            | string[] | No       | Limit to specific sources                     |
+| `timezone`           | string   | No       | Timezone for this schedule (overrides global) |
 
 **Cron Format:** `minute hour day-of-month month day-of-week`
 
+**Timezone:** Use IANA timezone names (e.g., `America/New_York`, `Europe/London`, `Asia/Tokyo`). If not specified, the system timezone is used.
+
 ### `archive`
 
 Archive creation settings.
diff --git a/package.json b/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@climactic/backitup",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "Secure backup utility with glob patterns, tar.gz archives, local + S3 storage, and safe cleanup",
   "author": {
     "name": "Climactic",
diff --git a/src/config/validator.ts b/src/config/validator.ts
@@ -215,6 +215,24 @@ function validateSchedule(name: string, schedule: unknown, sourceNames: string[]
       }
     }
   }
+
+  if (sched.timezone !== undefined && typeof sched.timezone !== "string") {
+    throw new ConfigError(`schedules.${name}.timezone must be a string`);
+  }
+}
+
+/**
+ * Validate the scheduler configuration
+ */
+function validateSchedulerConfig(config: unknown): void {
+  if (!config) return;
+  if (typeof config !== "object") {
+    throw new ConfigError("scheduler must be an object");
+  }
+  const scheduler = config as Record<string, unknown>;
+  if (scheduler.timezone !== undefined && typeof scheduler.timezone !== "string") {
+    throw new ConfigError("scheduler.timezone must be a string");
+  }
 }
 
 /**
@@ -242,4 +260,5 @@ export function validateConfig(config: unknown): asserts config is BackitupConfi
   validators.schedules!(c, sourceNames);
   validators.storage!(c);
   validators.docker!(c);
+  validateSchedulerConfig(c.scheduler);
 }
diff --git a/src/core/scheduler/cron-parser.ts b/src/core/scheduler/cron-parser.ts
@@ -14,10 +14,15 @@ import { CronExpressionParser } from "cron-parser";
 
 export interface ParsedCron {
   expression: string;
+  timezone?: string;
   interval: ReturnType<typeof CronExpressionParser.parse>;
 }
 
-export function parseCron(expression: string): ParsedCron {
+export interface ParseCronOptions {
+  timezone?: string;
+}
+
+export function parseCron(expression: string, options?: ParseCronOptions): ParsedCron {
   // Validate that we have exactly 5 fields (standard cron format)
   const fields = expression.trim().split(/\s+/);
   if (fields.length !== 5) {
@@ -26,8 +31,9 @@ export function parseCron(expression: string): ParsedCron {
     );
   }
 
-  const interval = CronExpressionParser.parse(expression);
-  return { expression, interval };
+  const parserOptions = options?.timezone ? { tz: options.timezone } : undefined;
+  const interval = CronExpressionParser.parse(expression, parserOptions);
+  return { expression, timezone: options?.timezone, interval };
 }
 
 export function matchesCron(cron: ParsedCron, date: Date): boolean {
@@ -38,9 +44,13 @@ export function matchesCron(cron: ParsedCron, date: Date): boolean {
 
   // Get the next scheduled time from a minute before
   const checkDate = new Date(testDate.getTime() - 60000);
-  const interval = CronExpressionParser.parse(cron.expression, {
+  const parserOptions: { currentDate: Date; tz?: string } = {
     currentDate: checkDate,
-  });
+  };
+  if (cron.timezone) {
+    parserOptions.tz = cron.timezone;
+  }
+  const interval = CronExpressionParser.parse(cron.expression, parserOptions);
 
   const nextDate = interval.next().toDate();
   nextDate.setSeconds(0);
@@ -50,9 +60,17 @@ export function matchesCron(cron: ParsedCron, date: Date): boolean {
 }
 
 export function getNextRun(cron: ParsedCron, fromDate?: Date): Date {
-  const interval = CronExpressionParser.parse(cron.expression, {
-    currentDate: fromDate,
-  });
+  const parserOptions: { currentDate?: Date; tz?: string } = {};
+  if (fromDate) {
+    parserOptions.currentDate = fromDate;
+  }
+  if (cron.timezone) {
+    parserOptions.tz = cron.timezone;
+  }
+  const interval = CronExpressionParser.parse(
+    cron.expression,
+    Object.keys(parserOptions).length > 0 ? parserOptions : undefined,
+  );
   return interval.next().toDate();
 }
 
diff --git a/src/core/scheduler/daemon.ts b/src/core/scheduler/daemon.ts
@@ -25,16 +25,22 @@ export class Scheduler {
   constructor(config: BackitupConfig) {
     this.config = config;
 
+    // Get global timezone from scheduler config
+    const globalTimezone = config.scheduler?.timezone;
+
     for (const [name, scheduleConfig] of Object.entries(config.schedules)) {
       try {
-        const cron = parseCron(scheduleConfig.cron);
+        // Use schedule-specific timezone, falling back to global timezone
+        const timezone = scheduleConfig.timezone ?? globalTimezone;
+        const cron = parseCron(scheduleConfig.cron, { timezone });
         this.schedules.set(name, {
           name,
           cron,
           lastRun: null,
           retention: scheduleConfig.retention,
         });
-        logger.debug(`Parsed schedule "${name}": ${scheduleConfig.cron}`);
+        const tzInfo = timezone ? ` (${timezone})` : "";
+        logger.debug(`Parsed schedule "${name}": ${scheduleConfig.cron}${tzInfo}`);
       } catch (error) {
         logger.error(`Failed to parse schedule "${name}": ${(error as Error).message}`);
       }
@@ -125,31 +131,40 @@ export class Scheduler {
       return null;
     }
 
-    const now = new Date();
-    const maxIterations = 60 * 24 * 366;
+    try {
+      const now = new Date();
+      const maxIterations = 60 * 24 * 366;
 
-    for (let i = 0; i < maxIterations; i++) {
-      const checkTime = new Date(now.getTime() + i * 60 * 1000);
-      checkTime.setSeconds(0);
-      checkTime.setMilliseconds(0);
+      for (let i = 0; i < maxIterations; i++) {
+        const checkTime = new Date(now.getTime() + i * 60 * 1000);
+        checkTime.setSeconds(0);
+        checkTime.setMilliseconds(0);
 
-      if (matchesCron(state.cron, checkTime)) {
-        return checkTime;
+        if (matchesCron(state.cron, checkTime)) {
+          return checkTime;
+        }
       }
-    }
 
-    return null;
+      return null;
+    } catch (error) {
+      logger.error(
+        `Failed to calculate next run for "${scheduleName}": ${(error as Error).message}`,
+      );
+      return null;
+    }
   }
 
   getStatus(): {
     name: string;
     cron: string;
+    timezone?: string;
     lastRun: Date | null;
     nextRun: Date | null;
   }[] {
     const status: {
       name: string;
       cron: string;
+      timezone?: string;
       lastRun: Date | null;
       nextRun: Date | null;
     }[] = [];
@@ -160,6 +175,7 @@ export class Scheduler {
         status.push({
           name,
           cron: scheduleConfig.cron,
+          timezone: state.cron.timezone,
           lastRun: state.lastRun,
           nextRun: this.getNextRun(name),
         });
diff --git a/src/types/config.ts b/src/types/config.ts
@@ -32,6 +32,13 @@ export interface ScheduleConfig {
   cron: string;
   retention: RetentionConfig;
   sources?: string[];
+  /** Timezone for this schedule (overrides global timezone) */
+  timezone?: string;
+}
+
+export interface SchedulerConfig {
+  /** Global timezone for all schedules (default: system timezone) */
+  timezone?: string;
 }
 
 export interface SafetyConfig {
@@ -97,6 +104,7 @@ export interface BackitupConfig {
   local: LocalStorageConfig;
   s3: S3StorageConfig;
   schedules: Record<string, ScheduleConfig>;
+  scheduler?: SchedulerConfig;
   archive?: ArchiveConfig;
   safety?: SafetyConfig;
   docker?: DockerConfig;
diff --git a/tests/config/loader.test.ts b/tests/config/loader.test.ts
@@ -422,6 +422,92 @@ schedules:
       expect(loaded.schedules.daily!.sources).toEqual(["app"]);
     });
 
+    // Timezone validation tests
+    describe("timezone validation", () => {
+      test("accepts valid schedule timezone", async () => {
+        const config = {
+          ...validConfig,
+          schedules: {
+            daily: {
+              cron: "0 2 * * *",
+              retention: { maxCount: 7, maxDays: 30 },
+              timezone: "America/New_York",
+            },
+          },
+        };
+        const loaded = await writeAndLoad(config);
+        expect(loaded.schedules.daily!.timezone).toBe("America/New_York");
+      });
+
+      test("accepts schedule without timezone", async () => {
+        const loaded = await writeAndLoad(validConfig);
+        expect(loaded.schedules.daily!.timezone).toBeUndefined();
+      });
+
+      test("throws for non-string schedule timezone", async () => {
+        const config = {
+          ...validConfig,
+          schedules: {
+            daily: {
+              cron: "0 2 * * *",
+              retention: { maxCount: 7, maxDays: 30 },
+              timezone: 123,
+            },
+          },
+        };
+        await expect(writeAndLoad(config)).rejects.toThrow(
+          "schedules.daily.timezone must be a string",
+        );
+      });
+
+      test("accepts valid global scheduler timezone", async () => {
+        const config = {
+          ...validConfig,
+          scheduler: {
+            timezone: "Europe/London",
+          },
+        };
+        const loaded = await writeAndLoad(config);
+        expect(loaded.scheduler?.timezone).toBe("Europe/London");
+      });
+
+      test("accepts config without scheduler section", async () => {
+        const loaded = await writeAndLoad(validConfig);
+        expect(loaded.scheduler).toBeUndefined();
+      });
+
+      test("throws for non-object scheduler", async () => {
+        const config = {
+          ...validConfig,
+          scheduler: "invalid",
+        };
+        await expect(writeAndLoad(config)).rejects.toThrow("scheduler must be an object");
+      });
+
+      test("throws for non-string scheduler.timezone", async () => {
+        const config = {
+          ...validConfig,
+          scheduler: {
+            timezone: 123,
+          },
+        };
+        await expect(writeAndLoad(config)).rejects.toThrow("scheduler.timezone must be a string");
+      });
+
+      test("accepts common IANA timezones", async () => {
+        const timezones = ["UTC", "America/Los_Angeles", "Europe/Paris", "Asia/Tokyo"];
+
+        for (const tz of timezones) {
+          const config = {
+            ...validConfig,
+            scheduler: { timezone: tz },
+          };
+          const loaded = await writeAndLoad(config);
+          expect(loaded.scheduler?.timezone).toBe(tz);
+        }
+      });
+    });
+
     // Docker containerStop validation tests
     describe("docker containerStop validation", () => {
       const dockerBaseConfig = {
diff --git a/tests/core/scheduler.test.ts b/tests/core/scheduler.test.ts

Original file line number	Diff line number	Diff line change
`@@ -1,6 +1,6 @@`
`1`	`1`	`{`
`2`	`2`	`"name": "@climactic/backitup",`
`3`		`- "version": "1.0.0",`
	`3`	`+ "version": "1.1.0",`
`4`	`4`	`"description": "Secure backup utility with glob patterns, tar.gz archives, local + S3 storage, and safe cleanup",`
`5`	`5`	`"author": {`
`6`	`6`	`"name": "Climactic",`
Original file line number	Diff line number	Diff line change
`@@ -215,6 +215,24 @@ function validateSchedule(name: string, schedule: unknown, sourceNames: string[]`
`215`	`215`	`}`
`216`	`216`	`}`
`217`	`217`	`}`
	`218`	`+`
	`219`	`+ if (sched.timezone !== undefined && typeof sched.timezone !== "string") {`
	`220`	+ throw new ConfigError(`schedules.${name}.timezone must be a string`);
	`221`	`+ }`
	`222`	`+}`
	`223`	`+`
	`224`	`+/**`
	`225`	`+ * Validate the scheduler configuration`
	`226`	`+ */`
	`227`	`+function validateSchedulerConfig(config: unknown): void {`
	`228`	`+ if (!config) return;`
	`229`	`+ if (typeof config !== "object") {`
	`230`	`+ throw new ConfigError("scheduler must be an object");`
	`231`	`+ }`
	`232`	`+ const scheduler = config as Record<string, unknown>;`
	`233`	`+ if (scheduler.timezone !== undefined && typeof scheduler.timezone !== "string") {`
	`234`	`+ throw new ConfigError("scheduler.timezone must be a string");`
	`235`	`+ }`
`218`	`236`	`}`
`219`	`237`
`220`	`238`	`/**`
`@@ -242,4 +260,5 @@ export function validateConfig(config: unknown): asserts config is BackitupConfi`
`242`	`260`	`validators.schedules!(c, sourceNames);`
`243`	`261`	`validators.storage!(c);`
`244`	`262`	`validators.docker!(c);`
	`263`	`+ validateSchedulerConfig(c.scheduler);`
`245`	`264`	`}`