hecks 3.1.3 → 3.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 88b11874249737158a9451d66aa0842ef88fb3f1ff047cced68d97b2ce9fdc5f
-  data.tar.gz: 2872e381ce8e7fe5d46ef7a7623134dc23d923e57bdf194758effedaa1cc4671
+  metadata.gz: c79ef6cb53e23b9faa0f452f116af208c659512f00716e47c7f3cdaad3d51e86
+  data.tar.gz: b693ea21f847607ca2964759f9e0cec9dc7c4f8e1ea341b6636e99f8b4b1d294
 SHA512:
-  metadata.gz: 76a39ab361adfb4e07bb558cb917d46bf3d7b6bb21340ff9789cb7b6c10be47a3197df4f394e8da73129feeb5b8439d9401f5e83b8620e0a512fce966c891377
-  data.tar.gz: 58f1514450a234f3807897401daf7db410739463a8603bf58b7d73e548f14424211b4d1c5f3af1dc7421b769f39582e15c6f22188932af3de054961eed2cb641
+  metadata.gz: 38d1467d95484bcf093d6671982bf5e4edc4fc1be8907d849a88df9b85ab2b9810f88ce9533a9d1d125187fd47c26191fbe3e104e90307ee6fb19b3cffa37546
+  data.tar.gz: 329631cf0d425b281c4a4770318d2956ae95ca7d2e0b12e2e0054bd2f0d72a3310a92d1ce2fa125d5a056c76026c27472230a0710335790267db173ada8e48db

data/lib/hecks/deploy/bluebook/deploy.bluebook

@@ -665,6 +665,111 @@ Hecks.bluebook "Deploy" do
     trigger MakefileCheck::Flag, with: { refusal: :refusal }
   end
 
+  aggregate "CostCheck" do
+    description "One reading of what hosting costs a month, against a budget."
+
+    attribute :run,     RunKey
+    attribute :budget,  Budget
+    attribute :since,   Since
+    attribute :report,  Report, optional: true
+    attribute :refusal, Report, optional: true
+    identified_by :run
+
+    value_object "RunKey" do
+      attribute :value, String, pattern: '[^ \t\n\r]'
+
+      invariant("a run is named") { !value.to_s.empty? }
+    end
+
+    # Whole dollars a month.
+    value_object "Budget" do
+      attribute :value, Integer
+
+      invariant("a budget is positive") { value.positive? }
+    end
+
+    # The first day to count, as `YYYY-MM-DD`: the first complete day after the last change to
+    # what is running, so a bill that still carries the old setup is not read as the new one.
+    value_object "Since" do
+      attribute :value, String, pattern: '[0-9]{4}-[0-9]{2}-[0-9]{2}'
+    end
+
+    value_object "Report" do
+      attribute :value, String
+    end
+
+    lifecycle :status, default: "requested" do
+      transition "Pass" => "within_budget", from: "requested"
+      transition "Flag" => "flagged",       from: "requested"
+    end
+
+    # The reading is the billed daily total from the first complete day since `since` up to
+    # yesterday, scaled to a month; today is left out because its bill is still partial.
+    command "Check" do
+      goal "Read what hosting has billed since a day and compare its monthly rate to a budget"
+
+      attribute :run,    RunKey
+      attribute :budget, Budget
+      attribute :since,  Since
+
+      sets :run
+      sets :budget
+      sets :since
+
+      emits "CostCheckRequested"
+    end
+
+    command "Pass" do
+      goal "Record that the monthly rate is within the budget, and what it was"
+
+      reference_to CostCheck
+      attribute :report, Report
+
+      sets :report
+
+      emits "CostWithinBudget"
+    end
+
+    command "Flag" do
+      goal "Record that the monthly rate is over the budget, or that it could not be read, and what was said"
+
+      reference_to CostCheck
+      attribute :refusal, Report
+
+      sets :refusal
+
+      emits "CostFlagged"
+    end
+
+    query "Verdict" do
+      description "What one reading found: its status, and the report or the reason it was flagged."
+      attribute :run, RunKey
+      where(run: :run)
+      order_by :run
+    end
+
+    query "Flagged" do
+      description "Every reading that was over its budget or could not be taken."
+      where(status: "flagged")
+      order_by :run
+    end
+  end
+
+  policy "MeasureWhenChecked" do
+    on      "CostCheck.CostCheckRequested"
+    trigger CostCheck::CostExplorer::Measure, with: { run: :run }
+  end
+
+  policy "RecordTheCostWithinBudget" do
+    on      "CostCheck.CostAnswered"
+    trigger CostCheck::Pass, with: { report: :report }
+  end
+
+  policy "RecordTheFlaggedCost" do
+    on      "CostCheck.CostRefused"
+    trigger CostCheck::Flag, with: { refusal: :refusal }
+  end
+
   aggregate "TemplateComparison" do
     description "One offline comparison of two CloudFormation templates, by logical id."
 

