cpflow 5.2.0 → 5.3.0

data/lib/core/controlplane_api_direct.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-class ControlplaneApiDirect
+class ControlplaneApiDirect # rubocop:disable Metrics/ClassLength
   class RedactedDebugOutput
     SAFE_HEADERS = %w[Content-Type Content-Length Accept Host Date Cache-Control Connection].freeze
     HEADER_REGEX = /^([A-Za-z-]+): (.+)$/
@@ -40,6 +40,9 @@ class ControlplaneApiDirect
     end
   end
 
+  # Raised when fetching the API token via `cpln profile token` fails.
+  class TokenRefreshError < StandardError; end
+
   API_METHODS = {
     get: Net::HTTP::Get,
     patch: Net::HTTP::Patch,
@@ -51,40 +54,200 @@ class ControlplaneApiDirect
 
   API_TOKEN_EXPIRY_SECONDS = 300
 
-  class << self
-    attr_accessor :trace
+  # GET alone retries 5xx responses or transport failures after the request may
+  # have reached the server. Every method may retry an explicit 429 response.
+  # DELETE stays out of this set because after other errors the client cannot
+  # know whether deletion applied server-side.
+  IDEMPOTENT_METHODS = %i[get].freeze
+
+  # Bounded so a retried connect failure fits within the retry deadline.
+  OPEN_TIMEOUT_SECONDS = 10
+  BEST_EFFORT_TIMEOUT_SECONDS = 5
+  RequestPolicy = Struct.new(:sensitive, :retry_transient, :timeout, keyword_init: true) do
+    def initialize(sensitive:, retry_transient:, timeout:)
+      super
+      freeze
+    end
   end
+  DEFAULT_REQUEST_POLICY = RequestPolicy.new(sensitive: false, retry_transient: true, timeout: nil)
+  BEST_EFFORT_SENSITIVE_REQUEST_POLICY = RequestPolicy.new(
+    sensitive: true,
+    retry_transient: false,
+    timeout: BEST_EFFORT_TIMEOUT_SECONDS
+  )
+
+  # Thread-safe API token cache. A single instance is shared process-wide by
+  # default (see `default_token_provider`) so each `ControlplaneApiDirect.new`
+  # per API call reuses the cached token; tests inject a fresh instance.
+  class ApiToken
+    def initialize
+      @mutex = Mutex.new
+      @data = nil
+    end
 
-  def call(url, method:, host: :api, body: nil) # rubocop:disable Metrics/MethodLength, Metrics/CyclomaticComplexity
-    trace = ControlplaneApiDirect.trace
-    uri = URI("#{api_host(host)}#{url}")
-    request = API_METHODS[method].new(uri)
-    request["Content-Type"] = "application/json"
+    def fetch
+      @mutex.synchronize do
+        @data = load_token if @data.nil?
+        refresh! if expiring_soon?
+        @data
+      end
+    end
 
-    refresh_api_token if should_refresh_api_token?
+    def reset
+      @mutex.synchronize { @data = nil }
+    end
 
-    request["Authorization"] = authorization_header
-    request.body = body.to_json if body
+    private
 
-    Shell.debug(method.upcase, "#{uri} #{body&.to_json}")
+    def load_token
+      token = ENV.fetch("CPLN_TOKEN", nil)
+      return validate!(token: token, comes_from_profile: false) if token
 
-    http = Net::HTTP.new(uri.hostname, uri.port)
-    http.use_ssl = uri.scheme == "https"
-    http.set_debug_output(RedactedDebugOutput.new) if trace
+      validate!(token: fetch_profile_token, comes_from_profile: true)
+    end
 
-    response = http.start { |ht| ht.request(request) }
+    def refresh!
+      @data = validate!(token: fetch_profile_token, comes_from_profile: true)
+    end
 
-    case response
-    when Net::HTTPOK
-      JSON.parse(response.body)
-    when Net::HTTPAccepted
+    def fetch_profile_token
+      result = Shell.cmd("cpln", "profile", "token")
+      unless result[:success]
+        raise TokenRefreshError,
+              "Failed to fetch the API token via 'cpln profile token'. " \
+              "Please re-run 'cpln profile login' or set the CPLN_TOKEN env variable."
+      end
+
+      result[:output].chomp
+    end
+
+    def validate!(data)
+      token = data[:token]
+      # Allow any token that does not contain line breaks. Scoped service-account
+      # tokens include punctuation such as '/', '+', ':', and '=', so format
+      # validation is deferred to the Control Plane API.
+      return data if token && !token.empty? && !token.match?(/[\r\n]/)
+
+      raise "Unknown API token format. " \
+            "Please re-run 'cpln profile login' or set the correct CPLN_TOKEN env variable."
+    end
+
+    # Returns `true` when a profile-sourced JWT expires within 5 minutes.
+    def expiring_soon?
+      return false unless @data[:comes_from_profile]
+
+      payload, = JWT.decode(@data[:token], nil, false, algorithms: [])
+      return false unless payload.is_a?(Hash) && payload["exp"]
+
+      payload["exp"].to_i - Time.now.to_i <= API_TOKEN_EXPIRY_SECONDS
+    rescue JWT::DecodeError
+      false
+    end
+  end
+
+  # Retry policy for transient failures: tracks attempts, enforces the attempt
+  # and elapsed-time caps, and sleeps between tries (capped `Retry-After` when
+  # the server provides one, exponential backoff with jitter otherwise).
+  # The deadline is checked only before starting a new attempt: no new attempt
+  # begins after `MAX_TOTAL_RETRY_SECONDS`, but an in-flight attempt may run
+  # past it (bounded by the per-attempt open/read timeouts).
+  class Retrier
+    MAX_ATTEMPTS = 3
+    MAX_TOTAL_RETRY_SECONDS = 120
+    BASE_RETRY_DELAY_SECONDS = 0.5
+    MAX_RETRY_DELAY_SECONDS = 10
+    TRANSIENT_NETWORK_ERRORS = [
+      Net::OpenTimeout, Net::ReadTimeout,
+      Errno::ECONNRESET, Errno::ECONNREFUSED, Errno::EPIPE, Errno::ETIMEDOUT,
+      EOFError, OpenSSL::SSL::SSLError, SocketError
+    ].freeze
+
+    def initialize(sleeper:)
+      @sleeper = sleeper
+      @attempts_made = 1
+      @deadline = Retrier.monotonic_time + MAX_TOTAL_RETRY_SECONDS
+    end
+
+    def self.monotonic_time
+      Process.clock_gettime(Process::CLOCK_MONOTONIC)
+    end
+
+    # Retries 429 responses for every method, but limits 5xx retries to
+    # idempotent requests.
+    def retry_response?(response, idempotent)
+      retriable = response.is_a?(Net::HTTPTooManyRequests) ||
+                  (idempotent && response.is_a?(Net::HTTPServerError))
+      return false unless retriable
+
+      retry?(retry_after: response["Retry-After"])
+    end
+
+    # Whether to retry a transient network error. Non-idempotent requests only
+    # retry when the failure happened before the request may have hit the wire.
+    def retry_exception?(idempotent, request_sent)
+      return false if request_sent && !idempotent
+
+      retry?
+    end
+
+    private
+
+    # When another attempt is allowed, sleeps through the delay and returns `true`.
+    def retry?(retry_after: nil)
+      return false if @attempts_made >= MAX_ATTEMPTS || Retrier.monotonic_time >= @deadline
+
+      @sleeper.call(next_delay(retry_after))
+      @attempts_made += 1
       true
-    when Net::HTTPNotFound
-      nil
-    when Net::HTTPForbidden
-      raise ForbiddenError.new(url: url, response: response)
-    else
-      raise("#{response} #{response.body}")
+    end
+
+    def next_delay(retry_after)
+      seconds = parse_retry_after(retry_after)
+      return seconds if seconds
+
+      backoff = [BASE_RETRY_DELAY_SECONDS * (2**(@attempts_made - 1)), MAX_RETRY_DELAY_SECONDS].min
+      (backoff / 2) + (rand * backoff / 2)
+    end
+
+    # Supports the delta-seconds form of `Retry-After`, capped so a slow or
+    # misconfigured server cannot stall the CLI.
+    def parse_retry_after(value)
+      return nil unless value.to_s.match?(/\A\d+\z/)
+
+      [Integer(value, 10), MAX_RETRY_DELAY_SECONDS].min
+    end
+  end
+
+  class << self
+    attr_accessor :trace
+    attr_reader :default_token_provider
+
+    # Preserved seam: `Controlplane#profile_switch` invalidates the cached
+    # token when the CPLN profile changes.
+    def reset_api_token = default_token_provider.reset
+  end
+
+  @default_token_provider = ApiToken.new
+
+  def initialize(token_provider: ControlplaneApiDirect.default_token_provider, sleeper: nil)
+    @token_provider = token_provider
+    @sleeper = sleeper || ->(seconds) { Kernel.sleep(seconds) }
+  end
+
+  def call(url, method:, host: :api, body: nil, request_policy: DEFAULT_REQUEST_POLICY)
+    uri = URI("#{api_host(host)}#{url}")
+    # Token fetch and request construction happen outside the transient rescue
+    # in attempt_request so their failures (e.g. TokenRefreshError from the
+    # `cpln` shell-out) are never misclassified as retryable network errors.
+    request = build_request(uri, method, body)
+    retrier = Retrier.new(sleeper: @sleeper)
+
+    debug_body = request_policy.sensitive && body ? "[REDACTED]" : body&.to_json
+    Shell.debug(method.upcase, "#{uri} #{debug_body}")
+
+    loop do
+      response = attempt_request(uri, request, method, retrier, request_policy)
+      return handle_response(response, url, request_policy) if response
     end
   end
 
@@ -104,54 +267,85 @@ class ControlplaneApiDirect
     "Bearer #{token}"
   end
 
-  # rubocop:disable Style/ClassVars
-  def api_token # rubocop:disable Metrics/MethodLength
-    return @@api_token if defined?(@@api_token)
-
-    @@api_token = {
-      token: ENV.fetch("CPLN_TOKEN", nil),
-      comes_from_profile: false
-    }
-    if @@api_token[:token].nil?
-      @@api_token = {
-        token: Shell.cmd("cpln", "profile", "token")[:output].chomp,
-        comes_from_profile: true
-      }
-    end
-    token = @@api_token[:token]
-    # Allow any token that does not contain line breaks. Scoped service-account
-    # tokens include punctuation such as '/', '+', ':', and '=', so format
-    # validation is deferred to the Control Plane API.
-    return @@api_token if token && !token.empty? && !token.match?(/[\r\n]/)
+  def api_token = @token_provider.fetch
 
-    raise "Unknown API token format. " \
-          "Please re-run 'cpln profile login' or set the correct CPLN_TOKEN env variable."
+  def self.parse_org(url)
+    url.match(%r{^/org/([^/]+)})&.[](1)
   end
 
-  # Returns `true` when the token is about to expire in 5 minutes
-  def should_refresh_api_token?
-    return false unless api_token[:comes_from_profile]
+  private
 
-    payload, = JWT.decode(api_token[:token], nil, false, algorithms: [])
-    return false unless payload.is_a?(Hash) && payload["exp"]
+  # Returns the response, or `nil` when the attempt failed transiently and the
+  # retrier approved (and already slept before) another attempt. Only the
+  # transport phase (connect + request) is covered by the transient rescue.
+  def attempt_request(uri, request, method, retrier, request_policy)
+    request_sent = false
+    idempotent = IDEMPOTENT_METHODS.include?(method)
+    response = transport_request(uri, request, request_policy) { request_sent = true }
+    return response unless request_policy.retry_transient && retrier.retry_response?(response, idempotent)
 
-    difference_in_seconds = payload["exp"].to_i - Time.now.to_i
+    nil
+  rescue *Retrier::TRANSIENT_NETWORK_ERRORS
+    raise unless request_policy.retry_transient && retrier.retry_exception?(idempotent, request_sent)
 
-    difference_in_seconds <= API_TOKEN_EXPIRY_SECONDS
-  rescue JWT::DecodeError
-    false
+    nil
   end
 
-  def refresh_api_token
-    @@api_token[:token] = Shell.cmd("cpln", "profile", "token")[:output].chomp
+  def transport_request(uri, request, request_policy)
+    http = build_http(uri, request_policy)
+    http.start
+    # Set request_sent before `http.request` deliberately: a reset before bytes
+    # are written is indistinguishable from one after a partial write, so treat
+    # both as sent conservatively.
+    yield
+    begin
+      http.request(request)
+    ensure
+      http.finish if http.started?
+    end
   end
 
-  def self.reset_api_token
-    remove_class_variable(:@@api_token) if defined?(@@api_token)
+  def build_request(uri, method, body)
+    request = API_METHODS[method].new(uri)
+    request["Content-Type"] = "application/json"
+    request["Authorization"] = authorization_header
+    request.body = body.to_json if body
+    request
   end
-  # rubocop:enable Style/ClassVars
 
-  def self.parse_org(url)
-    url.match(%r{^/org/([^/]+)})&.[](1)
+  def build_http(uri, request_policy)
+    http = Net::HTTP.new(uri.hostname, uri.port)
+    http.use_ssl = uri.scheme == "https"
+    # Net::HTTP transparently re-sends requests it deems idempotent once on
+    # mid-flight failures; disable so the Retrier owns the entire retry policy.
+    http.max_retries = 0
+    http.open_timeout = request_policy.timeout || OPEN_TIMEOUT_SECONDS
+    http.read_timeout = request_policy.timeout if request_policy.timeout
+    http.set_debug_output(RedactedDebugOutput.new) if ControlplaneApiDirect.trace && !request_policy.sensitive
+    http
+  end
+
+  def handle_response(response, url, request_policy)
+    case response
+    when Net::HTTPOK then parse_response_body(response, request_policy)
+    when Net::HTTPAccepted then true
+    when Net::HTTPNotFound then nil
+    when Net::HTTPForbidden then raise(ForbiddenError.new(url: url, response: response))
+    else raise(response_error_message(response, request_policy))
+    end
+  end
+
+  def parse_response_body(response, request_policy)
+    JSON.parse(response.body)
+  rescue JSON::ParserError
+    raise unless request_policy.sensitive
+
+    raise JSON::ParserError, "Control Plane API returned invalid JSON for a sensitive request.", cause: nil
+  end
+
+  def response_error_message(response, request_policy)
+    return response.to_s if request_policy.sensitive
+
+    "#{response} #{response.body}"
   end
 end

data/lib/core/shell.rb

@@ -65,15 +65,22 @@ class Shell
     tmp_stderr && !verbose
   end
 
-  def self.cmd(*cmd_to_run, capture_stderr: false)
-    output, status = capture_stderr ? Open3.capture2e(*cmd_to_run) : Open3.capture2(*cmd_to_run)
+  def self.cmd(*cmd_to_run, capture_stderr: false, separate_stderr: false)
+    return cmd_with_separate_stderr(*cmd_to_run) if separate_stderr
 
+    output, status = capture_stderr ? Open3.capture2e(*cmd_to_run) : Open3.capture2(*cmd_to_run)
     {
       output: output,
       success: status.success?
     }
   end
 
+  def self.cmd_with_separate_stderr(*cmd_to_run)
+    output, error_output, status = Open3.capture3(*cmd_to_run)
+    { output: output, error_output: error_output, success: status.success? }
+  end
+  private_class_method :cmd_with_separate_stderr
+
   #
   # Hide sensitive data based on the passed pattern
   #

data/lib/cpflow/version.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
 module Cpflow
-  VERSION = "5.2.0"
+  VERSION = "5.3.0"
   MIN_CPLN_VERSION = "3.1.0"
 end

data/lib/github_flow_templates/.github/cpflow-help.md

@@ -1,10 +1,9 @@
-# Review App Commands
+# Review App Help
 
+You asked for review app help.
 These commands are generated by [cpflow](https://github.com/shakacode/control-plane-flow).
-For full setup, version-pinning, and troubleshooting details, see the upstream
-[CI automation guide](https://github.com/shakacode/control-plane-flow/blob/__CPFLOW_GITHUB_ACTIONS_REF__/docs/ci-automation.md).
 
-## Pull Request Commands
+## Review App Commands
 
 Comment with exactly one command, with no surrounding text or trailing spaces.
 A single trailing newline from GitHub's comment editor is accepted.
@@ -15,13 +14,19 @@ A single trailing newline from GitHub's comment editor is accepted.
 | `+review-app-delete` | Deletes the review app. This also runs automatically when the PR closes. |
 | `+review-app-help` | Posts this help message on the PR. |
 
-## Standard Setup
+For complete setup, version-pinning, and troubleshooting guidance, see the upstream
+[CI automation guide](https://github.com/shakacode/control-plane-flow/blob/__CPFLOW_GITHUB_ACTIONS_REF__/docs/ci-automation.md).
+
+<details>
+<summary>GitHub Actions setup options</summary>
+
+## GitHub Actions Secrets
 
-For the normal generated review-app path, GitHub needs one repository secret:
+For the normal generated review-app path, GitHub Actions needs one secret:
 
 | Name | Where | Notes |
 | --- | --- | --- |
-| `CPLN_TOKEN_STAGING` | Repository secret | Control Plane service-account token for the staging/review org. |
+| `CPLN_TOKEN_STAGING` | GitHub Actions secret | Service-account token scoped to the staging Control Plane org on controlplane.com. |
 
 For public repositories, use a staging/review token that cannot access
 production Control Plane resources. Generated review-app deploys skip fork PR
@@ -29,7 +34,9 @@ heads because Docker builds use repository secrets. If a forked change needs a
 review app, first move the reviewed change to a trusted branch in this
 repository.
 
-No repository variables are required for the standard review-app path when
+## GitHub Actions Variables
+
+No GitHub Actions variables are required for the standard review-app path when
 `.controlplane/controlplane.yml` has exactly one review app entry with
 `match_if_app_name_starts_with: true`. cpflow infers the review-app prefix and
 staging org from that config.
@@ -54,10 +61,12 @@ Optional overrides exist for forks, clones, and unusual apps:
 
 | Name | Notes |
 | --- | --- |
-| `CPLN_ORG_STAGING` | Override the staging/review Control Plane org inferred from `controlplane.yml`. |
+| `CPLN_ORG_STAGING` | Control Plane org on controlplane.com for staging and review apps. Overrides the org inferred from `controlplane.yml`. |
 | `REVIEW_APP_PREFIX` | Override the review-app prefix inferred from `controlplane.yml`. |
 | `PRIMARY_WORKLOAD` | Public workload used for review URLs and health checks; defaults to `rails`. |
 
+</details>
+
 ## Staging And Production
 
 Staging deploys use the same `CPLN_TOKEN_STAGING` secret plus `STAGING_APP_NAME`.
@@ -118,6 +127,9 @@ gh secret list --org OWNER | grep '^CPLN_TOKEN_PRODUCTION[[:space:]]' || true
 Before the first promotion, bootstrap the production app the same way in the
 production org, using production-only secrets and values.
 
+<details>
+<summary>Version locking and advanced options</summary>
+
 ## Version Locking
 
 Generated wrappers pin Control Plane Flow with a release tag, for example
@@ -157,7 +169,7 @@ bin/pin-cpflow-github-ref <40-character-control-plane-flow-commit-sha>
 bin/test-cpflow-github-flow ruby /path/to/control-plane-flow/bin/cpflow
 ```
 
-## Advanced Variables
+## Advanced GitHub Actions Variables
 
 Most apps do not need these:
 
@@ -176,3 +188,5 @@ that copy the workflow before configuring Control Plane can remove
 `.github/workflows/cpflow-review-app-help.yml` or uncomment and adapt the
 wrapper-level `if:` guard shown in that file, for example
 `vars.REVIEW_APP_PREFIX != '' || vars.CPLN_ORG_STAGING != ''`.
+
+</details>

data/lib/github_flow_templates/.github/workflows/cpflow-delete-review-app.yml

@@ -1,5 +1,7 @@
 name: Delete Review App
 
+run-name: "Delete Review App - PR #${{ github.event.pull_request.number || github.event.issue.number || github.event.inputs.pr_number }}"
+
 on:
   pull_request_target:
     types: [closed]
@@ -11,9 +13,15 @@ on:
         description: Pull request number targeted for deletion
         required: true
         type: number
+      reconcile_intent_run_id:
+        description: Authenticated internal handoff; manual values are rejected
+        required: false
+        type: string
 
 permissions:
+  actions: write
   contents: read
+  deployments: write
   issues: write
   pull-requests: write
 
@@ -22,6 +30,8 @@ jobs:
     # pull_request_target is intentional: fork PR-close events need access to
     # staging secrets to delete review apps and update PR comments. The upstream
     # reusable workflow checks out trusted base-branch action code, not fork code.
+    # author_association is a cheap caller-side cost filter. The reusable workflow
+    # still checks the commenter's current repository permission before privileged work.
     if: |
       (github.event_name == 'issue_comment' &&
        github.event.issue.pull_request &&

data/lib/github_flow_templates/.github/workflows/cpflow-deploy-review-app.yml

@@ -13,15 +13,24 @@ on:
         description: Pull request number to deploy
         required: true
         type: number
+      reconcile_intent_run_id:
+        description: Authenticated internal handoff; manual values are rejected
+        required: false
+        type: string
 
 permissions:
+  actions: write
   contents: read
   deployments: write
   issues: write
   pull-requests: write
 
 jobs:
+  # The reusable job exposes `image_built`; downstream jobs can read
+  # `needs.deploy.outputs.image_built`. A value of `false` means this check did not validate the Docker image.
   deploy:
+    # author_association is a cheap caller-side cost filter. The reusable workflow
+    # still checks the commenter's current repository permission before privileged work.
     if: |
       (github.event_name == 'pull_request' &&
        github.event.pull_request.head.repo.full_name == github.repository) ||

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: cpflow
 version: !ruby/object:Gem::Version
-  version: 5.2.0
+  version: 5.3.0
 platform: ruby
 authors:
 - Justin Gordon
@@ -95,6 +95,7 @@ files:
 - ".github/actions/cpflow-setup-environment/action.yml"
 - ".github/actions/cpflow-validate-config/action.yml"
 - ".github/actions/cpflow-wait-for-health/action.yml"
+- ".github/pull_request_template.md"
 - ".github/workflows/check_cpln_links.yml"
 - ".github/workflows/claude-code-review.yml"
 - ".github/workflows/claude.yml"
@@ -303,7 +304,7 @@ licenses:
 metadata:
   rubygems_mfa_required: 'true'
 post_install_message: |
-  cpflow 5.2.0 installed.
+  cpflow 5.3.0 installed.
 
   If this repository already uses generated cpflow GitHub Actions, update the
   checked-in wrappers so GitHub loads the matching control-plane-flow release tag: