Correctness and documentation of the samples (#85)

* validated all samples except tensorflow

* deleted non-samples, tested tensorflow sample, added types and comments

* new readmes for fan-out-fan-in and function-chaining

* renamed some functions so they are easier to reason about

* disable aiohttp's input validation... potentially unsafe. ExternalEvents now shows no warnings!

Author: davidmrdavid

azure/durable_functions/models/utils/http_utils.py

@@ -21,7 +21,11 @@ async def post_async_request(url: str, data: Any = None) -> [int, Any]:
     async with aiohttp.ClientSession() as session:
         async with session.post(url,
                                 json=data) as response:
-            data = await response.json()
+            # We disable aiohttp's input type validation
+            # as the server may respond with alternative
+            # data encodings. This is potentially unsafe.
+            # More here: https://docs.aiohttp.org/en/stable/client_advanced.html
+            data = await response.json(content_type=None)
             return [response.status, data]
 
 

host.json

@@ -0,0 +1,7 @@
+{
+  "version": "2.0",
+  "extensionBundle": {
+    "id": "Microsoft.Azure.Functions.ExtensionBundle",
+    "version": "[1.*, 2.0.0)"
+  }
+}

samples/durable_cli/setup.ps1

@@ -1,11 +1,30 @@
 import json
 import logging
-
+from typing import List
 import azure.durable_functions as df
 import azure.functions as func
 
 
-def orchestrator_function(context: df.DurableOrchestrationContext):
+def orchestrator_function(context: df.DurableOrchestrationContext) -> List[str]:
+
+    """This function provides the core function chaining orchestration logic
+
+    Parameters
+    ----------
+    context: DurableOrchestrationContext
+        This context has the past history and the durable orchestration API
+
+    Returns
+    -------
+    output: List[str]
+        Returns an array of result by the activity functions.
+
+    Yields
+    -------
+    call_activity: str
+        Yields, depending on the `json_rule`, to wait on either all
+        tasks to complete, or until one of the tasks completes.
+    """
 
 
     logging.debug("Creating the orchestrator function")

samples/external_events/DurableOrchestrationTrigger/__init__.py renamed to samples/external_events/DurableOrchestration/__init__.py

@@ -0,0 +1,33 @@
+import logging
+
+from azure.durable_functions import DurableOrchestrationClient
+import azure.functions as func
+
+
+async def main(req: func.HttpRequest, starter: str) -> func.HttpResponse:
+    """This function starts up the orchestrator from an HTTP endpoint
+
+    Parameters
+    ----------
+    req: func.HttpRequest
+        An HTTP Request object, it can be used to parse URL
+        parameters.
+
+    starter: str
+        A JSON-formatted string describing the orchestration context
+
+    Returns
+    -------
+    func.HttpResponse
+        An HTTP response containing useful URLs for monitoring the
+        status of newly generated orchestration instance
+    """
+
+    logging.debug("Recevied http request call with value {}".format(starter))
+    function_name = req.route_params.get('functionName')
+    client = DurableOrchestrationClient(starter)
+
+    logging.debug("About to call function {} asyncrounously".format(function_name))
+    instance_id = await client.start_new(function_name, None, None)
+
+    return client.create_check_status_response(req, instance_id)

samples/external_events/DurableOrchestrationTrigger/function.json renamed to samples/external_events/DurableOrchestration/function.json

@@ -1,27 +1,27 @@
-{
-  "scriptFile": "__init__.py",
-  "bindings": [
-    {
-      "authLevel": "function",
-      "name": "req",
-      "type": "httpTrigger",
-      "direction": "in",
-      "route": "orchestrators/{functionName}",
-      "methods": [
-        "post",
-        "get"
-      ]
-    },
-    {
-      "direction": "out",
-      "name": "$return",
-      "type": "http"
-    },
-    {
-      "name": "starter",
-      "type": "durableClient",
-      "direction": "in",
-      "datatype": "string"
-    }
-  ]
-}
+{
+  "scriptFile": "__init__.py",
+  "bindings": [
+    {
+      "authLevel": "function",
+      "name": "req",
+      "type": "httpTrigger",
+      "direction": "in",
+      "route": "orchestrators/{functionName}",
+      "methods": [
+        "post",
+        "get"
+      ]
+    },
+    {
+      "direction": "out",
+      "name": "$return",
+      "type": "http"
+    },
+    {
+      "name": "starter",
+      "type": "orchestrationClient",
+      "direction": "in",
+      "datatype": "string"
+    }
+  ]
+}

samples/external_events/DurableOrchestrationClient/__init__.py

@@ -6,6 +6,23 @@
 
 
 async def main(req: func.HttpRequest, starter: str) -> func.HttpResponse:
+    """Activity function to raise an external event to the orchestrator
+    
+    Parameters
+    ----------
+    req: func.HttpRequest
+        An HTTP Request object, it can be used to parse URL
+        parameters.
+
+    starter: str
+        A JSON-formatted string describing the orchestration context
+
+    Returns
+    -------
+    func.HttpResponse
+        HTTP response object whose body indicates which event
+        was raised
+    """
 
     logging.info("Recevied http request to check startus {}".format(starter))
     client = DurableOrchestrationClient(starter)
@@ -16,5 +33,4 @@ async def main(req: func.HttpRequest, starter: str) -> func.HttpResponse:
     logging.info("Will check on event: {}".format(event_name))
 
     await client.raise_event(instance_id, event_name, True)
-
     return func.HttpResponse(f'"{event_name}" event is sent')

samples/external_events/DurableTrigger/__init__.py

@@ -1,26 +1,26 @@
-{
-  "scriptFile": "__init__.py",
-  "bindings": [
-    {
-      "authLevel": "function",
-      "name": "req",
-      "type": "httpTrigger",
-      "direction": "in",
-      "methods": [
-        "post",
-        "get"
-      ]
-    },
-    {
-      "name": "starter",
-      "type": "durableClient",
-      "direction": "in",
-      "datatype": "string"
-    },
-    {
-      "type": "http",
-      "direction": "out",
-      "name": "$return"
-    }
-  ]
+{
+  "scriptFile": "__init__.py",
+  "bindings": [
+    {
+      "authLevel": "function",
+      "name": "req",
+      "type": "httpTrigger",
+      "direction": "in",
+      "methods": [
+        "post",
+        "get"
+      ]
+    },
+    {
+      "name": "starter",
+      "type": "orchestrationClient",
+      "direction": "in",
+      "datatype": "string"
+    },
+    {
+      "type": "http",
+      "direction": "out",
+      "name": "$return"
+    }
+  ]
 }