data/lib/hecks/deploy/bluebook/deploy.hecksagon

@@ -35,6 +35,14 @@ Hecks.hecksagon "Deploy" do
     end
   end
 
+  Deploy::CostCheck.port "CostExplorer" do
+    asks "Measure", to: CostCheck do
+      attribute :run, RunKey
+      answers "CostAnswered"
+      refuses "CostRefused"
+    end
+  end
+
   Deploy::TemplateComparison.port "DeployToolchain" do
     asks "Compare", to: TemplateComparison do
       attribute :run, RunKey

data/lib/hecks/deploy/oidc.json

@@ -6,6 +6,21 @@
       "verb": "Deploy::BoxTarget.Declare",
       "role": null
     },
+    {
+      "scope": "deploy:cost_check.check",
+      "verb": "Deploy::CostCheck.Check",
+      "role": null
+    },
+    {
+      "scope": "deploy:cost_check.flag",
+      "verb": "Deploy::CostCheck.Flag",
+      "role": null
+    },
+    {
+      "scope": "deploy:cost_check.pass",
+      "verb": "Deploy::CostCheck.Pass",
+      "role": null
+    },
     {
       "scope": "deploy:fargate_target.declare",
       "verb": "Deploy::FargateTarget.Declare",

data/lib/hecks/hecks/adapters/cost_explorer.adapter

@@ -0,0 +1,7 @@
+# Required by name, not relative to this file: a fuzz or model check boots a copy of this directory,
+# and the implementation must load once, from `lib/`, not from the copy.
+require "hecks/hecks/adapters/cost_explorer"
+
+Hecks.adapter "CostExplorer" do
+  port "CostExplorer"
+end

data/lib/hecks/hecks/adapters/cost_explorer.rb

@@ -0,0 +1,102 @@
+# frozen_string_literal: true
+
+require "open3"
+require "json"
+require "date"
+
+module Hecks
+  module Adapters
+    # The `CostExplorer` port's adapter: reads what an AWS account has billed, with the `aws`
+    # command, and compares the monthly rate to a budget.
+    #
+    # It reads the daily unblended cost from the check's `since` day up to yesterday. Today is left
+    # out because its bill is still partial, and a day is counted whatever Cost Explorer marks it
+    # (a day stays "estimated" for a while after it ends). The rate is the mean daily cost scaled
+    # to an average month. A rate within the budget is answered with a one-line report; a rate over
+    # it, a span with no complete day, or a failed `aws` call is refused with a reason, which the
+    # runtime records on the check.
+    class CostExplorer
+      # Days in an average month, for scaling a daily mean to a monthly rate.
+      DAYS_IN_MONTH = 30.4375
+
+      # How many of the biggest services the report names.
+      TOP_SERVICES = 3
+
+      # @param aggregate [Object, nil] unused
+      # @param settings [Hash] `today:` pins the day the span ends before, for tests
+      # @param root [String, nil] unused
+      def initialize(aggregate: nil, settings: {}, root: nil)
+        @today = settings[:today]
+      end
+
+      # Reads the billed cost since a day and compares its monthly rate to the budget.
+      #
+      # @param held [Hash] the check's fields: `budget:` whole dollars a month and `since:` the
+      #   first day to count (`YYYY-MM-DD`), each a value object or a plain value
+      # @return [Hash{Symbol => Hash}] `report:` the rate against the budget, the shape
+      #   `CostCheck.Pass` takes
+      # @raise [RuntimeError] when no complete day has passed since `since`, `aws` fails, or the
+      #   rate is over the budget
+      def measure(**held)
+        budget = Integer(plain(held[:budget]))
+        first = Date.iso8601(plain(held[:since]).to_s)
+        last = today
+        raise "no complete day since #{first}; today (#{last}) is still being billed" if first >= last
+
+        days = daily_costs(first, last)
+        line = report_line(first, last, days, budget)
+        raise "over budget: #{line}" if monthly_rate(days) > budget
+
+        { report: { value: line } }
+      end
+
+      private
+
+      # @return [Date] the day the span ends before: today, in UTC
+      def today = @today ? Date.iso8601(@today.to_s) : Time.now.utc.to_date
+
+      # @return [Hash{String => Hash{String => Float}}] day => service => dollars
+      def daily_costs(first, last)
+        out, err, status = Open3.capture3(
+          "aws", "ce", "get-cost-and-usage", "--time-period", "Start=#{first},End=#{last}",
+          "--granularity", "DAILY", "--metrics", "UnblendedCost",
+          "--group-by", "Type=DIMENSION,Key=SERVICE", "--output", "json"
+        )
+        raise "aws ce get-cost-and-usage failed: #{err.strip.empty? ? out.strip : err.strip}" unless status.success?
+
+        rows = JSON.parse(out).fetch("ResultsByTime")
+        raise "Cost Explorer returned no days for #{first}..#{last}" if rows.empty?
+
+        rows.to_h { |row| [row.dig("TimePeriod", "Start"), by_service(row)] }
+      end
+
+      def by_service(row)
+        row.fetch("Groups").to_h do |group|
+          [group.fetch("Keys").first, group.dig("Metrics", "UnblendedCost", "Amount").to_f]
+        end
+      end
+
+      # @return [Float] the mean daily total, scaled to an average month
+      def monthly_rate(days)
+        mean = days.values.sum { |services| services.values.sum } / days.size
+        mean * DAYS_IN_MONTH
+      end
+
+      def report_line(first, last, days, budget)
+        mean = days.values.sum { |services| services.values.sum } / days.size
+        biggest = totals_by_service(days).max_by(TOP_SERVICES) { |_name, dollars| dollars }
+        named = biggest.map { |name, dollars| "#{name} $#{format('%.2f', dollars / days.size)}/day" }.join(", ")
+        "#{first}..#{last - 1} (#{days.size} days): $#{format('%.2f', mean)}/day, " \
+          "$#{format('%.2f', monthly_rate(days))}/month against $#{budget}; biggest: #{named}"
+      end
+
+      def totals_by_service(days)
+        days.values.each_with_object(Hash.new(0.0)) do |services, totals|
+          services.each { |name, dollars| totals[name] += dollars }
+        end
+      end
+
+      def plain(argument) = argument.is_a?(Hash) ? argument[:value] : argument
+    end
+  end
+end

data/lib/hecks/hecks/hecks.hecksagon

@@ -368,6 +368,14 @@ Hecks.hecksagon "Hecks" do
     end
   end
 
+  Deploy::CostCheck.port "CostExplorer" do
+    asks "Measure", to: CostCheck do
+      attribute :run, RunKey
+      answers "CostAnswered"
+      refuses "CostRefused"
+    end
+  end
+
   Deploy::TemplateComparison.port "DeployToolchain" do
     asks "Compare", to: TemplateComparison do
       attribute :run, RunKey

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

@@ -62,7 +62,7 @@ ROLL=$(jq -n --arg compose "$(B64 "$WORK/compose.json")" --arg secrets "$(B64 "$
     "aws ecr get-login-password --region '"$REGION"' | docker login --username AWS --password-stdin \($registry) >/dev/null",
     "docker compose -f compose.json pull --quiet",
     "docker compose -f compose.json up -d --remove-orphans",
-    "sleep 20; docker compose -f compose.json ps --format \"table {{.Service}}\\t{{.Status}}\""],
+    "for i in $(seq 1 40); do docker compose -f compose.json ps --format \"{{.Status}}\" | grep -qE \"^Up (Less than a second|[0-4] seconds?)|Restarting|Created|Exited\" || break; sleep 1; done; docker compose -f compose.json ps --format \"table {{.Service}}\\t{{.Status}}\""],
    executionTimeout: ["900"]}')
 
 echo "==> rolling $BOX_STACK ($BOX) at $(date -u +%H:%M:%SZ)"

