dash 4.1.3 → 4.2.0

data/lib/dash/configuration/docs/configuration.yml

@@ -136,8 +136,8 @@ allow_empty_roles: false
 
 # Retain containers
 #
-# How many old containers we retain per role, and how many images we retain,
-# defaults to 5:
+# How many old containers we retain per role (per replica slot, for a role with
+# `replicas`), and how many images we retain, defaults to 5:
 retain_containers: 3
 
 # Minimum version
@@ -205,6 +205,12 @@ accessories:
 proxy:
   ...
 
+# Autoscale
+#
+# The provider that holds the pool members of scaled roles, see dash docs autoscale:
+autoscale:
+  ...
+
 # SSHKit
 #
 # See dash docs sshkit:

data/lib/dash/configuration/docs/proxy.yml

@@ -837,7 +837,7 @@ proxy:
                                    # below already embeds its ghcr.io host
     repository: ghcr.io/zoolutions/dash-proxy # Container repository for the
                                    # dash-proxy image (this is the default)
-    version: v1.1.0.3              # Version tag of the dash-proxy image to use.
+    version: v1.1.0.4              # Version tag of the dash-proxy image to use.
                                    # Defaults to the minimum version this gem
                                    # requires - only pin it to roll forward early,
                                    # never below the default

data/lib/dash/configuration/docs/role.yml

@@ -66,6 +66,209 @@ servers:
       limit: 25%
       wait: 10
 
