hecks 3.10.0 → 3.12.0

data/lib/hecks/ports/persistence/plugins/era/era_check.rb

@@ -126,7 +126,7 @@ module Hecks
       #   skips the vendored lookup
       # @return [Array<String>] file paths to read, in load order; `[]` when none applies
       def fallback_source_files(bluebook, directory, domain_files, registry)
-        vendored_name = registry && vendored_bluebook_name_for(registry, bluebook.name)
+        vendored_name = registry && vendored_bluebook_name_for(registry, bluebook.name, directory)
         framework_path = Framework.members[bluebook.name]
         return [framework_path] if framework_path
         return vendored_source_for(directory, vendored_name) if vendored_name
@@ -139,19 +139,30 @@ module Hecks
 
       # Recovers the vendored package name behind a bluebook, if some hecksagon vendored it.
       #
-      # Matched by Pascal-casing: the vendored name Pascal-cases to this
-      # bluebook's own declared name.
+      # Matched first by Pascal-casing (the package name Pascal-cases to the bluebook's declared
+      # name), then by the package's own files: a package whose chapter is named otherwise (the
+      # package `gallery` declaring `Galleries`) is the one whose files declare that name.
       #
       # @param registry [Runtime::Registry] the registry whose hecksagons are searched
       # @param bluebook_name [String] the bluebook's declared Pascal-case name
+      # @param directory [String] path of the domain's own bluebook directory, whose parent
+      #   holds `vendor/embryonaut_bluebooks`
       # @return [String, nil] the package name as written in `attaches ... from: :vendor`; nil
-      #   when no hecksagon vendored a package whose name Pascal-cases to `bluebook_name`
-      def vendored_bluebook_name_for(registry, bluebook_name)
-        registry.hecksagons.each_value do |hecksagon|
-          match = hecksagon.vendored_packages.find { |name| Naming.pascal(name) == bluebook_name }
-          return match if match
-        end
-        nil
+      #   when no vendored package matches `bluebook_name` by name or by declaration
+      def vendored_bluebook_name_for(registry, bluebook_name, directory)
+        names = registry.hecksagons.each_value.flat_map(&:vendored_packages).uniq
+        names.find { |name| Naming.pascal(name) == bluebook_name } ||
+          names.find { |name| declared_by_package?(directory, name, bluebook_name) }
+      end
+
+      # Asks whether any file of a vendored package opens the named bluebook.
+      #
+      # @param directory [String] path of the domain's own bluebook directory
+      # @param package [String] the vendored package name
+      # @param bluebook_name [String] the declared bluebook name looked for
+      # @return [Boolean] true when some `.bluebook` file of the package declares `bluebook_name`
+      def declared_by_package?(directory, package, bluebook_name)
+        vendored_source_for(directory, package).any? { |path| declares_bluebook?(path, bluebook_name) }
       end
 
       # Lists the `.bluebook` files a vendored embryonaut package ships.

data/lib/hecks/ports/persistence/plugins/era/postgres_era/boot.rb

@@ -1,3 +1,5 @@
+require_relative "../../../../../indifferent_key"
+
 module Hecks
   module Adapters
     class PostgresEra
@@ -17,11 +19,11 @@ module Hecks
         # Coalesce instead of `setting` for the era: the factory always passes `era:`, nil until
         # the boot gate resolves it, and nil can never be a real override.
         def resolve_era!(settings)
-          @era = settings.key?(:era) ? settings[:era] : settings["era"]
+          @era = IndifferentKey.read(settings, :era)
           @era ||= @lineage.current_era
           # Non-nil only for a held-but-superseded boot. `append` and `atomic_put` refuse on it
           # because a superuser walks through the RLS fence.
-          @superseded_by = settings.key?(:superseded_by) ? settings[:superseded_by] : settings["superseded_by"]
+          @superseded_by = IndifferentKey.read(settings, :superseded_by)
         end
 
         def provision!

data/lib/hecks/ports/persistence/plugins/era/postgres_era/lineage_manager/era_resolver.rb

@@ -1,6 +1,7 @@
 require_relative "../lineage"
 require_relative "../../storage_shape"
 require_relative "context"
+require_relative "../../../../../../indifferent_key"
 
 module Hecks
   module Adapters