data/lib/hecks/tools/deploy_recipe.rb

@@ -252,6 +252,7 @@ module Hecks
       # @return [void]
       def write(artifact, out_dir)
         written = Hecks::Projector.write(artifact, out_dir, as: :files)
+        written.each { |path| File.chmod(0o755, path) if path.end_with?(".sh") }
 
         written.each { |path| puts "wrote #{path}" }
         puts

data/lib/hecks/version.rb

@@ -1,5 +1,5 @@
 module Hecks
   # Read directly by the gemspec, so this file must never require the
   # rest of the gem (its dependencies aren't resolved yet at that point).
-  VERSION = "3.1.3".freeze
+  VERSION = "3.2.0".freeze
 end

data/rust/host/HECKS_RELEASE

@@ -1 +1 @@
-3.1.3
+3.2.0

data/rust/host/src/auth.rs

@@ -592,8 +592,25 @@ pub async fn active_role(client: &Mutex<Client>, domain_ir: &Value, email: &str)
         .and_then(|(_, state)| role_of(state).map(String::from)))
 }
 
+/// The Governance identity id linked to the member with `email`, read from
+/// the live membership head. `None` when the member has not signed in yet.
+pub async fn member_identity_id(client: &Mutex<Client>, domain_ir: &Value, email: &str) -> anyhow::Result<Option<String>> {
+    let email = email.to_lowercase();
+    Ok(member_rows(client, domain_ir)
+        .await?
+        .iter()
+        .find(|(id, state)| id.to_lowercase() == email && !is_deleted(state))
+        .and_then(|(_, state)| linked_identity_id(state)))
+}
+
+// The id the sign-in flow wrote onto a Member row, or `None` before then.
+fn linked_identity_id(state: &Value) -> Option<String> {
+    state.get("identity_id").and_then(|v| v.get("value")).and_then(|v| v.as_str()).map(str::to_string)
+}
+
 /// Every admitted person as a JSON row: name, email, role, `linked`
