hecks 4.0.0 → 6.0.0

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

@@ -76,22 +76,7 @@ module Hecks
               else
                 [health_probe("the proxy serves /", "", '[ "${code#5}" = "$code" ]')]
               end
-            (probes + tunnel_probe(plan)).join("\n")
-          end
-
-          # @param plan [Settings::Plan] the resolved settings
-          # @return [Array<String>] the probe that waits for the tunnel to register, when one runs
-          def tunnel_probe(plan)
-            return [] unless plan.tunnel_service
-
-            [<<~SH.chomp]
-              for _ in 1 2 3 4 5 6; do
-                n=$(docker compose -f compose.json logs --no-color cloudflared 2>&1 | grep -ci "registered tunnel connection" || true)
-                [ "$n" -gt 0 ] && break
-                sleep 5
-              done
-              [ "$n" -gt 0 ] && echo "ok   the tunnel registered $n connections" || { echo "FAIL the tunnel has no connection"; BAD=1; }
-            SH
+            probes.join("\n")
           end
 
           # @param plan [Settings::Plan] the resolved settings

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

@@ -7,7 +7,7 @@ module Hecks
     module Deploy
       module Box
         module Settings
-          # Reads the containers a box runs and what points at them: routes, the default, a tunnel.
+          # Reads the containers a box runs and what points at them: routes and the default.
           # Extended onto `Settings`, which supplies the checks.
           module ContainerReaders
             include Patterns
@@ -67,20 +67,13 @@ module Hecks
               raise ArgumentError, "#{key}: #{name.inspect} is not a declared container"
             end
 
-            # `tunnel true` only opens the outbound port; a hash also runs cloudflared as a service.
+            # A world that still declares `tunnel` is refused, so the tunnel it relied on does not
+            # vanish from the box without a word (ADR 0156).
             #
-            # @param value [Boolean, Hash{Symbol => Object}] the world's `tunnel` setting
-            # @param containers [Array<Container>] the declared containers
-            # @return [Array(Boolean, Tunnel)] whether the egress opens, and the service if one runs
-            def read_tunnel(value, containers)
-              return [boolean(:tunnel, value), nil] unless value.is_a?(Hash)
-
-              to = value.fetch(:to) { raise ArgumentError, TUNNEL_SHAPE }
-              target = known_container!(:tunnel, check(:tunnel_to, to, NAME), containers)
-              token = check(:tunnel_token_secret, value.fetch(:token_secret) { raise ArgumentError, TUNNEL_SHAPE }, SECRET_NAME)
-              image = check(:tunnel_image, value.fetch(:image, TUNNEL_IMAGE), IMAGE)
-              port = containers.find { |c| c.name == target }.port
-              [true, Tunnel.new(container: target, port: port, token_secret: token, image: image)]
+            # @param settings [Hash{Symbol => Object}] the world's `AwsBox` settings
+            # @raise [ArgumentError] when the world declares `tunnel`
+            def refuse_tunnel!(settings)
+              raise ArgumentError, TUNNEL_REMOVED if settings.key?(:tunnel)
             end
 
             def missing_containers
@@ -112,9 +105,30 @@ module Hecks
                 env:           string_map(:env, spec.fetch(:env, {}), ENV_KEY, ENV_VALUE),
                 secrets:       string_map(:secrets, spec.fetch(:secrets, {}), ENV_KEY, SECRET_NAME),
                 tag_parameter: check(:tag_parameter, spec.fetch(:tag_parameter, default_tag_parameter(name)),
-                                     HostingSettings::PARAMETER)
+                                     HostingSettings::PARAMETER),
+                **build_fields(spec)
               }
             end
+
+            # A container that names a Dockerfile is built from the checkout before push; one that
+            # names none (both fields nil) pushes an image built elsewhere, as before.
+            def build_fields(spec)
+              dockerfile = spec[:dockerfile]
+              return { dockerfile: nil, build_context: nil } if dockerfile.nil?
+
+              {
+                dockerfile:    relative_path(:dockerfile, dockerfile),
+                build_context: relative_path(:context, spec.fetch(:context, "."))
+              }
+            end
+
+            # A path inside the checkout: relative, not empty, and not climbing out of it with "..".
+            def relative_path(key, value)
+              str = value.to_s
+              return str unless str.empty? || str.start_with?("/") || str.split("/").include?("..")
+
+              raise ArgumentError, "#{key}: #{value.inspect} must be a path inside the checkout"
+            end
           end
         end
       end

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

