improve logging, log status and guide user to doc

lizk886 · lizk886 · commit b57e1ba70534 · 2025-11-13T13:12:43.000-08:00
diff --git a/src/main/java/com/uid2/shared/Const.java b/src/main/java/com/uid2/shared/Const.java
@@ -91,6 +91,7 @@ public static class Config {
 
         // Others
         public static final String SaltsExpiredShutdownHours = "salts_expired_shutdown_hours";
+        public static final String KeysetKeyShutdownHours = "keyset_key_shutdown_hours";
         public static final String encryptionSupportVersion = "encryption_support_version";
     }
 
diff --git a/src/main/java/com/uid2/shared/attest/UidCoreClient.java b/src/main/java/com/uid2/shared/attest/UidCoreClient.java
@@ -89,8 +89,12 @@ private InputStream internalDownload(String path) throws CloudStorageException {
                 inputStream = getWithAttest(path);
             }
             return inputStream;
+        } catch (CloudStorageException e) {
+            throw e;
         } catch (Exception e) {
-            throw new CloudStorageException("download error: " + e.getMessage(), e);
+            throw new CloudStorageException(
+                "Cannot download required files from UID2 core service, exception: " + e.getClass().getSimpleName() + 
+                ", please visit UID2 guides for troubleshooting", e);
         }
     }
 
@@ -108,7 +112,12 @@ private InputStream getWithAttest(String path) throws IOException, AttestationRe
         HttpResponse<String> httpResponse;
         httpResponse = sendHttpRequest(path, attestationToken);
         if (httpResponse.statusCode() != 200) {
-            throw new CloudStorageException(String.format("Non-success response from core on request to %s. Status code: %d", path, httpResponse.statusCode()));
+            // Don't log full path as it may contain sensitive information
+            URI uri = URI.create(path);
+            String safeEndpoint = uri.getHost() + uri.getPath();
+            throw new CloudStorageException(String.format(
+                "Cannot download required files from UID2 core service, HTTP response code %d, endpoint: %s, please visit UID2 guides for troubleshooting", 
+                httpResponse.statusCode(), safeEndpoint));
         }
         return Utils.convertHttpResponseToInputStream(httpResponse);
     }
diff --git a/src/main/java/com/uid2/shared/vertx/RotatingStoreVerticle.java b/src/main/java/com/uid2/shared/vertx/RotatingStoreVerticle.java
@@ -15,6 +15,7 @@
 
 import java.util.concurrent.atomic.AtomicInteger;
 import java.util.concurrent.atomic.AtomicLong;