+    # Replicas
+    #
+    # How many containers of this role run on EACH of its hosts. A process that cannot
+    # use more than one core by itself — open-source Sidekiq is one Ruby process — gets
+    # the rest of a bigger host this way, without declaring the same worker twice.
+    #
+    # `replicas: 2` is shorthand for `{ min: 2, max: 2 }`; the default is one, which is
+    # the behaviour without the key. A deploy boots as many replicas as are running now,
+    # kept within `min` and `max`, so a count changed at runtime with
+    # `dash scale set <role> <count>` survives the next deploy. With nothing running it
+    # boots `min`. `max` is the ceiling for `dash scale set`.
+    #
+    # Replicas of a proxied role are all targets of the role's one dash-proxy service,
+    # which balances across them. Replicas of any other role are independent containers.
+    # Replica 1 keeps the container name the role always had; replica 2 and up put the
+    # slot into the role segment (`app-workers.2-<version>`), and every replica of a
+    # scalable role gets the `replica` label and the `DASH_REPLICA` env var.
+    #
+    # Every replica opens its own database pool, so `pool × replicas × hosts` has to fit
+    # the database's (or the pooler's) connection limit.
+    #
+    # More than one replica cannot set the `publish`, `p`, `name` or `hostname` docker
+    # options, which every replica on a host would claim, and cannot yet be combined with
+    # `proxy/sleep`. Host volumes are shared by every replica on a host, which is fine for
+    # read-only config or a shared cache and wrong for a per-process store, so they warn.
+    replicas:
+      min: 1
+      max: 4
+
+    # Drain
+    #
+    # How a replica of a role WITHOUT the proxy leaves when `dash scale set` removes it:
+    # `signal` is sent first (e.g. TSTP, so Sidekiq stops taking new jobs), then dash
+    # waits `wait` seconds before `docker stop`. A role with a `sidekiq` scale signal stops
+    # waiting as soon as Sidekiq reports the leaving containers' processes quiet with
+    # nothing busy (it reports both every few seconds), so `wait` is then the most it waits. Keep `wait` inside the stop budget described on the worker
+    # roles page. A role behind dash-proxy has no drain: the proxy drains it, so setting one
+    # there is an error.
+    drain:
+      signal: TSTP
+      wait: 20
+
+    # Scale
+    #
+    # Extra hosts a role can run on beyond the ones listed under `hosts`, which stay the
+    # baseline: always on, deployed as before, never stopped by dash. The extra hosts are
+    # pool members that live in the cloud provider named under the root `autoscale:` key
+    # (see dash docs autoscale), not in this file. dash finds them by their labels —
+    # `dash.service=<service>`, `dash.destination=<destination, or -  without one>` and
+    # `dash.role=<role>` — and every member that is `started` is a host of the role for
+    # every command; stopped members are never touched. A provider that cannot be reached
+    # fails the command. `--hosts` then names the member hosts to act on, with a warning —
+    # for one scaled role at a time (pick it with `--roles` when there are more).
+    #
+    # `min` and `max` count HOSTS, the baseline included, so `min` is at least the number of
+    # `hosts`; `replicas` counts containers per host. `dash scale set <role> <count>` counts
+    # containers across all of them.
+    #
+    # A scaled role behind dash-proxy needs the load balancer, which turns on by itself for
+    # it even with one baseline host; `proxy/loadbalancer: false` is an error for it.
+    #
+    # `schedule`, `signal`, `warmup`, `cooldown` and `step` drive the autoscaling controller
+    # (`dash autoscale run`), which then owns the role's count: a manual `dash scale set`
+    # lasts until its next tick unless the role is paused (`dash autoscale pause ROLE`). A
+    # scaled role with neither a `schedule` nor a `signal` stays manual.
+    scale:
+      min: 2
+      max: 4
+
+      # How extra hosts come to exist. `power` (the default) powers stopped members on and
+      # off again; they are created beforehand, with Terraform for example, carrying the
+      # three labels. `create` creates a member from `template` when one is needed and
+      # destroys it when it leaves. On UpCloud a stopped server's compute is free only on
+      # Cloud Native plans; any other plan bills a powered-off member as if it ran.
+      members: power
+
+      # What a `create` member is built from (UpCloud): the template storage to clone, the
+      # plan and zone, the user dash connects as with its SSH keys, the private network
+      # (SDN) to attach — required when `address` is private — and cloud-init user data,
+      # for a Tailscale join for example. Only `create` uses it, and `create` requires it.
+      template:
+        storage: 01234567-89ab-cdef-0123-456789abcdef
+        plan: CLOUDNATIVE-8xCPU-16GB
+        zone: de-fra1
+        login_user: deploy
+        ssh_keys:
+          - "ssh-ed25519 AAAA... deploy"
+        network: 03abcdef-0123-4567-89ab-cdef01234567
+        user_data: |
+          #!/bin/sh
+          tailscale up --authkey ...
+
+      # Which of a member's addresses dash connects to: private (the default), public or
+      # utility.
+      address: private
+
+      # Seconds from powering a member on (or creating it) until it answers SSH, default 300.
+      # The controller also replaces a started member that has not answered SSH for this
+      # long: out of the load balancer, powered off (deleted for `create`), and the next
+      # tick restores the count with a healthy one.
+      boot_timeout: 300
+
+      # Windows of guaranteed capacity, in containers (the unit of `dash scale set`). From
+      # every minute `cron` matches, for `for` (seconds, or a number with s, m, h or d, at
+      # most 7d), the controller keeps at least `min` containers running; overlapping
+      # windows take the largest `min`. Outside every window it returns to scale min ×
+      # replicas min. The target never goes above scale max × replicas max.
+      #
+      # `cron` has five fields - minute, hour, day-of-month, month, day-of-week - each `*`,
+      # a number, a range `a-b`, a list `a,b` or a step `*/n` or `a-b/n`; day-of-week 0 and
+      # 7 are Sunday. When both day fields are set, a day matches if either does. There
+      # are no names, `L`, `W` or `#`. It is evaluated in `autoscale/timezone`.
+      #
+      # "The evening before the 1st and the 15th" has no exact cron: this example starts on
+      # the 14th and on each of the 28th to 31st (so on several evenings at a month end).
+      # When a few hours of lead are not needed, start on the day itself: `0 0 1,15 * *`.
+      schedule:
+        - cron: "0 22 14,28-31 * *"
+          for: 30h
+          min: 10
+
+      # Seconds a member that just joined counts as warming up: the controller never scales
+      # in while one is, nor replaces it for not answering SSH. Default: `boot_timeout`.
+      warmup: 300
+
+      # Seconds between the controller's actions. A scale-in step waits `down` (default
+      # 600) after the last scale-out or scale-in. A signal-driven scale-out waits `up`
+      # (default 60) after the last one. A schedule floor scales out at once, whatever the
+      # cooldown.
+      cooldown:
+        up: 60
+        down: 600
+
+      # Containers added or removed per signal-driven step, and removed per scale-in step
+      # back to a floor; default `replicas/max` (one host's worth). A step lands on a count
+      # the hosts can split. Scale-out to a schedule floor goes straight to it.
+      step: 3
+
+      # The reactive rules: the controller reads `signal` every tick and holds it inside a
+      # band. Above `up/above` for `up/for` it scales out by `step`, at most once per
+      # `cooldown/up`, up to scale max × replicas max. Below `down/below` for `down/for` it
+      # scales in by `step`, at most once per `cooldown/down`, never below the floor (scale
+      # min × replicas min, raised by schedule windows) and never while a member warms up.
+      # Inside the band it holds. A sample it cannot read holds the role (`missing_data`),
+      # and starts both windows over; a floor still applies.
+      #
+      # `source` is one of:
+      #
+      # - `sidekiq`: the age in seconds of the oldest job across `queues`, read from Redis
+      #   (`autoscale/redis`). Sidekiq 7's float seconds and Sidekiq 8's integer
+      #   milliseconds are both read. Draining a Sidekiq container on scale-in ends as soon
+      #   as Sidekiq reports it quiet with nothing busy, instead of always waiting
+      #   `drain/wait`.
+      # - `pgbus`: the age in seconds of the oldest claimable message across `queues`,
+      #   read from Postgres (`autoscale/postgres`): the pgmq table `pgmq.q_<prefix><queue>`,
+      #   `prefix` defaulting to `pgbus_`. Scheduled messages do not count. pgbus has no
+      #   quiet mode, so leave `drain/signal` unset and give the role a stop timeout of at
+      #   least pgbus's `drain_timeout`.
+      # - `prometheus`: the value of one PromQL `query` (`autoscale/prometheus`), the
+      #   largest when it returns several series. An empty result is a missing sample.
+      #
+      # A role with a `schedule` and no `signal` keeps returning to its floor a step at a time.
+      #
+      # Tuning: record a busy day with `dash autoscale run --record FILE`, then try a band,
+      # a step or a cooldown with `dash autoscale simulate --samples FILE` before deploying
+      # it. Judoscale's worker defaults make a sound start: a queue-latency band of 1-5
+      # seconds, up after one breach, down after 10 minutes. In an app whose roles share a
+      # database, give every signalled role a `hold_when` guard on it. `dash autoscale signal
+      # ROLE` reads the signal and guards live, as the controller does. Simulation replays
+      # what the queue did with the containers that really ran, not the simulated ones; it
+      # starts its cooldowns at the tick that acted, where live they start once the scale
+      # finishes, and its breach windows empty - so it is a guide, not a forecast.
+      signal:
+        source: sidekiq
+        queues:
+          - default
+          - billing
+
+      # Scale out above this, after this long above it (seconds, or a number with s, m, h
+      # or d, at most 1d). `for` defaults to 0: the first sample above.
+      up:
+        above: 10
+        for: 30s
+
+      # Scale in below this, after this long below it (default 10m). `up/above` must be
+      # greater than `down/below`.
+      down:
+        below: 2
+        for: 10m
+
+      # Saturation guards: while any query reads above its `above` - or cannot be read -
+      # a signal-driven scale-out holds (`held_by_guard`), since more containers would only
+      # queue on what is already full. `source` is `prometheus` (a PromQL query) or
+      # `postgres` (SQL, run read-only with a 5 second timeout; the first column of the
+      # first row). Guards never hold a schedule floor: a window is capacity asked for.
+      hold_when:
+        - source: prometheus
+          query: max(pgbouncer_pools_client_waiting_connections)
+          above: 0
+        - source: postgres
+          query: SELECT count(*) FROM pg_stat_activity
+          above: 180
+
     # Option values are shell-escaped before reaching `docker run`, but `${...}` is
     # deliberately left for the deploy host's shell to expand. Role `env` is never
     # defined in that shell, so `${MY_VAR}` resolves to empty. Use the bare `$MY_VAR`