@@ -36,12 +36,11 @@ module Hecks
             SHARED_INSTANCE_SETTINGS = %i[database_class storage_gb engine_version backup_days].freeze
             # Default images, each a version tag plus the digest of its multi-architecture index,
             # so a rebuilt box pulls the same bytes.
-            TUNNEL_IMAGE = "cloudflare/cloudflared:2026.9.3" \
-                           "@sha256:072c067d25ccbe61d46e18f0d0723255f2bb5304f7317caa95b27031520ff92c".freeze
-            PROXY_IMAGE  = "public.ecr.aws/docker/library/caddy:2.8" \
-                           "@sha256:226d1f059b75399fe19182893c7184591c07b97afc8dfcf44eeb80c9a77a530f".freeze
-            TUNNEL_SHAPE = "tunnel: a hash needs `to` (the container it forwards to) and `token_secret` " \
-                           "(the secret holding the tunnel token)".freeze
+            PROXY_IMAGE = "public.ecr.aws/docker/library/caddy:2.8" \
+                          "@sha256:226d1f059b75399fe19182893c7184591c07b97afc8dfcf44eeb80c9a77a530f".freeze
+            TUNNEL_REMOVED = "tunnel: a box is reached through the CDN or load balancer and Caddy with an origin-secret " \
+                             "header; no third-party tunnel runs on it (ADR 0156). Delete the setting and declare " \
+                             "`cdn` and `origin_secret` instead".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/

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

@@ -16,7 +16,10 @@ module Hecks
             #   resolved on the box at deploy time and never written into a template
             # @!attribute [r] tag_parameter [String] the stack parameter that holds this container's
             #   image tag, which a hosting `deploy-service.sh` sets
-            Container = Struct.new(:name, :repository, :port, :env, :secrets, :tag_parameter, keyword_init: true)
+            # @!attribute [r] dockerfile [String, nil] a repo-root Dockerfile to build, else nil
+            # @!attribute [r] build_context [String, nil] the build context, set with dockerfile
+            Container = Struct.new(:name, :repository, :port, :env, :secrets, :tag_parameter,
+                                   :dockerfile, :build_context, keyword_init: true)
 
             # A set of URL paths one container serves.
             #
@@ -24,14 +27,6 @@ module Hecks
             # @!attribute [r] paths [Array<String>] Caddy path patterns, such as "/cms/*"
             Route = Struct.new(:container, :paths, keyword_init: true)
 
-            # A Cloudflare tunnel the box runs as a service, pointed at one container.
-            #
-            # @!attribute [r] container [String] the container the tunnel forwards to
-            # @!attribute [r] port [Integer] that container's port
-            # @!attribute [r] token_secret [String] the secret holding the tunnel token
-            # @!attribute [r] image [String] the cloudflared image
-            Tunnel = Struct.new(:container, :port, :token_secret, :image, keyword_init: true)
-
             # The data a project moves from its old database into the new RDS instance.
             #
             # @!attribute [r] schemas [Array<String>] the schemas to copy
@@ -55,7 +50,7 @@ module Hecks
               :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,
+              :secret_prefixes, :writable_secrets, :origin_env, :proxy_image,
               :task_definition, :migration, :s3_buckets, :hosting, :shared_database, :cdn,
               :logs, :log_retention_days, keyword_init: true
             ) do

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

@@ -26,6 +26,9 @@ module Hecks
           extend CdnReaders
           extend LogReaders
 
+          # Any character a database name may not hold.
+          NOT_ALPHANUMERIC = /[^a-zA-Z0-9]/
+
           module_function
 
           # @param deploy_settings [Hash{Symbol => Object}] the world's `AwsBox` settings
@@ -41,7 +44,7 @@ module Hecks
             listed = s.fetch(:containers) { raise ArgumentError, missing_containers }
             task_definition = read_task_definition(s[:task_definition], listed)
             containers = read_containers(listed, infra_name)
-            edge = edge_fields(s, containers, task_definition)
+            edge = edge_fields(s, task_definition)
             Plan.new(**plan_fields(s, target, infra_name, database_name, containers), **edge,
                      **extra_fields(s, task_definition, database_name))
           end
@@ -58,15 +61,13 @@ module Hecks
           end
 
           # @param settings [Hash{Symbol => Object}] the world's `AwsBox` settings
