[macOS] Extract codecs from plugin API

Extracts method codecs into stand-alone objects, and allows plugins to
indicate that they use a codec other than JSON. This is an incremental
step toward aligning the plugin API with Flutter's MethodChannel API.

For now no other codecs are actually implemented in the framework, and
the default is still JSON (unlike in existing Flutter code) so that this
is not a breaking change. A future change will full move to MethodChannel,
which will be a breaking change.

Partially addresses issue google#67 in that custom codecs are now supported,
even though the Standard (binary) codec is not yet implemented.

Author: stuartmorgan-g

macos/library/FLEChannels.h

@@ -16,16 +16,9 @@
 
 /**
  * An object encapsulating a method call from Flutter.
- *
- * TODO: Move serialization details into a method codec class, to match mobile Flutter plugin APIs.
  */
 @interface FLEMethodCall : NSObject
 
-/**
- * Returns a new FLEMethodCall created from a JSON message received from the Flutter engine.
- */
-+ (nullable instancetype)methodCallFromMessage:(nonnull NSDictionary *)message;
-
 /**
  * Initializes an FLEMethodCall. If |arguments| is provided, it must be serializable to JSON.
  */
@@ -47,11 +40,6 @@
  */
 @property(readonly, nonatomic, nullable) id arguments;
 
-/**
- * Returns a version of the method call serialized in the format expected by the Flutter engine.
- */
-- (nonnull NSDictionary *)asMessage;
-
 @end
 
 #pragma mark -
@@ -100,11 +88,3 @@ extern NSString const *_Nonnull FLEMethodNotImplemented;
 @property(readonly, nonatomic, nullable) id details;
 
 @end
-
-/**
- * Returns the serialized JSON data that should be sent to the engine for the given
- * FLEMethodResult argument.
- *
- * // TODO: Move this logic into method codecs.
- */
-NSData *_Nullable EngineResponseForMethodResult(id _Nullable result);

macos/library/FLEChannels.m

@@ -16,23 +16,8 @@
 
 NSString const *FLEMethodNotImplemented = @"notimplemented";
 
-static NSString *const kMessageMethodKey = @"method";
-static NSString *const kMessageArgumentsKey = @"args";
-
 @implementation FLEMethodCall
 
-+ (nullable instancetype)methodCallFromMessage:(nonnull NSDictionary *)message {
-  NSString *method = message[kMessageMethodKey];
-  if (!method) {
-    return nil;
-  }
-  id arguments = message[kMessageArgumentsKey];
-  if (arguments == [NSNull null]) {
-    arguments = nil;
-  }
-  return [[self alloc] initWithMethodName:method arguments:arguments];
-}
-
 - (nonnull instancetype)initWithMethodName:(nonnull NSString *)name
                                  arguments:(nullable id)arguments {
   self = [super init];
@@ -43,13 +28,6 @@ - (nonnull instancetype)initWithMethodName:(nonnull NSString *)name
   return self;
 }
 
-- (nonnull NSDictionary *)asMessage {
-  return @{
-    kMessageMethodKey : _methodName,
-    kMessageArgumentsKey : _arguments ?: [NSNull null],
-  };
-}
-
 @end
 
 #pragma mark -
@@ -69,31 +47,3 @@ - (nonnull instancetype)initWithCode:(nonnull NSString *)code
 }
 
 @end
-
-#pragma mark -
-
-NSData *EngineResponseForMethodResult(id result) {
-  // The engine expects one of three responses to a platform message:
-  // - No data, indicating that the method is not implemented.
-  // - A one-element array indicating succes, with the response payload as the element.
-  // - A three-element array indicating an error, consisting of:
-  //   * An error code string.
-  //   * An optional human-readable error string.
-  //   * An optional object with more error information.
-  NSArray *responseObject = nil;
-  if (result == FLEMethodNotImplemented) {
-    // Note that the compare above deliberately uses pointer equality rather than string equality
-    // since only the constant itself should be treated as 'not implemented'.
-    return nil;
-  } else if ([result isKindOfClass:[FLEMethodError class]]) {
-    FLEMethodError *error = (FLEMethodError *)result;
-    responseObject = @[
-      error.code,
-      error.message ?: [NSNull null],
-      error.details ?: [NSNull null],
-    ];
-  } else {
-    responseObject = @[ result ?: [NSNull null] ];
-  }
-  return [NSJSONSerialization dataWithJSONObject:responseObject options:0 error:NULL];
-}

macos/library/FLECodecs.h

@@ -0,0 +1,61 @@
+// Copyright 2018 Google LLC
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//      http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+#import <Foundation/Foundation.h>
+
+#import "FLEChannels.h"
+
+/**
+ * Translates between a binary message and higher-level method call and response/error objects.
+ */
+@protocol FLEMethodCodec
+
+/**
+ * Returns the shared instance of the codec.
+ */
++ (nonnull instancetype)sharedInstance;
+
+/**
+ * Returns a binary encoding of the given |methodCall|, or nil if the method call cannot be
+ * serialized by this codec.
+ */
+- (nullable NSData*)encodeMethodCall:(nonnull FLEMethodCall*)methodCall;
+
+/**
+ * Returns the FLEMethodCall encoded in |methodData|, or nil if it cannot be decoded.
+ */
+- (nullable FLEMethodCall*)decodeMethodCall:(nonnull NSData*)methodData;
+
+/**
+ * Returns a binary encoding of |result|. Returns nil if |result| is not a type supported by the
+ * codec.
+ */
+- (nullable NSData*)encodeSuccessEnvelope:(nullable id)result;
+
+/**
+ * Returns a binary encoding of |error|. Returns nil if the |details| parameter of |erorr| is not
+ * a type supported by the codec.
+ */
+- (nullable NSData*)encodeErrorEnvelope:(nonnull FLEMethodError*)error;
+
+@end
+
+/**
+ * A codec that uses JSON as the encoding format. Method arguments and error details for plugins
+ * using this codec must be serializable to JSON.
+ */
+@interface FLEJSONMethodCodec : NSObject <FLEMethodCodec>
+@end
+
+// TODO: Implement the other core Flutter codecs. Issue #67.