data/lib/dash/configuration/loadbalancer.rb

@@ -26,8 +26,9 @@ class Dash::Configuration::Loadbalancer < Dash::Configuration::Proxy
   # The hosts the load balancer forwards to: every host of every role that
   # runs a proxy. One source of truth for the deploy step and the reboot
   # re-registration, so their target lists cannot diverge.
+  # Once each: a host two proxied roles share is one target.
   def target_hosts
-    config.roles.select(&:running_proxy?).flat_map(&:hosts)
+    config.roles.select(&:running_proxy?).flat_map(&:hosts).uniq
   end
 
   def directory
@@ -95,7 +96,7 @@ class Dash::Configuration::Loadbalancer < Dash::Configuration::Proxy
 
   # When loadbalancer is on a proxy host, it takes over the proxy role
   def on_proxy_host?
-    config.proxy_hosts.include?(config.proxy.effective_loadbalancer)
+    config.baseline_proxy_hosts.include?(config.proxy.effective_loadbalancer)
   end
 
   private

data/lib/dash/configuration/proxy/run.rb

@@ -1,5 +1,5 @@
 class Dash::Configuration::Proxy::Run
-  MINIMUM_VERSION = "v1.1.0.3"
+  MINIMUM_VERSION = "v1.1.0.4"
   DEFAULT_HTTP_PORT = 80
   DEFAULT_HTTPS_PORT = 443
   DEFAULT_LOG_MAX_SIZE = "10m"

