Import of Cloud Functions JVM from Git-on-Borg.

  - a6111561e09808f60fd1e79b7d3f2035fcb047bc Change invoker to depend on API version 1.0.0-alpha-2-rc3. by Éamonn McManus <[email protected]>
  - 7007628de5e20984babc8be8764325c2c2cad607 Revise background functions API. by Éamonn McManus <[email protected]>

PiperOrigin-RevId: 279283731

Author: eamonnmcmanus

functions-framework-api/pom.xml

@@ -24,7 +24,7 @@
 
   <groupId>com.google.cloud.functions</groupId>
   <artifactId>functions-framework-api</artifactId>
-  <version>1.0.0-alpha-2-rc2-SNAPSHOT</version>
+  <version>1.0.0-alpha-2-rc3-SNAPSHOT</version>
 
   <properties>
     <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
@@ -179,12 +179,4 @@
       </build>
     </profile>
   </profiles>
-  <dependencies>
-    <dependency>
-      <groupId>com.google.code.gson</groupId>
-      <artifactId>gson</artifactId>
-      <version>2.8.6</version>
-      <type>jar</type>
-    </dependency>
-  </dependencies>
 </project>

functions-framework-api/src/main/java/com/google/cloud/functions/BackgroundFunction.java

@@ -14,38 +14,22 @@
 
 package com.google.cloud.functions;
 
-import com.google.gson.JsonElement;
-
 /**
- * Represents a Cloud Function that is activated by an event.
+ * Represents a Cloud Function that is activated by an event and parsed into a user-supplied class.
+ * The payload of the event is a JSON object, which is deserialized into a user-defined class as
+ * described for
+ * <a href="https://github.com/google/gson/blob/master/UserGuide.md#TOC-Object-Examples">Gson</a>.
  *
- * <p>Here is an example of an implementation that operates on the JSON payload of the event
- * directly:
+ * <p>Here is an example of an implementation that accesses the {@code messageId} property from
+ * a payload that matches a user-defined {@code PubSubMessage} class:
  *
  * <pre>
- * public class Example implements BackgroundFunction {
+ * public class Example implements {@code BackgroundFunction<PubSubMessage>} {
  *   private static final Logger logger = Logger.getLogger(Example.class.getName());
  *
  *   {@code @Override}
- *   public void accept(JsonElement json, Context context) {
- *     JsonElement messageId = json.getAsJsonObject().get("messageId");
- *     String messageIdString = messageId.getAsJsonString();
- *     logger.info("Got messageId " + messageIdString);
- *   }
- * }
- * </pre>
- *
- * <p>Here is an example of an implementation that deserializes the JSON payload into a Java
- * object for simpler access:
- *
- * <pre>
- * public class Example implements BackgroundFunction {
- *   private static final Logger logger = Logger.getLogger(Example.class.getName());
- *
- *   {@code @Override}
- *   public void accept(JsonElement json, Context context) {
- *     PubSubMessage message = Gson.fromJson(json, PubSubMessage.class);
- *     logger.info("Got messageId " + message.messageId);
+ *   public void accept(PubSubMessage pubSubMessage, Context context) {
+ *     logger.info("Got messageId " + pubSubMessage.messageId);
  *   }
  * }
  *
@@ -57,17 +41,19 @@
  *   String publishTime;
  * }
  * </pre>
+ *
+ * @param <T> the class of payload objects that this function expects.
  */
 @FunctionalInterface
