Extract codecs from plugin API (#110)

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 only a minor breaking change, and only on Linux (unavoidable due to
the initial use of Json::Value in key interfaces; the JsonPlugin class is
designed to minimize impact on existing plugins). A future change will
move to MethodChannel, which will be a more significant breaking
change.

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

Author: stuartmorgan

linux/library/include/flutter_desktop_embedding/json_method_call.h

@@ -0,0 +1,53 @@
+// 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.
+#ifndef LINUX_LIBRARY_INCLUDE_FLUTTER_DESKTOP_EMBEDDING_JSON_METHOD_CALL_H_
+#define LINUX_LIBRARY_INCLUDE_FLUTTER_DESKTOP_EMBEDDING_JSON_METHOD_CALL_H_
+
+#include <string>
+
+#include <json/json.h>
+
+#include "method_call.h"
+
+namespace flutter_desktop_embedding {
+
+// A concrete implmentation of MethodCall for use with the JSON codec.
+class JsonMethodCall : public MethodCall {
+ public:
+  // Creates a MethodCall with the given name and, optionally, arguments.
+  explicit JsonMethodCall(const std::string &method_name,
+                          const Json::Value &arguments = Json::Value());
+  ~JsonMethodCall();
+
+  // Prevent copying.
+  JsonMethodCall(JsonMethodCall const &) = delete;
+  JsonMethodCall &operator=(JsonMethodCall const &) = delete;
+
+  // MethodCall:
+  // Returns a pointer to a Json::Value object. This will never return null;
+  // 'no arguments' is represented with a JSON::nullValue.
+  const void *arguments() const override;
+
+  // Returns a reference to the object pointed to by arguments().
+  // This is a convience method for code that is interacting directly with a
+  // JsonMethodCall to avoid casting and dereferencing.
+  const Json::Value &GetArgumentsAsJson() const;
+
+ private:
+  Json::Value arguments_;
+};
+
+}  // namespace flutter_desktop_embedding
+
+#endif  // LINUX_LIBRARY_INCLUDE_FLUTTER_DESKTOP_EMBEDDING_JSON_METHOD_CALL_H_

linux/library/include/flutter_desktop_embedding/json_method_codec.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.
+#ifndef LINUX_LIBRARY_INCLUDE_FLUTTER_DESKTOP_EMBEDDING_JSON_METHOD_CODEC_H_
+#define LINUX_LIBRARY_INCLUDE_FLUTTER_DESKTOP_EMBEDDING_JSON_METHOD_CODEC_H_
+
+#include <json/json.h>
+
+#include "method_codec.h"
+
+namespace flutter_desktop_embedding {
+
+// An implementation of MethodCodec that uses JSON strings as the serialization.
+//
+// void* types in this implementation must always be Json::Value* types (from
+// the jsoncpp library).
+class JsonMethodCodec : public MethodCodec {
+ public:
+  // Returns the shared instance of the codec.
+  static const JsonMethodCodec &GetInstance();
+
+  ~JsonMethodCodec() = default;
+
+  // Prevent copying.
+  JsonMethodCodec(JsonMethodCodec const &) = delete;
+  JsonMethodCodec &operator=(JsonMethodCodec const &) = delete;
+
+ protected:
+  // Instances should be obtained via GetInstance.
+  JsonMethodCodec() = default;
+
+  // MethodCodec:
+  std::unique_ptr<MethodCall> DecodeMethodCallInternal(
+      const uint8_t *message, const size_t message_size) const override;
+  std::unique_ptr<std::vector<uint8_t>> EncodeMethodCallInternal(
+      const MethodCall &method_call) const override;
+  std::unique_ptr<std::vector<uint8_t>> EncodeSuccessEnvelopeInternal(
+      const void *result) const override;
+  std::unique_ptr<std::vector<uint8_t>> EncodeErrorEnvelopeInternal(
+      const std::string &error_code, const std::string &error_message,
+      const void *error_details) const override;
+
+ private:
+  // Serializes |json| into a byte stream.
+  std::unique_ptr<std::vector<uint8_t>> EncodeJsonObject(
+      const Json::Value &json) const;
+};
+
+}  // namespace flutter_desktop_embedding
+
+#endif  // LINUX_LIBRARY_INCLUDE_FLUTTER_DESKTOP_EMBEDDING_JSON_METHOD_CODEC_H_

linux/library/include/flutter_desktop_embedding/json_plugin.h

@@ -0,0 +1,55 @@
+// 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.
+#ifndef LINUX_LIBRARY_INCLUDE_FLUTTER_DESKTOP_EMBEDDING_JSON_PLUGIN_H_
+#define LINUX_LIBRARY_INCLUDE_FLUTTER_DESKTOP_EMBEDDING_JSON_PLUGIN_H_
+
+#include "json_method_call.h"
+#include "plugin.h"
+
+namespace flutter_desktop_embedding {
+
+// A base class for plugins using the JSON method codec.
+//
+// Provides a few utility shims from the type-agnostic Plugin class.
+class JsonPlugin : public Plugin {
+ public:
+  // See Plugin for constructor details.
+  explicit JsonPlugin(const std::string &channel, bool input_blocking = false);
+  virtual ~JsonPlugin();
+
+  // Prevent copying.
+  JsonPlugin(JsonPlugin const &) = delete;
+  JsonPlugin &operator=(JsonPlugin const &) = delete;
+
+  // Plugin implementation:
+  const MethodCodec &GetCodec() const override;
+  void HandleMethodCall(const MethodCall &method_call,
+                        std::unique_ptr<MethodResult> result) override;
+
+ protected:
+  // Identical to HandleMethodCall, except that the call has been cast to the
+  // more specific type. Subclasses must implement this instead of
+  // HandleMethodCall.
+  virtual void HandleJsonMethodCall(const JsonMethodCall &method_call,
+                                    std::unique_ptr<MethodResult> result) = 0;
+
+  // Calls InvokeMethodCall with a JsonMethodCall constructed from the given
+  // values.
+  void InvokeMethod(const std::string &method,
+                    const Json::Value &arguments = Json::Value());
+};
+
+}  // namespace flutter_desktop_embedding
+
+#endif  // LINUX_LIBRARY_INCLUDE_FLUTTER_DESKTOP_EMBEDDING_JSON_PLUGIN_H_

linux/library/include/flutter_desktop_embedding/method_call.h

@@ -14,43 +14,31 @@
 #ifndef LINUX_LIBRARY_INCLUDE_FLUTTER_DESKTOP_EMBEDDING_METHOD_CALL_H_
 #define LINUX_LIBRARY_INCLUDE_FLUTTER_DESKTOP_EMBEDDING_METHOD_CALL_H_
 
-#include <json/json.h>
-
-#include <memory>
 #include <string>
 
-#include <flutter_embedder.h>
-
 namespace flutter_desktop_embedding {
 
 // An object encapsulating a method call from Flutter.
-// TODO: Move serialization details into a method codec class, to match mobile
-// Flutter plugin APIs.
 class MethodCall {
  public:
-  // Creates a MethodCall with the given name and, optionally, arguments.
-  explicit MethodCall(const std::string &method_name,
-                      const Json::Value &arguments = Json::Value());
+  // Creates a MethodCall with the given name. Used only as a superclass
+  // constructor for subclasses, which should also take the arguments.
+  explicit MethodCall(const std::string &method_name);
+  virtual ~MethodCall();
 
-  // Returns a new MethodCall created from a JSON message received from the
-  // Flutter engine.
-  static std::unique_ptr<MethodCall> CreateFromMessage(
-      const Json::Value &message);
-  ~MethodCall();
+  // Prevent copying.
+  MethodCall(MethodCall const &) = delete;
+  MethodCall &operator=(MethodCall const &) = delete;
 
   // The name of the method being called.
   const std::string &method_name() const { return method_name_; }
 
-  // The arguments to the method call, or a nullValue if there are none.
-  const Json::Value &arguments() const { return arguments_; }
-
-  // Returns a version of the method call serialized in the format expected by
-  // the Flutter engine.
-  Json::Value AsMessage() const;
+  // The arguments to the method call, or NULL if there are none. The type of
+  // the object being pointed to is determined by the concrete subclasses.
+  virtual const void *arguments() const = 0;
 
  private:
   std::string method_name_;
-  Json::Value arguments_;
 };
 
 }  // namespace flutter_desktop_embedding

linux/library/include/flutter_desktop_embedding/method_codec.h

@@ -0,0 +1,68 @@
+// 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.
+#ifndef LINUX_LIBRARY_INCLUDE_FLUTTER_DESKTOP_EMBEDDING_METHOD_CODEC_H_
+#define LINUX_LIBRARY_INCLUDE_FLUTTER_DESKTOP_EMBEDDING_METHOD_CODEC_H_
+
+#include <memory>
+#include <string>
+#include <vector>
+
+#include "method_call.h"
+
+namespace flutter_desktop_embedding {
+
+// Translates between a binary message and higher-level method call and
+// response/error objects.
+class MethodCodec {
+ public:
+  virtual ~MethodCodec();
+
+  // Returns the MethodCall encoded in |message|, or nullptr if it cannot be
+  // decoded.
+  // TODO: Consider adding absl as a dependency and using absl::Span.
+  std::unique_ptr<MethodCall> DecodeMethodCall(const uint8_t *message,
+                                               const size_t message_size) const;
+
+  // Returns a binary encoding of the given |method_call|, or nullptr if the
+  // method call cannot be serialized by this codec.
+  std::unique_ptr<std::vector<uint8_t>> EncodeMethodCall(
+      const MethodCall &method_call) const;
+
+  // Returns a binary encoding of |result|. |result| must be a type supported
+  // by the codec.
+  std::unique_ptr<std::vector<uint8_t>> EncodeSuccessEnvelope(
+      const void *result = nullptr) const;
+
+  // Returns a binary encoding of |error|. The |error_details| must be a type
+  // supported by the codec.
+  std::unique_ptr<std::vector<uint8_t>> EncodeErrorEnvelope(
+      const std::string &error_code, const std::string &error_message = "",
+      const void *error_details = nullptr) const;
+
+ protected:
+  // Implementations of the public interface, to be provided by subclasses.
+  virtual std::unique_ptr<MethodCall> DecodeMethodCallInternal(
+      const uint8_t *message, const size_t message_size) const = 0;
+  virtual std::unique_ptr<std::vector<uint8_t>> EncodeMethodCallInternal(
+      const MethodCall &method_call) const = 0;
+  virtual std::unique_ptr<std::vector<uint8_t>> EncodeSuccessEnvelopeInternal(
+      const void *result) const = 0;
+  virtual std::unique_ptr<std::vector<uint8_t>> EncodeErrorEnvelopeInternal(
+      const std::string &error_code, const std::string &error_message,
+      const void *error_details) const = 0;
+};
+
+}  // namespace flutter_desktop_embedding
+
+#endif  // LINUX_LIBRARY_INCLUDE_FLUTTER_DESKTOP_EMBEDDING_METHOD_CODEC_H_

linux/library/include/flutter_desktop_embedding/method_result.h

@@ -14,30 +14,34 @@
 #ifndef LINUX_LIBRARY_INCLUDE_FLUTTER_DESKTOP_EMBEDDING_METHOD_RESULT_H_
 #define LINUX_LIBRARY_INCLUDE_FLUTTER_DESKTOP_EMBEDDING_METHOD_RESULT_H_
 
-#include <json/json.h>
-
-#include <memory>
 #include <string>
 
-#include <flutter_embedder.h>
-
 namespace flutter_desktop_embedding {
 
 // Encapsulates a result sent back to the Flutter engine in response to a
 // MethodCall. Only one method should be called on any given instance.
 class MethodResult {
  public:
+  MethodResult();
+  virtual ~MethodResult();
+
+  // Prevent copying.
+  MethodResult(MethodResult const &) = delete;
+  MethodResult &operator=(MethodResult const &) = delete;
+
   // Sends a success response, indicating that the call completed successfully.
-  // An optional value can be provided as part of the success message.
-  void Success(const Json::Value &result = Json::Value());
+  // An optional value can be provided as part of the success message. The value
+  // must be a type handled by the channel's codec.
+  void Success(const void *result = nullptr);
 
   // Sends an error response, indicating that the call was understood but
   // handling failed in some way. A string error code must be provided, and in
   // addition an optional user-readable error_message and/or details object can
-  // be included.
+  // be included. The details, if provided, must be a type handled by the
+  // channel's codec.
   void Error(const std::string &error_code,
              const std::string &error_message = "",
-             const Json::Value &error_details = Json::Value());
+             const void *error_details = nullptr);
 
   // Sends a not-implemented response, indicating that the method either was not
   // recognized, or has not been implemented.
@@ -46,45 +50,13 @@ class MethodResult {
  protected:
   // Internal implementation of the interface methods above, to be implemented
   // in subclasses.
-  virtual void SuccessInternal(const Json::Value &result) = 0;
+  virtual void SuccessInternal(const void *result) = 0;
   virtual void ErrorInternal(const std::string &error_code,
                              const std::string &error_message,
-                             const Json::Value &error_details) = 0;
+                             const void *error_details) = 0;
   virtual void NotImplementedInternal() = 0;
 };
 
-// Implemention of MethodResult using JSON as the protocol.
-// TODO: Move this logic into method codecs.
-class JsonMethodResult : public MethodResult {
- public:
-  // Creates a result object that will send results to |engine|, tagged as
-  // associated with |response_handle|. The engine pointer must remain valid for
-  // as long as this object exists.
-  JsonMethodResult(FlutterEngine engine,
-                   const FlutterPlatformMessageResponseHandle *response_handle);
-  ~JsonMethodResult();
-
- protected:
-  void SuccessInternal(const Json::Value &result) override;
-  void ErrorInternal(const std::string &error_code,
-                     const std::string &error_message,
-                     const Json::Value &error_details) override;
-  void NotImplementedInternal() override;
-
- private:
-  // Sends the given JSON response object to the engine.
-  void SendResponseJson(const Json::Value &response);
-
-  // Sends the given response data (which must either be nullptr or a serialized
-  // JSON response) to the engine.
-  // Uses a pointer rather than a reference since nullptr is used to indicate
-  // not-implemented (which is represented to Flutter by no data).
-  void SendResponse(const std::string *serialized_response);
-
-  FlutterEngine engine_;
-  const FlutterPlatformMessageResponseHandle *response_handle_;
-};
-
 }  // namespace flutter_desktop_embedding
 
 #endif  // LINUX_LIBRARY_INCLUDE_FLUTTER_DESKTOP_EMBEDDING_METHOD_RESULT_H_