@@ -22,7 +23,7 @@ module Hecks
             lineage.check_fence_applies!(allow_superuser: PostgresEra.setting(settings, :allow_superuser, default: false))
             lineage.ensure_base!
             # key? first, never `||`: a stored `false` must not read as an absent key.
-            role = settings.key?(:role) ? settings[:role] : settings["role"]
+            role = IndifferentKey.read(settings, :role)
             resolve_era(Context.new(registry: registry, bluebook: bluebook, current_text: current_text,
                                     lineage: lineage, role: role, directory: directory))
           ensure

data/lib/hecks/ports/persistence/repository_factory.rb

@@ -26,7 +26,7 @@ module Hecks
         # @raise [ArgumentError] on an unknown option
         def build(registry, domain, aggregate, bind, **)
           opts = BuildOptions.new(**)
-          settings = adapter_settings(registry, domain, bind, opts.settings_verb)
+          settings = adapter_settings(registry, domain, aggregate, bind, opts.settings_verb)
           adapter = registry.adapter_class(bind.adapter).new(aggregate: aggregate, settings: settings, root: registry.root)
           repository = AppendOnly.new(CodecBoundary.guard!(adapter))
           # `:atomic_append` (PostgresEra) means `append` already committed the
@@ -39,14 +39,17 @@ module Hecks
         #
         # @param registry [Runtime::Registry] the booted registry
         # @param domain [String, Symbol] the domain the aggregate belongs to
+        # @param aggregate [Bluebook::Aggregate] the aggregate the adapter is built for
         # @param bind [Bluebook::Bind] the bind naming the adapter
         # @param settings_verb [String] the verb whose settings configure the adapter
-        # @return [Hash] the declared settings plus the domain, resolved era and superseding era
-        def adapter_settings(registry, domain, bind, settings_verb)
+        # @return [Hash] the declared settings, under the adapter's own declared defaults, plus
+        #   the domain, resolved era and superseding era
+        def adapter_settings(registry, domain, aggregate, bind, settings_verb)
           registry.check_verb(bind)
           settings = registry.binding_settings(domain, settings_verb, bind.adapter)
                              .reject { |key, _| key.to_sym == :role }
           registry.check_settings(bind, settings)
