sidekiq-vigil 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 9ba1173ca461f02e3504da159ae2d276024e06abe21498ed68cd366f81451474
+  data.tar.gz: be2bd213fe4c4687a06acfbb706f3b7847df9e913d0028f14ff25da4cce24bed
+SHA512:
+  metadata.gz: ebec4298778df2aeee2a848b20cbec83a8224de9946849d0a04f436e32466f8bccbb8c663a3b58b2146f41e00d13a446d8135cb26e202679c2e846807dc6bef9
+  data.tar.gz: bff257da92bb81f5036d7a3ea6d2a4d64a7edb4dcef71d1d135a5a0d58a3fe90636e20b6b8bb08cc1c50a130c07bd61946a45e60dd20e3a546a6aa087908c1bd

data/.rubocop.yml

@@ -0,0 +1,39 @@
+AllCops:
+  NewCops: enable
+  TargetRubyVersion: 3.2
+  SuggestExtensions: false
+  UseCache: false
+  Exclude:
+    - "vendor/**/*"
+    - "gemfiles/**/*"
+
+Layout/LineLength:
+  Max: 140
+
+Metrics/BlockLength:
+  Exclude:
+    - "spec/**/*"
+    - "*.gemspec"
+    - "lib/generators/**/templates/*.rb"
+
+Metrics/ClassLength:
+  Max: 180
+
+Metrics/AbcSize:
+  Max: 30
+
+Metrics/MethodLength:
+  Max: 35
+
+Metrics/ParameterLists:
+  Max: 8
+
+Naming/PredicateMethod:
+  AllowedMethods:
+    - notify
+
+Style/StringLiterals:
+  EnforcedStyle: double_quotes
+
+Style/Documentation:
+  Enabled: false

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Yudai Takada
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,237 @@
+# Sidekiq Vigil
+
+Sidekiq Vigil is battery-included monitoring and alerting for Sidekiq. It runs against the Redis you already use, evaluates twelve health checks, keeps an alert lifecycle across restarts, and sends firing, ongoing, and recovery notifications.
+
+[![CI](https://github.com/ydah/sidekiq-vigil/actions/workflows/main.yml/badge.svg)](https://github.com/ydah/sidekiq-vigil/actions/workflows/main.yml)
+
+## Requirements
+
+- Ruby 3.2 or newer
+- Sidekiq 7.x or 8.x
+- Redis 7 or a Sidekiq-compatible Redis implementation
+
+Sidekiq is the only runtime dependency.
+
+## Five-minute quick start
+
+Add the gem from Git until the first RubyGems release:
+
+```ruby
+gem "sidekiq-vigil", github: "ydah/sidekiq-vigil"
+```
+
+Generate an initializer in Rails:
+
+```sh
+bundle install
+bundle exec rails generate sidekiq_vigil:install
+```
+
+Or create a pure Ruby initializer:
+
+```ruby
+require "sidekiq_vigil"
+
+SidekiqVigil.configure do |config|
+  config.key_prefix = "myapp"
+  config.redis = { url: ENV["REDIS_URL"] }
+
+  config.notifier :slack,
+    webhook_url: ENV["SLACK_WEBHOOK_DEFAULT"],
+    routes: { critical: ENV["SLACK_WEBHOOK_INCIDENTS"] }.compact,
+    mention: { critical: "<!here>" },
+    web_ui_url: "https://example.com/sidekiq"
+  config.notifier :log
+
+  config.check :queue_latency, warn: 60, critical: 300
+  config.check :queue_size, warn: 1_000, critical: 10_000
+end
+```
+
+Start Sidekiq normally. The server middleware, Reporter, and leader-elected Checker are installed automatically. Outside `production`, external notification is disabled unless `config.enabled = true` is assigned explicitly; Log remains available.
+
+Test every configured notifier before relying on it:
+
+```sh
+bundle exec vigil --config config/sidekiq_vigil.rb test-notify
+```
+
+## Recommended production topology
+
+Use Embedded mode for collection and checks, expose `SidekiqVigil::HealthApp`, and have an external uptime monitor call `/healthz`. Embedded monitoring cannot run when every Sidekiq process is dead; the endpoint detects that condition because an expired snapshot returns 503.
+
+```ruby
+# config.ru
+require "sidekiq_vigil"
+
+storage = SidekiqVigil.build_storage
+health = SidekiqVigil::HealthApp.new(
+  storage: storage,
+  interval: SidekiqVigil.config.interval
+)
+
+# Authentication is intentionally supplied by the application.
+use Rack::Auth::Basic do |username, password|
+  Rack::Utils.secure_compare(username, ENV.fetch("VIGIL_HEALTH_USER")) &&
+    Rack::Utils.secure_compare(password, ENV.fetch("VIGIL_HEALTH_PASSWORD"))
+end
+run health
+```
+
+`GET /healthz` returns 200 only when every result is OK and the snapshot is at most `interval × 2` old. `GET /status.json` includes check results, freshness, and age. Both return 503 when unhealthy or unavailable.
+
+## Execution modes
+
+| Mode | Command/integration | Collection | Detects total Sidekiq outage |
+|---|---|---:|---:|
+| Embedded (default) | Require the gem in Sidekiq | Reporter + leader Checker | Through stale external `/healthz` probe |
+| Standalone | `vigil --config config/vigil.rb` | Checker only | Yes |
+| Oneshot | `vigil --config config/vigil.rb check --once` | One Checker cycle | Yes, when scheduled externally |
+
+Standalone configuration is plain Ruby and must not depend on Rails constants.
+
+```sh
+bundle exec vigil --config config/vigil.rb status
+bundle exec vigil --config config/vigil.rb mute 30m --reason "database maintenance"
+bundle exec vigil --config config/vigil.rb unmute
+```
+
+`TERM` and `INT` stop Standalone mode gracefully and release its leader lock.
+
+## Check catalog
+
+| Check | Default behavior | Important options |
+|---|---|---|
+| `queue_latency` | Warn 60s, critical 300s | `queues`, `per_queue` |
+| `queue_size` | Warn 1,000, critical 10,000 | `queues`, `per_queue` |
+| `retry_set` | Warn 100, critical 1,000 | `growth_only` |
+| `dead_set` | Warn 1, critical 50 | `growth_only` |
+| `process_alive` | Require at least one active process | `min_processes`, `quiet_threshold` |
+| `utilization` | Warn 85%, critical 95% after 300s | `sustained` |
+| `failure_rate` | Warn 5%, critical 20%, minimum 20 attempts | `window`, `min_samples` |
+| `stuck_jobs` | Critical after 30 minutes | `threshold` |
+| `memory` | Warn 1,500 MiB, critical 2,500 MiB | `warn_mb`, `critical_mb` |
+| `redis_health` | PING latency and maxmemory usage | `latency_ms`, `memory_pct` |
+| `scheduled_backlog` | Warn on jobs overdue by five minutes | `overdue` |
+| `throughput_anomaly` | Disabled by default | `drop_pct`, `baseline_days`, `min_samples` |
+
+All checks use Sidekiq's public `sidekiq/api` objects. A check exception becomes an `error` result; it does not terminate Sidekiq or the Checker loop. Custom checks subclass `SidekiqVigil::Check::Base` and return one `SidekiqVigil::Result` or an array.
+
+Failure rate counts execution attempts, so a job that fails and retries can contribute more than one failure. Stuck-job duration assumes synchronized host clocks (NTP).
+
+## Full configuration reference
+
+```ruby
+SidekiqVigil.configure do |config|
+  config.enabled = true
+  config.interval = 30
+  config.flush_interval = 10
+  config.key_prefix = "myapp"
+  config.timezone = "Asia/Tokyo"
+  config.redis = {
+    url: ENV["REDIS_URL"],
+    pool_size: 5,
+    pool_timeout: 1
+  }
+
+  config.notifier :slack,
+    webhook_url: ENV["SLACK_WEBHOOK_DEFAULT"],
+    routes: { critical: ENV["SLACK_WEBHOOK_INCIDENTS"] },
+    mention: { critical: "<!subteam^S012345>" },
+    web_ui_url: "https://example.com/sidekiq"
+  config.notifier :webhook, url: "https://events.example.com/sidekiq"
+  config.notifier :log
+
+  config.alerting do |alerting|
+    alerting.pending_cycles = 2
+    alerting.cooldown = 600
+    alerting.resolve_notice = true
+    alerting.flap_window = 120
+    alerting.flap_threshold = 4
+    alerting.escalate_after = 3
+    alerting.group_threshold = 5
+    alerting.group_top_n = 5
+    alerting.mutes = [
+      { cron: "0 3 * * 0", duration: 3_600, reason: "weekly maintenance" }
+    ]
+  end
+end
+```
+
+Slack Incoming Webhooks have a fixed channel. Severity routing therefore selects different URLs; Sidekiq Vigil does not attempt to override `channel` in a payload. Mentions must use `<@U…>`, `<!subteam^S…>`, or `<!here>` syntax. Plain text such as `@oncall` fails configuration validation. Secret URLs are filtered from notifier inspection and error logging.
+
+The generic webhook contract and examples are documented in [docs/webhook_schema.md](docs/webhook_schema.md).
+
+The five Slack Block Kit shapes are contract-tested against JSON previews for [critical](spec/fixtures/slack/critical.json), [warn](spec/fixtures/slack/warn.json), [resolved](spec/fixtures/slack/resolved.json), [still-firing](spec/fixtures/slack/still_firing.json), and [digest](spec/fixtures/slack/digest.json). A real Slack screenshot must come from the manual pre-release check; generated imagery is not used as release evidence.
+
+## Alert lifecycle
+
+Each `check_name + target` moves through `OK → PENDING → FIRING → RESOLVED → OK`. State survives leader changes and process restarts.
+
+- `pending_cycles` removes single-cycle noise.
+- `cooldown` controls ongoing notifications.
+- `escalate_after` upgrades sustained warnings to critical.
+- `flap_threshold` transitions inside `flap_window` emit one flapping event and hold refiring until the window closes.
+- history retains the latest 30 values for 24 hours.
+- targets that disappear are pruned every cycle.
+- more than `group_threshold` events in one cycle become one digest with severity counts and `group_top_n` details.
+- mute windows continue state transitions but suppress delivery; unmute reports current firing state once.
+
+Mute cron expressions use the standard five fields and support lists (`1,3`), ranges (`1-5`), and steps (`*/10`). When both day-of-month and weekday are restricted, standard cron OR semantics apply.
+
+All Redis keys start with `vigil:<key_prefix>:`. The Storage API rejects non-positive or missing TTLs except for the explicitly managed `alerts` hash. The complete, contract-tested key list is in [docs/redis_keys.md](docs/redis_keys.md).
+
+## Existing tools
+
+| Tool | Primary purpose | Built-in lifecycle/notifications | Additional stack |
+|---|---|---:|---:|
+| yabeda-sidekiq / Prometheus exporters | Metrics export | No | Prometheus/Grafana/Alertmanager |
+| Sidekiq Alive | Kubernetes liveness | No | External probe |
+| sidekiq-job_alert | Queue/dead Slack alerts | Limited | No |
+| Sidekiq Web metrics | Execution exploration | No | No |
+| Sidekiq Vigil | Checks, lifecycle, mute/group/recovery | Yes | No |
+
+## Known limitations
+
+- During complete Redis failure, each process loses leader coordination and direct `redis_health` notifications can be duplicated. Recovery may also cause another notification. Use an external `/healthz` probe as the primary total-outage signal.
+- Throughput anomaly baseline uses the previous seven same-time windows and does not model weekday/weekend seasonality. It is opt-in and has a minimum-sample guard.
+- Stuck-job detection compares timestamps from different hosts and requires synchronized clocks.
+- RSS collection supports Linux `/proc` and macOS `ps`; the memory check is skipped on Windows.
+- Sidekiq Pro and Enterprise use only the same public APIs, but the combinations are not yet separately certified.
+- Slack Bot Token mode, thread tracking, weekday baselines, and Prometheus output are planned after v1.
+
+## Development
+
+```sh
+bundle install
+redis-server --port 16379 --save "" --appendonly no
+VIGIL_REDIS_URL=redis://127.0.0.1:16379/15 bundle exec rake
+bundle exec appraisal sidekiq_7 rspec
+bundle exec appraisal sidekiq_8 rspec
+bundle exec ruby benchmark/middleware_overhead.rb
+bundle exec rake build
+```
+
+The benchmark compares middleware-on and middleware-off in the same process, writes a JSON artifact, and only warns when the relative run has unusually high overhead.
+
+## FAQ
+
+**Does the middleware call Redis for every job?**
+
+No. It updates a mutex-protected in-process counter. Reporter flushes aggregates in a Redis pipeline.
+
+**Can I run Embedded and Standalone together?**
+
+Yes. The Redis leader lock prevents duplicate normal checks. A configuration digest warning appears when process configurations differ.
+
+**Why did Slack not receive a development notification?**
+
+External notifiers are safe by default outside production. Explicitly assign `config.enabled = true`, then run `vigil test-notify`.
+
+**Can I keep using yabeda or an APM?**
+
+Yes. Sidekiq Vigil does not replace or modify Sidekiq's metrics subsystem.
+
+## License
+
+MIT. See [LICENSE.txt](LICENSE.txt).

data/Rakefile

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+require "rubocop/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+RuboCop::RakeTask.new(:rubocop)
+
+task default: %i[spec rubocop]

data/docs/redis_keys.md

@@ -0,0 +1,18 @@
+# Redis key contract
+
+Every key is namespaced below `vigil:<key_prefix>:`. Storage writes require a positive TTL; the `alerts` hash is the only persistent exception and is explicitly pruned by `Alert::Manager`.
+
+The first column of this table is contract-tested against `SidekiqVigil::Storage::KEY_CATALOG`.
+
+| Key suffix | Type | Content | TTL | Owner |
+|---|---|---|---|---|
+| `stats:{yyyymmddHHMM}` | hash | Minute counters for processed/failed jobs and worker classes | 8 days | Reporter |
+| `exec:{queue}` | hash | Execution count/sum/max by queue | 1 hour | Reporter |
+| `alerts` | hash | Serialized alert lifecycle state | Explicitly managed; stale targets are pruned | Alert::Manager |
+| `history:{alert_id}` | list | Latest 30 observed values for a single alert | 24 hours | Alert::Manager |
+| `snapshot` | string | Timestamped check results and alert states | `interval × 4` | Checker |
+| `leader` | string | Leader-election token | `interval × 3` | LeaderElection |
+| `mem:{process_id}` | string | Reporter RSS in KiB | `flush_interval × 3` | Reporter |
+| `config_digest` | hash | Configuration digest by process | 1 hour | Reporter |
+| `mute` | string | Manual mute reason and expiration | Requested duration | Alert::Mute |
+| `check_state:{check-specific-suffix}` | string | Growth, quiet-process, or sustained-condition state | Check-specific positive TTL | Checks |

data/docs/webhook_event.schema.json

@@ -0,0 +1,41 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/ydah/sidekiq-vigil/blob/main/docs/webhook_event.schema.json",
+  "title": "Sidekiq Vigil webhook event",
+  "type": "object",
+  "required": ["schema_version", "event", "alert_id", "timestamp"],
+  "properties": {
+    "schema_version": { "const": "1.0" },
+    "event": {
+      "enum": ["firing", "still_firing", "resolved", "escalated", "flapping", "unmuted", "digest"]
+    },
+    "alert_id": { "type": "string", "minLength": 1 },
+    "timestamp": { "type": "string", "format": "date-time" },
+    "alert": {
+      "type": "object",
+      "required": ["check_name", "target", "severity", "metadata"],
+      "properties": {
+        "check_name": { "type": "string" },
+        "target": { "type": "string" },
+        "severity": { "enum": ["ok", "warn", "critical", "error"] },
+        "value": {},
+        "threshold": {},
+        "message": { "type": ["string", "null"] },
+        "metadata": { "type": "object" }
+      },
+      "additionalProperties": false
+    },
+    "state": { "type": "object" },
+    "history": { "type": "array" },
+    "counts": { "type": "object" },
+    "alerts": { "type": "array" }
+  },
+  "allOf": [
+    {
+      "if": { "properties": { "event": { "const": "digest" } } },
+      "then": { "required": ["counts", "alerts"] },
+      "else": { "required": ["alert", "state", "history"] }
+    }
+  ],
+  "additionalProperties": false
+}

data/docs/webhook_schema.md

@@ -0,0 +1,64 @@
+# Webhook payload schema
+
+The generic webhook notifier sends one JSON object per alert event. The normative JSON Schema is [`webhook_event.schema.json`](webhook_event.schema.json).
+
+## Compatibility
+
+- `schema_version` is currently `1.0`.
+- New optional properties may be added in a minor release.
+- Removing a property, changing its type, or changing event semantics requires a schema major-version change.
+- Receivers should ignore unknown optional properties.
+
+## Regular event
+
+```json
+{
+  "schema_version": "1.0",
+  "event": "firing",
+  "alert_id": "queue_size:critical",
+  "timestamp": "2026-07-28T12:00:00Z",
+  "alert": {
+    "check_name": "queue_size",
+    "target": "critical",
+    "severity": "critical",
+    "value": 250,
+    "threshold": 200,
+    "message": "250 jobs waiting",
+    "metadata": {}
+  },
+  "state": {
+    "status": "firing",
+    "cycles": 2,
+    "first_seen_at": 1785239970.0,
+    "last_notified_at": 1785240000.0,
+    "last_transition_at": 1785240000.0,
+    "severity": "critical",
+    "value": 250,
+    "threshold": 200,
+    "message": "250 jobs waiting",
+    "suppressed": false,
+    "flap_notified": false,
+    "flapping_until": null,
+    "transition_timestamps": [1785240000.0]
+  },
+  "history": [
+    { "timestamp": 1785239970.0, "value": 190, "severity": "warn" },
+    { "timestamp": 1785240000.0, "value": 250, "severity": "critical" }
+  ]
+}
+```
+
+## Digest event
+
+A digest replaces individual notifications when the number of events in one checker cycle is greater than `group_threshold`. It contains severity counts and the highest-severity alerts.
+
+```json
+{
+  "schema_version": "1.0",
+  "event": "digest",
+  "alert_id": "digest",
+  "timestamp": "2026-07-28T12:00:00Z",
+  "counts": { "critical": 3, "warn": 4 },
+  "alerts": []
+}
+```

data/exe/vigil

@@ -0,0 +1,6 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "sidekiq_vigil"
+
+exit SidekiqVigil::CLI.new.run(ARGV)

data/lib/generators/sidekiq_vigil/install_generator.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+require "fileutils"
+
+begin
+  require "rails/generators"
+
+  module SidekiqVigil
+    module Generators
+      class InstallGenerator < Rails::Generators::Base
+        source_root File.expand_path("templates", __dir__)
+
+        def copy_initializer
+          template "sidekiq_vigil.rb", "config/initializers/sidekiq_vigil.rb"
+        end
+      end
+    end
+  end
+rescue LoadError
+  module SidekiqVigil
+    module Generators
+      class InstallGenerator
+        TEMPLATE = File.expand_path("templates/sidekiq_vigil.rb", __dir__)
+
+        def self.install(destination)
+          FileUtils.mkdir_p(File.dirname(destination))
+          FileUtils.cp(TEMPLATE, destination)
+        end
+      end
+    end
+  end
+end

data/lib/generators/sidekiq_vigil/templates/sidekiq_vigil.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+require "sidekiq_vigil"
+
+SidekiqVigil.configure do |config|
+  # Monitoring is enabled by default. External notification is enabled by
+  # default only in production; set this explicitly to opt in elsewhere.
+  config.enabled = ENV.fetch("VIGIL_ENABLED") == "true" if ENV.key?("VIGIL_ENABLED")
+  config.interval = Integer(ENV.fetch("VIGIL_INTERVAL", "30"))
+  config.flush_interval = Integer(ENV.fetch("VIGIL_FLUSH_INTERVAL", "10"))
+  config.key_prefix = ENV.fetch("VIGIL_KEY_PREFIX", "myapp")
+  config.timezone = ENV.fetch("VIGIL_TIMEZONE", "UTC")
+  redis_url = ENV.fetch("REDIS_URL", nil)
+  config.redis = { url: redis_url } if redis_url
+
+  config.check :queue_latency, warn: 60, critical: 300
+  config.check :queue_size, warn: 1_000, critical: 10_000
+  config.check :retry_set, warn: 100, critical: 1_000
+  config.check :dead_set, warn: 1, critical: 50, growth_only: true
+  config.check :process_alive, min_processes: 1
+  config.check :utilization, warn: 0.85, critical: 0.95, sustained: 300
+  config.check :failure_rate, warn: 0.05, critical: 0.20, window: 300, min_samples: 20
+  config.check :stuck_jobs, threshold: 1_800
+  config.check :memory, warn_mb: 1_500, critical_mb: 2_500
+  config.check :redis_health, latency_ms: 100, memory_pct: 0.9
+  config.check :scheduled_backlog, overdue: 300
+  # Opt in after enough history has accumulated:
+  # config.check :throughput_anomaly, drop_pct: 0.5, baseline_days: 7
+
+  slack_webhook = ENV.fetch("SLACK_WEBHOOK_DEFAULT", nil)
+  if slack_webhook
+    config.notifier :slack,
+                    webhook_url: slack_webhook,
+                    routes: { critical: ENV.fetch("SLACK_WEBHOOK_INCIDENTS", nil) }.compact,
+                    mention: { critical: ENV.fetch("SLACK_CRITICAL_MENTION", nil) }.compact,
+                    web_ui_url: ENV.fetch("SIDEKIQ_WEB_UI_URL", nil)
+  end
+  config.notifier :log
+
+  config.alerting do |alerting|
+    alerting.pending_cycles = 2
+    alerting.cooldown = 600
+    alerting.resolve_notice = true
+    alerting.flap_window = 120
+    alerting.flap_threshold = 4
+    alerting.group_threshold = 5
+    alerting.group_top_n = 5
+  end
+end

data/lib/sidekiq/vigil/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+require_relative "../../sidekiq_vigil/version"
+
+module Sidekiq
+  Vigil = SidekiqVigil unless const_defined?(:Vigil)
+end

data/lib/sidekiq/vigil.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+require_relative "../sidekiq_vigil"
+
+module Sidekiq
+  Vigil = SidekiqVigil unless const_defined?(:Vigil)
+end

data/lib/sidekiq_vigil/alert/cron.rb

@@ -0,0 +1,106 @@
+# frozen_string_literal: true
+
+module SidekiqVigil
+  module Alert
+    class Cron
+      Field = Data.define(:values, :wildcard)
+
+      FIELD_RANGES = [
+        (0..59),
+        (0..23),
+        (1..31),
+        (1..12),
+        (0..7)
+      ].freeze
+
+      def initialize(expression)
+        fields = expression.to_s.split
+        raise ConfigError, "mute cron must contain five fields" unless fields.length == FIELD_RANGES.length
+
+        @fields = fields.zip(FIELD_RANGES).map { |field, range| parse_field(field, range) }
+      end
+
+      def match?(time)
+        minute, hour, day, month, weekday = fields
+        fixed_fields = [[minute, time.min], [hour, time.hour], [month, time.month]]
+        return false unless fixed_fields.all? { |field, value| field.values.include?(value) }
+
+        day_matches = day.values.include?(time.day)
+        weekday_matches = weekday.values.include?(time.wday)
+        return day_matches || weekday_matches unless day.wildcard || weekday.wildcard
+
+        day_matches && weekday_matches
+      end
+
+      private
+
+      attr_reader :fields
+
+      def parse_field(source, range)
+        wildcard = source.start_with?("*")
+        values = source.split(",").flat_map { |part| expand_part(part, range) }.map do |value|
+          normalize_weekday(value, range)
+        end
+        raise ConfigError, "mute cron field #{source.inspect} selects no values" if values.empty?
+
+        Field.new(values: values.uniq.freeze, wildcard:)
+      rescue ArgumentError
+        raise ConfigError, "invalid mute cron field #{source.inspect}"
+      end
+
+      def expand_part(part, range)
+        base, raw_step = split_part(part)
+        step = parse_step(raw_step)
+        values = base_values(base, range, stepped: !raw_step.nil?)
+        values.each_with_index.filter_map { |value, index| value if (index % step).zero? }
+      end
+
+      def split_part(part)
+        base, raw_step, extra = part.split("/", 3)
+        raise ArgumentError if base.nil? || base.empty? || extra
+
+        [base, raw_step]
+      end
+
+      def parse_step(raw_step)
+        return 1 unless raw_step
+
+        step = Integer(raw_step, 10)
+        raise ArgumentError unless step.positive?
+
+        step
+      end
+
+      def base_values(base, range, stepped:)
+        return range.to_a if base == "*"
+
+        if base.include?("-")
+          first, last, extra = base.split("-", 3)
+          raise ArgumentError if extra
+
+          first = bounded_integer(first, range)
+          last = bounded_integer(last, range)
+          raise ArgumentError if first > last
+
+          return (first..last).to_a
+        end
+
+        first = bounded_integer(base, range)
+        return (first..range.end).to_a if stepped
+
+        [first]
+      end
+
+      def bounded_integer(value, range)
+        integer = Integer(value, 10)
+        raise ArgumentError unless range.cover?(integer)
+
+        integer
+      end
+
+      def normalize_weekday(value, range)
+        range.end == 7 && value == 7 ? 0 : value
+      end
+    end
+  end
+end