add ability to comment in uncovered endpoints file

Author: david-crespo

nexus/tests/integration_tests/audit_log.rs

@@ -38,6 +38,20 @@ use std::str::FromStr;
 type ControlPlaneTestContext =
     nexus_test_utils::ControlPlaneTestContext<omicron_nexus::Server>;
 
+/// Strip lines starting with `#` from a snapshot file so that the file
+/// can contain human-readable comments explaining why each entry is there.
+fn strip_comments(s: &str) -> String {
+    let mut out: String = s
+        .lines()
+        .filter(|line| !line.starts_with('#'))
+        .collect::<Vec<_>>()
+        .join("\n");
+    if s.ends_with('\n') {
+        out.push('\n');
+    }
+    out
+}
+
 fn to_q(d: DateTime<Utc>) -> String {
     d.to_rfc3339_opts(chrono::SecondsFormat::Micros, true)
 }
@@ -711,7 +725,9 @@ async fn test_audit_log_coverage(ctx: &ControlPlaneTestContext) {
 
     // Print a helpful message when there are new uncovered endpoints
     let expected_path = "tests/output/uncovered-audit-log-endpoints.txt";
-    let expected = std::fs::read_to_string(expected_path).unwrap_or_default();
+    let expected = strip_comments(
+        &std::fs::read_to_string(expected_path).unwrap_or_default(),
+    );
     let expected_ops: std::collections::HashSet<&str> = expected
         .lines()
         .skip(1) // skip the header line
@@ -767,8 +783,9 @@ async fn test_audit_log_coverage(ctx: &ControlPlaneTestContext) {
     }
 
     let get_expected_path = "tests/output/audited-get-endpoints.txt";
-    let get_expected =
-        std::fs::read_to_string(get_expected_path).unwrap_or_default();
+    let get_expected = strip_comments(
+        &std::fs::read_to_string(get_expected_path).unwrap_or_default(),
+    );
     let get_expected_ops: std::collections::HashSet<&str> = get_expected
         .lines()
         .skip(1) // skip the header line

nexus/tests/output/uncovered-audit-log-endpoints.txt

@@ -1,8 +1,17 @@
 Mutating endpoints without audit logging:
+# Intermediate steps of the device OAuth flow. The meaningful endpoint is
+# device_auth_confirm, which is where authentication and token creation
+# happen. device_auth_request has no user identity, and device_access_token
+# is just polling (mostly 400s) until the token created by confirm is ready.
 device_access_token                          (post   "/device/token")
 device_auth_request                          (post   "/device/auth")
+# Called too many times per disk image upload, other related endpoints cover it.
+# See https://github.com/oxidecomputer/omicron/pull/10046 for rationale.
 disk_bulk_write_import                       (post   "/v1/disks/{disk}/bulk-write")
+# Needs rework to extract actor identity before we can log it. Low priority
+# since sessions expire anyway.
 logout                                       (post   "/v1/logout")
+# Read-only queries that happen to use POST for the request body
 system_timeseries_query                      (post   "/v1/system/timeseries/query")
 timeseries_query                             (post   "/v1/timeseries/query")