hecks 2.8.0 → 2.9.0

data/lib/hecks/projections/deploy/preview/access_yaml.rb

@@ -4,29 +4,16 @@ module Hecks
   module Projections
     module Deploy
       module Preview
-        # The secrets and IAM roles of a preview stack.
-        #
-        # The task role reads the shared database secret and this preview's own
-        # secrets and nothing owned by the main stack. The execution role also reads
-        # the database secret, only so the one-shot task can receive the credentials
-        # as container secrets.
+        # The secrets and IAM roles of a preview stack, scoped away from the main stack.
         module AccessYaml
           extend YamlText
 
           module_function
 
-          # Renders the secrets a preview generates: its session secret and the ones
-          # containers declare.
-          #
-          # @param settings [Settings] the resolved preview settings
-          # @return [Array<String>] one YAML resource block per secret
           def secrets(settings)
             [session_secret, *settings.containers.flat_map { |c| container_secrets(c) }]
           end
 
-          # Renders the per-branch session secret the host reads at start.
-          #
-          # @return [String] the secret's resource block
           def session_secret
             <<~YAML.chomp
               # No explicit Name: Secrets Manager keeps a deleted secret through its recovery window,
@@ -43,10 +30,6 @@ module Hecks
             YAML
           end
 
-          # Renders one generated secret per name a container declares.
-          #
-          # @param container [Containers::Entry] the container
-          # @return [Array<String>] one resource block per declared secret name
           def container_secrets(container)
             container.secrets.map do |name|
               <<~YAML.chomp
@@ -63,10 +46,6 @@ module Hecks
             end
           end
 
-          # Renders the task execution role and the task role.
-          #
-          # @param settings [Settings] the resolved preview settings
-          # @return [Array<String>] the two role resource blocks
           def roles(settings)
             assume = <<~YAML.chomp
               AssumeRolePolicyDocument:
@@ -79,11 +58,6 @@ module Hecks
             [execution_role(assume), task_role(assume, settings)]
           end
 
-          # Renders the execution role, which pulls images and hands the one-shot task
-          # its credentials.
-          #
-          # @param assume [String] the shared trust policy block
-          # @return [String] the role's resource block
           def execution_role(assume)
             <<~YAML.chomp
               # The execution role reads the database secret only so the one-shot task can be given
@@ -105,12 +79,6 @@ module Hecks
             YAML
           end
 
-          # Renders the task role: read access to the shared database secret and this
-          # preview's own secrets.
-          #
-          # @param assume [String] the shared trust policy block
-          # @param settings [Settings] the resolved preview settings
-          # @return [String] the role's resource block
           def task_role(assume, settings)
             readable = ["SessionSecret", *settings.containers.flat_map { |c| c.secrets.map { |n| secret_id(c, n) } }]
             <<~YAML.chomp

data/lib/hecks/projections/deploy/preview/containers.rb

@@ -2,54 +2,15 @@ module Hecks
   module Projections
     module Deploy
       module Preview
-        # The containers one preview task runs, in one normalized shape.
-        #
-        # A preview task runs the same containers as the stack it previews.
-        # This module is the single place that decides which containers those
-        # are, so the rest of `Preview` never asks where the list came from.
-        #
-        # ## One adapter to the shared setting
-        #
-        # The main Fargate stack is growing a multi-container setting.
-        # `shared_setting` is the only method that reads it; every other
-        # method here works on the normalized entries described below. When
-        # that setting lands with a different shape, translate it inside
-        # `shared_setting` and nothing else changes.
-        #
-        # ## Entry keys
-        #
-        # Each entry is a Hash with Symbol keys:
-        #
-        # - `name` (required): lowercase letters, digits and hyphens; also the
-        #   container name and the suffix of its ECR repository.
-        # - `port` (required): the port the container listens on. Unique
-        #   across the task, since all containers share one network namespace.
-        # - `health_check_path`: target group health check path, default `"/"`.
-        # - `paths`: load balancer path patterns forwarded to this container.
-        # - `default`: `true` sends every unmatched request here. When no
-        #   entry says so, the `host` entry is the default, else the first.
-        # - `host`: `true` marks the Hecks host container. It gets the domain,
-        #   session and database environment, and the signup path.
-        # - `database`: `true` gives a non-host container the database
-        #   environment as well. The host always has it.
-        # - `environment`: extra environment, name to value. `{{preview_url}}`
-        #   inside a value becomes the preview's public https URL.
-        # - `secrets`: environment variable names. Each becomes a per-branch
-        #   generated secret whose ARN is that variable's value.
-        # - `image`: the local docker image `preview.sh` pushes for this
-        #   container, default `"<name>:latest"`.
+        # The containers one preview task runs, normalized via `resolve`; `shared_setting`
+        # is the one hook into the main stack's own (still-growing) multi-container setting.
         module Containers
           # One normalized container of the preview task.
           Entry = Data.define(:name, :port, :health_check_path, :paths, :default, :host, :database,
                               :environment, :secrets, :image) do