-/// (signed in), `granted` (has access), and `disabled`.
+/// (signed in), `granted` (has access), `disabled`, and `identity_id`
+/// (the Governance identity id, `null` until the person has signed in).
 pub async fn all_people(client: &Mutex<Client>, domain_ir: &Value) -> anyhow::Result<Vec<Value>> {
     Ok(member_rows(client, domain_ir)
         .await?
@@ -610,6 +627,7 @@ pub async fn all_people(client: &Mutex<Client>, domain_ir: &Value) -> anyhow::Re
                 "linked": linked,
                 "granted": role.is_some() && !disabled,
                 "disabled": disabled,
+                "identity_id": linked_identity_id(&state),
             })
         })
         .collect())
@@ -1206,9 +1224,15 @@ mod tests {
         let chris = people.iter().find(|p| p["email"] == "chris@example.com").unwrap();
         assert_eq!(chris["linked"], true);
         assert_eq!(chris["granted"], true);
+        assert_eq!(chris["identity_id"], "id-1");
         let angie = people.iter().find(|p| p["email"] == "angie@example.com").unwrap();
         assert_eq!(angie["linked"], false);
         assert_eq!(angie["granted"], false);
+        assert!(angie["identity_id"].is_null());
+
+        assert_eq!(member_identity_id(&db, &domain_ir, "Chris@Example.com").await.unwrap().as_deref(), Some("id-1"));
+        assert_eq!(member_identity_id(&db, &domain_ir, "angie@example.com").await.unwrap(), None);
+        assert_eq!(member_identity_id(&db, &domain_ir, "nobody@example.com").await.unwrap(), None);
     }
 
     #[tokio::test]