-public interface BackgroundFunction {
+public interface BackgroundFunction<T> {
   /**
    * Called to service an incoming event. This interface is implemented by user code to
-   * provide the action for a given background function.
+   * provide the action for a given background function. If this method throws any exception
    * (including any {@link Error}) then the HTTP response will have a 500 status code.
    *
-   * @param json the payload of the event, as a parsed JSON object.
+   * @param payload the payload of the event, deserialized from the original JSON string.
    * @param context the context of the event. This is a set of values that every event has,
    *     separately from the payload, such as timestamp and event type.
    */
-  public void accept(JsonElement json, Context context);
+  void accept(T payload, Context context);
 }

functions-framework-api/src/main/java/com/google/cloud/functions/RawBackgroundFunction.java

@@ -0,0 +1,74 @@
+// Copyright 2019 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.
+
+package com.google.cloud.functions;
+
+/**
+ * Represents a Cloud Function that is activated by an event. The payload of the event is a JSON
+ * object, which can be parsed using a JSON package such as
+ * <a href="https://github.com/google/gson/blob/master/UserGuide.md">GSON</a>.
+ *
+ * <p>Here is an example of an implementation that parses the JSON payload using Gson, to access its
+ * {@code messageId} property:
+ *
+ * <pre>
+ * public class Example implements RawBackgroundFunction {
+ *   private static final Logger logger = Logger.getLogger(Example.class.getName());
+ *
+ *   {@code @Override}
+ *   public void accept(String json, Context context) {
+ *     JsonObject jsonObject = new Gson().fromJson(json, JsonObject.class);
+ *     JsonElement messageId = jsonObject.get("messageId");
+ *     String messageIdString = messageId.getAsJsonString();
+ *     logger.info("Got messageId " + messageIdString);
+ *   }
+ * }
+ * </pre>
+ *
+ * <p>Here is an example of an implementation that deserializes the JSON payload into a Java
+ * object for simpler access, again using Gson:
+ *
+ * <pre>
+ * public class Example implements RawBackgroundFunction {
+ *   private static final Logger logger = Logger.getLogger(Example.class.getName());
+ *
+ *   {@code @Override}
+ *   public void accept(String json, Context context) {
+ *     PubSubMessage message = new Gson().fromJson(json, PubSubMessage.class);
+ *     logger.info("Got messageId " + message.messageId);
+ *   }
+ * }
+ *
+ * // Where PubSubMessage is a user-defined class like this:
+ * public class PubSubMessage {
+ *   String data;
+ *   {@code Map<String, String>} attributes;
+ *   String messageId;
+ *   String publishTime;
+ * }
+ * </pre>
+ */
+@FunctionalInterface
+public interface RawBackgroundFunction {
+  /**
+   * Called to service an incoming event. This interface is implemented by user code to
+   * provide the action for a given background function. If this method throws any exception
+   * (including any {@link Error}) then the HTTP response will have a 500 status code.
+   *
+   * @param json the payload of the event, as a JSON string.
+   * @param context the context of the event. This is a set of values that every event has,
+   *     separately from the payload, such as timestamp and event type.
+   */
+  void accept(String json, Context context);
+}

invoker-core/pom.xml

@@ -14,7 +14,7 @@
     <dependency>
       <groupId>com.google.cloud.functions</groupId>
       <artifactId>functions-framework-api</artifactId>
-      <version>1.0.0-alpha-2-rc2</version>
+      <version>1.0.0-alpha-2-rc3</version>
     </dependency>
     <dependency>
         <groupId>javax.servlet</groupId>

invoker-core/src/main/java/com/google/cloud/functions/invoker/NewBackgroundFunctionExecutor.java

@@ -1,11 +1,16 @@
 package com.google.cloud.functions.invoker;
 
 import com.google.cloud.functions.BackgroundFunction;
+import com.google.cloud.functions.Context;
+import com.google.cloud.functions.RawBackgroundFunction;
 import com.google.gson.Gson;
 import com.google.gson.GsonBuilder;
+import com.google.gson.JsonParseException;
 import com.google.gson.TypeAdapter;
 import java.io.BufferedReader;
 import java.io.IOException;
+import java.lang.reflect.Type;
+import java.util.Arrays;
 import java.util.Optional;
 import java.util.logging.Level;
 import java.util.logging.Logger;
@@ -17,9 +22,9 @@
 public class NewBackgroundFunctionExecutor extends HttpServlet {
   private static final Logger logger = Logger.getLogger("com.google.cloud.functions.invoker");
 
-  private final BackgroundFunction function;
+  private final RawBackgroundFunction function;
 
-  private NewBackgroundFunctionExecutor(BackgroundFunction function) {
+  private NewBackgroundFunctionExecutor(RawBackgroundFunction function) {
     this.function = function;
   }
 
@@ -30,8 +35,8 @@ private NewBackgroundFunctionExecutor(BackgroundFunction function) {
    * {@code Optional.empty()}.
    *
    * @throws RuntimeException if we succeed in loading the class named by {@code target} but then
-   *    either the class does not implement {@link HttpFunction} or we are unable to construct an
-   *    instance using its no-arg constructor.
+   *    either the class does not implement {@link RawBackgroundFunction} or we are unable to
+   *    construct an instance using its no-arg constructor.
    */
   public static Optional<NewBackgroundFunctionExecutor> forTarget(String target) {
     Class<?> c;
@@ -40,17 +45,83 @@ public static Optional<NewBackgroundFunctionExecutor> forTarget(String target) {
     } catch (ClassNotFoundException e) {
       return Optional.empty();
     }
-    if (!BackgroundFunction.class.isAssignableFrom(c)) {
+    if (!BackgroundFunction.class.isAssignableFrom(c)
+        && !RawBackgroundFunction.class.isAssignableFrom(c)) {
       throw new RuntimeException(
-          "Class " + c.getName() + " does not implement " + BackgroundFunction.class.getName());
+          "Class " + c.getName() + " implements neither " + BackgroundFunction.class
+              .getName() + " nor " + RawBackgroundFunction.class.getName());
     }
-    Class<? extends BackgroundFunction> functionClass = c.asSubclass(BackgroundFunction.class);
+    Object instance;
     try {
-      BackgroundFunction function = functionClass.getConstructor().newInstance();
-      return Optional.of(new NewBackgroundFunctionExecutor(function));
+      instance = c.getConstructor().newInstance();
     } catch (ReflectiveOperationException e) {
       throw new RuntimeException("Could not construct an instance of " + target + ": " + e, e);
     }
+    RawBackgroundFunction function =
+        (instance instanceof RawBackgroundFunction)
+            ? (RawBackgroundFunction) instance
+            : asRaw((BackgroundFunction<?>) instance);
+    return Optional.of(new NewBackgroundFunctionExecutor(function));
+  }
+
+  private static <T> RawBackgroundFunction asRaw(BackgroundFunction<T> backgroundFunction) {
+    Optional<Type> maybeTargetType = backgroundFunctionTypeArgument(backgroundFunction.getClass());
+    if (!maybeTargetType.isPresent()) {
+      // This is probably because the user implemented just BackgroundFunction rather than
+      // BackgroundFunction<T>.
+      throw new RuntimeException(
+          "Could not determine the payload type for BackgroundFunction of type "
+              + backgroundFunction.getClass().getName()
+              + "; must implement BackgroundFunction<T> for some T");
+    }
+    return new AsRaw<T>(maybeTargetType.get(), backgroundFunction);
+  }
+
+  /**
+   * Returns the {@code T} of a concrete class that implements
+   * {@link BackgroundFunction BackgroundFunction<T>}. Returns an empty {@link Optional} if
+   * {@code T} can't be determined.
+   */
+  static Optional<Type> backgroundFunctionTypeArgument(
+      Class<? extends BackgroundFunction> functionClass) {
+    // If this is BackgroundFunction<Foo> then the user must have implemented a method
+    // accept(Foo, Context), so we look for that method and return the type of its first argument.
+    // We must be careful because the compiler will also have added a synthetic method
+    // accept(Object, Context).
+    return Arrays.stream(functionClass.getMethods())
+        .filter(m -> m.getName().equals("accept") && m.getParameterCount() == 2
+            && m.getParameterTypes()[1] == Context.class
+            && m.getParameterTypes()[0] != Object.class)
+        .map(m -> m.getGenericParameterTypes()[0])
+        .findFirst();
+  }
+
+  /**
+   * Wraps a typed {@link BackgroundFunction} as a {@link RawBackgroundFunction} that takes its
+   * input JSON string and deserializes it into the payload type of the {@link BackgroundFunction}/
+   */
+  private static class AsRaw<T> implements RawBackgroundFunction {
+    private final Gson gson = new Gson();
+    private final Type targetType;
+    private final BackgroundFunction<T> backgroundFunction;
+
+    private AsRaw(Type targetType, BackgroundFunction<T> backgroundFunction) {
+      this.targetType = targetType;
+      this.backgroundFunction = backgroundFunction;
+    }
+
+    @Override
+    public void accept(String json, Context context) {
+      T payload;
+      try {
+        payload = gson.fromJson(json, targetType);
+      } catch (JsonParseException e) {
+        logger.log(Level.WARNING,
+            "Could not convert payload to target type " + targetType.getTypeName(), e);
+        return;
+      }
+      backgroundFunction.accept(payload, context);
+    }
   }
 
   /** Executes the user's background function, can handle all HTTP type methods. */
@@ -69,7 +140,7 @@ public void service(HttpServletRequest req, HttpServletResponse res) throws IOEx
 
     Event event = gson.fromJson(body, Event.class);
     try {
-      function.accept(event.getData(), event.getContext());
+      function.accept(gson.toJson(event.getData()), event.getContext());
       res.setStatus(HttpServletResponse.SC_OK);
     } catch (Throwable t) {
       res.setStatus(HttpServletResponse.SC_INTERNAL_SERVER_ERROR);

invoker-core/src/test/java/com/google/cloud/functions/invoker/IntegrationTest.java

@@ -8,8 +8,8 @@
 import com.google.common.collect.ImmutableMap;
 import com.google.common.io.Files;
 import com.google.common.io.Resources;
+import com.google.gson.Gson;
 import com.google.gson.JsonObject;
-import com.google.gson.JsonParser;
 import java.io.BufferedReader;
 import java.io.File;
 import java.io.IOException;
@@ -133,35 +133,38 @@ public void newEchoUrl() throws Exception {
 
   @Test
   public void background() throws Exception {
-    URL resourceUrl = getClass().getResource("/adder_gcf_ga_event.json");
-    assertThat(resourceUrl).isNotNull();
-    File snoopFile = File.createTempFile("FunctionsIntegrationTest", ".txt");
-    snoopFile.deleteOnExit();
-    String originalJson = Resources.toString(resourceUrl, StandardCharsets.UTF_8);
-    JsonObject json = new JsonParser().parse(originalJson).getAsJsonObject();
-    JsonObject jsonData = json.getAsJsonObject("data");
-    jsonData.addProperty("targetFile", snoopFile.toString());
-    testBackgroundFunction("BackgroundSnoop.snoop",
-        TestCase.builder().setRequestText(json.toString()).build());
-    String snooped = Files.asCharSource(snoopFile, StandardCharsets.UTF_8).read();
-    JsonObject snoopedJson = new JsonParser().parse(snooped).getAsJsonObject();
-    assertThat(snoopedJson).isEqualTo(json);
+    backgroundTest("BackgroundSnoop.snoop");
   }
 
   @Test
   public void newBackground() throws Exception {
+    backgroundTest("NewBackgroundSnoop");
+  }
+
+  @Test
+  public void newTypedBackground() throws Exception {
+    backgroundTest("NewTypedBackgroundSnoop");
+  }
+
+  // In these tests, we test a number of different functions that express the same functionality
+  // in different ways. Each function is invoked with a complete HTTP body that looks like a real
+  // event. We start with a fixed body and insert into its JSON an extra property that tells the
+  // function where to write what it received. We have to do this since background functions, by
+  // design, don't return a value.
+  private void backgroundTest(String functionTarget) throws Exception {
+    Gson gson = new Gson();
     URL resourceUrl = getClass().getResource("/adder_gcf_ga_event.json");
     assertThat(resourceUrl).isNotNull();
     File snoopFile = File.createTempFile("FunctionsIntegrationTest", ".txt");
     snoopFile.deleteOnExit();
     String originalJson = Resources.toString(resourceUrl, StandardCharsets.UTF_8);
-    JsonObject json = new JsonParser().parse(originalJson).getAsJsonObject();
+    JsonObject json = gson.fromJson(originalJson, JsonObject.class);
     JsonObject jsonData = json.getAsJsonObject("data");
     jsonData.addProperty("targetFile", snoopFile.toString());
-    testBackgroundFunction("NewBackgroundSnoop",
+    testBackgroundFunction(functionTarget,
         TestCase.builder().setRequestText(json.toString()).build());
     String snooped = Files.asCharSource(snoopFile, StandardCharsets.UTF_8).read();
-    JsonObject snoopedJson = new JsonParser().parse(snooped).getAsJsonObject();
+    JsonObject snoopedJson = gson.fromJson(snooped, JsonObject.class);
     assertThat(snoopedJson).isEqualTo(json);
   }