feat: Support strongly typed functions signature

src/functions_framework/__init__.py

@@ -13,20 +13,25 @@
 # limitations under the License.
 
 import functools
+import inspect
 import io
 import json
 import logging
 import os.path
 import pathlib
 import sys
+import types
+
+from inspect import signature
+from typing import Type
 
 import cloudevents.exceptions as cloud_exceptions
 import flask
 import werkzeug
 
 from cloudevents.http import from_http, is_binary
 
-from functions_framework import _function_registry, event_conversion
+from functions_framework import _function_registry, event_conversion, typed_event
 from functions_framework.background_event import BackgroundEvent
 from functions_framework.exceptions import (
     EventConversionException,
@@ -67,6 +72,32 @@ def wrapper(*args, **kwargs):
     return wrapper
 
 
+def typed(googleType):
+    # no parameter to the decorator
+    if isinstance(googleType, types.FunctionType):
+        func = googleType
+        typed_event.register_typed_event("", func)
+
+        @functools.wraps(func)
+        def wrapper(*args, **kwargs):
+            return func(*args, **kwargs)
+
+        return wrapper
+    # type parameter provided to the decorator
+    else:
+
+        def func_decorator(func):
+            typed_event.register_typed_event(googleType, func)
+
+            @functools.wraps(func)
+            def wrapper(*args, **kwargs):
+                return func(*args, **kwargs)
+
+            return wrapper
+
+        return func_decorator
+
+
 def http(func):
     """Decorator that registers http as user function signature type."""
     _function_registry.REGISTRY_MAP[
@@ -106,6 +137,21 @@ def _run_cloud_event(function, request):
     function(event)
 
 
+def _typed_event_func_wrapper(function, request, inputType: Type):
+    def view_func(path):
+        data = request.get_json()
+        input = inputType.from_dict(data)
+        response = function(input)
+        if response is None:
+            return "OK"
+        if response.__class__.__module__ == "builtins":
+            return response
+        typed_event.validate_return_type(response)
+        return response.to_dict()
+
+    return view_func
+
+
 def _cloud_event_view_func_wrapper(function, request):
     def view_func(path):
         ce_exception = None
@@ -174,7 +220,7 @@ def view_func(path):
     return view_func
 
 
-def _configure_app(app, function, signature_type):
+def _configure_app(app, function, signature_type, inputType):
     # Mount the function at the root. Support GCF's default path behavior
     # Modify the url_map and view_functions directly here instead of using
     # add_url_rule in order to create endpoints that route all methods
@@ -216,6 +262,21 @@ def _configure_app(app, function, signature_type):
         app.view_functions[signature_type] = _cloud_event_view_func_wrapper(
             function, flask.request
         )
+    elif signature_type == _function_registry.TYPED_SIGNATURE_TYPE:
+        # validity_check()
+        app.url_map.add(
+            werkzeug.routing.Rule(
+                "/", defaults={"path": ""}, endpoint=signature_type, methods=["POST"]
+            )
+        )
+        app.url_map.add(
+            werkzeug.routing.Rule(
+                "/<path:path>", endpoint=signature_type, methods=["POST"]
+            )
+        )
+        app.view_functions[signature_type] = _typed_event_func_wrapper(
+            function, flask.request, inputType
+        )
     else:
         raise FunctionsFrameworkException(
             "Invalid signature type: {signature_type}".format(
@@ -288,8 +349,9 @@ def handle_none(rv):
     # Get the configured function signature type
     signature_type = _function_registry.get_func_signature_type(target, signature_type)
     function = _function_registry.get_user_function(source, source_module, target)
+    inputType = _function_registry.get_func_input_type(target)
 
-    _configure_app(_app, function, signature_type)
+    _configure_app(_app, function, signature_type, inputType)
 
     return _app
 

src/functions_framework/_cli.py

@@ -26,7 +26,7 @@
 @click.option(
     "--signature-type",
     envvar="FUNCTION_SIGNATURE_TYPE",
-    type=click.Choice(["http", "event", "cloudevent"]),
+    type=click.Choice(["http", "event", "cloudevent", "typed"]),
     default="http",
 )
 @click.option("--host", envvar="HOST", type=click.STRING, default="0.0.0.0")

src/functions_framework/_function_registry.py

@@ -16,6 +16,9 @@
 import sys
 import types
 
+from re import T
+from typing import Type
+
 from functions_framework.exceptions import (
     InvalidConfigurationException,
     InvalidTargetTypeException,
@@ -28,10 +31,12 @@
 HTTP_SIGNATURE_TYPE = "http"
 CLOUDEVENT_SIGNATURE_TYPE = "cloudevent"
 BACKGROUNDEVENT_SIGNATURE_TYPE = "event"
+TYPED_SIGNATURE_TYPE = "typed"
 
 # REGISTRY_MAP stores the registered functions.
 # Keys are user function names, values are user function signature types.
 REGISTRY_MAP = {}
+INPUT_MAP = {}
 
 
 def get_user_function(source, source_module, target):
@@ -120,3 +125,8 @@ def get_func_signature_type(func_name: str, signature_type: str) -> str:
     if os.environ.get("ENTRY_POINT"):
         os.environ["FUNCTION_TRIGGER_TYPE"] = sig_type
     return sig_type
+
+
+def get_func_input_type(func_name: str) -> Type:
+    registered_type = INPUT_MAP[func_name] if func_name in INPUT_MAP else ""
+    return registered_type

src/functions_framework/event_conversion.py

@@ -115,6 +115,7 @@
 
 
 def background_event_to_cloud_event(request) -> CloudEvent:
+    print("background_event_to_cloud_event")
     """Converts a background event represented by the given HTTP request into a CloudEvent."""
     event_data = marshal_background_event_data(request)
     if not event_data:
@@ -185,6 +186,7 @@ def background_event_to_cloud_event(request) -> CloudEvent:
 
 
 def is_convertable_cloud_event(request) -> bool:
+    print("is_convertable_cloud_event")
     """Is the given request a known CloudEvent that can be converted to background event."""
     if is_binary(request.headers):
         event_type = request.headers.get("ce-type")
@@ -208,6 +210,7 @@ def _split_ce_source(source) -> Tuple[str, str]:
 
 
 def cloud_event_to_background_event(request) -> Tuple[Any, Context]:
+    print("cloud_event_to_background_event")
     """Converts a background event represented by the given HTTP request into a CloudEvent."""
     try:
         event = from_http(request.headers, request.get_data())
@@ -294,6 +297,7 @@ def _split_resource(context: Context) -> Tuple[str, str, str]:
 
 
 def marshal_background_event_data(request):
+    print("marshal_background_event_data")
     """Marshal the request body of a raw Pub/Sub HTTP request into the schema that is expected of
     a background event"""
     try:

src/functions_framework/exceptions.py

@@ -35,3 +35,15 @@ class MissingTargetException(FunctionsFrameworkException):
 
 class EventConversionException(FunctionsFrameworkException):
     pass
+
+
+class MissingTypeException(FunctionsFrameworkException):
+    pass
+
+
+class TypeMismatchException(FunctionsFrameworkException):
+    pass
+
+
+class MissingMethodException(FunctionsFrameworkException):
+    pass

src/functions_framework/typed_event.py

@@ -0,0 +1,88 @@
+# Copyright 2021 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 inspect
+
+from inspect import signature
+
+from functions_framework import _function_registry
+from functions_framework.exceptions import (
+    MissingMethodException,
+    MissingTypeException,
+    TypeMismatchException,
+)
+
+
+class TypedEvent(object):
+
+    # Supports v1beta1, v1beta2, and v1 event formats.
+    def __init__(
+        self,
+        data,
+    ):
+        self.data = data
+
+
+def register_typed_event(decorator_type, func):
+    sig = signature(func)
+    annotation_type = list(sig.parameters.values())[0].annotation
+
+    type_validity_check(decorator_type, annotation_type)
+    if decorator_type == "":
+        decorator_type = annotation_type
+
+    _function_registry.INPUT_MAP[func.__name__] = decorator_type
+    _function_registry.REGISTRY_MAP[
+        func.__name__
+    ] = _function_registry.TYPED_SIGNATURE_TYPE
+
+
+def validate_return_type(response):
+    if not (hasattr(response, "to_dict") and callable(getattr(response, "to_dict"))):
+        raise MissingMethodException(
+            "The type {response} does not have the required method called "
+            " 'to_dict'.".format(response=response)
+        )
+
+
+def type_validity_check(decorator_type, annotation_type):
+    if decorator_type == "" and annotation_type is inspect._empty:
+        raise MissingTypeException(
+            "The function defined does not contain Type of the input object."
+        )
+
+    if (
+        decorator_type != ""
+        and annotation_type is not inspect._empty
+        and decorator_type != annotation_type
+    ):
+        raise TypeMismatchException(
+            "The object type provided via 'typed' {decorator_type}"
+            "is different from the one in the function annotation {annotation_type}.".format(
+                decorator_type=decorator_type, annotation_type=annotation_type
+            )
+        )
+
+    if decorator_type == "":
+        decorator_type = annotation_type
+
+    if not (
+        hasattr(decorator_type, "from_dict")
+        and callable(getattr(decorator_type, "from_dict"))
+    ):
+        raise MissingMethodException(
+            "The type {decorator_type} does not have the required method called "
+            " 'from_dict'.".format(decorator_type=decorator_type)
+        )

tests/test_functions/typed_events/missing_from_dict.py

@@ -0,0 +1,55 @@
+# Copyright 2021 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.
+
+"""Function used to test handling functions using typed decorators."""
+from typing import Any, TypeVar
+
+import flask
+
+import functions_framework
+
+T = TypeVar("T")
+
+
+def from_str(x: Any) -> str:
+    assert isinstance(x, str)
+    return x
+
+
+def from_int(x: Any) -> int:
+    assert isinstance(x, int) and not isinstance(x, bool)
+    return x
+
+
+class TestTypeMissingFromDict:
+    name: str
+    age: int
+
+    def __init__(self, name: str, age: int) -> None:
+        self.name = name
+        self.age = age
+
+    def to_dict(self) -> dict:
+        result: dict = {}
+        result["name"] = from_str(self.name)
+        result["age"] = from_int(self.age)
+        return result
+
+
+@functions_framework.typed(TestTypeMissingFromDict)
+def function_typed_missing_from_dict(test_type: TestTypeMissingFromDict):
+    valid_event = test_type.name == "john" and test_type.age == 10
+    if not valid_event:
+        flask.abort(500)
+    return test_type