data/lib/dash/configuration/proxy.rb

@@ -251,7 +251,7 @@ class Dash::Configuration::Proxy
   end
 
   def loadbalancer_on_proxy_host?
-    load_balancing? && config.proxy_hosts.include?(effective_loadbalancer)
+    load_balancing? && config.baseline_proxy_hosts.include?(effective_loadbalancer)
   end
 
   def custom_ssl_certificate?
@@ -391,8 +391,11 @@ class Dash::Configuration::Proxy
       .merge(target_options).compact
   end
 
-  def deploy_command_args(target:)
-    optionize ({ target: "#{target}:#{app_port}" }).merge(deploy_options), with: "="
+  # dash-proxy takes a comma-separated target list, waits until every target is healthy,
+  # then swaps the whole pool and drains the one it replaced - which is how all replicas
+  # of a role on a host go live together.
+  def deploy_command_args(targets:)
+    optionize ({ target: target_list(targets) }).merge(deploy_options), with: "="
   end
 
   # dash-proxy rollout deploy only accepts the target and the timeouts - the service already
@@ -404,8 +407,8 @@ class Dash::Configuration::Proxy
     }.compact
   end
 
-  def rollout_deploy_command_args(target:)
-    optionize ({ target: "#{target}:#{app_port}" }).merge(rollout_deploy_options), with: "="
+  def rollout_deploy_command_args(targets:)
+    optionize ({ target: target_list(targets) }).merge(rollout_deploy_options), with: "="
   end
 
   def rollout_set_command_args(percent: nil, list: nil)
@@ -428,6 +431,10 @@ class Dash::Configuration::Proxy
   end
 
   private
+    def target_list(targets)
+      Array(targets).map { |target| "#{target}:#{app_port}" }.join(",")
+    end
+
     # Which dispositions this layer keeps. The per-app proxy behind a load
     # balancer sheds the edge concerns; without load balancing there is no
     # other layer to defer to. Dash::Configuration::Loadbalancer overrides
@@ -436,8 +443,9 @@ class Dash::Configuration::Proxy
       load_balancing? ? %i[ per_app both ] : %i[ edge per_app both ]
     end
 
+    # A baseline host: the load balancer must not move with the pool.
     def primary_role_first_host