+import java.util.function.Consumer;
 
 public class RotatingStoreVerticle extends AbstractVerticle {
     private static final Logger LOGGER = LoggerFactory.getLogger(RotatingStoreVerticle.class);
@@ -31,47 +32,54 @@ public class RotatingStoreVerticle extends AbstractVerticle {
     private final AtomicLong latestVersion = new AtomicLong(-1L);
     private final AtomicLong latestEntryCount = new AtomicLong(-1L);
     private final AtomicInteger storeRefreshIsFailing = new AtomicInteger(0);
+    private final Consumer<Boolean> refreshCallback;
 
     private final long refreshIntervalMs;
 
     public RotatingStoreVerticle(String storeName, long refreshIntervalMs, IMetadataVersionedStore versionedStore) {
+        this(storeName, refreshIntervalMs, versionedStore, null);
+    }
+
+    public RotatingStoreVerticle(String storeName, long refreshIntervalMs, IMetadataVersionedStore versionedStore,
+            Consumer<Boolean> refreshCallback) {
         this.healthComponent = HealthManager.instance.registerComponent(storeName + "-rotator");
         this.healthComponent.setHealthStatus(false, "not started");
 
         this.storeName = storeName;
         this.counterStoreRefreshed = Counter
-            .builder("uid2_config_store_refreshed_total")
-            .tag("store", storeName)
-            .description("counter for how many times " + storeName + " store is refreshed")
-            .register(Metrics.globalRegistry);
+                .builder("uid2_config_store_refreshed_total")
+                .tag("store", storeName)
+                .description("counter for how many times " + storeName + " store is refreshed")
+                .register(Metrics.globalRegistry);
         this.counterStoreRefreshTimeMs = Counter
-            .builder("uid2_config_store_refreshtime_ms_total")
-            .tag("store", storeName)
-            .description("counter for total time (ms) " + storeName + " store spend in refreshing")
-            .register(Metrics.globalRegistry);
+                .builder("uid2_config_store_refreshtime_ms_total")
+                .tag("store", storeName)
+                .description("counter for total time (ms) " + storeName + " store spend in refreshing")
+                .register(Metrics.globalRegistry);
         this.counterStoreRefreshFailures = Counter
-            .builder("uid2_config_store_refresh_failures_total")
-            .tag("store", storeName)
-            .description("counter for number of " + storeName + " store refresh failures")
-            .register(Metrics.globalRegistry);
+                .builder("uid2_config_store_refresh_failures_total")
+                .tag("store", storeName)
+                .description("counter for number of " + storeName + " store refresh failures")
+                .register(Metrics.globalRegistry);
         this.gaugeStoreVersion = Gauge
-            .builder("uid2_config_store_version", () -> this.latestVersion.get())
-            .tag("store", storeName)
-            .description("gauge for " + storeName + " store version")
-            .register(Metrics.globalRegistry);
+                .builder("uid2_config_store_version", () -> this.latestVersion.get())
+                .tag("store", storeName)
+                .description("gauge for " + storeName + " store version")
+                .register(Metrics.globalRegistry);
         this.gaugeStoreEntryCount = Gauge
-            .builder("uid2_config_store_entry_count", () -> this.latestEntryCount.get())
-            .tag("store", storeName)
-            .description("gauge for " + storeName + " store total entry count")
-            .register(Metrics.globalRegistry);
+                .builder("uid2_config_store_entry_count", () -> this.latestEntryCount.get())
+                .tag("store", storeName)
+                .description("gauge for " + storeName + " store total entry count")
+                .register(Metrics.globalRegistry);
         this.gaugeConsecutiveRefreshFailures = Gauge
-            .builder("uid2_config_store_consecutive_refresh_failures", () -> this.storeRefreshIsFailing.get())
-            .tag("store", storeName)
-            .description("gauge for number of consecutive " + storeName + " store refresh failures")
-            .register(Metrics.globalRegistry);
+                .builder("uid2_config_store_consecutive_refresh_failures", () -> this.storeRefreshIsFailing.get())
+                .tag("store", storeName)
+                .description("gauge for number of consecutive " + storeName + " store refresh failures")
+                .register(Metrics.globalRegistry);
         this.versionedStore = versionedStore;
         this.refreshIntervalMs = refreshIntervalMs;
         this.storeRefreshTimer = Metrics.timer("uid2_store_refresh_duration", "store_name", storeName);
+        this.refreshCallback = refreshCallback;
     }
 
     @Override
@@ -98,7 +106,8 @@ private void startRefresh(Promise<Void> promise) {
                 this.startBackgroundRefresh();
             } else {
                 this.healthComponent.setHealthStatus(false, ar.cause().getMessage());
-                LOGGER.error("Failed " + this.storeName + " loading. Trying again in " + refreshIntervalMs + "ms", ar.cause());
+                LOGGER.error("Failed " + this.storeName + " loading. Trying again in " + refreshIntervalMs + "ms",
+                        ar.cause());
                 vertx.setTimer(refreshIntervalMs, id -> this.startRefresh(promise));
             }
         });
@@ -109,23 +118,28 @@ private void startBackgroundRefresh() {
             final long start = System.nanoTime();
 
             vertx.executeBlocking(() -> {
-                    this.refresh();
-                    return null;
-                }).onComplete(asyncResult -> {
-                    final long end = System.nanoTime();
-                    final long elapsed = ((end - start) / 1000000);
-                    this.counterStoreRefreshTimeMs.increment(elapsed);
-                    if (asyncResult.failed()) {
-                        this.counterStoreRefreshFailures.increment();
-                        this.storeRefreshIsFailing.set(1);
-                        LOGGER.error("Failed to load " + this.storeName + ", " + elapsed + " ms", asyncResult.cause());
-                    } else {
-                        this.counterStoreRefreshed.increment();
-                        this.storeRefreshIsFailing.set(0);
-                        LOGGER.trace("Successfully refreshed " + this.storeName + ", " + elapsed + " ms");
+                this.refresh();
+                return null;
+            }).onComplete(asyncResult -> {
+                final long end = System.nanoTime();
+                final long elapsed = ((end - start) / 1000000);
+                this.counterStoreRefreshTimeMs.increment(elapsed);
+                if (asyncResult.failed()) {
+                    this.counterStoreRefreshFailures.increment();
+                    this.storeRefreshIsFailing.set(1);
+                    LOGGER.error("Failed to load " + this.storeName + ", " + elapsed + " ms", asyncResult.cause());
+                    if (this.refreshCallback != null) {
+                        this.refreshCallback.accept(false);
+                    }
+                } else {
+                    this.counterStoreRefreshed.increment();
+                    this.storeRefreshIsFailing.set(0);
+                    LOGGER.trace("Successfully refreshed " + this.storeName + ", " + elapsed + " ms");
+                    if (this.refreshCallback != null) {
+                        this.refreshCallback.accept(true);
                     }
                 }
-            );
+            });
         });
     }
 
