Synchronizer: Add consolidated sync report and --fail-on-error flag

polaris-synchronizer/README.md

@@ -184,3 +184,25 @@ java -jar cli/build/libs/polaris-synchronizer-cli.jar sync-polaris \
 > nor remove or modify them or their assignments to principals/principal-roles on the target. This is to accommodate that 
 > the tool itself will be running with the permission levels for these principals and roles, and we do not want to modify 
 > the tool's permissions at runtime.
+
+At the end of every run, `sync-polaris` prints a consolidated synchronization report summarizing how
+many entities of each type were created, overwritten, removed, skipped (already in sync), or failed,
+along with a list of any failures encountered:
+
+```
+=== Synchronization Report ===
+Principal:               3 created, 0 overwritten, 0 removed, 0 skipped, 1 failed
+Catalog:                  2 created, 1 overwritten, 0 removed, 5 skipped, 0 failed
+Table:                   20 created, 0 overwritten, 0 removed, 40 skipped, 2 failed
+
+Failures:
+  - Principal 'alice': <exception message>
+  - Table 'db.orders': <exception message>
+===============================
+```
+
+By default, `sync-polaris` exits with status `0` regardless of whether individual entities failed to
+synchronize (matching the pre-existing behavior, where failures are logged and the run continues).
+Pass `--fail-on-error` to make the command exit with a non-zero status if the report contains any
+failures. This is distinct from `--halt-on-failure`, which aborts the run as soon as the first failure
+occurs; `--fail-on-error` lets the run finish synchronizing everything it can, then fails afterward.

polaris-synchronizer/api/src/main/java/org/apache/polaris/tools/sync/polaris/planning/plan/EntityType.java

@@ -0,0 +1,32 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+package org.apache.polaris.tools.sync.polaris.planning.plan;
+
+/** The category of entity a {@link SynchronizationReport} outcome is recorded against. */
+public enum EntityType {
+  PRINCIPAL,
+  PRINCIPAL_ROLE,
+  PRINCIPAL_ROLE_ASSIGNMENT,
+  CATALOG,
+  CATALOG_ROLE,
+  CATALOG_ROLE_ASSIGNMENT,
+  GRANT,
+  NAMESPACE,
+  TABLE
+}

polaris-synchronizer/api/src/main/java/org/apache/polaris/tools/sync/polaris/planning/plan/SyncOutcome.java

@@ -0,0 +1,28 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+package org.apache.polaris.tools.sync.polaris.planning.plan;
+
+/** The outcome of an individual entity sync attempt, recorded in a {@link SynchronizationReport}. */
+public enum SyncOutcome {
+  CREATED,
+  OVERWRITTEN,
+  REMOVED,
+  SKIPPED,
+  FAILED
+}

polaris-synchronizer/api/src/main/java/org/apache/polaris/tools/sync/polaris/planning/plan/SynchronizationReport.java