+          settings = registry.with_adapter_defaults(bind.adapter, aggregate, settings)
           # domain, resolved era and superseding era ride along outside the declared
           # settings: a lineage adapter needs them to journal per domain, per-era.
           settings.merge(domain: domain.to_s, era: registry.resolved_eras[domain.to_s],

data/lib/hecks/projection_files/expression_tables.rb

@@ -47,10 +47,15 @@ module Hecks
         declared = algebra.fetch(operator[:symbol]) do
           raise Refused, "#{operator[:symbol]} is admitted but Vocabulary::Comparison declares no algebra for it"
         end
-        row.merge(compares_less_than: declared[:compares_less_than],
-                  compares_equal: declared[:compares_equal], negated: declared[:negated])
+        row.merge(compares_less_than: spelled_true?(declared[:compares_less_than]),
+                  compares_equal:     spelled_true?(declared[:compares_equal]),
+                  negated:            spelled_true?(declared[:negated]))
       end
 
+      # @param cell [Object] a `Comparison` cell, declared as the text `"true"` or `"false"`
+      # @return [Boolean] whether the cell spells true
+      def spelled_true?(cell) = cell.to_s == "true"
+
       # @param dropped [Hash{String => Array<String>}] operator to the guards evaluating through it
       # @return [String] one line for each operator a projection would strand
       def dropped_message(dropped)

data/lib/hecks/projections/deploy/box/compose.rb

@@ -13,11 +13,13 @@ module Hecks
           #   an ECS task definition when the world names one
           def render_compose_sh(plan, region)
             if plan.task_definition
-              template("render-compose-taskdef.sh.tmpl", "STACK" => plan.infra_name, "FAMILY" => plan.task_definition,
-                                                          "PROXY_IMAGE" => plan.proxy_image)
+              template("render-compose-taskdef.sh.tmpl",
+                       { "STACK" => plan.infra_name, "FAMILY" => plan.task_definition, "PROXY_IMAGE" => plan.proxy_image }
+                         .merge(compose_log_values(plan, region, "$s.name")))
             else
-              template("render-compose.sh.tmpl", "STACK" => plan.infra_name, "REGION" => region,
-                                                 "DB_NAME" => plan.database_name, "PROXY_IMAGE" => plan.proxy_image)
+              template("render-compose.sh.tmpl",
+                       { "STACK" => plan.infra_name, "REGION" => region, "DB_NAME" => plan.database_name,
+                         "PROXY_IMAGE" => plan.proxy_image }.merge(compose_log_values(plan, region, ".name")))
             end
           end
 

data/lib/hecks/projections/deploy/box/edge.rb

@@ -0,0 +1,62 @@
+module Hecks
+  module Projections
+    module Deploy
+      module Box
+        # The CloudFront edge of a box deploy, for a world that declares `cdn`: the `edge.yaml`
+        # stack, the `edge.mk` that deploys it, and the two pieces `make stacks` gains so the box
+        # admits the CDN's addresses. Mixed into `Box`, which supplies `template`.
+        module Edge
+          # The AWS-managed prefix list of CloudFront's origin-facing addresses. Its id differs in
+          # every region, so it is looked up by this name rather than written down.
+          PREFIX_LIST_NAME = "com.amazonaws.global.cloudfront.origin-facing".freeze
+
+          # @param plan [Settings::Plan] the resolved settings
+          # @param region [String] the validated region
+          # @return [Hash{String => String}] `edge.yaml` and `edge.mk`, or nothing without a `cdn`
+          def edge_files(plan, region)
+            return {} unless plan.cdn
+
+            { "edge.yaml" => edge_yaml(plan),
+              "edge.mk"   => template("edge.mk.tmpl", "EDGE_STACK" => plan.edge_stack, "REGION" => region) }
+          end
+
+          # @param plan [Settings::Plan] the resolved settings, with a `cdn`
+          # @return [String] the CloudFront stack
+          def edge_yaml(plan)
+            values = { "STACK" => plan.infra_name, "ALIASES" => plan.cdn.aliases.join(","),
+                       "ORIGIN_HEADER" => plan.origin_header, "ORIGIN_SECRET" => plan.origin_secret }
+            template("edge.yaml.tmpl", values)
+          end
+
+          # @param plan [Settings::Plan] the resolved settings
+          # @param region [String] the validated region
+          # @return [Hash{String => String}] the Makefile markers `CDN_CHECK` and `CDN_PARAM`:
+          #   empty without a `cdn`, so a world that does not opt in renders the same Makefile
+          def edge_makefile_values(plan, region)
+            return { "CDN_CHECK" => "", "CDN_PARAM" => "" } unless plan.cdn
+
+            { "CDN_CHECK" => prefix_list_check(region), "CDN_PARAM" => "\t\tCdnPrefixListId=#{prefix_list_lookup(region)} \\" }
+          end
+
+          private
+
+          def prefix_list_query(region)
+            "aws ec2 describe-managed-prefix-lists --region #{region} --filters " \
+              "Name=prefix-list-name,Values=#{PREFIX_LIST_NAME} --query \"PrefixLists[0].PrefixListId\" --output text"
+          end
+
+          def prefix_list_lookup(region)
+            "$$(#{prefix_list_query(region)})"
+          end
+
+          # Stops `make stacks` before it changes anything when the prefix list cannot be found,
+          # because a box deployed without it has no inbound rule and the CDN gets a 504.
+          def prefix_list_check(region)
+            "\t@#{prefix_list_query(region)} | grep -q '^pl-' || { echo \"no #{PREFIX_LIST_NAME} " \
+              "prefix list in #{region}: the box would admit no CDN and answer 504\" >&2; exit 1; }"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/hecks/projections/deploy/box/logging.rb

@@ -0,0 +1,99 @@
+module Hecks
+  module Projections
+    module Deploy
+      module Box
+        # Where the box's containers write their logs. With `logs "cloudwatch"` (the default) every
+        # service uses Docker's `awslogs` driver into one log group the box stack creates, one
+        # stream per service, and the box role may write to that group only. With `logs "local"`
+        # the services keep Docker's rotating `json-file` logs, which a roll deletes with the
+        # container.
+        #
+        # `docker logs` keeps working with `awslogs`: Docker's dual-logging cache (Docker 20.10 and
+        # later, which the Amazon Linux 2023 package installs) keeps a local copy for reads.
+        # Mixed into `Box`, which supplies `template`.
+        module Logging
+          LOG_EXIT_CODE = "#   44  the box stack has no log group yet: update the stack (make stacks) before rolling\n".freeze
+          LOG_NOTE = <<~NOTE.freeze
+            # Every container logs to the CloudWatch group the box stack creates. A container whose log
+            # stream cannot be written does not start, so the roll first checks that the stack has the
+            # group (and the role's right to write it) and exits 44 if not. SKIP_LOG_GROUP_CHECK=1 skips it.
+            # `docker logs` and the log capture below still read the box's local copy (Docker's dual-logging cache).
+            #
+          NOTE
+          LOG_GROUP_CHECK = <<~CHECK.freeze
+            if [ "${SKIP_LOG_GROUP_CHECK:-}" = 1 ]; then
+              echo "==> skipping the log group check (SKIP_LOG_GROUP_CHECK=1)"
+            elif ! aws cloudformation describe-stack-resource --stack-name "$BOX_STACK" --logical-resource-id BoxLogGroup >/dev/null 2>&1; then
+              echo "==> $BOX_STACK has no BoxLogGroup: its containers would fail to start on the awslogs driver." >&2
+              echo "    Run make stacks to update box.yaml (log group and the role's logs policy) first, then roll again." >&2
+              exit 44
+            fi
+          CHECK
+          COMPOSE_LOG_NOTE = <<~NOTE.freeze
+            #
+            # Every service logs to the CloudWatch group the box stack creates (one stream per service). A
+            # container whose stream cannot be written does not start, so update the box stack (make stacks:
+            # the group and the role's logs policy) before the first roll that uses this file. `docker logs`
+            # still reads the box's local copy.
+          NOTE
+          JSON_FILE = '{driver: "json-file", options: {"max-size": "10m", "max-file": "3"}}'.freeze
+
+          # @param plan [Settings::Plan] the resolved settings
+          # @return [String] the log group resource spliced into `box.yaml`, or nothing for `local`
+          def log_group_yaml(plan)
+            return "" unless plan.cloudwatch_logs?
+
+            template("log-group.yaml.tmpl", "LOG_GROUP"      => plan.log_group,
+                                            "RETENTION_DAYS" => plan.log_retention_days.to_s)
+          end
+
+          # @param plan [Settings::Plan] the resolved settings
+          # @return [String] the role policy that lets the box write to its log group only, or
+          #   nothing for `local`
+          def log_policy_yaml(plan)
+            plan.cloudwatch_logs? ? template("log-policy.yaml.tmpl", {}) : ""
+          end
+
+          # The values `render-compose.sh` splices in: the jq definition of `log` and the call that
+          # names each service's stream. `local` renders the `json-file` definition and the bare
+          # `log`, so its output does not change.
+          #
+          # @param plan [Settings::Plan] the resolved settings
+          # @param region [String] the validated region
+          # @param service [String] the jq expression for a service's name in the template
+          # @return [Hash{String => String}] the template values
+          def compose_log_values(plan, region, service)
+            return { "COMPOSE_LOG_NOTE" => "", **local_log_values } unless plan.cloudwatch_logs?
+
+            { "COMPOSE_LOG_NOTE" => COMPOSE_LOG_NOTE, "LOG_DEF" => awslogs_definition(plan, region),
+              "LOG_SERVICE" => "log(#{service})", "LOG_CADDY" => 'log("caddy")', "LOG_TUNNEL" => 'log("cloudflared")' }
+          end
+
+          # The `deploy-box.sh` pieces that stop a roll onto a stack without the log group.
+          #
+          # @param plan [Settings::Plan] the resolved settings
+          # @return [Hash{String => String}] the exit-code line, the comment and the check, or empty
+          #   strings for `local`
+          def log_roll_values(plan)
+            return { "LOG_EXIT_CODE" => "", "LOG_NOTE" => "", "LOG_GROUP_CHECK" => "" } unless plan.cloudwatch_logs?
+
+            { "LOG_EXIT_CODE" => LOG_EXIT_CODE, "LOG_NOTE" => LOG_NOTE, "LOG_GROUP_CHECK" => LOG_GROUP_CHECK }
+          end
+
+          private
+
+          def awslogs_definition(plan, region)
+            options = %({"awslogs-region": "#{region}", "awslogs-group": "#{plan.log_group}", \
+"awslogs-create-group": "false", tag: $service})
+            %(def log($service): {driver: "awslogs", options: #{options}};)
+          end
+
+          def local_log_values
+            { "LOG_DEF" => "def log: #{JSON_FILE};", "LOG_SERVICE" => "log", "LOG_CADDY" => "log",
+              "LOG_TUNNEL" => "log" }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/hecks/projections/deploy/box/roll_scripts.rb

@@ -45,7 +45,8 @@ module Hecks
                                            "RDS_STACK" => plan.rds_stack, "REGION" => region,
                                            "DIR" => "/opt/#{plan.infra_name}", "HEALTH_CHECKS" => health_checks(plan),
                                            "SMOKE_HEADER" => smoke_header(plan), "USAGE" => deploy_usage(plan),
-                                           "DB_SECRET_LINE" => database_secret_line(plan))
+                                           "DB_SECRET_LINE" => database_secret_line(plan),
+                                           **log_roll_values(plan))
           end
 
           # @param plan [Settings::Plan] the resolved settings
@@ -94,18 +95,25 @@ module Hecks
           end
 
           # @param plan [Settings::Plan] the resolved settings
+          # @param region [String] the validated region
           # @return [String] a Makefile whose targets create the two stacks and roll the box
-          def makefile(plan)
-            hint = plan.task_definition ? "[TASKDEF=family:revision]" : '[TAGS="web=20260101 worker=20260101"]'
-            base = template("Makefile.tmpl", { "STACK" => plan.infra_name, "DEPLOY_HINT" => hint,
-                                               "RDS_STACK" => plan.rds_stack, "BOX_STACK" => plan.box_stack,
-                                               "DEPLOY_RECIPE" => RollRecipe.deploy(plan) }
-                                               .merge(database_makefile_values(plan)))
-            plan.hosting ? "#{base}\ninclude hosting.mk\n" : base
+          def makefile(plan, region)
+            values = makefile_values(plan, region)
+            base = template("Makefile.tmpl", values)
+            includes = [("hosting.mk" if plan.hosting), ("edge.mk" if plan.cdn)].compact
+            includes.empty? ? base : "#{base}\n#{includes.map { |file| "include #{file}\n" }.join}"
           end
 
           private
 
+          def makefile_values(plan, region)
+            hint = plan.task_definition ? "[TASKDEF=family:revision]" : '[TAGS="web=20260101 worker=20260101"]'
+            { "STACK" => plan.infra_name, "DEPLOY_HINT" => hint, "RDS_STACK" => plan.rds_stack,
+              "BOX_STACK" => plan.box_stack, "DEPLOY_RECIPE" => RollRecipe.deploy(plan),
+              "AMI_PARAMETER" => ami_parameter(plan.instance_type) }
+              .merge(database_makefile_values(plan), edge_makefile_values(plan, region))
+          end
+
           def schema_list(migration)
             migration.schemas.map { |name| "`#{name}`" }.join(", ")
           end

data/lib/hecks/projections/deploy/box/settings/cdn.rb

@@ -0,0 +1,40 @@
+require_relative "patterns"
+
+module Hecks
+  module Projections
+    module Deploy
+      module Box
+        module Settings
+          # Reads the `cdn` setting: the CloudFront edge in front of the box. Extended onto
+          # `Settings`. The alias names themselves are checked by the Deploy bluebook's
+          # `BoxTarget.Declare` before this runs; this checks the shape and the guard.
+          module CdnReaders
+            include Patterns
+
+            # @param value [Hash{Symbol => Object}, nil] the world's `cdn` setting
+            # @param origin_header [String, nil] the declared origin header
+            # @return [Cdn, nil] the edge to generate, or nil when the world declares none
+            # @raise [ArgumentError] when the shape is wrong or there is no origin guard
+            def read_cdn(value, origin_header)
+              return nil if value.nil?
+
+              aliases = cdn_aliases(value)
+              raise ArgumentError, CDN_NEEDS_ORIGIN if origin_header.nil?
+
+              Settings::Cdn.new(aliases: aliases.uniq)
+            end
+
+            private
+
+            def cdn_aliases(value)
+              listed = value.is_a?(Hash) && value.keys == [:aliases] ? value[:aliases] : nil
+              raise ArgumentError, CDN_SHAPE unless listed.is_a?(Array) && !listed.empty?
+
+              listed.map { |name| check(:cdn_aliases, name, CDN_ALIAS) }
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/hecks/projections/deploy/box/settings/logs.rb

@@ -0,0 +1,40 @@
+require_relative "patterns"
+
+module Hecks
+  module Projections
+    module Deploy
+      module Box
+        module Settings
+          # Reads the `logs` and `log_retention_days` settings: where the containers' logs go and
+          # how long CloudWatch keeps them. Extended onto `Settings`.
+          #
+          # Retention is one of CloudWatch's own values and never "never expire", so a box's log
+          # bill is bounded by a declaration.
+          module LogReaders
+            include Patterns
+
+            # @param settings [Hash{Symbol => Object}] the world's `AwsBox` settings
+            # @return [Hash{Symbol => Object}] the plan's `logs` and `log_retention_days`
+            # @raise [ArgumentError] when `logs` is not a known destination, or the retention is not
+            #   a value CloudWatch accepts
+            def read_logs(settings)
+              destination = settings.fetch(:logs, "cloudwatch").to_s
+              raise ArgumentError, LOGS_SHAPE unless LOG_DESTINATIONS.include?(destination)
+
+              days = settings.fetch(:log_retention_days, DEFAULT_LOG_RETENTION_DAYS)
+              raise ArgumentError, retention_refusal(days) unless LOG_RETENTION_DAYS.include?(days)
+
+              { logs: destination, log_retention_days: days }
+            end
+
+            private
+
+            def retention_refusal(days)
+              "log_retention_days: #{days.inspect} is not a CloudWatch retention; use one of #{LOG_RETENTION_DAYS.join(", ")}"
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/hecks/projections/deploy/box/settings/patterns.rb

@@ -23,6 +23,13 @@ module Hecks
             S3_BUCKET   = /\A[a-z0-9][a-z0-9.-]{1,61}[a-z0-9]\z/
             S3_SHAPE    = "s3_access: a list of `{ bucket: \"name\", write: true }` hashes (write is optional)".freeze
             FROM_TASKDEF = %i[env secrets repository].freeze
+            LOG_DESTINATIONS = %w[cloudwatch local].freeze
+            DEFAULT_LOG_RETENTION_DAYS = 30
+            # The retention periods CloudWatch Logs accepts, in days, without "never expire".
+            LOG_RETENTION_DAYS = [1, 3, 5, 7, 14, 30, 60, 90, 120, 150, 180, 365, 400, 545, 731, 1096, 1827, 2192, 2557,
+                                  2922, 3288, 3653].freeze
+            LOGS_SHAPE = "logs: \"cloudwatch\" ships every container's log to CloudWatch Logs; " \
+                         "\"local\" keeps Docker's rotating json-file logs on the box".freeze
 
             # The settings that size an RDS instance: with `shared_database` they are the shared
             # instance's.
@@ -37,6 +44,10 @@ module Hecks
                            "(the secret holding the tunnel token)".freeze
             ORIGIN_ENV_SHAPE = "origin_env: the container environment variable names that hold the origin secret " \
                                "need an origin_secret and a task_definition to compare against".freeze
+            CDN_ALIAS = /\A[a-z0-9.-]{4,253}\z/
+            CDN_SHAPE = "cdn: a hash with `aliases`, the non-empty list of host names the CloudFront edge answers on".freeze
+            CDN_NEEDS_ORIGIN = "cdn: the box admits CloudFront's addresses on port 80, so it needs the origin guard " \
+                               "that refuses every other caller; declare origin_header and origin_secret".freeze
             ORIGIN_PAIR = "origin_header and origin_secret go together: the header a CDN sends, " \
                           "and the secret that holds its value".freeze
           end

data/lib/hecks/projections/deploy/box/settings/types.rb

@@ -45,18 +45,33 @@ module Hecks
             # @!attribute [r] write [Boolean] whether a production box may also write and delete
             Bucket = Struct.new(:name, :write, keyword_init: true)
 
+            # The CloudFront edge a world asks for with `cdn`.
+            #
+            # @!attribute [r] aliases [Array<String>] the host names the distribution answers on
+            Cdn = Struct.new(:aliases, keyword_init: true)
+
             # Everything the generator reads, checked.
             Plan = Struct.new(
               :infra_name, :stack_prefix, :instance_type, :volume_gb, :swap_gb, :database_class,
               :storage_gb, :backup_days, :snapshots_keep, :database_name, :engine_version,
               :containers, :routes, :default_container, :origin_header, :origin_secret,
               :secret_prefixes, :writable_secrets, :origin_env, :tunnel, :tunnel_service, :proxy_image,
-              :task_definition, :migration, :s3_buckets, :hosting, :shared_database, keyword_init: true
+              :task_definition, :migration, :s3_buckets, :hosting, :shared_database, :cdn,
+              :logs, :log_retention_days, keyword_init: true
             ) do
               # @return [String] the CloudFormation stack that holds the database: the shared
               #   instance's when the world names one, else this site's own
               def rds_stack = shared_database || "#{stack_prefix}-#{infra_name}-rds"
 
+              # @return [String] the CloudFormation stack that holds the CloudFront edge
+              def edge_stack = "#{stack_prefix}-#{infra_name}-edge"
+
+              # @return [String] the CloudWatch log group the box's containers write to
+              def log_group = "/#{box_stack}"
+
+              # @return [Boolean] whether the containers' logs ship to CloudWatch Logs
+              def cloudwatch_logs? = logs == "cloudwatch"
+
               # @return [Boolean] whether the database lives on an instance shared with other sites
               def shared? = !shared_database.nil?
 

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

@@ -4,6 +4,8 @@ require_relative "settings/types"
 require_relative "settings/checks"
 require_relative "settings/containers"
 require_relative "settings/origin"
+require_relative "settings/cdn"
+require_relative "settings/logs"
 
 module Hecks
   module Projections
@@ -21,6 +23,8 @@ module Hecks
           extend Checks
           extend ContainerReaders
           extend OriginReaders
+          extend CdnReaders
+          extend LogReaders
 
           module_function
 
@@ -50,7 +54,7 @@ module Hecks
               shared_database: read_shared_database(settings),
               s3_buckets: read_s3_access(settings.fetch(:s3_access, [])),
               hosting: HostingSettings.read(settings, task_definition)
-            }
+            }.merge(read_logs(settings))
           end
 
           # @param settings [Hash{Symbol => Object}] the world's `AwsBox` settings