-          # @param containers [Array<Container>] the declared containers
           # @param task_definition [String, nil] the declared task definition family
-          # @return [Hash{Symbol => Object}] the origin guard and the tunnel
-          def edge_fields(settings, containers, task_definition)
+          # @return [Hash{Symbol => Object}] the origin guard and the CDN
+          def edge_fields(settings, task_definition)
             header, secret = read_origin(settings)
             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, cdn: read_cdn(settings[:cdn], header) }
+            refuse_tunnel!(settings)
+            { origin_header: header, origin_secret: secret, origin_env: origin_env, cdn: read_cdn(settings[:cdn], header) }
           end
 
           # @return [Hash{Symbol => Object}] the plan's names, sizes, routes and secret scopes
@@ -152,7 +153,7 @@ module Hecks
           end
 
           def read_database_name(settings, infra_name)
-            check(:database_name, settings.fetch(:database_name, infra_name.gsub(/[^a-zA-Z0-9]/, "")), DB_NAME)
+            check(:database_name, settings.fetch(:database_name, infra_name.gsub(NOT_ALPHANUMERIC, "")), DB_NAME)
           end
 
           # With a task definition, the images, environment and secrets are read from it at deploy

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

@@ -5,6 +5,9 @@ module Hecks
         # The two CloudFormation stacks of a box deploy, and the pieces spliced into them. Mixed
         # into `Box`, which supplies `template`, the access statements and the constants.
         module StackYaml
+          # The family of an EC2 instance type built on Graviton (`t4g`, `m7gd`, `c6gn`).
+          GRAVITON_FAMILY = /\d+g[a-z]*\z/
+
           # @param plan [Settings::Plan] the resolved settings
           # @return [String] the database stack
           def rds_yaml(plan)
@@ -22,7 +25,6 @@ module Hecks
                      "VOLUME_GB" => plan.volume_gb.to_s, "SNAPSHOTS_KEEP" => plan.snapshots_keep.to_s,
                      "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),
                      "LOG_GROUP" => log_group_yaml(plan), "LOG_POLICY" => log_policy_yaml(plan))
@@ -36,7 +38,7 @@ module Hecks
           # @param instance_type [String] an EC2 instance type
           # @return [String] the SSM parameter of the matching Amazon Linux image
           def ami_parameter(instance_type)
-            arch = instance_type.split(".").first.match?(/\d+g[a-z]*\z/) ? "arm64" : "x86_64"
+            arch = instance_type.split(".").first.match?(GRAVITON_FAMILY) ? "arm64" : "x86_64"
             "/aws/service/ami-amazon-linux-latest/al2023-ami-kernel-default-#{arch}"
           end
 
@@ -46,14 +48,6 @@ module Hecks
             region == LEGACY_COMPUTE_REGION ? "compute-1.amazonaws.com" : "#{region}.compute.amazonaws.com"
           end
 
-          # @param plan [Settings::Plan] the resolved settings
-          # @return [String] the outbound rules a Cloudflare Tunnel sidecar needs, or nothing
-          def tunnel_egress(plan)
-            return "" unless plan.tunnel
-
-            template("tunnel-egress.yaml.tmpl", {})
-          end
-
           # @param plan [Settings::Plan] the resolved settings
           # @return [String] the user-data lines that add swap, or nothing when `swap_gb` is 0
           def swap_commands(plan)
@@ -75,9 +69,10 @@ module Hecks
           def ecr_repositories(plan)
             return "" if plan.task_definition
 
-            plan.containers.map do |container|
+            repositories = plan.containers.map do |container|
               ecr_repository(container).lines.map { |line| line.strip.empty? ? line : "  #{line}" }.join
-            end.join.chomp
+            end
+            repositories.join.chomp
           end
 
           # @param plan [Settings::Plan] the resolved settings
@@ -85,10 +80,11 @@ module Hecks
           def ecr_outputs(plan)
             return "" if plan.task_definition
 
-            plan.containers.map do |container|
+            outputs = plan.containers.map do |container|
               id = logical(container.name)
               "  #{id}RepositoryUri:\n    Value: !GetAtt #{id}Repository.RepositoryUri\n"
-            end.join.chomp
+            end
+            outputs.join.chomp
           end
 
           # @param name [String] a container name such as `web-app`

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