-            # Answers the CloudFormation logical-id fragment for this container.
-            #
-            # @return [String] `name` in CamelCase, such as `"MySite"` for `"my-site"`
+            # CamelCases `name`, e.g. `"my-site"` becomes `"MySite"`.
             def logical = name.split("-").map(&:capitalize).join
 
-            # Answers whether the container is reachable through the load balancer.
-            #
-            # @return [Boolean] true when it is the default or owns any path
             def routed? = default || !paths.empty?
           end
 
@@ -60,17 +21,8 @@ module Hecks
 
           module_function
 
-          # Answers the preview task's containers, normalized and validated.
-          #
-          # @param preview [Hash{Symbol => Object}] the preview settings; `:containers` wins
-          # @param deploy_settings [Hash{Symbol => Object}] the `deployed_to` settings, read
-          #   by `shared_setting`
-          # @param main [Hash{Symbol => Object}] the main stack's own facts; `:name`, `:port`,
-          #   `:image` describe the single container used when neither list is given
-          # @param signup_path [String, nil] path forwarded to the host container, or nil
-          # @return [Array<Entry>] at least one entry, exactly one of them the default
-          # @raise [ArgumentError] if an entry is malformed, a name or port repeats, or two
-          #   entries claim to be the default or the host
+          # `preview[:containers]` wins over the main stack's own multi-container setting,
+          # which wins over a single entry built from the main stack's own container.
           def resolve(preview:, deploy_settings:, main:, signup_path: nil)
             raw = preview[:containers] || shared_setting(deploy_settings) || [single(main)]
             entries = Array(raw).map { |item| normalize(item) }
@@ -78,31 +30,15 @@ module Hecks
             with_default(with_signup(entries, signup_path))
           end
 
-          # Reads the main stack's own container list, when it declares one.
-          #
-          # This is the one hook to the multi-container setting shared with the
-          # main template; it answers entries in the shape documented above.
-          #
-          # @param deploy_settings [Hash{Symbol => Object}] the `deployed_to` settings
-          # @return [Array<Hash>, nil] the list, or nil when the stack runs one container
           def shared_setting(deploy_settings)
             deploy_settings[:containers]
           end
 
-          # Builds the single-container entry a one-container stack previews as.
-          #
-          # @param main [Hash{Symbol => Object}] the main stack's facts, see `resolve`
-          # @return [Hash{Symbol => Object}] the entry, always the host and the default
           def single(main)
             name = main.fetch(:name).to_s.downcase.gsub(/[^a-z0-9]+/, "-").sub(/\A[^a-z]+/, "")[0, 30].sub(/-+\z/, "")
             { name: name, port: main.fetch(:port), host: true, default: true, image: main[:image] }
           end
 
-          # Turns one raw entry into an `Entry`, filling every default.
-          #
-          # @param item [Hash{Symbol => Object}] the raw entry, string keys accepted
-          # @return [Entry] the normalized entry
-          # @raise [ArgumentError] if the entry is not a Hash or lacks a valid `name` or `port`
           def normalize(item)
             raise ArgumentError, "preview container #{item.inspect} must be a Hash" unless item.is_a?(Hash)
 
@@ -117,13 +53,6 @@ module Hecks
             )
           end
 