data/rust/host/src/web.rs

@@ -369,7 +369,10 @@ async fn active_session_email(
 
 async fn accounts_me_route(domain_ir: &Value, cookies: &HashMap<String, String>, secret: &str, client: &Mutex<Client>) -> Value {
     match active_session_email(domain_ir, cookies, secret, client).await {
-        Ok(email) => respond(200, "application/json", &json!({"email": email}).to_string()),
+        Ok(email) => match auth::member_identity_id(client, domain_ir, &email).await {
+            Ok(identity_id) => respond(200, "application/json", &json!({"email": email, "identity_id": identity_id}).to_string()),
+            Err(e) => respond(500, "application/json", &json!({"error": format!("members lookup failed: {e}")}).to_string()),
+        },
         Err(response) => response,
     }
 }
@@ -434,7 +437,7 @@ pub(crate) async fn add_member_route(
         Ok(true) => respond(
             201,
             "application/json",
-            &json!({"name": name, "email": email, "role": role, "linked": false, "granted": true, "disabled": false}).to_string(),
+            &json!({"name": name, "email": email, "role": role, "linked": false, "granted": true, "disabled": false, "identity_id": null}).to_string(),
         ),
         Ok(false) => json_error(500, &format!("the person was admitted but the {role} role was not granted")),
         Err(e) => json_error(500, &format!("the person was admitted but the {role} role was not granted: {e}")),
@@ -2173,6 +2176,7 @@ mod tests {
         assert_eq!(response["statusCode"], 200, "{response:?}");
         let body: Value = serde_json::from_str(response["body"].as_str().unwrap()).unwrap();
         assert_eq!(body["email"], "zed@example.com");
+        assert_eq!(body["identity_id"], "id-1", "the signed-in account's Governance identity id");
 
         let empty = HashMap::new();
         assert_eq!(accounts_me_route(&domain_ir, &empty, secret, &client).await["statusCode"], 401);
@@ -2273,11 +2277,11 @@ mod tests {
         assert_eq!(names, ["amy", "Zed"], "sorted case-insensitively by name");
         assert_eq!(
             people[1],
-            json!({"name": "Zed", "email": "zed@example.com", "role": "Admin", "linked": true, "granted": true, "disabled": false})
+            json!({"name": "Zed", "email": "zed@example.com", "role": "Admin", "linked": true, "granted": true, "disabled": false, "identity_id": "id-1"})
         );
         assert_eq!(
             people[0],
-            json!({"name": "amy", "email": "amy@example.com", "role": null, "linked": false, "granted": false, "disabled": false})
+            json!({"name": "amy", "email": "amy@example.com", "role": null, "linked": false, "granted": false, "disabled": false, "identity_id": null})
         );
     }
 
@@ -2465,7 +2469,7 @@ mod tests {
         let created: Value = serde_json::from_str(response["body"].as_str().unwrap()).unwrap();
         assert_eq!(
             created,
-            json!({"name": "New Person", "email": "new@example.com", "role": "Admin", "linked": false, "granted": true, "disabled": false})
+            json!({"name": "New Person", "email": "new@example.com", "role": "Admin", "linked": false, "granted": true, "disabled": false, "identity_id": null})
         );
 
         let listing = members_route(&domain_ir, &cookies, secret, &client).await;

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: hecks
 version: !ruby/object:Gem::Version
-  version: 3.1.3
+  version: 3.2.0
 platform: ruby
 authors:
 - Chris Young
@@ -380,6 +380,8 @@ files:
 - lib/hecks/hecks/adapters/codebase/test_suite.rb
 - lib/hecks/hecks/adapters/codebase/tree.rb
 - lib/hecks/hecks/adapters/console_capture.rb
+- lib/hecks/hecks/adapters/cost_explorer.adapter
+- lib/hecks/hecks/adapters/cost_explorer.rb
 - lib/hecks/hecks/adapters/deploy_toolchain.adapter
 - lib/hecks/hecks/adapters/deploy_toolchain.rb
 - lib/hecks/hecks/adapters/finding_github.adapter