@@ -62,7 +66,7 @@ module Hecks
             origin_env = read_origin_env(settings, secret, task_definition)
             tunnel, tunnel_service = read_tunnel(settings.fetch(:tunnel, false), containers)
             { origin_header: header, origin_secret: secret, origin_env: origin_env,
-              tunnel: tunnel, tunnel_service: tunnel_service }
+              tunnel: tunnel, tunnel_service: tunnel_service, cdn: read_cdn(settings[:cdn], header) }
           end
 
           # @return [Hash{Symbol => Object}] the plan's names, sizes, routes and secret scopes

data/lib/hecks/projections/deploy/box/stack_yaml.rb

@@ -20,16 +20,19 @@ module Hecks
             template("box.yaml.tmpl",
                      "STACK" => plan.infra_name, "INSTANCE_TYPE" => plan.instance_type,
                      "VOLUME_GB" => plan.volume_gb.to_s, "SNAPSHOTS_KEEP" => plan.snapshots_keep.to_s,
-                     "AMI_PARAMETER" => ami_parameter(plan.instance_type),
                      "COMPUTE_DOMAIN" => compute_domain(region),
                      "SECRET_RESOURCES" => secret_resources(plan), "WRITABLE_SECRETS" => writable_secrets(plan),
                      "TUNNEL_EGRESS" => tunnel_egress(plan),
                      "SWAP_COMMANDS" => swap_commands(plan), "ECR_REPOSITORIES" => ecr_repositories(plan),
-                     "ECR_OUTPUTS" => ecr_outputs(plan), "S3_POLICY" => s3_policy(plan))
+                     "ECR_OUTPUTS" => ecr_outputs(plan), "S3_POLICY" => s3_policy(plan),
+                     "LOG_GROUP" => log_group_yaml(plan), "LOG_POLICY" => log_policy_yaml(plan))
           end
 
           # Graviton families end their generation digit with `g` (`t4g`, `m7gd`, `c6gn`).
           #