@@ -0,0 +1,140 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+package org.apache.polaris.tools.sync.polaris.planning.plan;
+
+import java.util.ArrayList;
+import java.util.EnumMap;
+import java.util.List;
+import java.util.Map;
+
+/**
+ * Accumulates the outcome of every individual entity sync attempt performed during a run, so that
+ * a single consolidated summary can be printed at the end instead of relying on interleaved logs.
+ */
+public class SynchronizationReport {
+
+  private record Failure(EntityType type, String identifier, String message) {}
+
+  private final Map<EntityType, Map<SyncOutcome, Integer>> counts;
+
+  private final List<Failure> failures;
+
+  public SynchronizationReport() {
+    this.counts = new EnumMap<>(EntityType.class);
+    for (EntityType type : EntityType.values()) {
+      Map<SyncOutcome, Integer> outcomeCounts = new EnumMap<>(SyncOutcome.class);
+      for (SyncOutcome outcome : SyncOutcome.values()) {
+        outcomeCounts.put(outcome, 0);
+      }
+      this.counts.put(type, outcomeCounts);
+    }
+    this.failures = new ArrayList<>();
+  }
+
+  /**
+   * Records that an entity was successfully synced.
+   *
+   * @param type the category of entity that was synced
+   * @param outcome the outcome of the sync; must not be {@link SyncOutcome#FAILED} - use {@link
+   *     #recordFailure(EntityType, String, Exception)} for failures
+   */
+  public void recordSuccess(EntityType type, SyncOutcome outcome) {
+    if (outcome == SyncOutcome.FAILED) {
+      throw new IllegalArgumentException("Use recordFailure() to record a failed sync.");
+    }
+    Map<SyncOutcome, Integer> outcomeCounts = counts.get(type);
+    outcomeCounts.put(outcome, outcomeCounts.get(outcome) + 1);
+  }
+
+  /**
+   * Records that an entity failed to sync.
+   *
+   * @param type the category of entity that failed to sync
+   * @param identifier a human-readable identifier for the entity, e.g. its name
+   * @param cause the exception that caused the failure
+   */
+  public void recordFailure(EntityType type, String identifier, Exception cause) {
+    Map<SyncOutcome, Integer> outcomeCounts = counts.get(type);
+    outcomeCounts.put(SyncOutcome.FAILED, outcomeCounts.get(SyncOutcome.FAILED) + 1);
+    failures.add(new Failure(type, identifier, cause.getMessage()));
+  }
+
+  /** Returns true if any entity failed to sync. */
+  public boolean hasFailures() {
+    return !failures.isEmpty();
+  }
+
+  private static String displayName(EntityType type) {
+    return switch (type) {
+      case PRINCIPAL -> "Principal";
+      case PRINCIPAL_ROLE -> "PrincipalRole";
+      case PRINCIPAL_ROLE_ASSIGNMENT -> "PrincipalRoleAssignment";
+      case CATALOG -> "Catalog";
+      case CATALOG_ROLE -> "CatalogRole";
+      case CATALOG_ROLE_ASSIGNMENT -> "CatalogRoleAssignment";
+      case GRANT -> "Grant";
+      case NAMESPACE -> "Namespace";
+      case TABLE -> "Table";
+    };
+  }
+
+  /** Renders the accumulated counts and failures as a human-readable text block. */
+  public String render() {
+    StringBuilder sb = new StringBuilder();
+    sb.append("=== Synchronization Report ===\n");
+
+    for (EntityType type : EntityType.values()) {
+      Map<SyncOutcome, Integer> outcomeCounts = counts.get(type);
+      int total =
+          outcomeCounts.get(SyncOutcome.CREATED)
+              + outcomeCounts.get(SyncOutcome.OVERWRITTEN)
+              + outcomeCounts.get(SyncOutcome.REMOVED)
+              + outcomeCounts.get(SyncOutcome.SKIPPED)
+              + outcomeCounts.get(SyncOutcome.FAILED);
+
+      if (total == 0) {
+        continue;
+      }
+
+      sb.append(
+          String.format(
+              "%-24s%d created, %d overwritten, %d removed, %d skipped, %d failed%n",
+              displayName(type) + ":",
+              outcomeCounts.get(SyncOutcome.CREATED),
+              outcomeCounts.get(SyncOutcome.OVERWRITTEN),
+              outcomeCounts.get(SyncOutcome.REMOVED),
+              outcomeCounts.get(SyncOutcome.SKIPPED),
+              outcomeCounts.get(SyncOutcome.FAILED)));
+    }
+
+    if (hasFailures()) {
+      sb.append("\nFailures:\n");
+      for (Failure failure : failures) {
+        sb.append(
+            String.format(
+                "  - %s '%s': %s%n",
+                displayName(failure.type()), failure.identifier(), failure.message()));
+      }
+    }
+
+    sb.append("===============================");
+
+    return sb.toString();
+  }
+}

polaris-synchronizer/api/src/test/java/org/apache/polaris/tools/sync/polaris/PolarisSynchronizerSkipIcebergContentTest.java

@@ -37,6 +37,7 @@
 import org.apache.polaris.tools.sync.polaris.catalog.NoOpETagManager;
 import org.apache.polaris.tools.sync.polaris.planning.NoOpSyncPlanner;
 import org.apache.polaris.tools.sync.polaris.planning.plan.SynchronizationPlan;
+import org.apache.polaris.tools.sync.polaris.planning.plan.SynchronizationReport;
 import org.apache.polaris.tools.sync.polaris.service.IcebergCatalogService;
 import org.apache.polaris.tools.sync.polaris.service.PolarisService;
 import org.junit.jupiter.api.Assertions;
@@ -299,6 +300,7 @@ public void testSkipIcebergContentSkipsIcebergSyncButStillSyncsCatalogRoles() {
             target,
             new NoOpETagManager(),
             false,
+            new SynchronizationReport(),
             true);
 
     synchronizer.syncCatalogs();
@@ -323,6 +325,7 @@ public void testIcebergContentSyncedWhenNotSkipped() {
             target,
             new NoOpETagManager(),
             false,
+            new SynchronizationReport(),
             false);
 
     synchronizer.syncCatalogs();