-          # Answers a value as a String, refusing one that does not match a pattern.
-          #
-          # @param value [Object] the raw value
-          # @param pattern [Regexp] what the string must match
-          # @param label [String] what the value is, for the message
-          # @return [String] the value as a String
-          # @raise [ArgumentError] if the string does not match
           def matching(value, pattern, label)
             text = value.to_s
             raise ArgumentError, "#{label} #{text.inspect} must match #{pattern.inspect}" unless text.match?(pattern)
@@ -131,19 +60,8 @@ module Hecks
             text
           end
 
-          # Answers one path pattern, refusing one the template could not quote safely.
-          #
-          # @param path [Object] the raw path
-          # @return [String] the path
-          # @raise [ArgumentError] if it does not start with `/` or holds an unexpected character
           def path_of(path) = matching(path, PATH_PATTERN, "preview container path")
 
-          # Reads and range-checks one entry's port.
-          #
-          # @param item [Hash{Symbol => Object}] the raw entry
-          # @param name [String] the entry's name, for the message
-          # @return [Integer] the port
-          # @raise [ArgumentError] if the port is missing or outside 1..65535
           def port_of(item, name)
             port = Integer(item[:port], exception: false)
             raise ArgumentError, "preview container #{name} needs a port between 1 and 65535" unless port&.between?(1, 65_535)
@@ -151,20 +69,10 @@ module Hecks
             port
           end
 
-          # Stringifies an entry's environment, keeping declaration order.
-          #
-          # @param environment [Hash{Symbol, String => Object}, nil] the raw environment
-          # @return [Hash{String => String}] name to value
           def environment_of(environment)
             (environment || {}).to_h { |name, value| [name.to_s, value.to_s] }
           end
 
-          # Refuses a list that cannot be one task.
-          #
-          # @param entries [Array<Entry>] the normalized entries
-          # @return [void]
-          # @raise [ArgumentError] on an empty list, a repeated name or port, more than one
-          #   default or host, or a secret name that is not an environment variable name
           def check!(entries)
             raise ArgumentError, "preview containers must not be empty" if entries.empty?
 
@@ -175,11 +83,6 @@ module Hecks
             check_roles!(entries)
           end
 
-          # Refuses a second default or host, and a secret that is not an environment variable name.
-          #
-          # @param entries [Array<Entry>] the normalized entries
-          # @return [void]
-          # @raise [ArgumentError] on a second default or host, or a malformed secret name
           def check_roles!(entries)
             raise ArgumentError, "at most one preview container may be the default" if entries.count(&:default) > 1
             raise ArgumentError, "at most one preview container may be the host" if entries.count(&:host) > 1
@@ -188,11 +91,7 @@ module Hecks
             raise ArgumentError, "preview secret name #{bad.inspect} must be an environment variable name" if bad
           end
 
-          # Adds the signup path to the host container's own paths.
-          #
-          # @param entries [Array<Entry>] the normalized entries
-          # @param signup_path [String, nil] the path, or nil for none
-          # @return [Array<Entry>] the entries, the host's paths extended when it needs a rule
+          # Skipped when the host is already the default: it gets unmatched traffic anyway.
           def with_signup(entries, signup_path)
             return entries unless signup_path
 
@@ -201,10 +100,6 @@ module Hecks
             end
           end
 
-          # Marks the default container when no entry does.
-          #
-          # @param entries [Array<Entry>] the normalized entries
-          # @return [Array<Entry>] the entries with exactly one default
           def with_default(entries)
             return entries if entries.any?(&:default)
 

data/lib/hecks/projections/deploy/preview/routing_yaml.rb

@@ -5,11 +5,8 @@ module Hecks
   module Projections
     module Deploy
       module Preview
-        # The network edge of a preview stack: security groups, target groups, the
-        # load balancer, its listener rules and the service that registers the containers.
-        #
-        # A container is reachable when it is the default or owns a path. Paths are
-        # split into rules of at most five, the most a load balancer condition holds.
+        # The network edge of a preview stack: security groups, load balancer and service.
+        # Paths are sliced into rules of at most five, the most a condition holds.
         module RoutingYaml
           CLOUDFRONT_PREFIX_LIST = "pl-3b927c52".freeze
           PATHS_PER_RULE = 5
@@ -22,10 +19,6 @@ module Hecks
 
           module_function
 