-      config.primary_role&.hosts&.first
+      config.primary_role&.baseline_hosts&.first
     end
 
     # Auto-activation needs a role the load balancer can actually front. The
@@ -445,10 +453,14 @@ class Dash::Configuration::Proxy
     # Dash::Cli::Proxy#loadbalancer), so a proxy-less primary role would boot a
     # load balancer with an empty --target. An explicit `loadbalancer:` setting
     # skips this check — the operator asked for it.
+    #
+    # A scaled proxied role turns it on too, even with one baseline host: its members can
+    # only reach traffic through the load balancer's target list.
     def auto_load_balanced_primary_role?
       primary_role = config.primary_role
+      return false unless primary_role.present?
 
-      primary_role.present? && primary_role.running_proxy? && Array(primary_role.hosts).size > 1
+      (primary_role.running_proxy? && primary_role.baseline_hosts.size > 1) || config.scaled_roles.any?(&:running_proxy?)
     end
 
     # Flags for dash-proxy's dynamic domain source (runtime TLS hostnames).

data/lib/dash/configuration/role/drain.rb

@@ -0,0 +1,49 @@
+# How a container of a role without the proxy leaves when it is scaled in: an optional
+# signal (e.g. TSTP, so Sidekiq stops fetching), then a wait, then `docker stop`. A
+# proxied role has none - dash-proxy drains it.
+class Dash::Configuration::Role::Drain
+  # The Linux signal names `docker kill --signal` accepts, without the SIG prefix.
+  SIGNALS = %w[
+    HUP INT QUIT ILL TRAP ABRT IOT BUS FPE KILL USR1 SEGV USR2 PIPE ALRM TERM STKFLT CHLD CONT
+    STOP TSTP TTIN TTOU URG XCPU XFSZ VTALRM PROF WINCH IO POLL PWR SYS
+  ]
+
+  # Linux signal numbers, SIGHUP through SIGRTMAX.
+  SIGNAL_NUMBERS = 1..64
+
+  attr_reader :context
+
+  def initialize(drain_config:, context:)
+    @drain_config = drain_config || {}
+    @context = context
+    validate!
+  end
+
+  def signal
+    @drain_config["signal"]&.to_s
+  end
+
+  def wait
+    @drain_config.fetch("wait", 0)
+  end
+
+  def configured?
+    @drain_config.present?
+  end
+
+  private
+    def validate!
+      raise Dash::ConfigurationError, "#{context}/wait: must be 0 or more seconds" if wait.negative?
+      return if signal.nil? || valid_signal?
+
+      raise Dash::ConfigurationError, "#{context}/signal: #{signal} is not a signal docker can send"
+    end
+
+    def valid_signal?
+      if signal.match?(/\A\d+\z/)
+        SIGNAL_NUMBERS.cover?(signal.to_i)
+      else
+        SIGNALS.include?(signal.upcase.delete_prefix("SIG"))
+      end
+    end
+end

data/lib/dash/configuration/role/replicas.rb

