[pigeon][swift] Removes FlutterError in favor of PigeonError (flutter#6611)

Swift has more strict type system than Objective-C. For example, protocol conformance must not be redundant[1]. Also, Both FlutterError and Swift.Error are public, extension `FlutterError` to `Swift.Error` is also public. If someone create a such extension in the plugin code, Flutter app can't create a such extension in the app code, which forces Plugin developers to use Objective-C when they want to use pigeon, instead of Swift.

To avoid this issue, this change makes pigeon to use another error type, named `PigeonError`, instead of `FlutterError`. By declaring `PigeonError` as internal visibility, their existence won't make compilation error even if `PigeonError` is declared in the app code.

Fixes flutter/flutter#147371.
See also flutter/flutter#137057 (comment).

[1] https://docs.swift.org/swift-book/documentation/the-swift-programming-language/declarations/#Protocol-Conformance-Must-Not-Be-Redundant

Author: bc-lee

packages/pigeon/CHANGELOG.md

@@ -1,5 +1,6 @@
-## NEXT
+## 19.0.0
 
+* **Breaking Change** [swift] Removes `FlutterError` in favor of `PigeonError`.
 * Updates minimum supported SDK version to Flutter 3.16/Dart 3.2.
 
 ## 18.0.1

packages/pigeon/README.md

@@ -53,8 +53,7 @@ should be returned via the provided callback.
 To pass custom details into `PlatformException` for error handling, 
 use `FlutterError` in your Host API. [Example](./example/README.md#HostApi_Example).
 
-To use `FlutterError` in Swift you must first extend a standard error.
-[Example](./example/README.md#AppDelegate.swift).
+For swift, use `PigeonError` instead of `FlutterError` when throwing an error. See [Example#Swift](./example/README.md#Swift) for more details.
 
 #### Objective-C and C++
 

packages/pigeon/example/README.md

@@ -115,27 +115,24 @@ Future<bool> sendMessage(String messageText) {
 ### Swift
 
 This is the code that will use the generated Swift code to receive calls from Flutter.
-packages/pigeon/example/app/ios/Runner/AppDelegate.swift
+Unlike other languages, when throwing an error, use `PigeonError` instead of `FlutterError`, as `FlutterError` does not conform to `Swift.Error`.
 <?code-excerpt "ios/Runner/AppDelegate.swift (swift-class)"?>
 ```swift
-// This extension of Error is required to do use FlutterError in any Swift code.
-extension FlutterError: Error {}
-
 private class PigeonApiImplementation: ExampleHostApi {
   func getHostLanguage() throws -> String {
     return "Swift"
   }
 
   func add(_ a: Int64, to b: Int64) throws -> Int64 {
     if a < 0 || b < 0 {
-      throw FlutterError(code: "code", message: "message", details: "details")
+      throw PigeonError(code: "code", message: "message", details: "details")
     }
     return a + b
   }
 
   func sendMessage(message: MessageData, completion: @escaping (Result<Bool, Error>) -> Void) {
     if message.code == Code.one {
-      completion(.failure(FlutterError(code: "code", message: "message", details: "details")))
+      completion(.failure(PigeonError(code: "code", message: "message", details: "details")))
       return
     }
     completion(.success(true))

packages/pigeon/example/app/ios/Runner/AppDelegate.swift

@@ -6,24 +6,21 @@ import Flutter
 import UIKit
 
 // #docregion swift-class
-// This extension of Error is required to do use FlutterError in any Swift code.
-extension FlutterError: Error {}
-
 private class PigeonApiImplementation: ExampleHostApi {
   func getHostLanguage() throws -> String {
     return "Swift"
   }
 
   func add(_ a: Int64, to b: Int64) throws -> Int64 {
     if a < 0 || b < 0 {
-      throw FlutterError(code: "code", message: "message", details: "details")
+      throw PigeonError(code: "code", message: "message", details: "details")
     }
     return a + b
   }
 
   func sendMessage(message: MessageData, completion: @escaping (Result<Bool, Error>) -> Void) {
     if message.code == Code.one {
-      completion(.failure(FlutterError(code: "code", message: "message", details: "details")))
+      completion(.failure(PigeonError(code: "code", message: "message", details: "details")))
       return
     }
     completion(.success(true))

packages/pigeon/example/app/ios/Runner/Messages.g.swift

@@ -14,11 +14,36 @@ import Foundation
   #error("Unsupported platform.")
 #endif
 
+/// Error class for passing custom error details to Dart side.
+final class PigeonError: Error {
+  let code: String
+  let message: String?
+  let details: Any?
+
+  init(code: String, message: String?, details: Any?) {
+    self.code = code
+    self.message = message
+    self.details = details
+  }
+
+  var localizedDescription: String {
+    return
+      "PigeonError(code: \(code), message: \(message ?? "<nil>"), details: \(details ?? "<nil>")"
+  }
+}
+
 private func wrapResult(_ result: Any?) -> [Any?] {
   return [result]
 }
 
 private func wrapError(_ error: Any) -> [Any?] {
+  if let pigeonError = error as? PigeonError {
+    return [
+      pigeonError.code,
+      pigeonError.message,
+      pigeonError.details,
+    ]
+  }
   if let flutterError = error as? FlutterError {
     return [
       flutterError.code,
@@ -33,8 +58,8 @@ private func wrapError(_ error: Any) -> [Any?] {
   ]
 }
 
-private func createConnectionError(withChannelName channelName: String) -> FlutterError {
-  return FlutterError(
+private func createConnectionError(withChannelName channelName: String) -> PigeonError {
+  return PigeonError(
     code: "channel-error", message: "Unable to establish connection on channel: '\(channelName)'.",
     details: "")
 }
@@ -194,7 +219,7 @@ class ExampleHostApiSetup {
 /// Generated protocol from Pigeon that represents Flutter messages that can be called from Swift.
 protocol MessageFlutterApiProtocol {
   func flutterMethod(
-    aString aStringArg: String?, completion: @escaping (Result<String, FlutterError>) -> Void)
+    aString aStringArg: String?, completion: @escaping (Result<String, PigeonError>) -> Void)
 }
 class MessageFlutterApi: MessageFlutterApiProtocol {
   private let binaryMessenger: FlutterBinaryMessenger
@@ -204,7 +229,7 @@ class MessageFlutterApi: MessageFlutterApiProtocol {
     self.messageChannelSuffix = messageChannelSuffix.count > 0 ? ".\(messageChannelSuffix)" : ""
   }
   func flutterMethod(
-    aString aStringArg: String?, completion: @escaping (Result<String, FlutterError>) -> Void
+    aString aStringArg: String?, completion: @escaping (Result<String, PigeonError>) -> Void
   ) {
     let channelName: String =
       "dev.flutter.pigeon.pigeon_example_package.MessageFlutterApi.flutterMethod\(messageChannelSuffix)"
@@ -218,11 +243,11 @@ class MessageFlutterApi: MessageFlutterApiProtocol {
         let code: String = listResponse[0] as! String
         let message: String? = nilOrValue(listResponse[1])
         let details: String? = nilOrValue(listResponse[2])
-        completion(.failure(FlutterError(code: code, message: message, details: details)))
+        completion(.failure(PigeonError(code: code, message: message, details: details)))
       } else if listResponse[0] == nil {
         completion(
           .failure(
-            FlutterError(
+            PigeonError(
               code: "null-error",
               message: "Flutter api returned null value for non-null return value.", details: "")))
       } else {

packages/pigeon/lib/generator_tools.dart

@@ -13,7 +13,7 @@ import 'ast.dart';
 /// The current version of pigeon.
 ///
 /// This must match the version in pubspec.yaml.
-const String pigeonVersion = '18.0.1';
+const String pigeonVersion = '19.0.0';
 
 /// Prefix for all local variables in methods.
 ///

packages/pigeon/lib/pigeon_lib.dart

@@ -705,6 +705,7 @@ class SwiftGeneratorAdapter implements GeneratorAdapter {
           ? _lineReader(
               path.posix.join(options.basePath ?? '', options.copyrightHeader))
           : null,
+      errorClassName: swiftOptions.errorClassName,
     ));
     const SwiftGenerator generator = SwiftGenerator();
     generator.generate(

packages/pigeon/lib/swift_generator.dart

@@ -19,16 +19,21 @@ class SwiftOptions {
   /// Creates a [SwiftOptions] object
   const SwiftOptions({
     this.copyrightHeader,
+    this.errorClassName,
   });
 
   /// A copyright header that will get prepended to generated code.
   final Iterable<String>? copyrightHeader;
 
+  /// The name of the error class used for passing custom error parameters.
+  final String? errorClassName;
+
   /// Creates a [SwiftOptions] from a Map representation where:
   /// `x = SwiftOptions.fromList(x.toMap())`.
   static SwiftOptions fromList(Map<String, Object> map) {
     return SwiftOptions(
       copyrightHeader: map['copyrightHeader'] as Iterable<String>?,
+      errorClassName: map['errorClassName'] as String?,
     );
   }
 
@@ -37,6 +42,7 @@ class SwiftOptions {
   Map<String, Object> toMap() {
     final Map<String, Object> result = <String, Object>{
       if (copyrightHeader != null) 'copyrightHeader': copyrightHeader!,
+      if (errorClassName != null) 'errorClassName': errorClassName!,
     };
     return result;
   }
@@ -316,7 +322,7 @@ class SwiftGenerator extends StructuredGenerator<SwiftOptions> {
           name: func.name,
           parameters: func.parameters,
           returnType: func.returnType,
-          errorTypeName: 'FlutterError',
+          errorTypeName: _getErrorClassName(generatorOptions),
           isAsynchronous: true,
           swiftFunction: func.swiftFunction,
           getParameterName: _getSafeArgumentName,
@@ -350,6 +356,7 @@ class SwiftGenerator extends StructuredGenerator<SwiftOptions> {
             indent, func.documentationComments, _docCommentSpec);
         _writeFlutterMethod(
           indent,
+          generatorOptions: generatorOptions,
           name: func.name,
           channelName: makeChannelName(api, func, dartPackageName),
           parameters: func.parameters,
@@ -614,10 +621,20 @@ class SwiftGenerator extends StructuredGenerator<SwiftOptions> {
     });
   }
 
-  void _writeWrapError(Indent indent) {
+  void _writeWrapError(SwiftOptions generatorOptions, Indent indent) {
     indent.newln();
     indent.write('private func wrapError(_ error: Any) -> [Any?] ');
     indent.addScoped('{', '}', () {
+      indent.write(
+          'if let pigeonError = error as? ${_getErrorClassName(generatorOptions)} ');
+      indent.addScoped('{', '}', () {
+        indent.write('return ');
+        indent.addScoped('[', ']', () {
+          indent.writeln('pigeonError.code,');
+          indent.writeln('pigeonError.message,');
+          indent.writeln('pigeonError.details,');
+        });
+      });
       indent.write('if let flutterError = error as? FlutterError ');
       indent.addScoped('{', '}', () {
         indent.write('return ');
@@ -645,13 +662,14 @@ private func nilOrValue<T>(_ value: Any?) -> T? {
 }''');
   }
 
-  void _writeCreateConnectionError(Indent indent) {
+  void _writeCreateConnectionError(
+      SwiftOptions generatorOptions, Indent indent) {
     indent.newln();
     indent.writeScoped(
-        'private func createConnectionError(withChannelName channelName: String) -> FlutterError {',
+        'private func createConnectionError(withChannelName channelName: String) -> ${_getErrorClassName(generatorOptions)} {',
         '}', () {
       indent.writeln(
-          'return FlutterError(code: "channel-error", message: "Unable to establish connection on channel: \'\\(channelName)\'.", details: "")');
+          'return ${_getErrorClassName(generatorOptions)}(code: "channel-error", message: "Unable to establish connection on channel: \'\\(channelName)\'.", details: "")');
     });
   }
 
@@ -669,19 +687,23 @@ private func nilOrValue<T>(_ value: Any?) -> T? {
         .whereType<AstFlutterApi>()
         .any((Api api) => api.methods.isNotEmpty);
 
+    _writePigeonError(generatorOptions, indent);
+
     if (hasHostApi) {
       _writeWrapResult(indent);
-      _writeWrapError(indent);
+      _writeWrapError(generatorOptions, indent);
     }
     if (hasFlutterApi) {
-      _writeCreateConnectionError(indent);
+      _writeCreateConnectionError(generatorOptions, indent);
     }
+
     _writeIsNullish(indent);
     _writeNilOrValue(indent);
   }
 
   void _writeFlutterMethod(
     Indent indent, {
+    required SwiftOptions generatorOptions,
     required String name,
     required String channelName,
     required List<Parameter> parameters,
@@ -693,7 +715,7 @@ private func nilOrValue<T>(_ value: Any?) -> T? {
       name: name,
       parameters: parameters,
       returnType: returnType,
-      errorTypeName: 'FlutterError',
+      errorTypeName: _getErrorClassName(generatorOptions),
       isAsynchronous: true,
       swiftFunction: swiftFunction,
       getParameterName: _getSafeArgumentName,
@@ -735,12 +757,12 @@ private func nilOrValue<T>(_ value: Any?) -> T? {
           indent.writeln('let message: String? = nilOrValue(listResponse[1])');
           indent.writeln('let details: String? = nilOrValue(listResponse[2])');
           indent.writeln(
-              'completion(.failure(FlutterError(code: code, message: message, details: details)))');
+              'completion(.failure(${_getErrorClassName(generatorOptions)}(code: code, message: message, details: details)))');
         }, addTrailingNewline: false);
         if (!returnType.isNullable && !returnType.isVoid) {
           indent.addScoped('else if listResponse[0] == nil {', '} ', () {
             indent.writeln(
-                'completion(.failure(FlutterError(code: "null-error", message: "Flutter api returned null value for non-null return value.", details: "")))');
+                'completion(.failure(${_getErrorClassName(generatorOptions)}(code: "null-error", message: "Flutter api returned null value for non-null return value.", details: "")))');
           }, addTrailingNewline: false);
         }
         indent.addScoped('else {', '}', () {
@@ -870,11 +892,41 @@ private func nilOrValue<T>(_ value: Any?) -> T? {
       indent.writeln('$varChannelName.setMessageHandler(nil)');
     });
   }
+
+  void _writePigeonError(SwiftOptions generatorOptions, Indent indent) {
+    indent.newln();
+    indent.writeln(
+        '/// Error class for passing custom error details to Dart side.');
+    indent.writeScoped(
+        'final class ${_getErrorClassName(generatorOptions)}: Error {', '}',
+        () {
+      indent.writeln('let code: String');
+      indent.writeln('let message: String?');
+      indent.writeln('let details: Any?');
+      indent.newln();
+      indent.writeScoped(
+          'init(code: String, message: String?, details: Any?) {', '}', () {
+        indent.writeln('self.code = code');
+        indent.writeln('self.message = message');
+        indent.writeln('self.details = details');
+      });
+      indent.newln();
+      indent.writeScoped('var localizedDescription: String {', '}', () {
+        indent.writeScoped('return', '', () {
+          indent.writeln(
+              '"${_getErrorClassName(generatorOptions)}(code: \\(code), message: \\(message ?? "<nil>"), details: \\(details ?? "<nil>")"');
+        }, addTrailingNewline: false);
+      });
+    });
+  }
 }
 
 /// Calculates the name of the codec that will be generated for [api].
 String _getCodecName(Api api) => '${api.name}Codec';
 
+String _getErrorClassName(SwiftOptions generatorOptions) =>
+    generatorOptions.errorClassName ?? 'PigeonError';
+
 String _getArgumentName(int count, NamedType argument) =>
     argument.name.isEmpty ? 'arg$count' : argument.name;
 

packages/pigeon/platform_tests/test_plugin/example/ios/RunnerTests/RunnerTests.swift

@@ -48,14 +48,16 @@ class RunnerTests: XCTestCase {
 }
 
 class FlutterApiFromProtocol: FlutterSmallApiProtocol {
-  func echo(string aStringArg: String, completion: @escaping (Result<String, FlutterError>) -> Void)
-  {
+  func echo(
+    string aStringArg: String,
+    completion: @escaping (Result<String, test_plugin.PigeonError>) -> Void
+  ) {
     completion(.success(aStringArg))
   }
 
   func echo(
     _ msgArg: test_plugin.TestMessage,
-    completion: @escaping (Result<test_plugin.TestMessage, FlutterError>) -> Void
+    completion: @escaping (Result<test_plugin.TestMessage, test_plugin.PigeonError>) -> Void
   ) {
     completion(.success(msgArg))
   }