+          # Only a first create reads it, from `make stacks`: a live box keeps the image it runs,
+          # because a newer one would replace the instance.
+          #
           # @param instance_type [String] an EC2 instance type
           # @return [String] the SSM parameter of the matching Amazon Linux image
           def ami_parameter(instance_type)

data/lib/hecks/projections/deploy/box/templates/Makefile.tmpl

@@ -1,21 +1,37 @@
 # @@STACK@@: @@WHAT@@.
 #   make stacks VPC=vpc-... PRIVATE_SUBNETS=subnet-a,subnet-b PUBLIC_SUBNET=subnet-c [REHEARSAL=true]
 #   make deploy @@DEPLOY_HINT@@
+# `make stacks` keeps a live box on the image it runs, so an update never replaces the instance.
+# To move to a newer image on purpose:  make stacks ... AMI_ID=ami-...
 RDS_STACK = @@RDS_STACK@@
 BOX_STACK = @@BOX_STACK@@
 @@REHEARSAL_NOTE@@
 REHEARSAL ?= false
+AMI_ID ?=
 
 HECKS ?= hecks
 
 @@PHONY@@
 stacks:
+@@CDN_CHECK@@
 @@RDS_DEPLOY@@
+	@AMI="$(AMI_ID)"; SRC="given as AMI_ID"; \
+	if [ -z "$$AMI" ]; then \
+		BOX=$$(aws cloudformation describe-stack-resource --stack-name $(BOX_STACK) --logical-resource-id Box --query StackResourceDetail.PhysicalResourceId --output text 2>/dev/null); \
+		case "$$BOX" in \
+			i-*) AMI=$$(aws ec2 describe-instances --instance-ids "$$BOX" --query "Reservations[0].Instances[0].ImageId" --output text); SRC="pinned: the image $$BOX runs" ;; \
+			*) AMI=$$(aws ssm get-parameter --name @@AMI_PARAMETER@@ --query Parameter.Value --output text); SRC="new: no $(BOX_STACK) stack yet, so the latest image" ;; \
+		esac; \
+	fi; \
+	case "$$AMI" in ami-*) ;; *) echo "no ami- image found for $(BOX_STACK): pass one with AMI_ID=ami-..." >&2; exit 1 ;; esac; \
+	echo "==> AmiId $$AMI ($$SRC)"; \
 	aws cloudformation deploy --template-file box.yaml --stack-name $(BOX_STACK) --capabilities CAPABILITY_IAM \
 		--parameter-overrides VpcId=$(VPC) SubnetId=$(PUBLIC_SUBNET) \
 		DbSecurityGroupId=$$(aws cloudformation describe-stacks --stack-name $(RDS_STACK) --query "Stacks[0].Outputs[?OutputKey=='DbSecurityGroupId'].OutputValue" --output text) \
 @@DB_SECRET_PARAM@@
