good_job 4.19.1 → 4.19.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7afb27ab67bbbe17bf951784355a40adf87515486c7fd28c5cb12af3e2135005
-  data.tar.gz: 9f1da0f02768f9131a3c75ff1d181170a169662f631a83f05862608c579a30e6
+  metadata.gz: b4d6ba03812a521f55ab70bb95caafb96aba83c049036e9f8cc5d7489f3f8dcc
+  data.tar.gz: 3898461e6eccf9e8c6106b69a41123b82ff2e5a4697205464c60336304b4a5ef
 SHA512:
-  metadata.gz: 4e9e6c72eba0c338334e2acb94cc87e2b5f433ac2b36fd2ec05a1a58656dc5c6ff7d5f4d22f218aeaa04b0f432a44d908654ab0c25dd7c82194acb505539952f
-  data.tar.gz: 912da2530fec05469474232f8246f9370dd1da24e822bcf6bcb37b6f649b43ab6d0836d5999a6105eb06f999cc26bde9e94601280093451becf34c2daeb76598
+  metadata.gz: c924ff049f2b6153f1e7a98f7ff5eb35f68dfecd38079e99d84f535da56628eef67ae453a2b6255759d037f563249f02e4c442eae4a5196fdbf7ca2655f62e39
+  data.tar.gz: a0724d9b3ded29985d5e16958d38ba3cddc90f66d800a0c13e68581f455a338263987ab167e2a8010289786d9917585f1b1627c5657696e84cfd8b90e96f3d9b

data/CHANGELOG.md

@@ -1,5 +1,55 @@
 # Changelog
 