-          # Renders the load balancer's security group and one ingress rule per routed container.
-          #
-          # @param settings [Settings] the resolved preview settings
-          # @return [Array<String>] the resource blocks
           def networking(settings)
             ingress = settings.containers.select(&:routed?).map do |c|
               <<~YAML.chomp
@@ -42,10 +35,6 @@ module Hecks
             [alb_security_group(settings), "#{INGRESS_NOTE}\n#{ingress.join("\n\n")}"]
           end
 
-          # Renders the load balancer's security group, open to CloudFront's prefix list only.
-          #
-          # @param settings [Settings] the resolved preview settings
-          # @return [String] the resource block
           def alb_security_group(settings)
             <<~YAML.chomp
               AlbSecurityGroup:
@@ -62,19 +51,11 @@ module Hecks
             YAML
           end
 
-          # Renders the target groups, the load balancer, its listener and the path rules.
-          #
-          # @param settings [Settings] the resolved preview settings
-          # @return [Array<String>] the resource blocks
           def load_balancing(settings)
             routed = settings.containers.select(&:routed?)
             [*routed.map { |c| target_group(c) }, alb(settings), listener(settings), *listener_rules(settings)]
           end
 
-          # Renders the target group of one routed container.
-          #
-          # @param container [Containers::Entry] the container
-          # @return [String] the resource block
           def target_group(container)
             <<~YAML.chomp
               #{container.logical}TargetGroup:
@@ -89,10 +70,6 @@ module Hecks
             YAML
           end
 
-          # Renders the internet-facing application load balancer.
-          #
-          # @param settings [Settings] the resolved preview settings
-          # @return [String] the resource block
           def alb(settings)
             <<~YAML.chomp
               Alb:
@@ -106,10 +83,7 @@ module Hecks
             YAML
           end
 
-          # Renders the port 80 listener, whose default action goes to the default container.
-          #
-          # @param settings [Settings] the resolved preview settings
-          # @return [String] the resource block
+          # The default action goes to the default container.
           def listener(settings)
             <<~YAML.chomp
               Listener:
@@ -124,11 +98,6 @@ module Hecks
             YAML
           end
 
-          # Lists the listener rules to render: a non-default container's paths, sliced to
-          # fit one condition.
-          #
-          # @param settings [Settings] the resolved preview settings
-          # @return [Array<Hash{Symbol => Object}>] entries with `:container`, `:paths` and `:id`
           def rule_specs(settings)
             settings.containers.reject(&:default).select(&:routed?).flat_map do |c|
               c.paths.each_slice(PATHS_PER_RULE).with_index.map do |slice, n|
@@ -137,19 +106,11 @@ module Hecks
             end
           end
 
-          # Renders every listener rule, with priorities counting up in tens.
-          #
-          # @param settings [Settings] the resolved preview settings
-          # @return [Array<String>] the resource blocks
+          # Priorities count up in tens.
           def listener_rules(settings)
             rule_specs(settings).each_with_index.map { |spec, i| listener_rule(spec, (i + 1) * 10) }
           end
 
-          # Renders one listener rule.
-          #
-          # @param spec [Hash{Symbol => Object}] one entry of `rule_specs`
-          # @param priority [Integer] the rule's listener priority
-          # @return [String] the resource block
           def listener_rule(spec, priority)
             <<~YAML.chomp
               #{spec[:id]}:
@@ -166,17 +127,8 @@ module Hecks
             YAML
           end
 
-          # Names one listener rule's logical id.
-          #
-          # @param container [Containers::Entry] the container the rule forwards to
-          # @param slice [Integer] the zero-based index of the rule among that container's rules
-          # @return [String] the logical id
           def rule_id(container, slice) = "ListenerRule#{container.logical}#{slice + 1}"
 
-          # Renders the service, which registers every routed container with its target group.
-          #
-          # @param settings [Settings] the resolved preview settings
-          # @return [String] the resource block
           def service(settings)
             rule_ids = rule_specs(settings).map { |spec| spec[:id] }
             <<~YAML.chomp
@@ -200,10 +152,6 @@ module Hecks
             YAML
           end
 
-          # Renders the service's load balancer registrations.
-          #
-          # @param settings [Settings] the resolved preview settings
-          # @return [String] one list entry per routed container
           def service_load_balancers(settings)
             settings.containers.select(&:routed?).map do |c|
               "- ContainerName: #{c.name}\n  ContainerPort: #{c.port}\n  TargetGroupArn: !Ref #{c.logical}TargetGroup"

