hecks 2.5.1 → 2.7.0

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

@@ -0,0 +1,193 @@
+require_relative "yaml"
+require_relative "settings"
+
+module Hecks
+  module Projections
+    module Deploy
+      module Fargate
+        # Fills the optional sections of a rendered Fargate template.
+        #
+        # The template text carries `# TMPL:<name>` marker lines where an
+        # optional section belongs. `apply` replaces each with what the stack's
+        # `Settings::Plan` calls for, and with nothing when the plan sets
+        # nothing there, so a world that uses none of the optional settings
+        # renders the template it always did.
+        module Assembly
+          module_function
+
+          # Replaces every optional-section marker in a rendered template.
+          #
+          # @param template [String] the rendered template holding `# TMPL:` marker lines
+          # @param plan [Settings::Plan] the stack's checked optional settings
+          # @param context [Hash{Symbol => Object}] `:stack_name`, `:vpc_ref`, `:listener_id`,
+          #   `:alb_id`, `:distribution_id` and `:db_secret_ref`
+          # @return [String] the template with the markers replaced
+          # @raise [ArgumentError] if `domain_env` removes a variable the generator does not set, or
+          #   the finished template declares one logical id or parameter twice
+          def apply(template, plan, context)
+            text = override_domain_env(template, plan.domain_env)
+            sections(plan, context).each { |marker, block| text = Yaml.splice(text, marker, block) }
+            check_duplicates!(text)
+            text
+          end
+
+          def sections(plan, context)
+            {
+              "domain_essential"          => domain_essential_yaml(plan.layout.domain),
+              "session_secret_properties" => session_secret_yaml(plan.extras[:session_secret]),
+              "execution_database_grant"  => execution_grant_yaml(plan, context),
+              "extra_execution_policies"  => Extras.policies_yaml(plan.extras[:execution_policies]),
+              "extra_task_policies"       => task_policies_yaml(plan),
+              "domain_env"                => domain_env_yaml(plan.domain_env),
+              "extra_containers"          => lines(Containers.definitions_yaml(plan.layout, plan.ids[:log_group])),
+              "target_group_attributes"   => Containers.target_group_attributes_yaml(plan.deregistration_delay),
+              "extra_target_groups"       => target_groups_yaml(plan, context),
+              "service_tuning"            => service_tuning_yaml(plan),
+              "extra_load_balancers"      => Containers.load_balancers_yaml(plan.layout),
+              "distribution"              => distribution_yaml(plan, context),
+              "extra_resources"           => extra_resources_yaml(plan, context),
+              "extra_outputs"             => outputs_yaml(plan)
+            }
+          end
+          private_class_method :sections
+
+          # Removes each default environment entry the world overrides, with the comments above it.
+          def override_domain_env(template, domain_env)
+            domain_env.keys.reduce(template) do |text, name|
+              entry = /(?:^[ \t]*#.*\n)*^[ \t]*- Name: #{Regexp.escape(name)}\n[ \t]+Value: .*\n/
+              if text.match?(entry)
+                text.sub(entry, "")
+              elsif domain_env[name].nil?
+                raise ArgumentError,
+                      "domain_env #{name} is nil, which removes a default variable, but the generator sets no #{name}"
+              else
+                text
+              end
+            end
+          end
+          private_class_method :override_domain_env
+
+          def execution_grant_yaml(plan, context)
+            return "" unless plan.execution_database_grant
+
+            <<~GRANT
+              - PolicyName: DbSecretRead
+                PolicyDocument:
+                  Version: '2012-10-17'
+                  Statement:
+                    - Effect: Allow
+                      Action: secretsmanager:GetSecretValue
+                      Resource: !Sub "${#{context[:db_secret_ref]}}"
+            GRANT
+          end
+          private_class_method :execution_grant_yaml
+
+          def domain_essential_yaml(domain)
+            domain.essential.nil? ? "" : "Essential: #{domain.essential}\n"
+          end
+          private_class_method :domain_essential_yaml
+
+          def domain_env_yaml(domain_env)
+            domain_env.compact.map do |name, value|
+              "- Name: #{name}\n  Value: #{Yaml.string(value)}\n"
+            end.join
+          end
+          private_class_method :domain_env_yaml
+
+          def session_secret_yaml(given)
+            [("Name: #{given[:name]}\n" if given[:name]),
+             ("Description: #{Yaml.string(given[:description])}\n" if given[:description])].compact.join
+          end
+          private_class_method :session_secret_yaml
+
+          def task_policies_yaml(plan)
+            Extras.policies_yaml(plan.extras[:task_policies]) + (plan.execute_command ? Extras.execute_command_policy_yaml : "")
+          end
+          private_class_method :task_policies_yaml
+
+          def service_tuning_yaml(plan)
+            lines = []
+            lines << "EnableExecuteCommand: true" if plan.execute_command
+            lines << "HealthCheckGracePeriodSeconds: #{plan.health_check_grace_period}" if plan.health_check_grace_period
+            lines.empty? ? "" : "#{lines.join("\n")}\n"
+          end
+          private_class_method :service_tuning_yaml
+
+          def target_groups_yaml(plan, context)
+            blocks(
+              [
+                Containers.target_groups_yaml(plan.layout, context[:vpc_ref], plan.deregistration_delay),
+                Containers.listener_rules_yaml(plan.layout, context[:listener_id])
+              ].reject(&:empty?).join("\n\n")
+            )
+          end
+          private_class_method :target_groups_yaml
+
+          def distribution_yaml(plan, context)
+            ids = { distribution_id: context[:distribution_id], alb_id: context[:alb_id] }
+            plan.cdn ? Cdn.yaml(plan.cdn, **ids) : Cdn.default_yaml(**ids)
+          end
+          private_class_method :distribution_yaml
+
+          def monitoring_context(plan, context, groups)
+            { ids: plan.ids, stack_name: context[:stack_name], alb_id: context[:alb_id],
+              distribution_id: context[:distribution_id], target_groups: groups }
+          end
+          private_class_method :monitoring_context
+
+          def extra_resources_yaml(plan, context)
+            alerts = plan.alerts
+            groups = plan.layout.balanced.to_h { |container| [container.name, container.target_group_id] }
+            monitoring = alerts ? Monitoring.yaml(alerts, monitoring_context(plan, context, groups)) : ""
+            blocks([Containers.repositories_yaml(plan.layout), Extras.resources_yaml(plan.extras),
+                    monitoring.rstrip].reject(&:empty?).join("\n\n"))
+          end
+          private_class_method :extra_resources_yaml
+
+          # Adds one output per added container's repository, plus the cluster and service names a
+          # deploy script needs to find the running service.
+          def outputs_yaml(plan)
+            listed = plan.layout.multi? ? container_outputs(plan) : ""
+            alerts = plan.alerts ? "AlertsTopicArn:\n  Value: !Ref #{plan.ids[:alerts_topic]}\n" : ""
+            listed + alerts + Extras.outputs_yaml(plan.extras[:outputs])
+          end
+          private_class_method :outputs_yaml
+
+          def container_outputs(plan)
+            repositories = plan.layout.all.map do |container|
+              "#{Yaml.camel(container.name)}RepositoryUri:\n  Value: !GetAtt #{container.repository_id}.RepositoryUri\n"
+            end
+            cluster = "ClusterName:\n  Value: !Ref #{plan.ids[:cluster]}\n"
+            service = "ServiceName:\n  Value: !GetAtt #{plan.ids[:service]}.Name\n"
+            cluster + service + repositories.join
+          end
+          private_class_method :container_outputs
+
+          # Joins resource blocks so the section ends in the blank line the template expects before
+          # the next resource, and is empty when there is nothing to add.
+          def blocks(text)
+            text.empty? ? "" : "#{text}\n\n"
+          end
+          private_class_method :blocks
+
+          # Ends a block in one newline, and leaves an empty block empty.
+          def lines(text)
+            text.empty? ? "" : "#{text}\n"
+          end
+          private_class_method :lines
+
+          def check_duplicates!(template)
+            resources = template[/^Resources:\n(.*?)^Outputs:/m, 1].to_s
+            parameters = template[/^Parameters:\n(.*?)^Resources:/m, 1].to_s
+            repeated = Yaml.duplicate_keys(resources) + Yaml.duplicate_keys(parameters)
+            unless repeated.empty?
+              raise ArgumentError, "logical id or parameter #{repeated.uniq.join(', ')} is declared more than once; " \
+                                   "check logical_ids, containers and parameters for clashes"
+            end
+          end
+          private_class_method :check_duplicates!
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,318 @@
+require_relative "check"
+require_relative "yaml"
+require_relative "cdn_default"
+
+module Hecks
+  module Projections
+    module Deploy
+      module Fargate
+        # The CloudFront distribution in front of the load balancer.
+        #
+        # With no `cdn` setting the stack gets `default_yaml`: the default
+        # certificate, one origin, and one behavior that caches nothing. A
+        # `cdn` setting replaces that with a distribution described by the
+        # world.
+        #
+        # ## Settings
+        #
+        # `cdn` is a hash with these optional keys:
+        #
+        # - `aliases`: hostnames the distribution answers to. Needs `certificate_arn`.
+        # - `certificate_arn`: an `ACM` certificate in us-east-1, or an intrinsic such as
+        #   `"!Ref CertArn"`.
+        # - `minimum_protocol`: the TLS policy for the certificate; `TLSv1.2_2021` by default.
+        # - `origin_id`: the id of the load-balancer origin; `<AlbId>Origin` by default.
+        # - `origin_ssl_protocols`: the TLS versions CloudFront may use to reach the origin, such
+        #   as `["TLSv1.2"]`.
+        # - `explicit_origin_ports`: false leaves `HTTPPort` and `HTTPSPort` unset; true by
+        #   default.
+        # - `origin_secret`: `{header:, parameter:}` sends a secret header to the origin, filled
+        #   from a `NoEcho` template parameter the stack declares under that name.
+        # - `extra_origins`: S3 origins, each `{id:, domain_name:, origin_access_control_id:}`.
+        # - `default_behavior`: `{origin:, viewer_protocol:, methods:, compress:, cache_policy:,
+        #   origin_request_policy:}`.
+        # - `behaviors`: entries of the same shape with a required `path`; the first match wins,
+        #   so order matters.
+        # - `retain`: true keeps the distribution when the stack is deleted or replaces it.
+        #
+        # A cache or origin-request policy is a managed policy's name (`caching_disabled`,
+        # `caching_optimized`, `all_viewer`, `all_viewer_except_host`, or `none` to omit an origin
+        # request policy) or the id of a policy in the account. `methods` is `all`, `read` or
+        # `get_head`.
+        module Cdn
+          module_function
+
+          MANAGED_POLICIES = {
+            "caching_disabled"       => ["4135ea2d-6df8-44a3-9df3-4b5a84be39ad", "Managed-CachingDisabled"],
+            "caching_optimized"      => ["658327ea-f89d-4fab-a63d-7e88639e58f6", "Managed-CachingOptimized"],
+            "all_viewer"             => ["216adef6-5c7f-47e4-b989-5492eafa07d3", "Managed-AllViewer"],
+            "all_viewer_except_host" => ["b689b0a8-53d0-40ab-baf2-68738e2966ac", "Managed-AllViewerExceptHostHeader"]
+          }.freeze
+          METHODS = {
+            "all"      => %w[GET HEAD OPTIONS PUT POST PATCH DELETE],
+            "read"     => %w[GET HEAD OPTIONS],
+            "get_head" => %w[GET HEAD]
+          }.freeze
+          PROTOCOLS = %w[allow-all https-only redirect-to-https].freeze
+          KEYS = [
+            :aliases, :certificate_arn, :minimum_protocol, :origin_id, :origin_ssl_protocols, :explicit_origin_ports,
+            :origin_secret, :extra_origins, :default_behavior, :behaviors, :retain
+          ].freeze
+          BEHAVIOR_KEYS = [:origin, :viewer_protocol, :methods, :compress, :cache_policy, :origin_request_policy].freeze
+          UUID = /\A[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}\z/
+          ACM_ARN = %r{\Aarn:aws:acm:us-east-1:\d{12}:certificate/[A-Za-z0-9-]+\z}
+          HOSTNAME = /\A(\*\.)?([A-Za-z0-9]([A-Za-z0-9-]*[A-Za-z0-9])?\.)+[A-Za-z]{2,}\z/
+
+          # Reads and checks the `cdn` setting.
+          #
+          # @param setting [Hash, nil] the world's `cdn` value, or nil when it sets none
+          # @param default_origin_id [String] the load-balancer origin's id when `origin_id` is not
+          #   set
+          # @return [Hash{Symbol => Object}, nil] the checked options with defaults applied, or nil
+          #   for none
+          # @raise [ArgumentError] if an option is unknown, malformed, or names an origin that does
+          #   not exist
+          def normalize(setting, default_origin_id:)
+            return nil if setting.nil?
+
+            given = Check.hash!(setting, "cdn", allowed: KEYS)
+            options = base_options(given, default_origin_id)
+            options[:extra_origins] = extra_origins(given.fetch(:extra_origins, []))
+            origins = [options[:origin_id], *options[:extra_origins].map { |origin| origin[:id] }]
+            check_unique!(origins, "cdn origin ids")
+            options[:default_behavior] =
+              behavior(given.fetch(:default_behavior, {}), "cdn default_behavior", options, origins, path: false)
+            options[:behaviors] = behaviors(given.fetch(:behaviors, []), options, origins)
+            options
+          end
+
+          # Lists the template parameters the options need.
+          #
+          # @param options [Hash, nil] the checked options from `normalize`
+          # @return [String] flush-left parameter text, or empty
+          def parameters_yaml(options)
+            secret = options && options[:origin_secret]
+            return "" unless secret
+
+            <<~PARAMETER
+              #{secret[:parameter]}:
+                Type: String
+                NoEcho: true
+                Description: Secret header value CloudFront sends to the origin, so the origin can tell its own traffic.
+            PARAMETER
+          end
+
+          # Renders the distribution for a set of checked options.
+          #
+          # @param options [Hash] the checked options from `normalize`
+          # @param distribution_id [String] the logical id the distribution is given
+          # @param alb_id [String] the logical id of the load balancer the origin points at
+          # @return [String] the flush-left resource text ending in a newline
+          def yaml(options, distribution_id:, alb_id:)
+            lines = ["#{distribution_id}:", "  Type: AWS::CloudFront::Distribution"]
+            lines.push("  DeletionPolicy: Retain", "  UpdateReplacePolicy: Retain") if options[:retain]
+            lines.push("  Properties:", "    DistributionConfig:", "      Enabled: true", "      HttpVersion: http2")
+            lines.concat(alias_lines(options), certificate_lines(options), origin_lines(options, alb_id))
+            lines.concat(behavior_lines("DefaultCacheBehavior", options[:default_behavior], "      "))
+            lines << "      CacheBehaviors:" unless options[:behaviors].empty?
+            options[:behaviors].each { |entry| lines.concat(behavior_lines(nil, entry, "        ")) }
+            "#{lines.join("\n")}\n"
+          end
+
+          def behaviors(entries, options, origins)
+            Check.hashes!(entries, "cdn behaviors", allowed: BEHAVIOR_KEYS + [:path], required: [:path]).map do |entry|
+              behavior(entry, "cdn behaviors[#{entry[:path]}]", options, origins, path: true)
+            end
+          end
+          private_class_method :behaviors
+
+          def base_options(given, default_origin_id)
+            aliases = Check.strings!(given.fetch(:aliases, []), "cdn aliases")
+            bad = aliases.grep_v(HOSTNAME)
+            raise ArgumentError, "cdn aliases must be hostnames, got #{bad.join(', ')}" unless bad.empty?
+
+            certificate = given[:certificate_arn]&.to_s
+            if !aliases.empty? && certificate.nil?
+              raise ArgumentError,
+                    "cdn aliases need a certificate_arn, since CloudFront serves an alias only over a certificate"
+            end
+
+            {
+              aliases: aliases, certificate_arn: certificate_arn(certificate),
+              minimum_protocol: given.fetch(:minimum_protocol, "TLSv1.2_2021").to_s,
+              origin_id: Check.logical_id!(given.fetch(:origin_id, default_origin_id), "cdn origin_id"),
+              origin_ssl_protocols: Check.strings!(given.fetch(:origin_ssl_protocols, []), "cdn origin_ssl_protocols"),
+              explicit_origin_ports: Check.boolean!(given.fetch(:explicit_origin_ports, true), "cdn explicit_origin_ports"),
+              origin_secret: origin_secret(given[:origin_secret]),
+              retain: Check.boolean!(given.fetch(:retain, false), "cdn retain")
+            }
+          end
+          private_class_method :base_options
+
+          def certificate_arn(value)
+            return nil if value.nil?
+            return value if value.start_with?("!") || ACM_ARN.match?(value)
+
+            raise ArgumentError,
+                  "cdn certificate_arn must be an ACM certificate ARN in us-east-1 (CloudFront reads no other region) " \
+                  "or an intrinsic, got #{value.inspect}"
+          end
+          private_class_method :certificate_arn
+
+          def origin_secret(value)
+            return nil if value.nil?
+
+            secret = Check.hash!(value, "cdn origin_secret", allowed: [:header, :parameter], required: [:header, :parameter])
+            unless secret[:header].to_s.match?(/\A[A-Za-z0-9-]+\z/)
+              raise ArgumentError,
+                    "cdn origin_secret header must be an HTTP header name, got #{secret[:header].inspect}"
+            end
+
+            { header: secret[:header].to_s, parameter: Check.logical_id!(secret[:parameter], "cdn origin_secret parameter") }
+          end
+          private_class_method :origin_secret
+
+          def extra_origins(entries)
+            Check.hashes!(entries, "cdn extra_origins", allowed:  [:id, :domain_name, :origin_access_control_id],
+                                                        required: [:id, :domain_name]).map do |entry|
+              { id: Check.logical_id!(entry[:id], "cdn extra_origins id"), domain_name: entry[:domain_name].to_s,
+                origin_access_control_id: entry[:origin_access_control_id]&.to_s }
+            end
+          end
+          private_class_method :extra_origins
+
+          def check_unique!(values, what)
+            repeated = values.tally.select { |_value, count| count > 1 }.keys
+            raise ArgumentError, "#{what} must be unique; repeated: #{repeated.join(', ')}" unless repeated.empty?
+          end
+          private_class_method :check_unique!
+
+          def behavior(entry, where, options, origins, path:)
+            given = Check.hash!(entry, where, allowed: BEHAVIOR_KEYS + (path ? [:path] : []))
+            origin = given.fetch(:origin, options[:origin_id]).to_s
+            unless origins.include?(origin)
+              raise ArgumentError,
+                    "#{where} origin #{origin.inspect} is not one of #{origins.join(', ')}"
+            end
+
+            balanced = origin == options[:origin_id]
+            result = {
+              origin: origin, methods: allowed_methods(given.fetch(:methods, path ? "read" : "all"), where),
+              viewer_protocol: Check.one_of!(given.fetch(:viewer_protocol, "redirect-to-https"), "#{where} viewer_protocol",
+                                             PROTOCOLS),
+              cache_policy: policy(given.fetch(:cache_policy, "caching_disabled"), "#{where} cache_policy"),
+              origin_request_policy: policy(given.fetch(:origin_request_policy, balanced ? "all_viewer" : "none"),
+                                            "#{where} origin_request_policy", none: true)
+            }
+            result[:compress] = Check.boolean!(given[:compress], "#{where} compress") if given.key?(:compress)
+            result[:compress] = true if !path && !given.key?(:compress)
+            result[:path] = path_pattern(given[:path], where) if path
+            result
+          end
+          private_class_method :behavior
+
+          def path_pattern(value, where)
+            text = value.to_s
+            raise ArgumentError, "#{where} path must start with / or *, got #{text.inspect}" unless text.start_with?("/", "*")
+
+            text
+          end
+          private_class_method :path_pattern
+
+          def allowed_methods(value, where)
+            return Check.strings!(value, "#{where} methods", min: 1) if value.is_a?(Array)
+            return METHODS.fetch(value.to_s) if METHODS.key?(value.to_s)
+
+            raise ArgumentError,
+                  "#{where} methods must be #{METHODS.keys.join(', ')} or a list of HTTP methods, got #{value.inspect}"
+          end
+          private_class_method :allowed_methods
+
+          def policy(value, where, none: false)
+            text = value.to_s
+            return nil if none && text == "none"
+            return MANAGED_POLICIES.fetch(text) if MANAGED_POLICIES.key?(text)
+            return [text, nil] if UUID.match?(text)
+
+            raise ArgumentError,
+                  "#{where} must be #{MANAGED_POLICIES.keys.join(', ')}#{', none' if none}, or a policy id, got #{value.inspect}"
+          end
+          private_class_method :policy
+
+          def alias_lines(options)
+            return [] if options[:aliases].empty?
+
+            ["      Aliases:"] + options[:aliases].map { |name| "        - #{name}" }
+          end
+          private_class_method :alias_lines
+
+          def certificate_lines(options)
+            return ["      ViewerCertificate:", "        CloudFrontDefaultCertificate: true"] unless options[:certificate_arn]
+
+            ["      ViewerCertificate:", "        AcmCertificateArn: #{options[:certificate_arn]}",
+             "        SslSupportMethod: sni-only", "        MinimumProtocolVersion: #{options[:minimum_protocol]}"]
+          end
+          private_class_method :certificate_lines
+
+          def origin_lines(options, alb_id)
+            ["      Origins:"] + alb_origin_lines(options, alb_id) + options[:extra_origins].flat_map do |origin|
+              s3_origin_lines(origin)
+            end
+          end
+          private_class_method :origin_lines
+
+          def alb_origin_lines(options, alb_id)
+            lines = ["        - Id: #{options[:origin_id]}", "          DomainName: !GetAtt #{alb_id}.DNSName"]
+            secret = options[:origin_secret]
+            if secret
+              lines.push("          OriginCustomHeaders:", "            - HeaderName: #{secret[:header]}",
+                         "              HeaderValue: !Ref #{secret[:parameter]}")
+            end
+            lines << "          CustomOriginConfig:"
+            lines << "            OriginProtocolPolicy: http-only"
+            lines.push("            HTTPPort: 80", "            HTTPSPort: 443") if options[:explicit_origin_ports]
+            unless options[:origin_ssl_protocols].empty?
+              lines << "            OriginSSLProtocols: #{Yaml.flow_list(options[:origin_ssl_protocols])}"
+            end
+            lines
+          end
+          private_class_method :alb_origin_lines
+
+          def s3_origin_lines(origin)
+            lines = ["        - Id: #{origin[:id]}", "          DomainName: #{Yaml.string(origin[:domain_name])}"]
+            if origin[:origin_access_control_id]
+              lines << "          OriginAccessControlId: #{Yaml.string(origin[:origin_access_control_id])}"
+            end
+            lines << "          S3OriginConfig: { OriginAccessIdentity: \"\" }"
+            lines
+          end
+          private_class_method :s3_origin_lines
+
+          def behavior_lines(key, entry, base)
+            pad = "#{base}  "
+            head = key ? "#{base}#{key}:" : "#{base}- PathPattern: #{Yaml.string(entry[:path])}"
+            [head, "#{pad}TargetOriginId: #{entry[:origin]}", *behavior_property_lines(entry, pad)]
+          end
+          private_class_method :behavior_lines
+
+          def behavior_property_lines(entry, pad)
+            lines = ["#{pad}ViewerProtocolPolicy: #{entry[:viewer_protocol]}",
+                     "#{pad}AllowedMethods: #{Yaml.flow_list(entry[:methods])}",
+                     "#{pad}CachedMethods: [GET, HEAD]"]
+            lines << "#{pad}Compress: #{entry[:compress]}" if entry.key?(:compress)
+            lines << policy_line(pad, "CachePolicyId", entry[:cache_policy])
+            lines << policy_line(pad, "OriginRequestPolicyId", entry[:origin_request_policy]) if entry[:origin_request_policy]
+            lines
+          end
+          private_class_method :behavior_property_lines
+
+          def policy_line(pad, key, policy)
+            id, label = policy
+            label ? "#{pad}#{key}: #{id} # #{label}" : "#{pad}#{key}: #{id}"
+          end
+          private_class_method :policy_line
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,87 @@
+module Hecks
+  module Projections
+    module Deploy
+      module Fargate
+        # The default distribution's text; `cdn.rb` documents the module.
+        module Cdn
+          module_function
+
+          # The distribution a stack gets when its world sets no `cdn` options.
+          #
+          # Real HTTPS in front of the load balancer's HTTP-only listener, and
+          # the one safe caching default the generator can offer: every route
+          # is treated as session-driven, so nothing is cached. The comment
+          # inside the rendered block explains why, and reaches the generated
+          # template unchanged.
+          #
+          # @param alb_id [String] the logical id of the load balancer
+          # @param distribution_id [String] the logical id the distribution is given
+          # @return [String] the flush-left resource text with its comments, ending in a newline
+          def default_yaml(alb_id:, distribution_id:)
+            <<~DEFAULT
+              # Real HTTPS (the ALB's own Listener above is HTTP-only —
+              # nothing else in this stack terminates TLS) and, just as
+              # important, the ONE safe default this generator can offer
+              # for caching it has no way to reason about: Managed-
+              # CachingDisabled. This domain's own routes — including
+              # every hecks-native /login, /logout, /auth/google(/callback),
+              # /admin/members request (web.rs's own auth_gate/auth_route,
+              # generic across every domain, not just this one's own
+              # dispatch commands) — are all session-cookie-driven, and
+              # this generator has no way to tell which of a domain's own
+              # paths would ever be safe to cache. Found live, the hard
+              # way (2026-09-21): a hand-authored CloudFront
+              # stack applied the OPPOSITE default — a custom, cookie-
+              # blind cache policy with a 90-120s TTL — and it served one
+              # signed-in session's own response (a short-lived SSO
+              # handoff token among them) back to a different, unrelated
+              # request within that window. A domain that DOES know one
+              # of its own paths is genuinely safe to cache (a public,
+              # non-personalized page) adds its own more specific
+              # CacheBehavior through the `cdn` setting's `behaviors`,
+              # never by loosening this one.
+              #{distribution_id}:
+                Type: AWS::CloudFront::Distribution
+                Properties:
+                  DistributionConfig:
+                    Enabled: true
+                    HttpVersion: http2
+                    # No ACM/custom domain by default — CloudFront requires
+                    # an ACM cert in us-east-1 specifically to attach a
+                    # custom Aliases entry, a real cross-region dependency
+                    # this generator can't assume. CloudFront's own default
+                    # *.cloudfront.net certificate/hostname are what
+                    # Outputs.CloudFrontDomain below reports; the `cdn`
+                    # setting's `aliases` and `certificate_arn` attach a
+                    # real domain.
+                    ViewerCertificate:
+                      CloudFrontDefaultCertificate: true
+                    Origins:
+                      - Id: #{alb_id}Origin
+                        DomainName: !GetAtt #{alb_id}.DNSName
+                        CustomOriginConfig:
+                          OriginProtocolPolicy: http-only
+                          HTTPPort: 80
+                          HTTPSPort: 443
+                    DefaultCacheBehavior:
+                      TargetOriginId: #{alb_id}Origin
+                      ViewerProtocolPolicy: redirect-to-https
+                      Compress: true
+                      AllowedMethods: [GET, HEAD, OPTIONS, PUT, PATCH, POST, DELETE]
+                      CachedMethods: [GET, HEAD]
+                      # Managed-CachingDisabled — see this resource's own
+                      # header comment for why nothing else is safe here
+                      # by default.
+                      CachePolicyId: 4135ea2d-6df8-44a3-9df3-4b5a84be39ad
+                      # Managed-AllViewer — forwards every cookie/header/
+                      # query string through uncached, so rust/host's own
+                      # session-cookie-based auth sees the real request
+                      # exactly as the browser sent it.
+                      OriginRequestPolicyId: 216adef6-5c7f-47e4-b989-5492eafa07d3
+            DEFAULT
+          end
+        end
+      end
+    end
+  end
+end