api: On parse failure, include details in exception

If the server's response is malformed, as with the server issue
that led to #383, the existing logging is unhelpful for working out
what the problem is, even in debug: we learn what request failed,
but not where in the response the misparse was.

When that issue happened, I debugged it with a cruder version of
this change, just augmenting this `catch` block to print the
exception and its stack trace.  But we can do better, using the
magic of Error.throwWithStackTrace.

Author: gnprice

assets/l10n/app_en.arb

@@ -319,6 +319,14 @@
       "httpStatus": {"type": "int", "example": "200"}
     }
   },
+  "errorMalformedResponseWithCause": "Server gave malformed response; HTTP status {httpStatus}; {details}",
+  "@errorMalformedResponseWithCause": {
+    "description": "Error message when an API call fails because we could not parse the response, with details of the failure.",
+    "placeholders": {
+      "httpStatus": {"type": "int", "example": "200"},
+      "details": {"type": "String", "example": "type 'Null' is not a subtype of type 'String' in type cast"}
+    }
+  },
   "errorRequestFailed": "Network request failed: HTTP status {httpStatus}",
   "@errorRequestFailed": {
     "description": "Error message when an API call fails.",

lib/api/core.dart

@@ -112,9 +112,12 @@ class ApiConnection {
 
     try {
       return fromJson(json);
-    } catch (e) {
-      throw MalformedServerResponseException(
-        routeName: routeName, httpStatus: httpStatus, data: json);
+    } catch (exception, stackTrace) { // TODO(log)
+      Error.throwWithStackTrace(
+        MalformedServerResponseException(
+          routeName: routeName, httpStatus: httpStatus, data: json,
+          causeException: exception),
+        stackTrace);
     }
   }
 

lib/api/exception.dart

@@ -112,10 +112,22 @@ class Server5xxException extends ServerException {
 ///
 /// See docs: https://zulip.com/api/rest-error-handling
 class MalformedServerResponseException extends ServerException {
+  /// The underlying exception from trying to parse the response, when applicable.
+  ///
+  /// This should be paired with the use of [Error.throwWithStackTrace]
+  /// in order to preserve the underlying exception's stack trace, which
+  /// may be more informative than the exception object itself.
+  final Object? causeException;
+
   MalformedServerResponseException({
     required super.routeName,
     required super.httpStatus,
     required super.data,
-  }) : super(message: GlobalLocalizations.zulipLocalizations
-         .errorMalformedResponse(httpStatus));
+    this.causeException,
+  }) : super(message: causeException == null
+         ? GlobalLocalizations.zulipLocalizations
+            .errorMalformedResponse(httpStatus)
+         : GlobalLocalizations.zulipLocalizations
+            .errorMalformedResponseWithCause(
+              httpStatus, causeException.toString()));
 }

test/api/core_test.dart

@@ -279,6 +279,31 @@ void main() {
     await checkMalformed(  json: {},         fromJson: (json) => json['x'] as String);
     await checkMalformed(  json: {'x': 3},   fromJson: (json) => json['x'] as String);
   });
+
+  test('malformed API success responses: exception preserves details', () async {
+    int distinctivelyNamedFromJson(Map<String, dynamic> json) {
+      throw DistinctiveError("something is wrong");
+    }
+
+    try {
+      await tryRequest(json: {}, fromJson: distinctivelyNamedFromJson);
+      assert(false);
+    } catch (e, st) {
+      check(e).isA<MalformedServerResponseException>()
+        ..causeException.isA<DistinctiveError>()
+        ..message.contains("something is wrong");
+      check(st.toString()).contains("distinctivelyNamedFromJson");
+    }
+  });
+}
+
+class DistinctiveError extends Error {
+  final String message;
+
+  DistinctiveError(this.message);
+
+  @override
+  String toString() => message;
 }
 
 Future<T> tryRequest<T>({

test/api/exception_checks.dart

@@ -26,5 +26,5 @@ extension Server5xxExceptionChecks on Subject<Server5xxException> {
 }
 
 extension MalformedServerResponseExceptionChecks on Subject<MalformedServerResponseException> {
-  // no properties not on ServerException
+  Subject<Object?> get causeException => has((e) => e.causeException, 'causeException');
 }