data/lib/hecks/projections/deploy/preview/script.rb

@@ -4,22 +4,13 @@ module Hecks
   module Projections
     module Deploy
       module Preview
-        # Renders `preview.sh`, the script that creates, updates and deletes one
-        # branch's preview stack.
-        #
-        # The script text lives in `preview.sh.erb` beside this file because it
-        # is a shell program, not Ruby: keeping it as a file lets `bash -n` and
-        # `shellcheck` read it as one. Every value baked into it has already
-        # passed `Settings`' patterns, so the template never quotes defensively.
+        # Renders `preview.sh` from `preview.sh.erb`, kept as a separate file so `bash -n`
+        # and `shellcheck` can read it; every baked-in value already passed `Settings`.
         module Script
           TEMPLATE = File.join(__dir__, "preview.sh.erb").freeze
 
           module_function
 
-          # Renders the script.
-          #
-          # @param settings [Settings] the resolved preview settings
-          # @return [String] the bash script, ending in one newline
           def render(settings)
             ERB.new(File.read(TEMPLATE), trim_mode: "-").result_with_hash(
               s: settings, image_hint: image_hint(settings)
@@ -27,9 +18,6 @@ module Hecks
           end
 
           # Names the local images `deploy` expects, for the script's header.
-          #
-          # @param settings [Settings] the resolved preview settings
-          # @return [String] the image references, comma separated
           def image_hint(settings)
             settings.containers.map(&:image).join(", ")
           end

data/lib/hecks/projections/deploy/preview/settings.rb

@@ -4,18 +4,8 @@ module Hecks
   module Projections
     module Deploy
       module Preview
-        # The resolved, validated settings of one preview stack family.
-        #
-        # `Settings.build` is the only place a raw `preview` block meets the
-        # main stack's own facts, so every default lives here and the two
-        # renderers (`Template`, `Script`) read plain values.
-        #
-        # ## Why validation is this strict
-        #
-        # Every value ends up in a CloudFormation name, a Postgres database
-        # name that `CREATE DATABASE` cannot parameterize, or a shell script
-        # baked with the value. Patterns are checked once here, so neither
-        # renderer has to quote defensively.
+        # The resolved, validated settings of one preview stack, built once by `build`.
+        # Checked strictly: values feed CloudFormation names and a baked shell script.
         class Settings
           KEYS = %i[prefix alb_prefix owner_stack database_stack database_endpoint_output database_secret_output
                     db_prefix protected_databases protected_branches cpu memory log_retention_days session_cookie
@@ -34,18 +24,7 @@ module Hecks
 
           attr_reader(*KEYS, :region, :stack_name, :infra_name, :main)
 
-          # Builds the settings for one domain's previews.
-          #
-          # @param raw [Hash{Symbol => Object}, true] the `preview` block; `true` accepts
-          #   every default
-          # @param deploy_settings [Hash{Symbol => Object}] the `deployed_to` settings
-          # @param main [Hash{Symbol => Object}] the main stack's facts: `:infra_name`,
-          #   `:stack_name`,
-          #   `:stack_prefix`, `:region`, `:cpu`, `:memory`, `:db_name`, `:owner_stack` (nil unless
-          #   the main stack borrows a database), `:name`, `:port`, `:image`, `:domain`, `:web`,
-          #   `:wasm_path`, `:ir_path`, `:schema`
-          # @return [Settings] the validated settings
-          # @raise [ArgumentError] if a key is unknown or a value breaks its pattern
+          # `raw` may be `true`, accepting every default.
           def self.build(raw, deploy_settings:, main:)
             raw = raw.is_a?(Hash) ? raw.transform_keys(&:to_sym) : {}
             unknown = raw.keys - KEYS
@@ -56,9 +35,6 @@ module Hecks
             new(raw, deploy_settings, main)
           end
 
-          # @param raw [Hash{Symbol => Object}] the symbolized `preview` settings
-          # @param deploy_settings [Hash{Symbol => Object}] the `deployed_to` settings
-          # @param main [Hash{Symbol => Object}] the main stack's facts, see `build`
           def initialize(raw, deploy_settings, main)
             @main = main
             @region = main.fetch(:region)
@@ -72,14 +48,8 @@ module Hecks
                                              signup_path: (signup_path if first_admin))
           end
 
-          # Answers the host container, when the task has one.
-          #
-          # @return [Containers::Entry, nil] the entry flagged `host`
           def host = containers.find(&:host)
 
-          # Answers the container that receives unmatched requests.
-          #
-          # @return [Containers::Entry] the default entry
           def default_container = containers.find(&:default)
 
           private

data/lib/hecks/projections/deploy/preview/task_yaml.rb

@@ -7,9 +7,6 @@ module Hecks
       module Preview
         # The task definitions of a preview stack: the containers it runs and the
         # one-shot task that creates its database.
-        #
-        # The host container gets the domain, session and database environment; a
-        # container's own `environment` wins over a generated entry of the same name.
         module TaskYaml
           # The one-shot task's script. Idempotent, and refuses names the preview must never touch.
           DB_INIT_SCRIPT = <<~SH.freeze
@@ -52,10 +49,7 @@ module Hecks
 
           module_function
 
-          # Renders the one-shot task that creates (or drops) this preview's database.
-          #
-          # @param settings [Settings] the resolved preview settings
-          # @return [String] the task definition's resource block
+          # Also renders the drop path, taken when `ACTION` is `drop`.
           def db_init_task(settings)
             <<~YAML.chomp
               # Run by preview.sh (`aws ecs run-task`) after the images are pushed and before the
@@ -100,10 +94,6 @@ module Hecks
             YAML
           end
 
-          # Renders the preview's task definition, one container per entry of the container list.
-          #
-          # @param settings [Settings] the resolved preview settings
-          # @return [String] the task definition's resource block
           def task_definition(settings)
             <<~YAML.chomp
               TaskDefinition:
@@ -124,11 +114,6 @@ module Hecks
             YAML
           end
 
-          # Renders one container of the task definition.
-          #
-          # @param settings [Settings] the resolved preview settings
-          # @param container [Containers::Entry] the container
-          # @return [String] the list entry
           def container_definition(settings, container)
             lines = [
               "- Name: #{container.name}",
@@ -141,10 +126,6 @@ module Hecks
             lines.join("\n")
           end
 
-          # Renders the log driver settings of one container.
-          #
-          # @param container [Containers::Entry] the container
-          # @return [String] the settings, ending in a newline
           def log_options(container)
             <<~YAML
               LogDriver: awslogs
@@ -155,23 +136,13 @@ module Hecks
             YAML
           end
 
-          # Renders one container's environment as a list.
-          #
-          # @param settings [Settings] the resolved preview settings
-          # @param container [Containers::Entry] the container
-          # @return [String] the list entries
           def environment_yaml(settings, container)
             environment_pairs(settings, container).map do |name, value|
               "- Name: #{name}\n  Value: #{value}"
             end.join("\n")
           end
 
-          # Orders one container's environment as `[name, rendered value]` pairs; the container's
-          # `environment` wins over a generated entry of the same name.
-          #
-          # @param settings [Settings] the resolved preview settings
-          # @param container [Containers::Entry] the container
-          # @return [Array<Array(String, String)>] the pairs, each value already rendered as YAML
+          # The container's own `environment` wins over a generated entry of the same name.
           def environment_pairs(settings, container)
             pairs = { "PORT" => scalar(container.port.to_s) }
             pairs.merge!(host_environment(settings)) if container.host
@@ -181,10 +152,6 @@ module Hecks
             pairs.to_a
           end
 
-          # Answers the environment only the Hecks host container gets.
-          #
-          # @param settings [Settings] the resolved preview settings
-          # @return [Hash{String => String}] name to rendered value
           def host_environment(settings)
             main = settings.main
             pairs = {
@@ -199,9 +166,6 @@ module Hecks
             pairs
           end
 
-          # Answers the environment that points a container at this preview's database.
-          #
-          # @return [Hash{String => String}] name to rendered value
           def database_environment
             {
               "DB_HOST" => "!Ref OwningDatabaseEndpoint", "DB_NAME" => "!Ref DbName",