@@ -74,7 +74,6 @@ Resources:
           FromPort: 443
           ToPort: 443
           CidrIp: 0.0.0.0/0
-@@TUNNEL_EGRESS@@
   BoxToDbIngress:
     Type: AWS::EC2::SecurityGroupIngress
     Properties:

data/lib/hecks/projections/deploy/box/templates/deploy-service.sh.tmpl

@@ -2,7 +2,8 @@
 # GENERATED by hecks deploy project -- re-run it to refresh this file rather than hand-editing.
 # Settings come from the domain's deployed_to("AwsBox") block (hosting_scripts true).
 #
-# Deploys ONE container's freshly built local image to @@STACK@@'s app box, under a fresh, unique ECR tag.
+# Builds ONE container's image from the checkout (when it declares a Dockerfile) and pushes it to
+# @@STACK@@'s app box under a fresh, unique ECR tag; an image built elsewhere is pushed as it is.
 #
 #   bash deploy-service.sh <service>
 #   EXISTING_TAG=<tag> bash deploy-service.sh <service>    redeploy a tag already in ECR (no push)
@@ -24,10 +25,11 @@
 #   32  the box's Compose file is unreadable    33  the box stack has no instance
 #   34  the stack has no parameter for the container   35  the stack update failed or did not settle
 #   36  a parameter other than the container's changed  37  the task definition lacks the pushed image
-#   38  the task definition has no such container      40-43  deploy-box.sh's own
+#   38  the task definition has no such container      39  cannot find the checkout root to build
+#   40-43  deploy-box.sh's own
 #
 # Environment:
-#   LOCAL_IMAGE               local image to push, default <ecr repository>:latest
+#   LOCAL_IMAGE               local image to push; naming it skips the build. default <ecr repository>:latest
 #   EXISTING_TAG              redeploy this tag from ECR instead of building and pushing
 #   SETTLE_TIMEOUT_SECS       default 1200, how long to wait for a stack update
 #   SKIP_POST_DEPLOY_SMOKE=1  passed through to smoke-after-deploy.sh
@@ -54,6 +56,7 @@ timed_out() { [ $((SECONDS - $1)) -gt "$SETTLE_TIMEOUT_SECS" ]; }
 @@REPOSITORY_STEP@@
 TAG="${EXISTING_TAG:-${SERVICE_NAME}-$(date -u +%Y%m%d%H%M%S)}"
 IMAGE_URI="${ECR_HOST}/${ECR_REPOSITORY}:${TAG}"
+LOCAL_IMAGE_SET="${LOCAL_IMAGE:+set}"
 LOCAL_IMAGE="${LOCAL_IMAGE:-${ECR_REPOSITORY}:latest}"
 
 if [ -n "${EXISTING_TAG:-}" ]; then
@@ -67,6 +70,16 @@ else
     echo "tag ${TAG} is already in ECR; a tag is never reused. Run again." >&2
     exit 31
   fi
+  # Build from the checkout first, unless the caller named a prebuilt image (LOCAL_IMAGE) or this
+  # service is built elsewhere (resolve_service set no BUILD_DOCKERFILE).
+  if [ -z "${LOCAL_IMAGE_SET:-}" ] && [ -n "${BUILD_DOCKERFILE:-}" ]; then
+    REPO_ROOT="$(git rev-parse --show-toplevel)" \
+      || { echo "cannot find the checkout root to build ${BUILD_DOCKERFILE}; pass LOCAL_IMAGE" >&2; exit 39; }
+    echo "==> building ${LOCAL_IMAGE} from ${BUILD_DOCKERFILE}"
+    docker build --platform linux/arm64 -t "$LOCAL_IMAGE" \
+      -f "${REPO_ROOT}/${BUILD_DOCKERFILE}" "${REPO_ROOT}/${BUILD_CONTEXT}"
+  fi
+
   echo "==> tagging ${LOCAL_IMAGE} as ${IMAGE_URI}"
   docker tag "$LOCAL_IMAGE" "$IMAGE_URI"
 

data/lib/hecks/projections/deploy/box/templates/hosting.mk.tmpl

@@ -10,16 +10,17 @@ URL     ?= @@URL@@
 
 # Pushes one container's already-built local image under a fresh tag and rolls it onto the box, as the
 # service_roll.run command: it runs deploy-service.sh, records the roll in the Hecks database
