hecks 2.7.0 → 2.9.0

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

@@ -6,32 +6,7 @@ module Hecks
     module Deploy
       module Fargate
         # The containers of one Fargate task and how the load balancer reaches them.
-        #
-        # A stack always has the domain container: `rust/host` built from the
-        # domain itself. The world's `containers` setting adds more containers
-        # to the same task (a website, a content admin), each with its own ECR
-        # repository, image-tag parameter, target group and health check.
-        # `routes` sends URL path patterns to a container through listener
-        # rules on the one load balancer, and `default_container` names the
-        # container that answers everything else.
-        #
-        # ## Settings
-        #
-        # `domain_container` renames the domain container's own pieces:
-        # `name`, `repository`, `image_tag_parameter` and `health_path`. Its `essential`
-        # writes an explicit `Essential` flag; the container is essential either way,
-        # since that is `ECS`'s default.
-        #
-        # Each `containers` entry takes `name` and `repository` (required),
-        # and `port`, `health_path`, `env`, `secrets`, `image_tag_parameter`,
-        # `essential`, `cpu`, `memory`, `repository_id` and `target_group_id`.
-        # A container without a `port` receives no load-balancer traffic.
-        # `env` values and `secrets` values may be CloudFormation intrinsics
-        # written as strings (`"!Ref Name"`, `"!Sub \"...\""`).
-        #
-        # Each `routes` entry takes `container`, `paths` (one to five path
-        # patterns, since a listener rule condition holds at most five),
-        # `priority` and an optional `id`.
+        # The domain container (`rust/host`) is always present; more are added via `containers`.
         module Containers
           module_function
 
@@ -43,23 +18,15 @@ module Hecks
           Route = Struct.new(:id, :container, :paths, :priority, keyword_init: true)
           Layout = Struct.new(:domain, :extras, :routes, :default_container, keyword_init: true) do
             # Lists the domain container followed by every added container.
-            #
-            # @return [Array<Container>] every container of the task
             def all = [domain, *extras]
 
             # Lists the containers that receive load-balancer traffic.
-            #
-            # @return [Array<Container>] the containers with a port
             def balanced = all.select(&:port)
 
             # Tells whether the stack has any container besides the domain's own.
-            #
-            # @return [Boolean] true when `containers` added at least one
             def multi? = !extras.empty?
 
             # Finds the container the listener forwards to by default.
-            #
-            # @return [Container] the default container
             def default = all.find { |container| container.name == default_container }
           end
 
@@ -71,15 +38,6 @@ module Hecks
           ROUTE_KEYS = [:container, :paths, :priority, :id].freeze
 
           # Reads the container-related settings into a `Layout`.