@@ -354,6 +357,7 @@ public void testTableScopedGrantsStillAttemptedWhenIcebergContentSkipped() {
             target,
             new NoOpETagManager(),
             false,
+            new SynchronizationReport(),
             true);
 
     synchronizer.syncCatalogs();

polaris-synchronizer/api/src/test/java/org/apache/polaris/tools/sync/polaris/planning/plan/SynchronizationReportTest.java

@@ -0,0 +1,112 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+package org.apache.polaris.tools.sync.polaris.planning.plan;
+
+import org.junit.jupiter.api.Assertions;
+import org.junit.jupiter.api.Test;
+
+public class SynchronizationReportTest {
+
+  @Test
+  public void recordSuccessIncrementsOnlyTargetedCell() {
+    SynchronizationReport report = new SynchronizationReport();
+
+    report.recordSuccess(EntityType.PRINCIPAL, SyncOutcome.CREATED);
+
+    String rendered = report.render();
+
+    Assertions.assertTrue(rendered.contains("Principal:"));
+    Assertions.assertTrue(rendered.contains("1 created, 0 overwritten, 0 removed, 0 skipped, 0 failed"));
+    Assertions.assertFalse(rendered.contains("Catalog:"));
+  }
+
+  @Test
+  public void recordFailureIncrementsFailedCountAndCapturesIdentifierAndMessage() {
+    SynchronizationReport report = new SynchronizationReport();
+
+    report.recordFailure(EntityType.TABLE, "db.orders", new RuntimeException("connection refused"));
+
+    String rendered = report.render();
+
+    Assertions.assertTrue(rendered.contains("Table:"));
+    Assertions.assertTrue(rendered.contains("0 created, 0 overwritten, 0 removed, 0 skipped, 1 failed"));
+    Assertions.assertTrue(rendered.contains("Table 'db.orders': connection refused"));
+  }
+
+  @Test
+  public void hasFailuresIsFalseForAnAllSuccessReport() {
+    SynchronizationReport report = new SynchronizationReport();
+
+    report.recordSuccess(EntityType.CATALOG, SyncOutcome.CREATED);
+    report.recordSuccess(EntityType.NAMESPACE, SyncOutcome.REMOVED);
+
+    Assertions.assertFalse(report.hasFailures());
+  }
+
+  @Test
+  public void hasFailuresIsTrueOnceAnyFailureIsRecorded() {
+    SynchronizationReport report = new SynchronizationReport();
+
+    report.recordSuccess(EntityType.CATALOG, SyncOutcome.CREATED);
+    report.recordFailure(EntityType.GRANT, "TABLE", new RuntimeException("boom"));
+
+    Assertions.assertTrue(report.hasFailures());
+  }
+
+  @Test
+  public void renderOmitsAllZeroEntityTypesAndFailuresSectionWhenEmpty() {
+    SynchronizationReport report = new SynchronizationReport();
+
+    report.recordSuccess(EntityType.PRINCIPAL_ROLE, SyncOutcome.CREATED);
+
+    String rendered = report.render();
+
+    Assertions.assertTrue(rendered.contains("PrincipalRole:"));
+    Assertions.assertFalse(rendered.contains("Grant:"));
+    Assertions.assertFalse(rendered.contains("Namespace:"));
+    Assertions.assertFalse(rendered.contains("Failures:"));
+  }
+
+  @Test
+  public void renderIncludesEachFailureWhenMultipleFailuresExist() {
+    SynchronizationReport report = new SynchronizationReport();
+
+    report.recordFailure(EntityType.PRINCIPAL, "alice", new RuntimeException("timeout"));
+    report.recordFailure(EntityType.TABLE, "db.returns", new RuntimeException("not found"));
+
+    String rendered = report.render();
+
+    Assertions.assertTrue(rendered.contains("Failures:"));
+    Assertions.assertTrue(rendered.contains("Principal 'alice': timeout"));
+    Assertions.assertTrue(rendered.contains("Table 'db.returns': not found"));
+  }
+
+  @Test
+  public void recordSuccessWithSkippedIncrementsSkippedCountAndDoesNotCountAsFailure() {
+    SynchronizationReport report = new SynchronizationReport();
+
+    report.recordSuccess(EntityType.NAMESPACE, SyncOutcome.SKIPPED);
+
+    String rendered = report.render();
+
+    Assertions.assertTrue(rendered.contains("Namespace:"));
+    Assertions.assertTrue(rendered.contains("0 created, 0 overwritten, 0 removed, 1 skipped, 0 failed"));
+    Assertions.assertFalse(report.hasFailures());
+  }
+}