+## [v4.19.3](https://github.com/bensheldon/good_job/tree/v4.19.3) (2026-09-21)
+
+[Full Changelog](https://github.com/bensheldon/good_job/compare/v4.19.2...v4.19.3)
+
+**Implemented enhancements:**
+
+- Add GoodJob::Configuration\#valid? to validate Cron configuration [\#1796](https://github.com/bensheldon/good_job/pull/1796) ([bensheldon](https://github.com/bensheldon))
+- Add time range controls to dashboard time-series charts [\#1782](https://github.com/bensheldon/good_job/pull/1782) ([TikiTDO](https://github.com/TikiTDO))
+- Allow Continuation jobs to be paused [\#1778](https://github.com/bensheldon/good_job/pull/1778) ([bdewater-thatch](https://github.com/bdewater-thatch))
+
+**Fixed bugs:**
+
+- Use GoodJob::Job.table\_name instead of hardcoded `good_jobs` [\#1815](https://github.com/bensheldon/good_job/pull/1815) ([gap777](https://github.com/gap777))
+
+**Closed issues:**
+
+- Hardcoded table names interfere with applications using custom table names. [\#1814](https://github.com/bensheldon/good_job/issues/1814)
+
+**Merged pull requests:**
+
+- Fix alphabetization of demo schema.rb columns [\#1818](https://github.com/bensheldon/good_job/pull/1818) ([bensheldon](https://github.com/bensheldon))
+- Pin json \< 3 as a temporary workaround [\#1817](https://github.com/bensheldon/good_job/pull/1817) ([gap777](https://github.com/gap777))
+- Add Azerbaijani locale [\#1813](https://github.com/bensheldon/good_job/pull/1813) ([jamalkamaladdin](https://github.com/jamalkamaladdin))
+- Bump github/codeql-action from 4.37.3 to 4.37.9 [\#1809](https://github.com/bensheldon/good_job/pull/1809) ([dependabot[bot]](https://github.com/apps/dependabot))
+- Deprecate the fallback when `probe_handler` can't be used [\#1808](https://github.com/bensheldon/good_job/pull/1808) ([shouichi](https://github.com/shouichi))
+- Bump github/codeql-action from 4 to 4.37.3 [\#1802](https://github.com/bensheldon/good_job/pull/1802) ([dependabot[bot]](https://github.com/apps/dependabot))
+- Add index for discarded jobs with job\_class [\#1795](https://github.com/bensheldon/good_job/pull/1795) ([clinejj](https://github.com/clinejj))
+
+## [v4.19.2](https://github.com/bensheldon/good_job/tree/v4.19.2) (2026-07-20)
+
+[Full Changelog](https://github.com/bensheldon/good_job/compare/v4.19.1...v4.19.2)
+
+**Fixed bugs:**
+
+- Resolve connection pool at call time in the `adapter_class` shim [\#1798](https://github.com/bensheldon/good_job/pull/1798) ([DaisyOli](https://github.com/DaisyOli))
+- Add GoodJob::Batch.where\(id:\) for GlobalID::Locator.fetch [\#1792](https://github.com/bensheldon/good_job/pull/1792) ([bensheldon](https://github.com/bensheldon))
+- Preserve created\_at when a job is retried [\#1789](https://github.com/bensheldon/good_job/pull/1789) ([ollym](https://github.com/ollym))
+
+**Closed issues:**
+
+- Memoized `adapter_class` proxy captures the pre-fork connection pool, crashing the Notifier in forked Puma workers \(Rails \< 7.2 + `preload_app!`\) [\#1797](https://github.com/bensheldon/good_job/issues/1797)
+- created\_at is reset every time a job is retried [\#1788](https://github.com/bensheldon/good_job/issues/1788)
+
+**Merged pull requests:**
+
+- Fix JRuby CI failure installing `rbs` gem [\#1794](https://github.com/bensheldon/good_job/pull/1794) ([bensheldon](https://github.com/bensheldon))
+- Fix flaky scheduled\_at precision comparison in adapter\_spec [\#1793](https://github.com/bensheldon/good_job/pull/1793) ([bensheldon](https://github.com/bensheldon))
+- Remove inline\_execution\_respects\_schedule config [\#1791](https://github.com/bensheldon/good_job/pull/1791) ([bensheldon](https://github.com/bensheldon))
+- Bump actions/checkout from 6 to 7 [\#1787](https://github.com/bensheldon/good_job/pull/1787) ([dependabot[bot]](https://github.com/apps/dependabot))
+
 ## [v4.19.1](https://github.com/bensheldon/good_job/tree/v4.19.1) (2026-06-25)
 
 [Full Changelog](https://github.com/bensheldon/good_job/compare/v4.19.0...v4.19.1)
@@ -134,6 +184,10 @@
 
 [Full Changelog](https://github.com/bensheldon/good_job/compare/v4.16.0...v4.17.0)
 
+**Implemented enhancements:**
+
+- Introduce advisory lock key customization support methods [\#1722](https://github.com/bensheldon/good_job/pull/1722) ([amkisko](https://github.com/amkisko))
+
 **Merged pull requests:**
 
 - Convert UI JavaScript modules to Stimulus controllers [\#1743](https://github.com/bensheldon/good_job/pull/1743) ([bensheldon](https://github.com/bensheldon))
@@ -149,6 +203,11 @@
 - Allow filtering by label on dashboard [\#1739](https://github.com/bensheldon/good_job/pull/1739) ([bensheldon](https://github.com/bensheldon))
 - Allow multiple concurrency rules per job via labels [\#1700](https://github.com/bensheldon/good_job/pull/1700) ([bscofield](https://github.com/bscofield))
 
+**Fixed bugs:**
+
+- Fix advisory lock connection stickiness in block contexts [\#1736](https://github.com/bensheldon/good_job/pull/1736) ([bensheldon](https://github.com/bensheldon))
+- Add JRuby 10 to testing matrix [\#1559](https://github.com/bensheldon/good_job/pull/1559) ([bensheldon](https://github.com/bensheldon))
+
 **Closed issues:**
 
 - Job duration misreported if interrupted [\#1723](https://github.com/bensheldon/good_job/issues/1723)
@@ -158,6 +217,7 @@
 - Use annotated git tag in release script [\#1741](https://github.com/bensheldon/good_job/pull/1741) ([bensheldon](https://github.com/bensheldon))
 - Double single-thread scheduler integration test timeout on JRuby [\#1738](https://github.com/bensheldon/good_job/pull/1738) ([bensheldon](https://github.com/bensheldon))
 - Fix JRuby test flakes for scheduler timeout and interrupted execution duration [\#1737](https://github.com/bensheldon/good_job/pull/1737) ([bensheldon](https://github.com/bensheldon))
+- Count Advisory Locks and refactor advisory lock lifecycle [\#1735](https://github.com/bensheldon/good_job/pull/1735) ([bensheldon](https://github.com/bensheldon))
 - Show interrupted execution recovery duration in dashboard [\#1733](https://github.com/bensheldon/good_job/pull/1733) ([bensheldon](https://github.com/bensheldon))
 - chore: use `merge` to avoid mutate the query object [\#1717](https://github.com/bensheldon/good_job/pull/1717) ([luizkowalski](https://github.com/luizkowalski))
 
@@ -173,6 +233,7 @@
 
 **Merged pull requests:**
 
+- Fix JRuby in development lockfile, with test [\#1734](https://github.com/bensheldon/good_job/pull/1734) ([bensheldon](https://github.com/bensheldon))
 - Add herb to linter [\#1732](https://github.com/bensheldon/good_job/pull/1732) ([bensheldon](https://github.com/bensheldon))
 - Update development dependencies; apply Rubocop to\_h lints [\#1728](https://github.com/bensheldon/good_job/pull/1728) ([bensheldon](https://github.com/bensheldon))
 
@@ -234,6 +295,7 @@
 
 **Fixed bugs:**
 
+- Check for graceful shutdown inside job cleanup loops [\#1711](https://github.com/bensheldon/good_job/pull/1711) ([bdewater-thatch](https://github.com/bdewater-thatch))
 - Add title to Good Job Dashboard layout [\#1701](https://github.com/bensheldon/good_job/pull/1701) ([mockdeep](https://github.com/mockdeep))
 
 **Closed issues:**
@@ -329,6 +391,7 @@
 **Merged pull requests:**
 
 - Update sorbet/tapioca [\#1681](https://github.com/bensheldon/good_job/pull/1681) ([bensheldon](https://github.com/bensheldon))
+- Remove obsolete property from tests [\#1676](https://github.com/bensheldon/good_job/pull/1676) ([RDIL](https://github.com/RDIL))
 - Bump actions/checkout from 4 to 5 [\#1673](https://github.com/bensheldon/good_job/pull/1673) ([dependabot[bot]](https://github.com/apps/dependabot))
 
 ## [v4.11.2](https://github.com/bensheldon/good_job/tree/v4.11.2) (2025-08-06)
@@ -451,6 +514,10 @@
 
 [Full Changelog](https://github.com/bensheldon/good_job/compare/v4.9.0...v4.9.1)
 
+**Implemented enhancements:**
+
+- Order Dashboard jobs in more "natural" order [\#1604](https://github.com/bensheldon/good_job/pull/1604) ([francois](https://github.com/francois))
+
 **Fixed bugs:**
 
 - \[dashboard\] Scheduled tasks are shown "backwards" [\#1580](https://github.com/bensheldon/good_job/issues/1580)
@@ -1936,7 +2003,6 @@
 - In tests, directly use `connection.truncate_tables` instead of  `ActiveRecord::Tasks::DatabaseTasks.truncate_all` [\#918](https://github.com/bensheldon/good_job/pull/918) ([bensheldon](https://github.com/bensheldon))
 - Use `GoodJob.capsule` in CLI instead of creating a new Capsule [\#916](https://github.com/bensheldon/good_job/pull/916) ([bensheldon](https://github.com/bensheldon))
 - Fix lint: missing fr and nl translations; readme whitespace [\#914](https://github.com/bensheldon/good_job/pull/914) ([bensheldon](https://github.com/bensheldon))
-- Switches from Chrome to Chromium to support Apple M1/Arm CPUs [\#910](https://github.com/bensheldon/good_job/pull/910) ([ckdake](https://github.com/ckdake))
 - Bump erb\_lint from 0.3.1 to 0.4.0 [\#906](https://github.com/bensheldon/good_job/pull/906) ([dependabot[bot]](https://github.com/apps/dependabot))
 
 ## [v3.15.0](https://github.com/bensheldon/good_job/tree/v3.15.0) (2023-04-02)

data/README.md

@@ -315,7 +315,6 @@ Available configuration options are:
 - `cleanup_preserved_jobs_before_seconds_ago` (integer) number of seconds to preserve jobs when using the `$ good_job cleanup_preserved_jobs` CLI command or calling `GoodJob.cleanup_preserved_jobs`. Defaults to `1209600` (14 days). Can also be set with  the environment variable `GOOD_JOB_CLEANUP_PRESERVED_JOBS_BEFORE_SECONDS_AGO`.
 - `cleanup_interval_jobs` (integer) Number of jobs a Scheduler will execute before cleaning up preserved jobs. Defaults to `1000`. Disable with `false`. Can also be set with  the environment variable `GOOD_JOB_CLEANUP_INTERVAL_JOBS` and disabled with `0`).
 - `cleanup_interval_seconds` (integer) Number of seconds a Scheduler will wait before cleaning up preserved jobs. Defaults to `600` (10 minutes). Disable with `false`. Can also be set with  the environment variable `GOOD_JOB_CLEANUP_INTERVAL_SECONDS` and disabled with `0`).
-- `inline_execution_respects_schedule` (boolean) Opt-in to future behavior of inline execution respecting scheduled jobs. Defaults to `false`.
 - `logger` ([Rails Logger](https://api.rubyonrails.org/classes/ActiveSupport/Logger.html)) lets you set a custom logger for GoodJob. It should be an instance of a Rails `Logger` (Default: `Rails.logger`).
 - `preserve_job_records` (boolean, symbol, or lambda) keeps job records in your database even after jobs are completed. If set to `true`, all job records are preserved. If set to `:on_unhandled_error`, only jobs that finished with an unhandled error are preserved. If set to a lambda, the lambda will be called with the error_event (e.g., `:discarded`, `:retry_stopped`, or `:unhandled`) and should return a boolean indicating whether to preserve the job. (Default: `true`)
 - `advisory_lock_heartbeat` (boolean) whether to use an advisory lock for the purpose of determining whether an execeution process is active. (Default `true` in Development; `false` in other environments)
@@ -339,6 +338,9 @@ Available configuration options are:
     ```
 
 - `enable_pauses` (boolean) whether job processing can be paused. Defaults to `false`. You can also set this with the environment variable `GOOD_JOB_ENABLE_PAUSES`.
+- `dequeue_query_sort` (symbol) sets the sort order used when querying for the next job(s) to execute. Defaults to `:created_at`. It can be any one of:
+    - `:created_at` sorts by priority, then job creation order. This is the default, but no longer best matches GoodJob's contemporary data model.
+    - `:scheduled_at` sorts by priority, then `scheduled_at`, then `id`, which better matches GoodJob's contemporary data model. This will become the default/only behavior in a future major release.
 
 By default, GoodJob configures the following execution modes per environment:
 
@@ -1505,9 +1507,7 @@ It is also possible to manually trigger a cleanup of preserved job records:
 
 By default, GoodJob uses its inline adapter in the test environment; the inline adapter is designed for the test environment. When enqueuing a job with GoodJob's inline adapter, the job will be executed immediately on the current thread; unhandled exceptions will be raised.
 
-In GoodJob 2.0, the inline adapter will execute future scheduled jobs immediately. In the next major release, GoodJob 3.0, the inline adapter will not execute future scheduled jobs and instead enqueue them in the database.
-
-To opt into this behavior immediately set: `config.good_job.inline_execution_respects_schedule = true`
+The inline adapter respects scheduled jobs: jobs scheduled for the future are enqueued in the database rather than executed immediately.
 
 To perform jobs inline at any time, use `GoodJob.perform_inline`. For example, using time helpers within an integration test:
 
@@ -1716,7 +1716,7 @@ Note that GoodJob doesn't include WEBrick as a dependency, so you'll need to add
 gem 'webrick'
 ```
 
-If WEBrick is configured to be used, but the dependency is not found, GoodJob will log a warning and fallback to the default probe server.
+If WEBrick is configured to be used, but the dependency is not found, GoodJob will log a warning and fallback to the default probe server. This behavior is deprecated and will raise in the next release. An unsupported `probe_handler` value behaves the same way.
 
 ### Pausing Jobs
 

data/app/charts/good_job/performance_index_chart.rb

@@ -2,39 +2,64 @@
 
 module GoodJob
   class PerformanceIndexChart < BaseChart
+    def initialize(range = GoodJob::PerformanceRange.new)
+      super()
+      @range = range
+    end
+
     def data
-      table_name = GoodJob::Execution.table_name
+      binds = @range.time_series_binds
+      bucket_sql = @range.time_series_bucket_sql(
+        "scheduled_at",
+        start_expression: "range_parameters.series_start_time",
+        interval_expression: "range_parameters.interval_seconds"
+      )
+      inner_sql = @range.apply(GoodJob::Execution).select(:job_class, :scheduled_at, :duration).to_sql
 
+      # Keep each bind placeholder single-use because JDBC binds every converted occurrence.
       sum_query = <<~SQL.squish
-        SELECT *
-        FROM generate_series(
-          date_trunc('hour', $1::timestamp),
-          date_trunc('hour', $2::timestamp),
-          '1 hour'
-        ) timestamp
-        LEFT JOIN (
+        WITH range_parameters AS (
           SELECT
-              date_trunc('hour', scheduled_at) AS scheduled_at,
-              job_class,
-              SUM(duration) AS sum
-            FROM #{table_name} sources
-            GROUP BY date_trunc('hour', scheduled_at), job_class
-        ) sources ON sources.scheduled_at = timestamp
+            $1::timestamp AS series_start_time,
+            $2::timestamp AS series_end_time,
+            $3::bigint AS interval_seconds
+        ), timestamps AS (
+          SELECT generate_series(
+            series_start_time,
+            series_end_time,
+            interval_seconds * INTERVAL '1 second'
+          ) AS timestamp
+          FROM range_parameters
+        ), sources AS (
+          SELECT
+            #{bucket_sql} AS scheduled_at,
+            job_class,
+            SUM(duration) AS sum
+          FROM (#{inner_sql}) executions
+          CROSS JOIN range_parameters
+          GROUP BY #{bucket_sql}, job_class
+        )
+        SELECT *
+        FROM timestamps
+        LEFT JOIN sources ON sources.scheduled_at = timestamps.timestamp
         ORDER BY timestamp ASC
       SQL
 
-      executions_data = GoodJob::Job.connection_pool.with_connection { |conn| conn.exec_query(GoodJob::Job.pg_or_jdbc_query(sum_query), "GoodJob Performance Chart", start_end_binds) }
+      executions_data = GoodJob::Job.connection_pool.with_connection { |conn| conn.exec_query(GoodJob::Job.pg_or_jdbc_query(sum_query), "GoodJob Performance Chart", binds) }
 
       job_names = executions_data.reject { |d| d['sum'].nil? }.map { |d| d['job_class'] || BaseFilter::EMPTY }.uniq
-      labels = []
+      timestamp_values = []
+      timestamps = []
       jobs_data = executions_data.to_a.group_by { |d| d['timestamp'] }.each_with_object({}) do |(timestamp, values), hash|
-        labels << timestamp.in_time_zone.strftime('%H:%M')
+        timestamp_values << timestamp
+        timestamps << @range.canonical_timestamp(timestamp)
         job_names.each do |job_class|
           sum = values.find { |d| d['job_class'] == job_class }&.[]('sum')
           duration = sum ? ActiveSupport::Duration.parse(sum).to_f : 0
           (hash[job_class] ||= []) << duration
         end
       end
+      labels = @range.chart_timestamp_labels(timestamp_values)
 
       {
         type: "line",
@@ -66,6 +91,14 @@ module GoodJob
             },
           },
         },
+        goodJob: {
+          interval_seconds: @range.interval_seconds,
+          range_end: @range.canonical_timestamp(@range.end_time),
+          range_start: @range.canonical_timestamp(@range.start_time),
+          timestamp_label_style: @range.label_style,
+          time_series: true,
+          timestamps: timestamps,
+        },
       }
     end
   end

data/app/charts/good_job/performance_range.rb

@@ -0,0 +1,380 @@
+# frozen_string_literal: true
+
+module GoodJob
+  class PerformanceRange
+    PARAMETER_KEYS = %w[chart_range chart_start chart_end].freeze
+    TIME_ZONE_PARAMETER_KEY = "chart_time_zone"
+    INPUT_PARAMETER_KEYS = [*PARAMETER_KEYS, TIME_ZONE_PARAMETER_KEY].freeze
+    DEFAULT_KEY = "24h"
+    MAXIMUM_TIME_SERIES_COORDINATES = 30
+    MAXIMUM_TIME_ZONE_LENGTH = 255
+    # Restrict custom bounds to portable four-digit years in the timezone used by the page.
+    MINIMUM_YEAR = 1000
+    MAXIMUM_YEAR = 9999
+    MINIMUM_LOCAL_VALUE = "1000-01-01T00:00:00"
+    MAXIMUM_LOCAL_VALUE = "9999-12-31T23:59:59"
+    TIMESTAMP_PATTERN = /\A\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?(?:Z|[+-]\d{2}:\d{2})\z/
+    LOCAL_TIMESTAMP_PATTERN = /\A(\d{4})-(\d{2})-(\d{2})T(\d{2}):(\d{2})(?::(\d{2}))?\z/
+
+    OPTIONS = {
+      "1h" => {
+        label: "1h",
+        duration: 1.hour,
+        interval_seconds: 5.minutes.to_i,
+        label_format: "%H:%M",
+        label_style: "time",
+      },
+      "6h" => {
+        label: "6h",
+        duration: 6.hours,
+        interval_seconds: 15.minutes.to_i,
+        label_format: "%H:%M",
+        label_style: "time",
+      },
+      "24h" => {
+        label: "24h",
+        duration: 24.hours,
+        interval_seconds: 1.hour.to_i,
+        label_format: "%H:%M",
+        label_style: "time",
+      },
+      "7d" => {
+        label: "7d",
+        duration: 24.hours * 7,
+        interval_seconds: 6.hours.to_i,
+        label_format: "%b %-d %H:%M",
+        label_style: "date_time",
+      },
+    }.freeze
+
+    # All candidates become integer seconds. The 30-day and 365-day scales are fixed elapsed
+    # durations for readable long-range charts, not calendar month or year aggregation.
+    SEMANTIC_INTERVALS = [
+      *[1, 2, 5, 10, 15, 30].map(&:seconds),
+      *[1, 2, 5, 10, 15, 30].map(&:minutes),
+      *[1, 2, 3, 6, 12].map(&:hours),
+      *[1, 2, 3, 5, 7, 14].map(&:days),
+      *[1, 2, 3, 6].map { |multiple| multiple * 30.days },
+      *[1, 2, 5, 10, 20, 50, 100, 200, 500].map { |multiple| multiple * 365.days },
+    ].map(&:to_i).uniq.sort.freeze
+
+    attr_reader :end_time, :interval_seconds, :key, :label_format, :label_style, :start_time
+
+    def initialize(params = nil, query_string: nil, **parameter_keywords)
+      @params = params || parameter_keywords
+      @repeated_parameter_keys = repeated_parameter_keys(query_string)
+      @local_time_zone = local_time_zone
+      resolve
+    end
+
+    def apply(relation)
+      relation.where(scheduled_at: start_time...end_time)
+    end
+
+    def canonical_parameters?(query_parameters)
+      query_parameters.slice(*INPUT_PARAMETER_KEYS) == to_params
+    end
+
+    def chart_timestamp_label(timestamp)
+      timestamp.in_time_zone.strftime(label_format)
+    end
+
+    def chart_timestamp_labels(timestamps)
+      labels = timestamps.map { |timestamp| chart_timestamp_label(timestamp) }
+
+      labels.each_index.group_by { |index| labels[index] }.each_value do |indices|
+        next unless indices.many?
+
+        offsets = indices.map { |index| timestamps[index].in_time_zone.formatted_offset }
+        next unless offsets.uniq.many?
+
+        indices.zip(offsets).each do |index, offset|
+          labels[index] = "#{labels[index]} #{offset}"
+        end
+      end
+
+      labels
+    end
+
+    def canonical_timestamp(timestamp)
+      timestamp = timestamp.in_time_zone
+      # ISO 8601 cannot preserve the sub-minute historical offsets present in some IANA zones.
+      timestamp.utc_offset.remainder(60).zero? ? timestamp.iso8601 : timestamp.utc.iso8601
+    end
+
+    def custom?
+      key.nil?
+    end
+
+    def custom_params
+      {
+        "chart_start" => canonical_timestamp(start_time),
+        "chart_end" => canonical_timestamp(end_time),
+      }
+    end
+
+    def default?
+      to_params.empty?
+    end
+
+    def end_label
+      range_label(end_time)
+    end
+
+    def end_local_value
+      local_value(end_time)
+    end
+
+    def navigation_params
+      return to_params unless key
+
+      # A preset is a relative definition; navigation also carries this evaluated instance.
+      {
+        "chart_range" => key,
+        "chart_start" => canonical_timestamp(start_time),
+        "chart_end" => canonical_timestamp(end_time),
+      }
+    end
+
+    def options
+      OPTIONS.map { |option_key, option| { key: option_key, label: option.fetch(:label) } }
+    end
+
+    def reload_params
+      return to_params if custom? || default?
+
+      { "chart_range" => key }
+    end
+
+    def start_end_binds
+      [
+        query_attribute("start_time", start_time, ActiveRecord::Type::DateTime.new),
+        query_attribute("end_time", end_time, ActiveRecord::Type::DateTime.new),
+      ]
+    end
+
+    def start_label
+      range_label(start_time)
+    end
+
+    def start_local_value
+      local_value(start_time)
+    end
+
+    # Keep this order in sync with the $1/$2/$3 placeholders in PerformanceIndexChart.
+    def time_series_binds
+      [
+        query_attribute("series_start_time", series_start_time, ActiveRecord::Type::DateTime.new),
+        query_attribute("series_end_time", series_end_time, ActiveRecord::Type::DateTime.new),
+        query_attribute("interval_seconds", interval_seconds, ActiveRecord::Type::Integer.new(limit: 8)),
+      ]
+    end
+
+    def time_series_bucket_sql(column_name, start_expression:, interval_expression:)
+      column_sql = GoodJob::Job.adapter_class.quote_column_name(column_name)
+
+      <<~SQL.squish
+        #{start_expression} +
+        FLOOR(EXTRACT(EPOCH FROM (#{column_sql} - #{start_expression})) / #{interval_expression}) *
+        #{interval_expression} * INTERVAL '1 second'
+      SQL
+    end
+
+    def time_series_coordinate_count
+      coordinate_count(interval_seconds)
+    end
+
+    def to_params
+      @canonical_params.dup
+    end
+
+    private
+
+    def align_time(time, interval = interval_seconds)
+      # JRuby can misreport rational epochs for extreme years even when integer seconds are correct.
+      (time - (time.to_i % interval) - time.subsec).utc
+    end
+
+    def aligned_epoch_seconds(time, interval)
+      time.to_i.div(interval) * interval
+    end
+
+    def coordinate_count(interval)
+      first_coordinate = aligned_epoch_seconds(start_time, interval)
+      last_coordinate = aligned_epoch_seconds(end_time - Rational(1, 1_000_000), interval)
+
+      ((last_coordinate - first_coordinate) / interval) + 1
+    end
+
+    def custom_times
+      parsed_start = parse_time("chart_start", @params[:chart_start])
+      parsed_end = parse_time("chart_end", @params[:chart_end])
+      return unless parsed_start && parsed_end && parsed_start < parsed_end
+
+      [parsed_start, parsed_end]
+    end
+
+    def custom_interval_seconds
+      # Fall back to the coarsest interval rather than raising: MINIMUM_YEAR/MAXIMUM_YEAR bound the
+      # widest possible range today, but nothing enforces that bound against SEMANTIC_INTERVALS.last.
+      SEMANTIC_INTERVALS.find do |interval|
+        coordinate_count(interval) <= MAXIMUM_TIME_SERIES_COORDINATES
+      end || SEMANTIC_INTERVALS.last
+    end
+
+    def custom_label_options
+      elapsed_seconds = end_time - start_time
+
+      if elapsed_seconds >= 365.days
+        { label_format: "%b %-d, %Y %H:%M", label_style: "date_time_year" }
+      elsif elapsed_seconds >= 24.hours
+        { label_format: "%b %-d %H:%M", label_style: "date_time" }
+      elsif interval_seconds < 1.minute
+        { label_format: "%H:%M:%S", label_style: "time_seconds" }
+      else
+        { label_format: "%H:%M", label_style: "time" }
+      end
+    end
+
+    def parse_time(parameter_key, value)
+      return if @repeated_parameter_keys.include?(parameter_key)
+      return unless value.is_a?(String)
+
+      timestamp = if TIMESTAMP_PATTERN.match?(value)
+                    Time.iso8601(value)
+                  elsif (local_match = LOCAL_TIMESTAMP_PATTERN.match(value))
+                    parse_local_time(parameter_key, local_match)
+                  end
+      return unless timestamp
+      return unless timestamp.to_f.finite?
+
+      timestamp = timestamp.in_time_zone.change(usec: 0)
+      return unless timestamp.year.between?(MINIMUM_YEAR, MAXIMUM_YEAR)
+
+      timestamp
+    rescue ArgumentError, RangeError
+      nil
+    end
+
+    def repeated_parameter_keys(query_string)
+      return [] if query_string.blank?
+
+      keys = URI.decode_www_form(query_string).filter_map do |key, _value|
+        key if INPUT_PARAMETER_KEYS.include?(key)
+      end
+      keys.tally.select { |_key, count| count > 1 }.keys
+    rescue ArgumentError
+      INPUT_PARAMETER_KEYS
+    end
+
+    def query_attribute(name, value, type)
+      ActiveRecord::Relation::QueryAttribute.new(name, value, type)
+    end
+
+    def local_value(time)
+      time.in_time_zone.strftime("%Y-%m-%dT%H:%M:%S")
+    end
+
+    def parse_local_time(parameter_key, match)
+      return unless @local_time_zone
+
+      components = match.captures
+      components[-1] ||= "0"
+      numeric_components = components.map { |component| Integer(component, 10) }
+      local_time = Time.utc(*numeric_components)
+      normalized_value = format("%04d-%02d-%02dT%02d:%02d:%02d", *numeric_components)
+      return unless local_time.strftime("%Y-%m-%dT%H:%M:%S") == normalized_value
+
+      periods = @local_time_zone.tzinfo.periods_for_local(local_time)
+      return if periods.empty?
+
+      # A local input cannot carry an offset. Include both repeated fall-back occurrences
+      # by resolving starts to the earlier instant and ends to the later instant.
+      instants = periods.map do |period|
+        (local_time - period.utc_total_offset).in_time_zone
+      end
+      parameter_key == "chart_end" ? instants.max : instants.min
+    end
+
+    def local_time_zone
+      return if @repeated_parameter_keys.include?(TIME_ZONE_PARAMETER_KEY)
+
+      value = @params[TIME_ZONE_PARAMETER_KEY] || @params[TIME_ZONE_PARAMETER_KEY.to_sym]
+      return Time.zone if value.nil?
+      return unless value.is_a?(String) && value.bytesize <= MAXIMUM_TIME_ZONE_LENGTH
+      return unless /\A[A-Za-z0-9._+-]+(?:\/[A-Za-z0-9._+-]+)*\z/.match?(value)
+
+      tzinfo = TZInfo::Timezone.get(value)
+      ActiveSupport::TimeZone.create(value, nil, tzinfo)
+    rescue TZInfo::InvalidTimezoneIdentifier
+      nil
+    end
+
+    def range_label(time)
+      local_time = time.in_time_zone
+      format = label_style == "date_time_year" ? "%b %-d, %Y %H:%M:%S" : "%b %-d, %H:%M:%S"
+      label = local_time.strftime(format)
+
+      backward_clock_transition? ? "#{label} #{local_time.formatted_offset}" : label
+    end
+
+    # Intentionally checks Time.zone (the server-rendered zone), not @local_time_zone: this backs
+    # the initial server-rendered label, before any browser-zone enhancement. The client mirrors
+    # this same concept for its own currently-displayed zone in
+    # performance_range_controller.js#crossesBackwardClockTransition — keep both in sync in spirit
+    # (elapsed exact time vs. elapsed civil time) but each must use its own zone, not the other's.
+    def backward_clock_transition?
+      @_backward_clock_transition ||= end_time.in_time_zone.utc_offset < start_time.in_time_zone.utc_offset
+    end
+
+    def resolve
+      range_key = preset_key
+
+      if (times = custom_times)
+        @start_time, @end_time = times
+
+        # Do not attach a preset identity to tampered bounds with a different elapsed duration.
+        if range_key && end_time - start_time == OPTIONS.fetch(range_key).fetch(:duration)
+          @key = range_key
+          @canonical_params = navigation_params
+          options = OPTIONS.fetch(key)
+        else
+          @key = nil
+          @canonical_params = custom_params
+          @interval_seconds = custom_interval_seconds
+          options = custom_label_options
+        end
+      else
+        @key = range_key || DEFAULT_KEY
+        options = OPTIONS.fetch(key)
+        @end_time = current_end_time
+        @start_time = end_time - options.fetch(:duration)
+        @canonical_params = range_key ? { "chart_range" => key } : {}
+      end
+
+      @interval_seconds ||= options.fetch(:interval_seconds)
+      @label_format = options.fetch(:label_format)
+      @label_style = options.fetch(:label_style)
+    end
+
+    def preset_key
+      return if @repeated_parameter_keys.include?("chart_range")
+
+      value = @params[:chart_range]
+      value if value.is_a?(String) && OPTIONS.key?(value)
+    end
+
+    def series_end_time
+      align_time(end_time - Rational(1, 1_000_000))
+    end
+
+    def series_start_time
+      align_time(start_time)
+    end
+
+    def current_end_time
+      current_time = Time.current
+      current_time.usec.zero? ? current_time : current_time.ceil
+    end
+  end
+end