-# (HECKS_DATABASE, default postgres://hecks@localhost/hecks) and requests the smoke. Build the image
-# first; see deploy-service.sh. EXISTING_TAG=<tag> redeploys a tag already in ECR. Without the
-# database the script runs by itself and the target exits non-zero (24 if it all passed).
+# this checkout's hecks.local.world names (default_database; with no local files nothing is
+# recorded) and requests the smoke. Build the image first; see deploy-service.sh. EXISTING_TAG=<tag>
+# redeploys a tag already in ECR. When that database cannot be opened the script runs by itself and
+# the target exits non-zero (24 if it all passed).
 deploy-service:
 	@@SERVICE_RECIPE@@
 
 # Waits for the last roll to settle, then dispatches and follows the smoke, as the smoke_run.run
-# command, which runs smoke-after-deploy.sh and records how it ended in the Hecks database
-# (HECKS_DATABASE, default postgres://hecks@localhost/hecks). Without that database the smoke still
-# runs and its result is printed, and the target exits non-zero (24 if the smoke passed).
+# command, which runs smoke-after-deploy.sh and records how it ended in the Hecks database this
+# checkout's hecks.local.world names. When that database cannot be opened the smoke still runs and
+# its result is printed, and the target exits non-zero (24 if the smoke passed).
 # SKIP_POST_DEPLOY_SMOKE=1 opts out, DRY_RUN=1 dispatches nothing.
 smoke-after-deploy:
 	@@SMOKE_RECIPE@@

data/lib/hecks/projections/deploy/box/templates/render-compose-taskdef.sh.tmpl

@@ -51,17 +51,13 @@ jq --argjson def "$DEF" --arg host "$DB_HOST" --arg secret "$DB_SECRET" '
           end)))
       + {caddy: ({image: "@@PROXY_IMAGE@@", network_mode: "host", restart: "unless-stopped",
                   volumes: ["./Caddyfile:/etc/caddy/Caddyfile:ro", "./caddy-extra:/etc/caddy/extra:ro"], logging: @@LOG_CADDY@@}
-                 + (if $in.origin then {env_file: ["caddy.secrets.env"]} else {} end))}
-      + (if $in.tunnel then {cloudflared: {image: $in.tunnel.image, network_mode: "host", restart: "unless-stopped",
-                  command: ["tunnel", "--no-autoupdate", "--url", $in.tunnel.url, "run"],
-                  env_file: ["cloudflared.secrets.env"], logging: @@LOG_TUNNEL@@}} else {} end))}' \
+                 + (if $in.origin then {env_file: ["caddy.secrets.env"]} else {} end))})}' \
   "$HERE/services.json" > compose.json
 
 jq --argjson def "$DEF" '. as $in
     | [ ($in.services | keys[]) as $n | $def[] | select(.name == $n) | (.secrets // [])[]
         | {service: $n, name: .name, valueFrom: .valueFrom} ]
-      + [ (if $in.origin then {service: "caddy", name: "ORIGIN_SECRET", valueFrom: $in.origin.secret} else empty end),
-          (if $in.tunnel then {service: "cloudflared", name: "TUNNEL_TOKEN", valueFrom: $in.tunnel.token_secret} else empty end) ]' \
+      + [ (if $in.origin then {service: "caddy", name: "ORIGIN_SECRET", valueFrom: $in.origin.secret} else empty end) ]' \
   "$HERE/services.json" > secrets.json
 
 echo "rendered compose.json and secrets.json ($(jq '.services | length' compose.json) services)"

data/lib/hecks/projections/deploy/box/templates/render-compose.sh.tmpl

@@ -29,16 +29,12 @@ jq --arg ecr "$ECR" --argjson tags "$TAGS" --arg host "$DB_HOST" --arg secret "$
         + (if (.secrets | length) > 0 then {env_file: [(.name + ".secrets.env")]} else {} end))))
       + {caddy: ({image: "@@PROXY_IMAGE@@", network_mode: "host", restart: "unless-stopped",
                   volumes: ["./Caddyfile:/etc/caddy/Caddyfile:ro", "./caddy-extra:/etc/caddy/extra:ro"], logging: @@LOG_CADDY@@}
-                 + (if $in.origin then {env_file: ["caddy.secrets.env"]} else {} end))}
-      + (if $in.tunnel then {cloudflared: {image: $in.tunnel.image, network_mode: "host", restart: "unless-stopped",
-                  command: ["tunnel", "--no-autoupdate", "--url", $in.tunnel.url, "run"],
-                  env_file: ["cloudflared.secrets.env"], logging: @@LOG_TUNNEL@@}} else {} end))}' \
+                 + (if $in.origin then {env_file: ["caddy.secrets.env"]} else {} end))})}' \
   "$HERE/services.json" > compose.json
 
 jq '. as $in
     | [ ($in.services[] | . as $v | ($v.secrets | to_entries[]) | {service: $v.name, name: .key, valueFrom: .value}),
-        (if $in.origin then {service: "caddy", name: "ORIGIN_SECRET", valueFrom: $in.origin.secret} else empty end),
-        (if $in.tunnel then {service: "cloudflared", name: "TUNNEL_TOKEN", valueFrom: $in.tunnel.token_secret} else empty end) ]' \
+        (if $in.origin then {service: "caddy", name: "ORIGIN_SECRET", valueFrom: $in.origin.secret} else empty end) ]' \
   "$HERE/services.json" > secrets.json
 
 echo "rendered compose.json and secrets.json ($(jq '.services | length' compose.json) services)"

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

