New plugin: Cron Matcher

Plugins
1

Hi Caddy community!

There’s A New Sheriff Matcher In Town :cowboy_hat_face:

I’m excited to introduce the Cron Matcher plugin, a new addition to Caddy’s ecosystem that enables powerful time-based request matching through cron expressions. This plugin is designed to add flexible scheduling capabilities to your Caddy server configuration, making it easy to activate or deactivate request routes and handlers based on flexible time schedules.

What Does the Cron Matcher Do?

The Cron Matcher adds a new matcher to Caddy, allowing you to define time windows during which specific routes or handlers should be active. With support for cron expressions, you can:

  • Enable maintenance modes on a schedule.
  • Restrict access to certain resources during specific hours.
  • Redirect to time-limited promotion pages.
  • Combine multiple schedules for more complex time-based logic.

Whether you need to schedule downtime, implement business hours, or manage time-sensitive access controls, the Cron Matcher makes it possible right from your Caddyfile.

How It Works

The Cron Matcher requires two parameters:

  • enable_at: Specifies when the matcher becomes active.
  • disable_at: Specifies when the matcher stops being active.

Requests match if the current time falls between these values. Multiple matchers within the same named matcher are OR’ed together.

Example Syntax:

@timedRequest cron "<enable_at>" "<disable_at>"

Example Use Cases:

  • Maintenance Windows: Activate a maintenance page every Sunday from 00:00 to 06:00.
@maintenance cron "0 0 * * SUN" "0 6 * * SUN"

handle @maintenance {
    respond "Maintenance in progress. Please check back later."
}

handle {
    reverse_proxy localhost:8080
}
  • Complex Maintenance Schedules: Combine multiple time windows for more advanced scheduling.
@complexSchedule {
    cron "0 23 * * 1-5" "0 0 * * 2-6"
    cron "0 22 * * SAT" "0 1 * * SUN"
}

handle @complexSchedule {
    respond "Scheduled maintenance active."
}

handle {
    reverse_proxy localhost:8080
}

Advanced Scheduling with Cron Expressions:
Schedule events on the third Tuesday of January, April, July, and October. This example highlights the use of advanced cron modifiers like # (Nth weekday).

@criticalPatchTuesday cron "0 0 * 1,4,7,10 2#3" "30 23 * 1,4,7,10 2#3"

handle @criticalPatchTuesday {
    respond "Oracle Critical Patch Update in progress: Third Tuesday of January, April, July, and October."
}

handle {
    reverse_proxy localhost:8080
}

Features

  • Precise Time Control: Use cron expressions to define exact start and end times for request handling. Whether you need daily schedules or specific times within a week, month, or year, the plugin has you covered.
  • Flexible Scheduling: Supports ranges, intervals, weekdays, and combinations of multiple schedules. You can define complex time windows such as “every third Tuesday of specific months” or “last Friday of the month.”
  • Support for Advanced Cron Expressions:
    Built on Gronx, the plugin supports more than just standard 5-segment cron expressions. It includes:
    • Year-Based Scheduling: Extend cron expressions to include a 6th segment for precise year-specific scheduling. For example, activate a handler from December 24, 2024 (0 0 24 12 * 2024) until December 31, 2024 (59 23 31 12 * 2024).
    • Second-Based Matching: Include an optional 7th segment for second-precise scheduling.
    • Modifiers for Complex Scenarios:
      • L: The last day of the month (L in the day segment) or the last occurrence of a weekday (2L for the last Tuesday).
      • W: The nearest weekday to a specific date (e.g., 15W for the closest weekday to the 15th of the month).
      • #: The nth occurrence of a specific weekday in a month (e.g., 2#3 for the third Tuesday of the month).

With these advanced features, you can implement time-based logic tailored to complex or niche requirements, all seamlessly integrated into your Caddyfile.

5 Likes
2

Very cool!! Thank you for making this and sharing it!

2 Likes