-          #
-          # @param settings [Hash{Symbol => Object}] the world's `deployed_to("AwsFargate")`
-          #   settings
-          # @param infra_name [String] the domain's own AWS-facing name, the default container name
-          # @param port [Integer] the validated port of the domain container
-          # @param ids [Hash{Symbol => String}] the resolved logical ids, for the domain container's
-          #   own
-          # @return [Layout] the containers, routes and default container
-          # @raise [ArgumentError] if a container, route or the default container is invalid
           def normalize(settings, infra_name:, port:, ids:)
             domain = domain_container(settings[:domain_container], infra_name: infra_name, port: port, ids: ids)
             extras = Check.hashes!(settings.fetch(:containers, []), "containers", allowed:  CONTAINER_KEYS,
@@ -96,9 +54,6 @@ module Hecks
           end
 
           # Renders the ECR repository of every added container.
-          #
-          # @param layout [Layout] the stack's containers
-          # @return [String] flush-left resources separated by blank lines, or empty
           def repositories_yaml(layout)
             layout.extras.map do |container|
               <<~REPOSITORY.rstrip
@@ -113,9 +68,6 @@ module Hecks
           end
 
           # Renders the image-tag parameter of every added container.
-          #
-          # @param layout [Layout] the stack's containers
-          # @return [String] flush-left parameters, each ending in a newline, or empty
           def parameters_yaml(layout)
             layout.extras.map do |container|
               <<~PARAMETER
@@ -128,21 +80,11 @@ module Hecks
           end
 
           # Renders the added containers as `ContainerDefinitions` list entries.
-          #
-          # @param layout [Layout] the stack's containers
-          # @param log_group_id [String] the logical id of the shared log group
-          # @return [String] flush-left list entries separated by blank lines, or empty
           def definitions_yaml(layout, log_group_id)
             layout.extras.map { |container| definition_yaml(container, log_group_id) }.join("\n\n")
           end
 
           # Renders the target group of every added container.
-          #
-          # @param layout [Layout] the stack's containers
-          # @param vpc_ref [String] the `!Ref` expression for the VPC the targets live in
-          # @param deregistration_delay [Integer, nil] seconds the load balancer drains a target, or
-          #   nil for the default
-          # @return [String] flush-left resources separated by blank lines, or empty
           def target_groups_yaml(layout, vpc_ref, deregistration_delay)
             layout.extras.select(&:port).map do |container|
               [
@@ -161,9 +103,6 @@ module Hecks
           end
 
           # Renders the `TargetGroupAttributes` property for a drain delay.
-          #
-          # @param deregistration_delay [Integer, nil] seconds the load balancer drains a target
-          # @return [String] flush-left property lines ending in a newline, or empty for nil
           def target_group_attributes_yaml(deregistration_delay)
             return "" unless deregistration_delay
 
@@ -175,10 +114,6 @@ module Hecks
           end
 
           # Renders one listener rule per route.
-          #
-          # @param layout [Layout] the stack's containers and routes
-          # @param listener_id [String] the logical id of the HTTP listener
-          # @return [String] flush-left resources separated by blank lines, or empty
           def listener_rules_yaml(layout, listener_id)
             layout.routes.map do |route|
               target = layout.all.find { |container| container.name == route.container }
@@ -199,9 +134,6 @@ module Hecks
           end
 
           # Renders the service's `LoadBalancers` entries for the added containers.
-          #
-          # @param layout [Layout] the stack's containers
-          # @return [String] flush-left list entries, or empty
           def load_balancers_yaml(layout)
             layout.extras.select(&:port).map do |container|
               <<~ENTRY
@@ -212,12 +144,8 @@ module Hecks
             end.join
           end
 
-          # Writes the `DependsOn` value that holds the service until the listener and its rules
-          # exist.
-          #
-          # @param layout [Layout] the stack's containers and routes
-          # @param listener_id [String] the logical id of the HTTP listener
-          # @return [String] a single id, or a flow list of ids
+          # Writes the `DependsOn` value that holds the service until the listener and its
+          # rules exist.
           def depends_on(layout, listener_id)
             return listener_id if layout.routes.empty?
 
@@ -225,9 +153,6 @@ module Hecks
           end
 
           # Finds the first and last container port the load balancer must reach.
-          #
-          # @param layout [Layout] the stack's containers
-          # @return [Range<Integer>] the security-group ingress port range
           def port_range(layout)
             ports = layout.balanced.map(&:port)
             ports.min..ports.max

data/lib/hecks/projections/deploy/fargate/extras.rb

@@ -5,26 +5,8 @@ module Hecks
   module Projections
     module Deploy
       module Fargate
-        # The extra resources, parameters, outputs and IAM grants a stack can
-        # declare beyond the ones the generator always makes.
-        #
-        # ## Settings
-        #
-        # - `buckets`: S3 buckets, each `{id:, name_prefix:, public_read:, cors_origins:}`. The
-        #   bucket is named `<name_prefix>-<account id>`. `public_read` opens the bucket to
-        #   anonymous `GetObject`. `cors_origins` allows those origins to `GET` from a browser.
-        # - `generated_secrets`: Secrets Manager secrets with a generated value, each
-        #   `{id:, name:, description:, key:, length:}`. `key` is the JSON field the value is
-        #   stored under (`secret`).
-        # - `session_secret`: `{name:, description:}` names the always-created session secret
-        #   and describes it.
-        # - `task_policies` and `execution_policies`: extra IAM policies for the task role (what
-        #   the containers may do) and the execution role (what `ECS` may do to start them).
-        #   Each is `{name:, statements: [{effect:, actions:, resources:}]}`; `effect` is `Allow`
-        #   by default and resources may be intrinsics.
-        # - `parameters`: extra template parameters, a map of name to
-        #   `{type:, default:, description:, no_echo:}`.
-        # - `outputs`: extra template outputs, a map of name to a value or intrinsic.
+        # The extra resources, parameters, outputs and IAM grants a stack can declare beyond
+        # what the generator always makes; settings are documented in the DSL reference.
         module Extras
           module_function
 
@@ -38,14 +20,6 @@ module Hecks
                             ssmmessages:OpenControlChannel ssmmessages:OpenDataChannel].freeze
 
           # Reads and checks the resource-declaring settings.
-          #
-          # @param settings [Hash{Symbol => Object}] the world's `deployed_to("AwsFargate")`
-          #   settings
-          # @return [Hash{Symbol => Object}] `:buckets`, `:secrets`, `:session_secret`,
-          #   `:task_policies`,
-          #   `:execution_policies`, `:parameters` and `:outputs`, each checked and defaulted to
-          #   empty
-          # @raise [ArgumentError] if any of those settings is malformed
           def normalize(settings)
             {
               buckets:            buckets(settings.fetch(:buckets, [])),
@@ -59,9 +33,6 @@ module Hecks
           end
 
           # Renders the buckets and generated secrets.
-          #
-          # @param extras [Hash] the checked settings from `normalize`
-          # @return [String] flush-left resources separated by blank lines, or empty
           def resources_yaml(extras)
             (extras[:buckets].flat_map { |bucket| bucket_blocks(bucket) } + extras[:secrets].map do |secret|
               secret_yaml(secret)
@@ -69,16 +40,11 @@ module Hecks
           end
 
           # Renders extra policies as entries of a role's `Policies` list.
-          #
-          # @param policies [Array<Hash>] the checked policies
-          # @return [String] flush-left list entries, or empty
           def policies_yaml(policies)
             policies.map { |policy| policy_yaml(policy) }.join
           end
 
           # Renders the policy that lets `aws ecs execute-command` open a session in a container.
-          #
-          # @return [String] one flush-left `Policies` list entry
           def execute_command_policy_yaml
             policy_yaml(
               name:       "EcsExecDebug",
@@ -87,9 +53,6 @@ module Hecks
           end
 
           # Renders the extra template parameters.
-          #
-          # @param parameters [Hash{String => Hash}] the checked parameters
-          # @return [String] flush-left parameters, or empty
           def parameters_yaml(parameters)
             parameters.map do |name, given|
               lines = ["#{name}:", "  Type: #{given[:type]}"]
@@ -101,9 +64,6 @@ module Hecks
           end
 
           # Renders the extra template outputs.
-          #
-          # @param outputs [Hash{String => Object}] the checked outputs
-          # @return [String] flush-left outputs, or empty
           def outputs_yaml(outputs)
             outputs.map { |name, value| "#{name}:\n  Value: #{Yaml.string(value)}\n" }.join
           end
@@ -253,8 +213,7 @@ module Hecks
           end
           private_class_method :policy_yaml
 
-          # One entry is written as a scalar, the form IAM policies are usually written in; more are
-          # a list.
+          # One entry is written as a scalar, the form IAM policies usually take; more are a list.
           def statement_list(key, values)
             return ["        #{key}: #{values.first}"] if values.one?
 

data/lib/hecks/projections/deploy/fargate/monitoring.rb

@@ -7,33 +7,6 @@ module Hecks
       module Fargate
         # Alerting for a Fargate stack: an `SNS` topic, CloudWatch alarms, and an
         # optional synthetic check.
-        #
-        # Every alarm reports to the topic on both alarm and recovery. An email
-        # address subscribes to the topic, but `SNS` holds the subscription as
-        # pending until the recipient follows the confirmation link it mails;
-        # the stack cannot do that step.
-        #
-        # ## Settings
-        #
-        # `alerts` is a hash:
-        #
-        # - `topic`: the `SNS` topic name (required).
-        # - `email`: an address to subscribe to the topic.
-        # - `alarms`: a list of kinds, each a string or a hash `{kind:, container:, threshold:,
-        #   period:, evaluation_periods:, datapoints_to_alarm:, description:}`. The kinds are
-        #   `alb_5xx` (5xx responses from targets), `target_unhealthy` (an unhealthy target, for
-        #   one `container` or for every load-balanced one) and `cloudfront_5xx` (5xx responses
-        #   counted at the edge).
-        # - `warmer`: `{paths:, namespace:, rate:}` adds a function that requests each path
-        #   through the CDN on a schedule and reports failures as a metric, with an alarm that
-        #   also fires when the metric goes silent. `code` replaces the function's inline source,
-        #   and `schedule_description` and `alarm_description` replace the schedule's and the
-        #   alarm's description text.
-        #
-        # The logical ids come from `logical_ids`: `alerts_topic`, `alerts_subscription`,
-        # `alb_5xx_alarm`, `cloudfront_5xx_alarm`, `cloudfront_monitoring`, `synthetic_alarm`,
-        # `warmer_role`, `warmer_function`, `scheduler_role` and `warmer_schedule`. A
-        # per-container alarm is `<Container>TargetUnhealthyAlarm`.
         module Monitoring
           module_function
 
@@ -56,13 +29,6 @@ module Hecks
             synthetic:        "The synthetic check found a non-200 response on a real path, or stopped reporting."
           }.freeze
 
-          # Reads and checks the `alerts` setting.
-          #
-          # @param setting [Hash, nil] the world's `alerts` value, or nil when it sets none
-          # @param containers [Array<String>] the names of the load-balanced containers
-          # @return [Hash{Symbol => Object}, nil] the checked settings, or nil for none
-          # @raise [ArgumentError] if a key is unknown or malformed, or an alarm names a container
-          #   that has no target group
           def normalize(setting, containers:)
             return nil if setting.nil?
 
@@ -76,20 +42,10 @@ module Hecks
             }
           end
 
-          # Tells whether any alarm needs the CloudFront metrics subscription.
-          #
-          # @param alerts [Hash, nil] the checked settings from `normalize`
-          # @return [Boolean] true when a `cloudfront_5xx` alarm is declared
           def cloudfront_metrics?(alerts)
             !alerts.nil? && alerts[:alarms].any? { |alarm| alarm[:kind] == "cloudfront_5xx" }
           end
 
-          # Renders every alerting resource.
-          #
-          # @param alerts [Hash] the checked settings from `normalize`
-          # @param context [Hash{Symbol => Object}] `:ids` (resolved logical ids), `:stack_name`,
-          #   `:alb_id`, `:distribution_id` and `:target_groups` (container name to target group id)
-          # @return [String] flush-left resources separated by blank lines, ending in a blank line
           def yaml(alerts, context)
             blocks = [topic_yaml(alerts, context[:ids])]
             blocks << subscription_yaml(alerts, context[:ids]) if alerts[:email]

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

@@ -12,44 +12,7 @@ module Hecks
         # Everything a `deployed_to("AwsFargate")` block can say beyond its
         # required settings, read and checked into one `Plan`.
         #
-        # A world that sets none of these keys resolves to a plan whose every
-        # value is the generator's own default: the derived logical ids and
-        # names, one container, no extra resources. That plan renders the same
-        # template the generator has always produced.
-        #
-        # ## Settings owned here
-        #
-        # - `logical_ids`: a map of role to logical id that replaces the id derived from the
-        #   stack name, so an existing stack's ids can be reproduced. The roles are `service`,
-        #   `ecr_repository`, `cluster`, `task_definition`, `execution_role`, `task_role`,
-        #   `log_group`, `target_group`, `alb`, `alb_security_group`, `listener`, `distribution`,
-        #   `session_secret`, `ingress_from_alb`, `database_prefix` and `compute_prefix`, plus
-        #   the alerting roles `Monitoring` lists. `database_prefix` and `compute_prefix` are the
-        #   prefixes of the VPC and database ids and of the compute security-group ids.
-        # - `names`: a map of role to the AWS name that replaces the derived one. The roles are
-        #   `cluster`, `log_group`, `service`, `alb` and `family`; `db_secret_policy`, the name of
-        #   the task role's database-secret policy (`DbSecretRead`); and
-        #   `alb_security_group_description`, the load balancer's security group description
-        #   (EC2 replaces the group when it changes).
-        # - `execution_role_database_grant`: false leaves the database secret out of the
-        #   execution role. The host reads that secret itself with the task role, so the
-        #   execution role needs it only when a container's `ECS` `Secrets` names it;
-        #   `execution_policies` must then hold a policy.
-        # - `execute_command`: true lets `aws ecs execute-command` open a session in a container.
-        # - `health_check_grace_period`: seconds `ECS` ignores failing load-balancer health
-        #   checks after a task starts.
-        # - `deregistration_delay`: seconds a target group drains a deregistered target.
-        # - `desired_count_parameter`: makes the service's desired count a template parameter
-        #   with this name, defaulting to `desired_count`.
-        # - `domain_env`: extra environment variables for the domain container, a map of name to
-        #   a value or intrinsic. A name the generator already sets replaces it; a `nil` value
-        #   removes it.
-        # - `install_dir`: where the Dockerfile installs the host binary and its `.wasm` and
-        #   `.ir.json` files, and where `HECKS_WASM_PATH` and `HECKS_IR_PATH` point
-        #   (`/usr/local/bin`).
-        # - `build_context_dir`: a directory prefix for the Dockerfile's `COPY` sources.
-        # - `db_name_parameter`: for `database "Shared"`, a template parameter that names the
-        #   shared database, defaulting to the owner's name.
+        # A world that sets none of these keys resolves entirely to the generator's own defaults.
         module Settings
           module_function
 
@@ -75,16 +38,7 @@ module Hecks
           NAME_ROLES = [:cluster, :log_group, :service, :alb, :family, :alb_security_group_description, :db_secret_policy].freeze
           DEFAULT_INSTALL_DIR = "/usr/local/bin".freeze
 
-          # Reads and checks every optional setting into a `Plan`.
-          #
-          # @param settings [Hash{Symbol => Object}] the world's `deployed_to("AwsFargate")`
-          #   settings
-          # @param base [Hash{Symbol => Object}] facts the generator has already resolved:
-          #   `:infra_name`,
-          #   `:logical_id`, `:db_id`, `:stack_name`, `:port`, `:desired_count` and `:shared`
-          # @return [Plan] the checked settings with every default applied
-          # @raise [ArgumentError] if any setting is malformed, or two settings contradict each
-          #   other
+          # Reads and checks every optional setting into a frozen `Plan`, applying every default.
           def resolve(settings, base)
             ids = logical_ids(settings[:logical_ids], base)
             layout = Containers.normalize(settings, infra_name: base[:infra_name], port: base[:port], ids: ids)
@@ -98,12 +52,6 @@ module Hecks
           end
 
           # Lists every template parameter the plan declares beyond the generator's own.
-          #
-          # @param plan [Plan] the resolved plan
-          # @param default_count [Integer] the service's `desired_count`, the default of its
-          #   parameter
-          # @param shared_db_name [String, nil] the owning database's name, when `database "Shared"`
-          # @return [String] flush-left parameter text separated by newlines, or empty
           def parameters_yaml(plan, default_count:, shared_db_name:)
             [
               Containers.parameters_yaml(plan.layout), Cdn.parameters_yaml(plan.cdn),

data/lib/hecks/projections/deploy/fargate/yaml.rb

@@ -4,23 +4,13 @@ module Hecks
       module Fargate
         # Text helpers the Fargate template generator renders YAML with.
         #
-        # The template is built as text, not as a data structure, so the
-        # comments that explain each resource survive into the generated file.
-        # These helpers cover the three things text rendering needs: writing a
-        # setting's value as a YAML scalar, indenting a flush-left block, and
-        # splicing a block into a marker line of the surrounding template.
+        # The template is built as text, not as a data structure, so the comments
+        # that explain each resource survive into the generated file.
         module Yaml
           module_function
 
-          # Writes one value as a YAML scalar.
-          #
-          # A string that starts with `!` is a CloudFormation intrinsic
-          # (`!Ref Name`, `!Sub "..."`, `!GetAtt Name.Arn`) and is written
-          # verbatim. Any other string is double-quoted, so a value such as
-          # `"1"` stays a string. Numbers and booleans are written bare.
-          #
-          # @param value [String, Integer, Float, true, false] the value to render
-          # @return [String] the YAML text for the value, on one line
+          # Writes one value as a YAML scalar; a leading `!` marks a CloudFormation
+          # intrinsic (`!Ref`, `!Sub`, `!GetAtt`) and is left unquoted.
           def scalar(value)
             case value
             when true, false, Integer, Float then value.to_s
@@ -30,28 +20,15 @@ module Hecks
             end
           end
 
-          # Writes a value as a scalar that must stay a string.
-          #
-          # Environment values and container settings such as a port are
-          # strings to `ECS` however they are typed in the world file, so a
-          # number is quoted here where `scalar` would leave it bare.
-          #
-          # @param value [Object] the value to render
-          # @return [String] the YAML text for the value, on one line
+          # Writes a value as a scalar that must stay a string, quoting a number
+          # where `scalar` would leave it bare.
           def string(value)
             text = value.to_s
             text.start_with?("!") ? text : text.to_json
           end
 
-          # Writes a list as a YAML flow sequence.
-          #
-          # A string made of a word (an id, an HTTP method) is left bare; any
-          # other string is written with `scalar`, so a value YAML would read
-          # as a number, a boolean or null stays a string.
-          #
-          # @param values [Array<Object>] the items, each rendered with `scalar` unless it is a
-          #   plain word
-          # @return [String] the `[a, b]` text
+          # Writes a list as a YAML flow sequence, rendering each item with `scalar`
+          # unless it is a bare word, so a numeric-looking string stays quoted.
           def flow_list(values)
             "[#{values.map { |value| plain_word?(value) ? value : scalar(value) }.join(', ')}]"
           end
@@ -62,26 +39,13 @@ module Hecks
           end
           private_class_method :plain_word?
 
-          # Indents every non-blank line of a block.
-          #
-          # @param text [String] the block to indent
-          # @param base [String] the whitespace to put in front of each non-blank line
-          # @return [String] the block, indented, with blank lines left empty
+          # Indents every non-blank line of a block; blank lines stay empty.
           def indent(text, base)
             text.each_line.map { |line| line.strip.empty? ? line : "#{base}#{line}" }.join
           end
 
-          # Replaces one `# TMPL:<marker>` line of a template with a block.
-          #
-          # The block is written flush-left and takes the marker line's own
-          # indentation. An empty block removes the marker line completely, so
-          # a template that uses none of the optional sections renders exactly
-          # as it did before those sections existed.
-          #
-          # @param template [String] the template holding the marker line
-          # @param marker [String] the marker name, without the `# TMPL:` prefix
-          # @param text [String] the flush-left block to splice in, ending in a newline or empty
-          # @return [String] the template with the marker line replaced
+          # Replaces one `# TMPL:<marker>` line of a template with a block, indented
+          # to the marker's own level; an empty block removes the marker line.
           def splice(template, marker, text)
             template.sub(/^([ \t]*)# TMPL:#{Regexp.escape(marker)}\n/) do
               text.empty? ? "" : indent(text, Regexp.last_match(1))
@@ -90,21 +54,12 @@ module Hecks
 
           # Turns a name such as `mock-payments` into a CloudFormation-safe
           # logical id part: `MockPayments`.
-          #
-          # @param name [String] a name made of letters, digits, `_` and `-`
-          # @return [String] the name in camel case, letters and digits only
           def camel(name)
             name.to_s.split(/[^a-zA-Z0-9]+/).reject(&:empty?).map { |part| part[0].upcase + part[1..] }.join
           end
 
-          # Finds keys declared more than once at one indentation in a section.
-          #
-          # YAML loaders keep the last of a repeated key without complaint, so
-          # two resources given the same logical id would silently drop one.
-          #
-          # @param section [String] the text of a `Resources:` or `Parameters:` section
-          # @param indent [Integer] the indentation of the keys to check
-          # @return [Array<String>] the keys that appear more than once
+          # Finds keys declared more than once at one indentation in a section, since
+          # YAML loaders silently keep the last and drop the others.
           def duplicate_keys(section, indent: 2)
             keys = section.scan(/^ {#{indent}}([A-Za-z0-9]+):(?:\s|$)/).flatten
             keys.tally.select { |_key, count| count > 1 }.keys