+		AmiId=$$AMI \
 		AlertTopicArn=$$(aws cloudformation describe-stacks --stack-name $(RDS_STACK) --query "Stacks[0].Outputs[?OutputKey=='AlertTopicArn'].OutputValue" --output text) \
+@@CDN_PARAM@@
 		Rehearsal=$(REHEARSAL)
 
 @@PROVISION@@

data/lib/hecks/projections/deploy/box/templates/box.yaml.tmpl

@@ -20,9 +20,12 @@ Parameters:
     Type: String
     Default: @@INSTANCE_TYPE@@
   AmiId:
-    Type: AWS::SSM::Parameter::Value<AWS::EC2::Image::Id>
-    Default: @@AMI_PARAMETER@@
-    Description: Never re-resolve this on a live box, because a newer image replaces the instance.
+    Type: AWS::EC2::Image::Id
+    Description: >-
+      The image the box runs, always given and never resolved here. Resolving the public image
+      key again on a live box finds the newest image, and a changed ImageId replaces the instance
+      and its Elastic IP association. make stacks passes the running box's own image, and takes a
+      newer one only when AMI_ID is given.
   RootVolumeGb:
     Type: Number
     Default: @@VOLUME_GB@@
@@ -82,7 +85,7 @@ Resources:
       SourceSecurityGroupId: !Ref BoxSecurityGroup
       Description: App box
 
-  BoxRole:
+@@LOG_GROUP@@  BoxRole:
     Type: AWS::IAM::Role
     Properties:
       AssumeRolePolicyDocument:
@@ -106,6 +109,7 @@ Resources:
 @@SECRET_RESOURCES@@
 @@WRITABLE_SECRETS@@
 @@S3_POLICY@@
+@@LOG_POLICY@@
 
   BoxProfile:
     Type: AWS::IAM::InstanceProfile