Extend error messages

2026-04-07 10:56:56 +02:00
parent 887a2ac95b
commit a67799b04c
3 changed files with 149 additions and 13 deletions
@@ -1,19 +1,42 @@
 #include "KOReaderSyncClient.h"

+#include <Arduino.h>
 #include <ArduinoJson.h>
 #include <Logging.h>
 #include <esp_crt_bundle.h>
+#include <esp_err.h>
+#include <esp_heap_caps.h>
 #include <esp_http_client.h>

 #include <algorithm>
 #include <cctype>
+#include <cstdio>
 #include <ctime>

 #include "KOReaderCredentialStore.h"

 int KOReaderSyncClient::lastHttpCode = 0;
+int KOReaderSyncClient::lastEspError = 0;
+unsigned KOReaderSyncClient::lastHeapAtFailure = 0;
+unsigned KOReaderSyncClient::lastContigHeapAtFailure = 0;
+const char* KOReaderSyncClient::lastOperation = "";

 namespace {
+// Static buffer for the detail string returned by lastFailureDetail() — sized to fit
+// the longest expected message including esp_err name (~32 chars), opcode (~10), heap
+// numbers, and HTTP status. Single-threaded sync flow makes static safe.
+char g_failureDetailBuf[160] = {0};
+
+// Reset the static diagnostic state at the start of each request and capture pre-flight
+// heap so failure reporting always reflects what was available when the request started.
+void beginRequest(const char* operation) {
+  KOReaderSyncClient::lastOperation = operation;
+  KOReaderSyncClient::lastEspError = 0;
+  KOReaderSyncClient::lastHttpCode = 0;
+  KOReaderSyncClient::lastHeapAtFailure = ESP.getFreeHeap();
+  KOReaderSyncClient::lastContigHeapAtFailure = heap_caps_get_largest_free_block(MALLOC_CAP_8BIT | MALLOC_CAP_DEFAULT);
+}
+
 // Device identifier for CrossPoint reader
 constexpr char DEVICE_NAME[] = "CrossPoint";
 constexpr char DEVICE_ID[] = "crosspoint-reader";
@@ -75,6 +98,24 @@ std::string base64Encode(const std::string& input) {
  return out;
 }

+// Verify there is enough contiguous heap to attempt a TLS handshake. mbedTLS needs a
+// large contiguous block during the handshake (~24-32 KB depending on cert chain depth).
+// Total free heap can mislead because fragmentation leaves no single block big enough,
+// which is precisely the scenario after recent PNG/JPG decode activity. Returns true if
+// we should proceed; false means caller must abort with NETWORK_ERROR — in which case
+// lastFailureDetail() will report the heap shortage instead of attempting a doomed handshake.
+bool checkHeapForTls() {
+  // beginRequest() already populated lastContigHeapAtFailure for the diagnostic path.
+  if (KOReaderSyncClient::lastContigHeapAtFailure < KOReaderSyncClient::MIN_CONTIG_HEAP_FOR_TLS) {
+    LOG_ERR("KOSync", "Insufficient contiguous heap for TLS: %u available, %u required",
+            KOReaderSyncClient::lastContigHeapAtFailure, KOReaderSyncClient::MIN_CONTIG_HEAP_FOR_TLS);
+    // Synthesize an esp_err_t-shaped value so the diagnostic detail string is uniform.
+    KOReaderSyncClient::lastEspError = ESP_ERR_NO_MEM;
+    return false;
+  }
+  return true;
+}
+
 // Create configured esp_http_client with small TLS buffers
 esp_http_client_handle_t createClient(const char* url, ResponseBuffer* buf,
                                      esp_http_client_method_t method = HTTP_METHOD_GET) {
@@ -111,8 +152,12 @@ KOReaderSyncClient::Error KOReaderSyncClient::registerUser() {
    return NO_CREDENTIALS;
  }

+  beginRequest("register");
+  if (!checkHeapForTls()) return NETWORK_ERROR;
+
  std::string url = KOREADER_STORE.getBaseUrl() + "/users/create";
-  LOG_DBG("KOSync", "Registering user: %s (heap: %u)", url.c_str(), (unsigned)ESP.getFreeHeap());
+  LOG_DBG("KOSync", "Registering user: %s (heap: %u, contig: %u)", url.c_str(), lastHeapAtFailure,
+          lastContigHeapAtFailure);

  JsonDocument doc;
  doc["username"] = KOREADER_STORE.getUsername();
@@ -124,7 +169,10 @@ KOReaderSyncClient::Error KOReaderSyncClient::registerUser() {

  ResponseBuffer buf;
  esp_http_client_handle_t client = createClient(url.c_str(), &buf, HTTP_METHOD_POST);
-  if (!client) return NETWORK_ERROR;
+  if (!client) {
+    lastEspError = ESP_ERR_NO_MEM;
+    return NETWORK_ERROR;
+  }

  esp_http_client_set_header(client, "Content-Type", "application/json");
  esp_http_client_set_post_field(client, body.c_str(), body.length());
@@ -132,9 +180,11 @@ KOReaderSyncClient::Error KOReaderSyncClient::registerUser() {
  esp_err_t err = esp_http_client_perform(client);
  const int httpCode = esp_http_client_get_status_code(client);
  lastHttpCode = httpCode;
+  lastEspError = err;
  esp_http_client_cleanup(client);

-  LOG_DBG("KOSync", "Register response: %d (err: %d) | body: %s", httpCode, err, buf.data ? buf.data : "");
+  LOG_DBG("KOSync", "Register response: %d (err: %s) | body: %s", httpCode, esp_err_to_name(err),
+          buf.data ? buf.data : "");

  if (err != ESP_OK) {
    return NETWORK_ERROR;
@@ -168,19 +218,27 @@ KOReaderSyncClient::Error KOReaderSyncClient::authenticate() {
    return NO_CREDENTIALS;
  }

+  beginRequest("auth");
+  if (!checkHeapForTls()) return NETWORK_ERROR;
+
  std::string url = KOREADER_STORE.getBaseUrl() + "/users/auth";
-  LOG_DBG("KOSync", "Authenticating: %s (heap: %u)", url.c_str(), (unsigned)ESP.getFreeHeap());
+  LOG_DBG("KOSync", "Authenticating: %s (heap: %u, contig: %u)", url.c_str(), lastHeapAtFailure,
+          lastContigHeapAtFailure);

  ResponseBuffer buf;
  esp_http_client_handle_t client = createClient(url.c_str(), &buf);
-  if (!client) return NETWORK_ERROR;
+  if (!client) {
+    lastEspError = ESP_ERR_NO_MEM;
+    return NETWORK_ERROR;
+  }

  esp_err_t err = esp_http_client_perform(client);
  const int httpCode = esp_http_client_get_status_code(client);
  lastHttpCode = httpCode;
+  lastEspError = err;
  esp_http_client_cleanup(client);

-  LOG_DBG("KOSync", "Auth response: %d (err: %d)", httpCode, err);
+  LOG_DBG("KOSync", "Auth response: %d (err: %s)", httpCode, esp_err_to_name(err));

  if (err != ESP_OK) return NETWORK_ERROR;
  if (httpCode == 200) return OK;
@@ -195,19 +253,27 @@ KOReaderSyncClient::Error KOReaderSyncClient::getProgress(const std::string& doc
    return NO_CREDENTIALS;
  }

+  beginRequest("get progress");
+  if (!checkHeapForTls()) return NETWORK_ERROR;
+
  std::string url = KOREADER_STORE.getBaseUrl() + "/syncs/progress/" + documentHash;
-  LOG_DBG("KOSync", "Getting progress: %s (heap: %u)", url.c_str(), (unsigned)ESP.getFreeHeap());
+  LOG_DBG("KOSync", "Getting progress: %s (heap: %u, contig: %u)", url.c_str(), lastHeapAtFailure,
+          lastContigHeapAtFailure);

  ResponseBuffer buf;
  esp_http_client_handle_t client = createClient(url.c_str(), &buf);
-  if (!client) return NETWORK_ERROR;
+  if (!client) {
+    lastEspError = ESP_ERR_NO_MEM;
+    return NETWORK_ERROR;
+  }

  esp_err_t err = esp_http_client_perform(client);
  const int httpCode = esp_http_client_get_status_code(client);
  lastHttpCode = httpCode;
+  lastEspError = err;
  esp_http_client_cleanup(client);

-  LOG_DBG("KOSync", "Get progress response: %d (err: %d)", httpCode, err);
+  LOG_DBG("KOSync", "Get progress response: %d (err: %s)", httpCode, esp_err_to_name(err));

  if (err != ESP_OK) return NETWORK_ERROR;

@@ -242,8 +308,12 @@ KOReaderSyncClient::Error KOReaderSyncClient::updateProgress(const KOReaderProgr
    return NO_CREDENTIALS;
  }

+  beginRequest("update progress");
+  if (!checkHeapForTls()) return NETWORK_ERROR;
+
  std::string url = KOREADER_STORE.getBaseUrl() + "/syncs/progress";
-  LOG_DBG("KOSync", "Updating progress: %s (heap: %u)", url.c_str(), (unsigned)ESP.getFreeHeap());
+  LOG_DBG("KOSync", "Updating progress: %s (heap: %u, contig: %u)", url.c_str(), lastHeapAtFailure,
+          lastContigHeapAtFailure);

  // Build JSON body
  JsonDocument doc;
@@ -260,7 +330,10 @@ KOReaderSyncClient::Error KOReaderSyncClient::updateProgress(const KOReaderProgr

  ResponseBuffer buf;
  esp_http_client_handle_t client = createClient(url.c_str(), &buf, HTTP_METHOD_PUT);
-  if (!client) return NETWORK_ERROR;
+  if (!client) {
+    lastEspError = ESP_ERR_NO_MEM;
+    return NETWORK_ERROR;
+  }

  esp_http_client_set_header(client, "Content-Type", "application/json");
  esp_http_client_set_post_field(client, body.c_str(), body.length());
@@ -268,9 +341,10 @@ KOReaderSyncClient::Error KOReaderSyncClient::updateProgress(const KOReaderProgr
  esp_err_t err = esp_http_client_perform(client);
  const int httpCode = esp_http_client_get_status_code(client);
  lastHttpCode = httpCode;
+  lastEspError = err;
  esp_http_client_cleanup(client);

-  LOG_DBG("KOSync", "Update progress response: %d (err: %d)", httpCode, err);
+  LOG_DBG("KOSync", "Update progress response: %d (err: %s)", httpCode, esp_err_to_name(err));

  if (err != ESP_OK) return NETWORK_ERROR;
  if (httpCode == 200 || httpCode == 202) return OK;
@@ -278,6 +352,30 @@ KOReaderSyncClient::Error KOReaderSyncClient::updateProgress(const KOReaderProgr
  return SERVER_ERROR;
 }

+const char* KOReaderSyncClient::lastFailureDetail() {
+  // Heap-pressure case: surfaced when checkHeapForTls() refused before any TCP/TLS work happened.
+  if (lastEspError == ESP_ERR_NO_MEM && lastHttpCode == 0) {
+    snprintf(g_failureDetailBuf, sizeof(g_failureDetailBuf),
+             "%s: low memory (%u free, %u contig, need %u). Reboot device.", lastOperation, lastHeapAtFailure,
+             lastContigHeapAtFailure, MIN_CONTIG_HEAP_FOR_TLS);
+    return g_failureDetailBuf;
+  }
+  // Network/TLS case: esp_http_client_perform() failed before getting a status code.
+  if (lastHttpCode == 0 && lastEspError != 0) {
+    snprintf(g_failureDetailBuf, sizeof(g_failureDetailBuf), "%s: %s (heap %u/%u contig)", lastOperation,
+             esp_err_to_name(lastEspError), lastHeapAtFailure, lastContigHeapAtFailure);
+    return g_failureDetailBuf;
+  }
+  // Server case: got an HTTP status the client didn't recognize as success.
+  if (lastHttpCode != 0) {
+    snprintf(g_failureDetailBuf, sizeof(g_failureDetailBuf), "%s: HTTP %d", lastOperation, lastHttpCode);
+    return g_failureDetailBuf;
+  }
+  // No prior request, or success.
+  g_failureDetailBuf[0] = '\0';
+  return g_failureDetailBuf;
+}
+
 const char* KOReaderSyncClient::errorString(Error error) {
  switch (error) {
    case OK: