fix: address code review feedback for health check

- Separate connection failure vs server error in DoclingFastServerClient:
  unreachable → "not available", HTTP 503 → "reachable but unhealthy"
- Add comment explaining why HancomClient accepts non-2xx responses
- Inline getClient() call in HybridDocumentProcessor
- Add comment explaining intentional pre-triage health check
- Update test assertions for 503 case and add RFC 5737 note

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: bundolee

java/opendataloader-pdf-core/src/main/java/org/opendataloader/pdf/hybrid/DoclingFastServerClient.java

@@ -99,16 +99,23 @@ public void checkAvailability() throws IOException {
             .get()
             .build();
 
-        try (Response response = healthClient.newCall(healthRequest).execute()) {
-            if (!response.isSuccessful()) {
-                throw new IOException("Hybrid server health check failed with status " + response.code());
-            }
+        Response response;
+        try {
+            response = healthClient.newCall(healthRequest).execute();
         } catch (IOException e) {
             throw new IOException(
                 "Hybrid server is not available at " + baseUrl + "\n"
                 + "Please start the server with: opendataloader-pdf-hybrid\n"
                 + "Or run without --hybrid flag for Java-only processing.", e);
         }
+        try (response) {
+            if (!response.isSuccessful()) {
+                throw new IOException(
+                    "Hybrid server at " + baseUrl + " returned HTTP " + response.code()
+                    + " during health check.\n"
+                    + "The server is reachable but may be starting up or unhealthy.");
+            }
+        }
     }
 
     @Override

java/opendataloader-pdf-core/src/main/java/org/opendataloader/pdf/hybrid/HancomClient.java

@@ -106,7 +106,9 @@ public void checkAvailability() throws IOException {
             .build();
 
         try (Response response = healthClient.newCall(request).execute()) {
-            // Any response means the server is reachable
+            // Any HTTP response (including 4xx/5xx) means the server is reachable.
+            // Hancom API requires authentication for all endpoints, so a 401/403
+            // is expected and still proves connectivity.
         } catch (IOException e) {
             throw new IOException(
                 "Hybrid server is not available at " + baseUrl + "\n"

java/opendataloader-pdf-core/src/main/java/org/opendataloader/pdf/processors/HybridDocumentProcessor.java

@@ -98,9 +98,10 @@ public static List<List<IObject>> processDocument(
         int totalPages = StaticContainers.getDocument().getNumberOfPages();
         LOGGER.log(Level.INFO, "Starting hybrid processing for {0} pages", totalPages);
 
-        // Phase 0: Check backend availability before any processing
-        HybridClient client = getClient(config);
-        client.checkAvailability();
+        // Phase 0: Check backend availability before any processing.
+        // Runs before triage intentionally — if the user explicitly requested hybrid mode,
+        // they expect the server to be available regardless of how pages would be routed.
+        getClient(config).checkAvailability();
 
         // Phase 1: Filter all pages and collect filtered contents
         Map<Integer, List<IObject>> filteredContents = filterAllPages(inputPdfName, config, pagesToProcess, totalPages);

java/opendataloader-pdf-core/src/test/java/org/opendataloader/pdf/hybrid/HealthCheckTest.java

@@ -96,8 +96,10 @@ void testDoclingHealthCheckFailsOnServerError() throws IOException {
 
         try {
             IOException exception = assertThrows(IOException.class, client::checkAvailability);
-            assertTrue(exception.getMessage().contains("not available"),
-                "Error message should indicate server is not available");
+            assertTrue(exception.getMessage().contains("returned HTTP 503"),
+                "Error message should include the HTTP status code");
+            assertTrue(exception.getMessage().contains("reachable but"),
+                "Error message should indicate server is reachable but unhealthy");
         } finally {
             client.shutdown();
         }
@@ -141,7 +143,9 @@ void testHancomHealthCheckFailsWhenServerDown() throws IOException {
 
     @Test
     void testHealthCheckTimesOutQuickly() throws IOException {
-        // Use a non-routable IP to trigger connect timeout
+        // Uses TEST-NET IP (RFC 5737) to trigger a connect timeout.
+        // Some CI environments may reject packets instantly instead of timing out,
+        // but the upper-bound assertion (< 10s) still holds in either case.
         String baseUrl = "http://192.0.2.1:9999";
         DoclingFastServerClient client = new DoclingFastServerClient(
             baseUrl, new OkHttpClient(), new ObjectMapper());