@@ -45,6 +45,16 @@ module Hecks
                       "# after adding one: the admin API is off, so a reload cannot reach it.\n" \
                       "import /etc/caddy/extra/*\n".freeze
 
+        # What a recipe tells the operator when the Hecks database cannot be opened: the database
+        # and role to create, and the local files that name it. Hecks is in Memory unless this
+        # checkout's `hecks.local.hecksagon` and `hecks.local.world` opt it in (ADR 0136).
+        NO_DATABASE_ADVICE = [
+          '  echo "    one-time setup on this machine: a database AND a non-superuser role that owns it" >&2; \\',
+          '  echo "    (a superuser skips the era write-fence, so createdb alone fails), then name it in" >&2; \\',
+          '  echo "    hecks.local.world: default_database postgres://<role>@localhost/<db>" >&2; \\',
+          '  echo "    and set persisted_by PostgresEra in hecks.local.hecksagon" >&2; \\'
+        ].freeze
+
         # The `smoke-after-deploy` recipe: the smoke runs as `smoke_run.run`, which finds
         # `smoke-after-deploy.sh` beside the Makefile and records how it ended in the Hecks
         # database. When that database cannot be opened the command never starts, so the recipe
@@ -55,9 +65,7 @@ module Hecks
           '$(HECKS) deploy smoke_run.run project="$(CURDIR)" --wait $(if $(TASKDEF),taskdef=$(TASKDEF)) 2>"$$err"; rc=$$?; \\',
           'if [ $$rc -ne 0 ] && grep -q \'^cannot open Hecks\' "$$err"; then \\',
           '  echo "==> the deploy record was NOT written: $$(grep -m1 \'^cannot open Hecks\' "$$err")" >&2; \\',
-          '  echo "    one-time setup on this machine: a database AND a non-superuser role that owns it" >&2; \\',
-          '  echo "    (a superuser skips the era write-fence, so createdb alone fails), then set" >&2; \\',
-          '  echo "    HECKS_DATABASE=postgres://<role>@localhost/<db>" >&2; \\',
+          *NO_DATABASE_ADVICE,
           '  echo "    running the smoke anyway so its result is not lost" >&2; \\',
           '  rm -f "$$err"; TASKDEF="$(TASKDEF)" bash ./smoke-after-deploy.sh; rc=$$?; \\',
           '  echo "==> smoke exit $$rc. The deploy record was NOT written: the database is unavailable (see above)." >&2; \\',
@@ -72,7 +80,7 @@ module Hecks
         # `fetch-secrets.sh`, `deploy-box.sh` and a `Makefile`, and for a world that declares a
         # `migration`, `restore-to-rds.sh`, `verify-copy.sh` and `MIGRATION.md`.
         #
-        # @param bluebook [Bluebook::Behaviour::Chapter] the domain's own booted chapter
+        # @param bluebook [Bluebook::Behaviour::Bluebook] the domain's own booted bluebook
         # @param options [Hash] generation options; same shape as `Fargate.call`'s
         # @return [Hash{String => String}] the generated file contents, keyed by filename
         # @raise [ArgumentError] if the domain's deploy settings are invalid or conflict