macos/library/FLECodecs.m

@@ -0,0 +1,85 @@
+// Copyright 2018 Google LLC
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//      http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+#import "FLECodecs.h"
+
+// Keys for JSON-encoded method calls.
+static NSString *const kMessageMethodKey = @"method";
+static NSString *const kMessageArgumentsKey = @"args";
+
+/**
+ * Returns the JSON serialiazation of |object|. If |object| is not serializable to JSON, logs an
+ * error and returns nil.
+ */
+static NSData *SerializeAsJSON(id object) {
+  if (![NSJSONSerialization isValidJSONObject:object]) {
+    NSLog(@"Error: Unable to construct a valid JSON object from %@", object);
+    return nil;
+  }
+
+  NSError *error = nil;
+  NSData *data = [NSJSONSerialization dataWithJSONObject:object options:0 error:&error];
+  if (error) {
+    NSLog(@"Error: Failed to create JSON message for %@: %@", object, error.debugDescription);
+  }
+  return data;
+}
+
+// See the documentation for the Dart JSONMethodCodec class for the JSON structures used by this
+// this class.
+@implementation FLEJSONMethodCodec
+
+#pragma mark FLEMethodCodec
+
++ (instancetype)sharedInstance {
+  static FLEJSONMethodCodec *sharedInstance;
+  if (!sharedInstance) {
+    sharedInstance = [[FLEJSONMethodCodec alloc] init];
+  }
+  return sharedInstance;
+}
+
+- (NSData *)encodeMethodCall:(FLEMethodCall *)methodCall {
+  return SerializeAsJSON(@{
+    kMessageMethodKey : methodCall.methodName,
+    kMessageArgumentsKey : methodCall.arguments ?: [NSNull null],
+  });
+}
+
+- (FLEMethodCall *)decodeMethodCall:(NSData *)methodData {
+  NSDictionary *message = [NSJSONSerialization JSONObjectWithData:methodData options:0 error:NULL];
+  NSString *method = message[kMessageMethodKey];
+  if (!method) {
+    return nil;
+  }
+  id arguments = message[kMessageArgumentsKey];
+  if (arguments == [NSNull null]) {
+    arguments = nil;
+  }
+  return [[FLEMethodCall alloc] initWithMethodName:method arguments:arguments];
+}
+
+- (NSData *)encodeSuccessEnvelope:(id _Nullable)result {
+  return SerializeAsJSON(@[ result ?: [NSNull null] ]);
+}
+
+- (NSData *)encodeErrorEnvelope:(FLEMethodError *)error {
+  return SerializeAsJSON(@[
+    error.code,
+    error.message ?: [NSNull null],
+    error.details ?: [NSNull null],
+  ]);
+}
+
+@end

macos/library/FLEPlugin.h

@@ -15,14 +15,18 @@
 #import <Foundation/Foundation.h>
 
 #import "FLEChannels.h"
+#import "FLECodecs.h"
 
 @class FLEViewController;
 
 /**
  * A plugin is an object that can respond appropriately to Flutter platform messages over a specific
  * named system channel. See https://flutter.io/platform-channels/.
+ *
+ * Note: This interface will be changing in the future to more closely match the iOS Flutter
+ * platform message API. It will be a one-time breaking change.
  */
-@protocol FLEPlugin
+@protocol FLEPlugin <NSObject>
 
 /**
  * A weak reference to the owning controller. May be used to send messages to the Flutter
@@ -50,4 +54,15 @@
  */
 - (void)handleMethodCall:(nonnull FLEMethodCall *)call result:(nonnull FLEMethodResult)result;
 
+@optional
+
+/**
+ * If implemented, returns the codec to use for method calls to this plugin.
+ *
+ * If not implemented, the codec is assumed to be FLEJSONMethodCodec. Note that this is different
+ * from existing Flutter platforms, which default to the standard codec; this is to preserve
+ * backwards compatibility for FLEPlugin until the breaking change for the platform messages API.
+ */
+@property(nonnull, readonly) id<FLEMethodCodec> codec;
+
 @end

macos/library/FLEViewController.h

@@ -14,6 +14,7 @@
 
 #import <Cocoa/Cocoa.h>
 
+#import "FLECodecs.h"
 #import "FLEOpenGLContextHandling.h"
 #import "FLEPlugin.h"
 
@@ -71,10 +72,20 @@
 - (BOOL)addPlugin:(nonnull id<FLEPlugin>)plugin;
 
 /**
- * Sends a platform message to the Flutter engine on the given channel.
+ * Sends a platform message to the Flutter engine on |channel|, encoded using |codec|.
  *
+ * // TODO: Move to an API that mirrors the FlutterMethodChannel API.
  * // TODO: Support responses.
  */
+- (void)invokeMethod:(nonnull NSString *)method
+           arguments:(nullable id)arguments
+           onChannel:(nonnull NSString *)channel
+           withCodec:(nonnull id<FLEMethodCodec>)codec;
+
+/**
+ * Calls invokeMethod:arguments:onChannel:withCodec: using FLEJSONCodec. See the note in
+ * FLEPlugin.h for why JSON is the default.
+ */
 - (void)invokeMethod:(nonnull NSString *)method
            arguments:(nullable id)arguments
            onChannel:(nonnull NSString *)channel;