diff --git a/src/test/java/com/uid2/shared/attest/UidCoreClientTest.java b/src/test/java/com/uid2/shared/attest/UidCoreClientTest.java
@@ -72,7 +72,7 @@ public void Download_AttestInternalFail_ExceptionThrown() throws IOException, At
         CloudStorageException result = assertThrows(CloudStorageException.class, () -> {
             uidCoreClient.download("https://download");
         });
-        String expectedExceptionMessage = "download error: AttestationResponseCode: AttestationFailure, test failure";
+        String expectedExceptionMessage = "Cannot download required files from UID2 core service, exception: AttestationResponseHandlerException, please visit UID2 guides for troubleshooting";
         assertEquals(expectedExceptionMessage, result.getMessage());
     }
 
@@ -100,4 +100,114 @@ void getJwtReturnsCoreToken() {
         when(mockAttestationResponseHandler.getCoreJWT()).thenReturn("coreJWT");
         Assertions.assertEquals("coreJWT", this.uidCoreClient.getJWT());
     }
+
+    @Test
+    public void Download_Http403Error_LogsStatusCodeAndEndpoint() throws IOException, AttestationResponseHandlerException {
+        HttpResponse<String> mockHttpResponse = mock(HttpResponse.class);
+        when(mockHttpResponse.statusCode()).thenReturn(403);
+        when(mockHttpClient.get(eq("https://core-prod.uidapi.com/sites/refresh"), any(HashMap.class))).thenReturn(mockHttpResponse);
+
+        CloudStorageException result = assertThrows(CloudStorageException.class, () -> {
+            uidCoreClient.download("https://core-prod.uidapi.com/sites/refresh");
+        });
+
+        assertAll(
+            () -> assertTrue(result.getMessage().contains("HTTP response code 403"), 
+                "Should contain HTTP status code 403"),
+            () -> assertTrue(result.getMessage().contains("Cannot download required files from UID2 core service"), 
+                "Should have customer-friendly message"),
+            () -> assertTrue(result.getMessage().contains("core-prod.uidapi.com/sites/refresh"), 
+                "Should contain safe endpoint"),
+            () -> assertTrue(result.getMessage().contains("please visit UID2 guides for troubleshooting"), 
+                "Should reference documentation")
+        );
+    }
+
+    @Test
+    public void Download_Http404Error_LogsStatusCode() throws IOException, AttestationResponseHandlerException {
+        HttpResponse<String> mockHttpResponse = mock(HttpResponse.class);
+        when(mockHttpResponse.statusCode()).thenReturn(404);
+        when(mockHttpClient.get(eq("https://core-prod.uidapi.com/keys/refresh"), any(HashMap.class))).thenReturn(mockHttpResponse);
+
+        CloudStorageException result = assertThrows(CloudStorageException.class, () -> {
+            uidCoreClient.download("https://core-prod.uidapi.com/keys/refresh");
+        });
+
+        assertAll(
+            () -> assertTrue(result.getMessage().contains("HTTP response code 404"), 
+                "Should contain HTTP status code 404"),
+            () -> assertTrue(result.getMessage().contains("core-prod.uidapi.com/keys/refresh"), 
+                "Should contain endpoint")
+        );
+    }
+
+    @Test
+    public void Download_Http500Error_LogsStatusCode() throws IOException, AttestationResponseHandlerException {
+        HttpResponse<String> mockHttpResponse = mock(HttpResponse.class);
+        when(mockHttpResponse.statusCode()).thenReturn(500);
+        when(mockHttpClient.get(eq("https://core-prod.uidapi.com/salts/refresh"), any(HashMap.class))).thenReturn(mockHttpResponse);
+
+        CloudStorageException result = assertThrows(CloudStorageException.class, () -> {
+            uidCoreClient.download("https://core-prod.uidapi.com/salts/refresh");
+        });
+
+        assertAll(
+            () -> assertTrue(result.getMessage().contains("HTTP response code 500"), 
+                "Should contain HTTP status code 500"),
+            () -> assertTrue(result.getMessage().contains("UID2 core service"), 
+                "Should identify source as UID2 core")
+        );
+    }
+
+    @Test
+    public void Download_Http503Error_LogsStatusCode() throws IOException, AttestationResponseHandlerException {
+        HttpResponse<String> mockHttpResponse = mock(HttpResponse.class);
+        when(mockHttpResponse.statusCode()).thenReturn(503);
+        when(mockHttpClient.get(eq("https://core-integ.uidapi.com/clients/refresh"), any(HashMap.class))).thenReturn(mockHttpResponse);
+
+        CloudStorageException result = assertThrows(CloudStorageException.class, () -> {
+            uidCoreClient.download("https://core-integ.uidapi.com/clients/refresh");
+        });
+
+        assertTrue(result.getMessage().contains("HTTP response code 503"), 
+            "Should contain HTTP status code 503");
+    }
+
+    @Test
+    public void Download_NetworkError_LogsExceptionType() throws IOException, AttestationResponseHandlerException {
+        IOException networkException = new IOException("Connection timeout");
+        when(mockHttpClient.get(anyString(), any(HashMap.class))).thenThrow(networkException);
+
+        CloudStorageException result = assertThrows(CloudStorageException.class, () -> {
+            uidCoreClient.download("https://core-prod.uidapi.com/sites/refresh");
+        });
+
+        assertAll(
+            () -> assertTrue(result.getMessage().contains("Cannot download required files from UID2 core service"), 
+                "Should have customer-friendly message"),
+            () -> assertTrue(result.getMessage().contains("exception: IOException"), 
+                "Should log exception type"),
+            () -> assertTrue(result.getMessage().contains("please visit UID2 guides"), 
+                "Should reference documentation")
+        );
+    }
+
+    @Test
+    public void Download_EndpointWithQueryParams_LogsOnlyHostAndPath() throws IOException, AttestationResponseHandlerException {
+        HttpResponse<String> mockHttpResponse = mock(HttpResponse.class);
+        when(mockHttpResponse.statusCode()).thenReturn(403);
+        // URL with query params (simulating potential sensitive data)
+        when(mockHttpClient.get(eq("https://core-prod.uidapi.com/sites/refresh?token=secret123"), any(HashMap.class))).thenReturn(mockHttpResponse);
+
+        CloudStorageException result = assertThrows(CloudStorageException.class, () -> {
+            uidCoreClient.download("https://core-prod.uidapi.com/sites/refresh?token=secret123");
+        });
+
+        assertAll(
+            () -> assertTrue(result.getMessage().contains("core-prod.uidapi.com/sites/refresh"), 
+                "Should contain host and path"),
+            () -> assertFalse(result.getMessage().contains("token=secret123"), 
+                "Should NOT contain query parameters with tokens")
+        );
+    }
 }