@@ -0,0 +1,72 @@
+# How many containers of one role run on each of its hosts. The bounds come from
+# deploy.yml; the count in between is never stored - it is whatever is running, which
+# `dash scale set` changes and a deploy reads back (see Dash::Cli::App::Boot).
+class Dash::Configuration::Role::Replicas
+  # Docker options every replica on a host would claim for itself.
+  EXCLUSIVE_OPTIONS = %w[ publish p name hostname ]
+  VOLUME_OPTIONS = %w[ volume v mount volumes-from ]
+
+  attr_reader :min, :max, :context
+
+  def initialize(replicas_config:, context:)
+    @context = context
+
+    case replicas_config
+    when nil then @min = @max = 1
+    when Integer then @min = @max = replicas_config
+    else
+      @min = replicas_config.fetch("min", 1)
+      @max = replicas_config.fetch("max", [ @min, 1 ].max)
+    end
+
+    validate!
+  end
+
+  def scalable?
+    max > 1
+  end
+
+  def numbers
+    (1..max).to_a
+  end
+
+  # A deploy boots the running count, kept within the bounds: a crash cannot shrink the
+  # role below min, and a lowered max takes effect.
+  def clamp(running)
+    running.clamp(min, max)
+  end
+
+  def to_s
+    min == max ? "× #{max} #{"replica".pluralize(max)}" : "× #{min}–#{max} replicas"
+  end
+
+  # Checks that need the rest of the role (its docker options, its proxy), which is only
+  # complete once Dash::Configuration has finished building - see
+  # Dash::Configuration#ensure_replicas_fit_their_roles.
+  def ensure_fits!(role, volumes:)
+    return unless scalable?
+
+    if (option = role.docker_option_keys.find { |key| EXCLUSIVE_OPTIONS.include?(key) })
+      error "max > 1 cannot be combined with options/#{option}, every replica on a host would claim it"
+    end
+
+    if role.running_proxy? && role.proxy.proxy_config.dig("sleep", "after").present?
+      error "max > 1 cannot be combined with proxy/sleep until dash-proxy is proven to sleep and wake every replica together"
+    end
+
+    shared = volumes + role.docker_option_values(*VOLUME_OPTIONS)
+    shared.each do |volume|
+      warn "#{context}: every replica on a host shares the volume #{volume} - fine for read-only config or a shared cache, wrong for a per-process store"
+    end
+  end
+
+  private
+    def validate!
+      error "min must be at least 1" unless min >= 1
+      error "min (#{min}) cannot be greater than max (#{max})" if min > max
+    end
+
+    def error(message)
+      raise Dash::ConfigurationError, "#{context}: #{message}"
+    end
+end

data/lib/dash/configuration/role/scale/guard.rb

@@ -0,0 +1,40 @@
+# One `scale.hold_when` entry: a saturation guard. While its query reads above `above` (or
+# cannot be read), the controller holds a signal-driven scale-out - more containers would
+# only queue on the database. A schedule floor still applies. See Dash::Autoscale::Guard.
+class Dash::Configuration::Role::Scale::Guard
+  SOURCES = %w[ prometheus postgres ]
+  KEYS = %w[ source query above ]
+
+  attr_reader :source, :query, :above
+
+  def initialize(guard_config:, context:)
+    @context = context
+    error nil, "should be a hash" unless guard_config.is_a?(Hash)
+    if (unknown = (guard_config.keys.map(&:to_s) - KEYS).first)
+      error nil, "unknown key: #{unknown}"
+    end
+
+    @source = guard_config["source"].to_s
+    @query = guard_config["query"]
+    @above = guard_config["above"]
+
+    error "source", "must be #{SOURCES.join(" or ")}, not #{source}" unless SOURCES.include?(source)
+    error "query", "is required" unless query.is_a?(String) && query.present?
+    error "above", "is required" if above.nil?
+    error "above", "should be a finite number" unless above.is_a?(Numeric) && above.real? && above.finite?
+  end
+
+  # The autoscale/<connection> block the guard reads through.
+  def connection
+    source
+  end
+
+  def to_h
+    { source: source, query: query, above: above }
+  end
+
+  private
+    def error(key, message)
+      raise Dash::ConfigurationError, "#{[ @context, key ].compact.join("/")}: #{message}"
+    end
+end

data/lib/dash/configuration/role/scale/signal.rb

