Add native stacktrace field for PlatformException (#63502)

* Add native stacktrace field for PlatformException

* Mute the readValue check for stacktrace.

* polish

* Add unit test and further polish

* Added more comments

* remove unnecessary import

* fill in stacktrace to JSONMethodCodec and fix tests

* fix style

* Fix format

* Remove unnecessary TODO since not all explicitly declared errors have stacktrace in it from native side.

* Handle case for exception without stacktrace on jsonMethodCodec

* Add more unit tests

* format test
Co-authored-by: Ben Li <libe@google.com>

packages/flutter/lib/src/services/message_codec.dart

@@ -80,9 +80,10 @@ abstract class MethodCodec {
 
   /// Encodes an error result into a binary envelope.
   ///
-  /// The specified error [code], human-readable error [message], and error
-  /// [details] correspond to the fields of [PlatformException].
-  ByteData encodeErrorEnvelope({ required String code, String? message, dynamic details });
+  /// The specified error [code], human-readable error [message], error
+  /// [details] correspond to the fields of [PlatformException] and error
+  /// [stacktrace] correspond to stacktrace from native platforms.
+  ByteData encodeErrorEnvelope({ required String code, String? message, dynamic details, String? stacktrace});
 }
 
 
@@ -107,6 +108,7 @@ class PlatformException implements Exception {
     required this.code,
     this.message,
     this.details,
+    this.stacktrace,
   }) : assert(code != null);
 
   /// An error code.
@@ -118,8 +120,18 @@ class PlatformException implements Exception {
   /// Error details, possibly null.
   final dynamic details;
 
+  /// Native stacktrace for the error, possibly null.
+  /// This is strictly for native platform stacktrace.
+  /// The stacktrace info on dart platform can be found within the try-catch block for example:
+  /// try {
+  ///   ...
+  /// } catch (e, stacktrace) {
+  ///   print(stacktrace);
+  /// }
+  final String? stacktrace;
+
   @override
-  String toString() => 'PlatformException($code, $message, $details)';
+  String toString() => 'PlatformException($code, $message, $details, $stacktrace)';
 }
 
 /// Thrown to indicate that a platform interaction failed to find a handling

packages/flutter/lib/src/services/message_codecs.dart

@@ -152,6 +152,16 @@ class JSONMethodCodec implements MethodCodec {
         message: decoded[1] as String,
         details: decoded[2],
       );
+    if (decoded.length == 4
+        && decoded[0] is String
+        && (decoded[1] == null || decoded[1] is String)
+        && (decoded[3] == null || decoded[3] is String))
+      throw PlatformException(
+        code: decoded[0] as String,
+        message: decoded[1] as String,
+        details: decoded[2],
+        stacktrace: decoded[3] as String,
+      );
     throw FormatException('Invalid envelope: $decoded');
   }
 
@@ -161,9 +171,9 @@ class JSONMethodCodec implements MethodCodec {
   }
 
   @override
-  ByteData encodeErrorEnvelope({ required String code, String? message, dynamic details }) {
+  ByteData encodeErrorEnvelope({ required String code, String? message, dynamic details, String? stacktrace}) {
     assert(code != null);
-    return const JSONMessageCodec().encodeMessage(<dynamic>[code, message, details])!;
+    return const JSONMessageCodec().encodeMessage(<dynamic>[code, message, details, stacktrace])!;
   }
 }
 
@@ -547,12 +557,13 @@ class StandardMethodCodec implements MethodCodec {
   }
 
   @override