@@ -142,15 +150,14 @@ module Hecks
         # @param region [String] the validated region
         # @return [Hash{String => String}] every generated file
         def render_all(plan, region)
-          {
+          files = {
             "box.yaml" => box_yaml(plan, region),
             "Caddyfile" => caddyfile(plan), "services.json" => services_json(plan),
             "render-compose.sh" => render_compose_sh(plan, region),
             "fetch-secrets.sh" => File.read(File.join(TEMPLATE_DIR, "fetch-secrets.sh")),
-            "deploy-box.sh" => deploy_box_sh(plan, region),
-            "Makefile" => makefile(plan, region)
-          }.merge(database_files(plan)).merge(migration_files(plan)).merge(edge_files(plan, region))
-            .then { |files| Hosting.extend_files(files, plan: plan, region: region) }
+            "deploy-box.sh" => deploy_box_sh(plan, region), "Makefile" => makefile(plan, region)
+          }.merge(database_files(plan), migration_files(plan), edge_files(plan, region))
+          Hosting.extend_files(files, plan: plan, region: region)
         end
 
         # @param plan [Settings::Plan] the resolved settings

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

@@ -11,6 +11,11 @@ module Hecks
         module Assembly
           module_function
 
+          # The body of a template's `Resources` section, up to `Outputs`.
+          RESOURCES_SECTION = /^Resources:\n(.*?)^Outputs:/m
+          # The body of a template's `Parameters` section, up to `Resources`.
+          PARAMETERS_SECTION = /^Parameters:\n(.*?)^Resources:/m
+
           # Replaces every optional-section marker in a rendered template.
           def apply(template, plan, context)
             text = override_domain_env(template, plan.domain_env)
@@ -35,8 +40,8 @@ module Hecks
           private_class_method :without_default
 
           def check_duplicates!(template)
-            resources = template[/^Resources:\n(.*?)^Outputs:/m, 1].to_s
-            parameters = template[/^Parameters:\n(.*?)^Resources:/m, 1].to_s
+            resources = template[RESOURCES_SECTION, 1].to_s
+            parameters = template[PARAMETERS_SECTION, 1].to_s
             repeated = Yaml.duplicate_keys(resources) + Yaml.duplicate_keys(parameters)
             return if repeated.empty?
 

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

@@ -6,6 +6,9 @@ module Hecks
           # Reads and checks the `cdn` setting into the options `Cdn.yaml` renders. Extended onto
           # `Cdn`, which supplies the constants and `Check`.
           module Options
+            # An HTTP header name.
+            HEADER_NAME = /\A[A-Za-z0-9-]+\z/
+
             private
 
             def base_options(given, default_origin_id)
@@ -57,7 +60,7 @@ module Hecks
               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/)
+              unless secret[:header].to_s.match?(HEADER_NAME)
                 raise ArgumentError,
                       "cdn origin_secret header must be an HTTP header name, got #{secret[:header].inspect}"
               end

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

@@ -9,6 +9,8 @@ module Hecks
 
           LOGICAL_ID = /\A[A-Za-z][A-Za-z0-9]*\z/
           RESOURCE_NAME = %r{\A[A-Za-z0-9][A-Za-z0-9_./-]*\z}
+          # An environment-variable style name: letters, digits and underscores.
+          ENV_NAME = /\A[A-Za-z_][A-Za-z0-9_]*\z/
 
           # Checks that a value is a hash with only known keys and returns it symbol-keyed.
           #
@@ -144,7 +146,7 @@ module Hecks
 
             value.to_h do |key, item|
               name = key.to_s
-              unless name.match?(/\A[A-Za-z_][A-Za-z0-9_]*\z/)
+              unless name.match?(ENV_NAME)
                 raise ArgumentError,
                       "#{where} key #{key.inspect} must be a name of letters, digits and underscores"
               end

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

@@ -6,6 +6,9 @@ module Hecks
           # Renders the resources of the added containers: repositories, parameters, target groups,
           # listener rules and the service's load-balancer entries. Extended onto `Containers`.
           module Rendering
+            # The start of every line, where an indent goes.
+            LINE_START = /^/
+
             # Renders the ECR repository of every added container.
             def repositories_yaml(layout)
               layout.extras.map do |container|
@@ -39,9 +42,8 @@ module Hecks
 
             # Renders the target group of every added container.
             def target_groups_yaml(layout, vpc_ref, deregistration_delay)
