cpflow 5.0.0.rc.1 → 5.0.0

data/docs/thruster.md

@@ -0,0 +1,149 @@
+# Thruster HTTP/2 Proxy on Control Plane
+
+[Thruster](https://github.com/basecamp/thruster) is Basecamp's zero-config HTTP/2 proxy for
+Ruby web applications. It provides HTTP/2 support, asset caching, compression, and early
+hints. Running it on Control Plane requires settings that differ from a standalone (e.g.,
+VPS) deployment, and getting them wrong produces a confusing `502 Bad Gateway` with a
+"protocol error" message.
+
+This page documents the configuration that works.
+
+## TL;DR
+
+- Workload port: `protocol: http` (not `http2`).
+- Dockerfile `CMD` runs Thruster: `CMD ["bundle", "exec", "thrust", "bin/rails", "server"]`.
+- End users still get HTTP/2; Control Plane's load balancer handles TLS termination.
+
+## Why `protocol: http` and not `http2`
+
+### Standalone Thruster (e.g., VPS)
+
+```
+User → HTTPS/HTTP2 → Thruster → HTTP/1.1 → Rails
+      (Thruster handles TLS + HTTP/2)
+```
+
+### Control Plane + Thruster
+
+```
+User → HTTPS/HTTP2 → Control Plane LB → HTTP/1.1 → Thruster → HTTP/1.1 → Rails
+                      (LB handles TLS)    (protocol: http)  (caching, compression)
+```
+
+In the diagram above, `protocol: http` is the workload port setting that governs the
+LB→Thruster hop; `caching, compression` describes what Thruster contributes in this
+path.
+
+On Control Plane, the load balancer terminates TLS and speaks HTTP/2 to the browser —
+so Thruster never sees TLS or HTTP/2 on its incoming side. This is the opposite of a
+standalone (VPS) deployment, where Thruster itself handles TLS and HTTP/2. Setting
+`protocol: http2` on the workload port tells the load balancer to expect HTTP/2 from
+the container, which Thruster does not emit on that hop, and protocol negotiation fails
+with `502 Bad Gateway`.
+
+Even with `protocol: http`, end users still get:
+
+- HTTP/2 to the browser (from the Control Plane load balancer)
+- HTTP/2 multiplexing (from the Control Plane load balancer)
+- Asset caching and compression (from Thruster)
+- Efficient static file serving (from Thruster)
+- Early Hints (103) from Thruster (reaches the browser only if the load balancer forwards 103 responses)
+
+## Workload template
+
+In `.controlplane/templates/rails.yml`:
+
+```yaml
+ports:
+  - number: 3000
+    protocol: http  # Required when fronting Rails with Thruster. Do not use http2.
+```
+
+## Dockerfile
+
+The container's `CMD` must launch Thruster. On Control Plane/Kubernetes the Dockerfile
+`CMD` determines container startup — the `Procfile` is not used (unlike Heroku).
+
+```dockerfile
+# .controlplane/Dockerfile
+CMD ["bundle", "exec", "thrust", "bin/rails", "server"]
+```
+
+## Troubleshooting
+
+### `502 Bad Gateway` with "protocol error"
+
+The workload port is set to `protocol: http2`. Change it to `protocol: http` in
+`rails.yml`, then push the workload spec.
+
+`cpflow apply-template` rewrites the workload from the template. If you have tuned
+CPU, memory, autoscaling, firewall, or other workload fields directly in the
+Control Plane UI (or via `cpln`) without mirroring those changes back into
+`rails.yml`, those edits will be reset. Either reconcile `rails.yml` with the live
+spec first, or change the port field in place:
+
+```sh
+# Option A — apply the full template (resets any drift between rails.yml and the live spec):
+cpflow apply-template rails -a <app>
+
+# Option B — edit only the port protocol in place (preserves UI-tuned fields):
+cpln workload edit <workload> --gvc <gvc> --org <org>
+# change spec.containers[].ports[].protocol from http2 to http
+```
+
+Inspect the current spec before choosing if you're unsure what would change:
+
+```sh
+cpln workload get <workload> --gvc <gvc> --org <org> -o yaml
+```
+
+Note: `cpflow deploy-image` alone is not sufficient — it only updates the container
+image reference and does not modify the workload's port configuration. Run it
+*after* the protocol change has been applied if you also want to ship a new image.
+
+The remaining troubleshooting commands use the raw Control Plane CLI (`cpln`) rather
+than `cpflow`; see
+[the Control Plane CLI quickstart](https://shakadocs.controlplane.com/quickstart/quick-start-3-cli#getting-started-with-the-cli)
+if you don't already have it installed.
+
+### Verify Thruster is the process running as PID 1
+
+`/proc/1/cmdline` stores arguments NUL-separated with no trailing newline, so pipe it
+through `tr` to make the output readable:
+
+```sh
+cpln workload exec <workload> --gvc <gvc> --org <org> --location <location> \
+  -- sh -c "tr '\0' ' ' < /proc/1/cmdline && echo"
+```
+
+You should see `thrust` in the output. If you see `rails` or `puma` directly, the
+Dockerfile `CMD` is not invoking Thruster.
+
+### Test HTTP connectivity through Thruster
+
+This hits Thruster on port 3000 — not Rails directly. A `200 OK` confirms the
+Thruster → Rails path within the container is healthy.
+
+```sh
+cpln workload exec <workload> --gvc <gvc> --org <org> --location <location> \
+  -- curl -s localhost:3000
+```
+
+### Inspect the workload port configuration
+
+```sh
+cpln workload get <workload> --gvc <gvc> --org <org> -o json | jq '.spec.containers[].ports'
+```
+
+## Reference implementation
+
+A working setup lives in the
+[react-webpack-rails-tutorial](https://github.com/shakacode/react-webpack-rails-tutorial)
+repository — see
+[`.controlplane/templates/rails.yml`](https://github.com/shakacode/react-webpack-rails-tutorial/blob/master/.controlplane/templates/rails.yml)
+on the `master` branch.
+
+## Further reading
+
+- [Thruster on GitHub](https://github.com/basecamp/thruster)
+- [DHH on Rails 8 with Thruster](https://world.hey.com/dhh/rails-8-with-thruster-by-default-c953f5e3)

data/docs/troubleshooting.md

@@ -4,3 +4,11 @@
 ## App Web Page Shows `upstream request timeout`
 
 If you get a blank screen showing the message `upstream request timeout` on your app after running `cpflow open -a my-app-name`, check out the application logs. Your image has been promoted and your app crashing when starting.
+
+## `502 Bad Gateway` with "protocol error" (Rails + Thruster)
+
+If a Rails app fronted by [Thruster](https://github.com/basecamp/thruster) returns `502 Bad Gateway` with a "protocol error" message, the workload port is likely set to `protocol: http2`.
+
+Thruster accepts HTTP/1.1 connections from the load balancer, so the workload port must be `protocol: http`. Control Plane's load balancer still serves HTTP/2 to end users.
+
+See [Thruster HTTP/2 Proxy on Control Plane](./thruster.md) for the full configuration and debugging commands.

data/lib/command/apply_template.rb

@@ -91,6 +91,10 @@ module Command
       raise "Can't find templates above, please create them."
     end
 
+    # The confirm_* helpers below prompt the user and mutate state (@asked_for_confirmation,
+    # report_skipped). `confirm_app` and `confirm_workload` return booleans but have side
+    # effects, so their names intentionally lack `?` (suppressed via the inline disables
+    # below). `confirm_apply` doesn't trip the cop and needs no annotation.
     def confirm_apply(message)
       return true if config.options[:yes]
 
@@ -98,7 +102,7 @@ module Command
       Shell.confirm(message)
     end
 
-    def confirm_app(template)
+    def confirm_app(template) # rubocop:disable Naming/PredicateMethod
       app = cp.fetch_gvc(template["name"])
       return true unless app
 
@@ -109,7 +113,7 @@ module Command
       false
     end
 
-    def confirm_workload(template)
+    def confirm_workload(template) # rubocop:disable Naming/PredicateMethod
       workload = cp.fetch_workload(template["name"])
       return true unless workload
 

data/lib/command/base.rb

@@ -502,6 +502,7 @@ module Command
         }
       }
     end
+
     # rubocop:enable Metrics/MethodLength
 
     def self.all_options

data/lib/command/cleanup_stale_apps.rb

@@ -2,20 +2,44 @@
 
 module Command
   class CleanupStaleApps < Base
+    CLEANUP_MODE_OPTION = {
+      name: :mode,
+      params: {
+        banner: "MODE",
+        desc: "Action to take on stale apps: `delete` (default) or `stop`",
+        type: :string,
+        required: false,
+        default: "delete",
+        valid_regex: /^(delete|stop)$/
+      }
+    }.freeze
+
     NAME = "cleanup-stale-apps"
     OPTIONS = [
       app_option(required: true),
-      skip_confirm_option
+      skip_confirm_option,
+      CLEANUP_MODE_OPTION
     ].freeze
-    DESCRIPTION = "Deletes the whole app (GVC with all workloads, all volumesets and all images) for all stale apps"
+    DESCRIPTION = "Deletes or stops stale apps based on the latest image's creation date"
     LONG_DESCRIPTION = <<~DESC
-      - Deletes the whole app (GVC with all workloads, all volumesets and all images) for all stale apps
-      - Also unbinds the app from the secrets policy, as long as both the identity and the policy exist (and are bound)
-      - Stale apps are identified based on the creation date of the latest image
+      - Acts on stale apps based on the creation date of the latest image, or the GVC if no images exist
+      - With `--mode=delete` (default): deletes the whole app (GVC with all workloads, all volumesets and all images), and unbinds the app from the secrets policy as long as both the identity and the policy exist (and are bound)
+      - With `--mode=stop`: suspends all workloads via `cpflow ps:stop` — no GVC, volumeset, or image is removed; resume with `cpflow ps:start`
+      - `--mode=stop` only suspends workloads listed in `app_workloads` + `additional_workloads`; workloads present in the live GVC but missing from the config are skipped silently
+      - `--mode=stop` returns once each workload is marked suspended; it does not wait for the workload to reach a not-ready state
       - Specify the amount of days after an app should be considered stale through `stale_app_image_deployed_days` in the `.controlplane/controlplane.yml` file
-      - If `match_if_app_name_starts_with` is `true` in the `.controlplane/controlplane.yml` file, it will delete all stale apps that start with the name
+      - If `match_if_app_name_starts_with` is `true` in the `.controlplane/controlplane.yml` file, it will act on all stale apps that start with the name
       - Will ask for explicit user confirmation
     DESC
+    EXAMPLES = <<~EX
+      ```sh
+      # Deletes stale apps (default).
+      cpflow cleanup-stale-apps -a $APP_NAME
+
+      # Stops stale apps instead of deleting them; resume with `cpflow ps:start`.
+      cpflow cleanup-stale-apps -a $APP_NAME --mode=stop
+      ```
+    EX
 
     def call # rubocop:disable Metrics/MethodLength
       return progress.puts("No stale apps found.") if stale_apps.empty?
@@ -25,11 +49,11 @@ module Command
         progress.puts("  - #{app[:name]} (#{Shell.color(app[:date].to_s, :red)})")
       end
 
-      return unless confirm_delete
+      return unless confirm_action
 
       progress.puts
       stale_apps.each do |app|
-        delete_app(app[:name])
+        process_app(app[:name])
         progress.puts
       end
     end
@@ -50,9 +74,11 @@ module Command
 
             images = cp.query_images(app_name)["items"].select { |item| item["name"].start_with?("#{app_name}:") }
             image = cp.latest_image_from(images, app_name: app_name, name_only: false)
-            next unless image
 
-            created_date = DateTime.parse(image["created"])
+            created_at = image ? image["created"] : gvc["created"]
+            next unless created_at
+
+            created_date = DateTime.parse(created_at)
             diff_in_days = (now - created_date).to_i
             next unless diff_in_days >= stale_app_image_deployed_days
 
@@ -66,14 +92,27 @@ module Command
         end
     end
 
-    def confirm_delete
+    def confirm_action
       return true if config.options[:yes]
 
-      Shell.confirm("\nAre you sure you want to delete these #{stale_apps.length} apps?")
+      Shell.confirm("\nAre you sure you want to #{action_description} these #{stale_apps.length} apps?")
+    end
+
+    def process_app(app)
+      if mode == "stop"
+        progress.puts("Stopping app '#{app}'")
+        run_cpflow_command("ps:stop", "-a", app)
+      else
+        run_cpflow_command("delete", "-a", app, "--yes")
+      end
+    end
+
+    def action_description
+      mode == "stop" ? "suspend all workloads in" : "delete"
     end
 
-    def delete_app(app)
-      run_cpflow_command("delete", "-a", app, "--yes")
+    def mode
+      @mode ||= config.options[:mode]
     end
   end
 end

data/lib/command/delete.rb

@@ -81,7 +81,9 @@ module Command
       progress.puts("#{Shell.color(message, :red)}\n#{images_list}\n\n")
     end
 
-    def confirm_delete(item)
+    # Prompts the user and writes to progress on confirm — returns boolean but
+    # has side effects, so the method name intentionally lacks `?`.
+    def confirm_delete(item) # rubocop:disable Naming/PredicateMethod
       return true if config.options[:yes]
 
       confirmed = Shell.confirm("Are you sure you want to delete '#{item}'?")

data/lib/command/deploy_image.rb

@@ -31,10 +31,13 @@ module Command
           next unless container["image"].match?(%r{^/org/#{config.org}/image/#{config.app}[:@]})
 
           container_name = container["name"]
-          step("Deploying image '#{image}' for workload '#{container_name}'") do
+          step("Deploying image '#{image}' for workload '#{workload}'") do
             cp.workload_set_image_ref(workload, container: container_name, image: image)
-            deployed_endpoints[container_name] = endpoint_for_workload(workload_data)
+            deployed_endpoints[workload] = endpoint_for_workload(workload_data)
           end
+          # Deploy the first matching app-image container per workload; CPLN workloads
+          # are expected to have a single container that runs the app image.
+          break
         end
       end
 

data/lib/command/generate.rb

@@ -93,9 +93,13 @@ module Command
     def asset_precompile_hook_run
       command = normalized_asset_precompile_hook_command
       return "" unless command
-      return "" unless single_line_asset_precompile_hook?(command)
 
-      "RUN #{command}\n\n"
+      # Folded YAML scalars carry a trailing newline even when they hold one command.
+      stripped = command.strip
+      return "" if stripped.empty?
+      return "" unless single_line_asset_precompile_hook?(stripped)
+
+      "RUN #{stripped}\n\n"
     end
 
     def single_line_asset_precompile_hook?(command)
@@ -122,7 +126,7 @@ module Command
       # Parse rather than regex-match: Shakapacker emits an environment-keyed YAML file
       # (the hook usually lives under `default:` or `production:`), and folded or quoted
       # multi-line values would also defeat a single-line regex.
-      config = YAML.safe_load(File.read("config/shakapacker.yml"), aliases: true)
+      config = YAML.safe_load_file("config/shakapacker.yml", aliases: true)
       hook = extract_shakapacker_precompile_hook(config)
       hook unless hook.nil? || hook.empty?
     rescue Psych::SyntaxError

data/lib/command/generate_github_actions.rb

@@ -14,8 +14,9 @@ module Command
 
     def copy_files
       relative_paths = generated_files
+      replacements = template_variables
       copy_template_files(relative_paths)
-      substitute_template_variables(relative_paths)
+      substitute_template_variables(relative_paths, replacements)
       make_shell_scripts_executable(relative_paths)
     end
 
@@ -39,9 +40,9 @@ module Command
 
     def template_variables
       {
-        "__CPFLOW_VERSION__" => ::Cpflow::VERSION,
+        "__CPFLOW_GITHUB_ACTIONS_REF__" => cpflow_github_actions_ref,
         "__STAGING_BRANCH_FILTER__" => staging_branch_filter,
-        "__STAGING_APP_BRANCH_EXPRESSION__" => staging_app_branch_expression
+        "__STAGING_BRANCH_DEFAULT__" => staging_branch_default
       }
     end
 
@@ -58,12 +59,23 @@ module Command
       branches.map(&:to_json).join(", ")
     end
 
-    def staging_app_branch_expression
-      return "${{ vars.STAGING_APP_BRANCH }}" unless staging_branch
+    def staging_branch_default
+      staging_branch.to_s
+    end
+
+    def cpflow_github_actions_ref
+      ref = ENV.fetch("CPFLOW_GITHUB_ACTIONS_REF", default_cpflow_github_actions_ref).to_s.strip
+      return default_cpflow_github_actions_ref if ref.empty?
+
+      if ref.match?(/[[:space:]]/)
+        Shell.abort("Invalid CPFLOW_GITHUB_ACTIONS_REF: #{ref.inspect}. Refs cannot contain whitespace.")
+      end
+
+      ref
+    end
 
-      # `valid_staging_branch?` excludes quotes, so this single-quoted GitHub
-      # expression literal cannot be broken by the generated branch name.
-      "${{ vars.STAGING_APP_BRANCH || '#{staging_branch}' }}"
+    def default_cpflow_github_actions_ref
+      "v#{::Cpflow::VERSION}"
     end
   end
 
@@ -84,7 +96,7 @@ module Command
     DESC
     EXAMPLES = <<~EX
       ```sh
-      # Creates .github/actions and .github/workflows files for the Control Plane flow
+      # Creates thin .github/workflows wrappers for the Control Plane flow
       cpflow generate-github-actions
 
       # Creates the flow with staging deploys triggered from develop

data/lib/command/generator_helpers.rb

@@ -22,10 +22,14 @@ module Command
 
     def make_shell_scripts_executable(file_paths)
       Array(file_paths).each do |path|
-        next unless File.file?(path) && File.extname(path) == ".sh"
+        next unless File.file?(path) && executable_script?(path)
 
         FileUtils.chmod(0o755, path)
       end
     end
+
+    def executable_script?(path)
+      File.extname(path) == ".sh" || File.open(path, &:gets).to_s.start_with?("#!")
+    end
   end
 end

data/lib/command/info.rb

@@ -106,7 +106,9 @@ module Command
       @app_workloads.keys.find { |app_name| config.app_matches?(app_name, app, config.apps[app.to_sym]) }
     end
 
-    def check_any_app_starts_with(app)
+    # Returns boolean but mutates @missing_apps_starting_with and writes to stdout,
+    # so the method name intentionally lacks `?`.
+    def check_any_app_starts_with(app) # rubocop:disable Naming/PredicateMethod
       if any_app_starts_with?(app)
         false
       else

data/lib/command/run.rb

@@ -265,7 +265,22 @@ module Command
 
     def run_interactive
       progress.puts("Connecting to replica '#{replica}'...\n\n")
-      cp.workload_exec(runner_workload, replica, location: location, container: container, command: command)
+      # workload_exec returns false on non-zero exit, nil when signal-killed (e.g. Ctrl-C).
+      # Both fall through to the cleanup hint instead of the generic "non-zero status" abort.
+      success = cp.workload_exec(runner_workload, replica, location: location, container: container, command: command)
+      return if success
+
+      print_interactive_cleanup_hint
+      exit(success.nil? ? ExitCode::INTERRUPT : ExitCode::ERROR_DEFAULT)
+    end
+
+    def print_interactive_cleanup_hint
+      progress.puts(Shell.color(
+                      "\nThe interactive session ended with a non-zero exit or signal from the upstream CLI. " \
+                      "If the runner workload is still running, stop it with:\n  " \
+                      "cpflow ps:stop #{app_workload_replica_args.join(' ')} --location #{location}",
+                      :yellow
+                    ))
     end
 
     def run_non_interactive

data/lib/command/test.rb

@@ -1,7 +1,5 @@
 # frozen_string_literal: true
 
-require "debug"
-
 module Command
   class Test < Base
     NAME = "test"
@@ -15,7 +13,7 @@ module Command
 
     def call
       # Modify this method to trigger the code you want to test.
-      # You can use `debugger` to debug.
+      # Add `require "debug"` locally if you want to use `debugger`.
       # You can use `run_cpflow_command` to simulate a command
       # (e.g., `run_cpflow_command("deploy-image", "-a", "my-app-name")`).
     end

data/lib/core/controlplane.rb

@@ -99,7 +99,7 @@ class Controlplane # rubocop:disable Metrics/ClassLength
     cmd << "--progress=plain" if ControlplaneApiDirect.trace
 
     cmd.concat(docker_args)
-    build_args.each { |build_arg| cmd.concat(["--build-arg", build_arg]) }
+    build_args.each { |build_arg| cmd.push("--build-arg", build_arg) }
     cmd << docker_context
 
     perform!(Shellwords.join(cmd))
@@ -282,7 +282,7 @@ class Controlplane # rubocop:disable Metrics/ClassLength
     cmd = "cpln workload exec #{workload} #{gvc_org} --replica #{replica} --location #{location} -it"
     cmd += " --container #{container}" if container
     cmd += " -- #{command}"
-    perform!(cmd, output_mode: :all)
+    perform(cmd, output_mode: :all)
   end
 
   def start_cron_workload(workload, job_start_yaml, location:)
@@ -472,8 +472,19 @@ class Controlplane # rubocop:disable Metrics/ClassLength
   private
 
   def org_exists?
-    items = api.list_orgs["items"]
+    result = api.list_orgs
+
+    # HTTP 404 from the list-orgs endpoint returns nil in ControlplaneApiDirect.
+    # Defer scoped-token/org problems to the command's target API call, which
+    # can produce a resource-specific error.
+    return true unless result
+
+    items = result.fetch("items", [])
     items.any? { |item| item["name"] == org }
+  rescue ControlplaneApiDirect::ForbiddenError => e
+    raise unless e.url == ControlplaneApi::LIST_ORGS_PATH
+
+    true
   end
 
   def ensure_org_exists!
@@ -519,7 +530,9 @@ class Controlplane # rubocop:disable Metrics/ClassLength
     kernel_system_with_pid_handling(cmd)
   end
 
-  # NOTE: full analogue of Kernel.system which returns pids and saves it to child_pids for proper killing
+  # NOTE: full analogue of Kernel.system which returns pids and saves it to child_pids for proper killing.
+  # Returns true on zero exit, false on non-zero exit, nil when the process was signal-killed.
+  # SystemCallError (e.g. cpln binary missing) propagates — startup checks ensure this is unreachable in practice.
   def kernel_system_with_pid_handling(cmd)
     pid = Process.spawn(cmd)
     $child_pids << pid # rubocop:disable Style/GlobalVars
@@ -528,8 +541,6 @@ class Controlplane # rubocop:disable Metrics/ClassLength
     $child_pids.delete(pid) # rubocop:disable Style/GlobalVars
 
     status.exited? ? status.success? : nil
-  rescue SystemCallError
-    nil
   end
 
   def perform!(cmd, output_mode: nil, sensitive_data_pattern: nil)

data/lib/core/controlplane_api.rb

@@ -1,8 +1,10 @@
 # frozen_string_literal: true
 
 class ControlplaneApi # rubocop:disable Metrics/ClassLength
+  LIST_ORGS_PATH = "/org"
+
   def list_orgs
-    api_json("/org", method: :get)
+    api_json(LIST_ORGS_PATH, method: :get)
   end
 
   def gvc_list(org:)