-  ByteData encodeErrorEnvelope({ required String code, String? message, dynamic details }) {
+  ByteData encodeErrorEnvelope({ required String code, String? message, dynamic details, String? stacktrace}) {
     final WriteBuffer buffer = WriteBuffer();
     buffer.putUint8(1);
     messageCodec.writeValue(buffer, code);
     messageCodec.writeValue(buffer, message);
     messageCodec.writeValue(buffer, details);
+    messageCodec.writeValue(buffer, stacktrace);
     return buffer.done();
   }
 
@@ -567,8 +578,9 @@ class StandardMethodCodec implements MethodCodec {
     final dynamic errorCode = messageCodec.readValue(buffer);
     final dynamic errorMessage = messageCodec.readValue(buffer);
     final dynamic errorDetails = messageCodec.readValue(buffer);
+    final String? errorStacktrace = (buffer.hasRemaining) ? messageCodec.readValue(buffer) as String : null;
     if (errorCode is String && (errorMessage == null || errorMessage is String) && !buffer.hasRemaining)
-      throw PlatformException(code: errorCode, message: errorMessage as String, details: errorDetails);
+      throw PlatformException(code: errorCode, message: errorMessage as String, details: errorDetails, stacktrace: errorStacktrace);
     else
       throw const FormatException('Invalid envelope');
   }

packages/flutter/test/services/message_codecs_test.dart

@@ -10,6 +10,7 @@
 import 'dart:typed_data';
 
 import 'package:flutter/services.dart';
+import 'package:matcher/matcher.dart';
 import '../flutter_test_alternative.dart';
 import 'message_codecs_testing.dart';
 
@@ -44,6 +45,64 @@ void main() {
       expect(string.decodeMessage(offsetByteData), ' world');
     });
   });
+  group('Standard method codec', () {
+    const MethodCodec method = StandardMethodCodec();
+    test('should decode error envelope without native stacktrace', () {
+      final ByteData errorData = method.encodeErrorEnvelope(
+        code: 'errorCode',
+        message: 'errorMessage',
+        details: 'errorDetails',
+      );
+      expect(
+          () => method.decodeEnvelope(errorData),
+          throwsA(predicate((PlatformException e) =>
+              e is PlatformException &&
+              e.code == 'errorCode' &&
+              e.message == 'errorMessage' &&
+              e.details == 'errorDetails')));
+    });
+    test('should decode error envelope with native stacktrace.', () {
+      final ByteData errorData = method.encodeErrorEnvelope(
+        code: 'errorCode',
+        message: 'errorMessage',
+        details: 'errorDetails',
+        stacktrace: 'errorStacktrace',
+      );
+      expect(
+          () => method.decodeEnvelope(errorData),
+          throwsA(predicate((PlatformException e) =>
+              e is PlatformException && e.stacktrace == 'errorStacktrace')));
+    });
+  });
+  group('Json method codec', () {
+    const JSONMethodCodec json = JSONMethodCodec();
+    test('should decode error envelope without native stacktrace', () {
+      final ByteData errorData = json.encodeErrorEnvelope(
+        code: 'errorCode',
+        message: 'errorMessage',
+        details: 'errorDetails',
+      );
+      expect(
+          () => json.decodeEnvelope(errorData),
+          throwsA(predicate((PlatformException e) =>
+              e is PlatformException &&
+              e.code == 'errorCode' &&
+              e.message == 'errorMessage' &&
+              e.details == 'errorDetails')));
+    });
+    test('should decode error envelope with native stacktrace.', () {
+      final ByteData errorData = json.encodeErrorEnvelope(
+        code: 'errorCode',
+        message: 'errorMessage',
+        details: 'errorDetails',
+        stacktrace: 'errorStacktrace',
+      );
+      expect(
+          () => json.decodeEnvelope(errorData),
+          throwsA(predicate((PlatformException e) =>
+              e is PlatformException && e.stacktrace == 'errorStacktrace')));
+    });
+  });
   group('JSON message codec', () {
     const MessageCodec<dynamic> json = JSONMessageCodec();
     test('should encode and decode simple messages', () {
@@ -151,8 +210,22 @@ void main() {
         standard,
         1.0,
         <int>[
-          6, 0, 0, 0, 0, 0, 0, 0,
-          0, 0, 0, 0, 0, 0, 0xf0, 0x3f,
+          6,
+          0,
+          0,
+          0,
+          0,
+          0,
+          0,
+          0,
+          0,
+          0,
+          0,
+          0,
+          0,
+          0,
+          0xf0,
+          0x3f,
         ],
       );
     });

packages/flutter/test/services/platform_channel_test.dart

@@ -131,6 +131,7 @@ void main() {
             'bad',
             'Something happened',
             <String, dynamic>{'a': 42, 'b': 3.14},
+            'errorStacktrace',
           ]);
         },
       );
@@ -141,6 +142,7 @@ void main() {
         expect(e.code, equals('bad'));
         expect(e.message, equals('Something happened'));
         expect(e.details, equals(<String, dynamic>{'a': 42, 'b': 3.14}));
+        expect(e.stacktrace, equals('errorStacktrace'));
       } catch (e) {
         fail('PlatformException expected');
       }