@@ -0,0 +1,93 @@
+# The `scale.signal` entry: the one number the controller scales a role on. `sidekiq` and
+# `pgbus` are the age in seconds of the oldest job waiting across `queues`; `prometheus` is
+# whatever its `query` returns (the largest value of a vector). See Dash::Autoscale::Signal.
+class Dash::Configuration::Role::Scale::Signal
+  SOURCES = %w[ sidekiq pgbus prometheus ]
+  KEYS = %w[ source queues prefix query ]
+  NAME = /\A[A-Za-z0-9_.:-]+\z/
+  DEFAULT_PGBUS_PREFIX = "pgbus_"
+
+  # The autoscale/<connection> block each source reads through.
+  CONNECTIONS = { "sidekiq" => "redis", "pgbus" => "postgres", "prometheus" => "prometheus" }.freeze
+
+  attr_reader :source, :queues, :prefix, :query
+
+  def initialize(signal_config:, context:)
+    @context = context
+    error nil, "should be a hash" unless signal_config.is_a?(Hash)
+    if (unknown = (signal_config.keys.map(&:to_s) - KEYS).first)
+      error nil, "unknown key: #{unknown}"
+    end
+
+    @source = signal_config["source"].to_s
+    validate_source!
+    @queues = parse_queues(signal_config["queues"])
+    @prefix = parse_prefix(signal_config["prefix"])
+    @query = parse_query(signal_config["query"])
+  end
+
+  def queues?
+    source != "prometheus"
+  end
+
+  def connection
+    CONNECTIONS.fetch(source)
+  end
+
+  def to_h
+    { source: source, queues: queues, prefix: prefix, query: query }.compact
+  end
+
+  private
+    def validate_source!
+      if source == "proxy"
+        error "source", "proxy (web queue time) comes with Phase 4 (zoolutions/dash#180), use #{SOURCES.to_sentence(last_word_connector: " or ")}"
+      end
+      error "source", "must be #{SOURCES.to_sentence(last_word_connector: " or ")}, not #{source}" unless SOURCES.include?(source)
+    end
+
+    def parse_queues(queues)
+      unless queues?
+        error "queues", "is only used with sidekiq and pgbus" unless queues.nil?
+        return
+      end
+
+      error "queues", "is required for #{source}" if queues.nil? || queues == []
+      error "queues", "should be an array" unless queues.is_a?(Array)
+      queues.each_with_index { |queue, index| error "queues/#{index}", "#{queue.inspect} #{name_rule}" unless name?(queue) }
+      queues
+    end
+
+    def parse_prefix(prefix)
+      unless source == "pgbus"
+        error "prefix", "is only used with pgbus" unless prefix.nil?
+        return
+      end
+
+      return DEFAULT_PGBUS_PREFIX if prefix.nil?
+      error "prefix", "#{prefix.inspect} #{name_rule}" unless name?(prefix)
+      prefix
+    end
+
+    def parse_query(query)
+      if queues?
+        error "query", "is only used with prometheus" unless query.nil?
+        return
+      end
+
+      error "query", "is required for prometheus" unless query.is_a?(String) && query.present?
+      query
+    end
+
+    def name?(value)
+      value.is_a?(String) && NAME.match?(value)
+    end
+
+    def name_rule
+      "should be letters, digits, _ . : or -"
+    end
+
+    def error(key, message)
+      raise Dash::ConfigurationError, "#{[ @context, key ].compact.join("/")}: #{message}"
+    end
+end

data/lib/dash/configuration/role/scale/window.rb

@@ -0,0 +1,37 @@
+# One `scale.schedule` entry: from every minute `cron` matches, for `duration` seconds, the
+# role runs at least `min` containers. Times are handed in already in `autoscale.timezone`,
+# so the cron is wall-clock there while the duration is real seconds (a window that spans a
+# DST change still lasts `for`).
+class Dash::Configuration::Role::Scale::Window
+  attr_reader :cron, :duration, :min
+
+  def initialize(cron:, duration:, min:)
+    @cron = cron
+    @duration = duration
+    @min = min
+  end
+
+  def active_at?(now)
+    !started_at(now).nil?
+  end
+
+  # The latest minute in (now - duration, now] the cron matches, scanned backwards: at most
+  # 10 080 steps for the 7-day limit.
+  def started_at(now)
+    earliest = now - duration
+    minute = now.change(sec: 0)
+
+    while minute > earliest
+      return minute if cron.match?(minute)
+      minute -= 60
+    end
+  end
+
+  def ends_at(now)
+    started_at(now)&.+(duration)
+  end
+
+  def to_h
+    { cron: cron.to_s, for: duration, min: min }
+  end
+end