Original file line number	Diff line number	Diff line change
`@@ -91,6 +91,7 @@ public static class Config {`
`91`	`91`
`92`	`92`	`// Others`
`93`	`93`	`public static final String SaltsExpiredShutdownHours = "salts_expired_shutdown_hours";`
	`94`	`+ public static final String KeysetKeyShutdownHours = "keyset_key_shutdown_hours";`
`94`	`95`	`public static final String encryptionSupportVersion = "encryption_support_version";`
`95`	`96`	`}`
`96`	`97`
Original file line number	Diff line number	Diff line change
`@@ -89,8 +89,12 @@ private InputStream internalDownload(String path) throws CloudStorageException {`
`89`	`89`	`inputStream = getWithAttest(path);`
`90`	`90`	`}`
`91`	`91`	`return inputStream;`
	`92`	`+ } catch (CloudStorageException e) {`
	`93`	`+ throw e;`
`92`	`94`	`} catch (Exception e) {`
`93`		`- throw new CloudStorageException("download error: " + e.getMessage(), e);`
	`95`	`+ throw new CloudStorageException(`
	`96`	`+ "Cannot download required files from UID2 core service, exception: " + e.getClass().getSimpleName() +`
	`97`	`+ ", please visit UID2 guides for troubleshooting", e);`
`94`	`98`	`}`
`95`	`99`	`}`
`96`	`100`
`@@ -108,7 +112,12 @@ private InputStream getWithAttest(String path) throws IOException, AttestationRe`
`108`	`112`	`HttpResponse<String> httpResponse;`
`109`	`113`	`httpResponse = sendHttpRequest(path, attestationToken);`
`110`	`114`	`if (httpResponse.statusCode() != 200) {`
`111`		`- throw new CloudStorageException(String.format("Non-success response from core on request to %s. Status code: %d", path, httpResponse.statusCode()));`
	`115`	`+ // Don't log full path as it may contain sensitive information`
	`116`	`+ URI uri = URI.create(path);`
	`117`	`+ String safeEndpoint = uri.getHost() + uri.getPath();`
	`118`	`+ throw new CloudStorageException(String.format(`
	`119`	`+ "Cannot download required files from UID2 core service, HTTP response code %d, endpoint: %s, please visit UID2 guides for troubleshooting",`
	`120`	`+ httpResponse.statusCode(), safeEndpoint));`
`112`	`121`	`}`
`113`	`122`	`return Utils.convertHttpResponseToInputStream(httpResponse);`
`114`	`123`	`}`