-              layout.extras.select(&:port).map do |container|
-                target_group_yaml(container, vpc_ref, deregistration_delay)
-              end.join("\n\n")
+              routed = layout.extras.select(&:port)
+              routed.map { |container| target_group_yaml(container, vpc_ref, deregistration_delay) }.join("\n\n")
             end
 
             # Renders the `TargetGroupAttributes` property for a drain delay.
@@ -65,7 +67,8 @@ module Hecks
 
             # Renders the service's `LoadBalancers` entries for the added containers.
             def load_balancers_yaml(layout)
-              layout.extras.select(&:port).map do |container|
+              routed = layout.extras.select(&:port)
+              routed.map do |container|
                 <<~ENTRY
                   - ContainerName: #{container.name}
                     ContainerPort: #{container.port}
@@ -91,7 +94,7 @@ module Hecks
             private
 
             def target_group_yaml(container, vpc_ref, deregistration_delay)
-              attributes = target_group_attributes_yaml(deregistration_delay).gsub(/^/, "    ")
+              attributes = target_group_attributes_yaml(deregistration_delay).gsub(LINE_START, "    ")
               "#{target_group_head(container, vpc_ref)}#{attributes}".rstrip
             end
 

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

@@ -9,7 +9,8 @@ module Hecks
             private
 
             def default_name(settings, layout)
-              name = settings.fetch(:default_container, layout.domain.name).to_s
+              domain = layout.domain
+              name = settings.fetch(:default_container, domain.name).to_s
               target = layout.all.find { |container| container.name == name }
               unless target
                 raise ArgumentError,

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

@@ -6,6 +6,9 @@ module Hecks
           # Reads and checks the `alerts` setting of a world. Extended onto `Monitoring`, which
           # supplies the key lists and defaults.
           module Reading
+            # An EventBridge schedule expression: `rate(...)` or `cron(...)`.
+            SCHEDULE_EXPRESSION = /\A(rate|cron)\(.+\)\z/
+
             private
 
             def alarms(entries, containers)
@@ -62,7 +65,7 @@ module Hecks
 
             def warmer_rate(given)
               rate = given.fetch(:rate, "rate(1 minute)").to_s
-              return rate if rate.match?(/\A(rate|cron)\(.+\)\z/)
+              return rate if rate.match?(SCHEDULE_EXPRESSION)
 
               raise ArgumentError,
                     "alerts warmer rate must be a schedule expression such as rate(1 minute), got #{rate.inspect}"

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

@@ -21,8 +21,9 @@ module Hecks
           end
 
           def task_sections(plan, context)
+            layout = plan.layout
             {
-              "domain_essential"          => domain_essential_yaml(plan.layout.domain),
+              "domain_essential"          => domain_essential_yaml(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]),
@@ -70,9 +71,10 @@ module Hecks
 
           def extra_resources_yaml(plan, context)
             alerts = plan.alerts
-            groups = plan.layout.balanced.to_h { |container| [container.name, container.target_group_id] }
+            layout = plan.layout
+            groups = 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),
+            blocks([Containers.repositories_yaml(layout), Extras.resources_yaml(plan.extras),
                     monitoring.rstrip].reject(&:empty?).join("\n\n"))
           end
           private_class_method :extra_resources_yaml
@@ -87,7 +89,8 @@ module Hecks
           private_class_method :outputs_yaml
 
           def container_outputs(plan)
-            repositories = plan.layout.all.map do |container|
+            layout = plan.layout
+            repositories = 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"

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

@@ -6,6 +6,9 @@ module Hecks
           # The logical ids and the AWS names of a stack's resources, derived from the stack and
           # overridable by the world. Extended onto `Settings`, which supplies the role lists.
           module Ids
+            # One to 255 printable ASCII characters, the only text EC2 takes as a description.
+            PRINTABLE_ASCII = /\A[\x20-\x7e]{1,255}\z/
+
             private
 
             def logical_ids(overrides, base)
@@ -42,7 +45,7 @@ module Hecks
               return Check.resource_name!(value, "names #{role}") unless role == :alb_security_group_description
 
               text = value.to_s
-              return text if text.match?(/\A[\x20-\x7e]{1,255}\z/)
+              return text if text.match?(PRINTABLE_ASCII)
 
               raise ArgumentError,
                     "names #{role} must be 1 to 255 printable ASCII characters (EC2 rejects anything else), got #{value.inspect}"