Azure Durable Functions for long running APIs in Javascript
I recently had the pleasure of exploring and implementing Azure Durable Functions. I love how quick and easy it is to get set up.
I’m going to spin that exploration and implementation into the following blog post — Briefing and creating first Azure Durable Function in Javascript for long running processes.
Introduction
Durable function is part of Azure function. It is an open source extention of Azure function. By Using Durable functions you can implement stateful functions in serverless environment. The Extention manages state, checkpoints and restarts.
There are 3 main pillars of Durabale function
1. Starter function
2. Orchestrator function
3. Activity function
Why Durable functions ?
By it’s name we clearly understand one of the purpose of it which is handlling long running services without timing out.
With durable functions you can run activities in parallel to achieve multi steps functionality.
Supported Languages
1. C#
2. Javascript
3. Python
4. F#
5. PowerShell
Overview
Http Starter Function:
Http trigger durablefunction to call the orchestration function and bind the request to it. We can specify the dynamic route and http methods in the function configuration.
Orchestrator Function:
Orchestrate the execution of other durable functions in the function app. This function defines the stateful workflow in code and invokes the activity functions. Orchestrator function should be deterministic because the code will be executed again and again till activity function complete.
Activity Function:
Activity functions are independent stateless function for single task purpose which have no awareness of bigger workflows. This function is called by orchestrator function, performs task and optionally return the output. Activity functions can be called parallelly and/or in chain pattern.
Workflow
As we know there are some API requests which taking time due some heavy operations at backend or 3rd party services. So we have to wait at client side long time and timeout issue occures. Following diagram let you understand how it works.
Sequence Diagram:
Now Let’s move towards the actual impletation.
Prerequisites:
> Visual Studio Code.
> Install the Azure Functions VS Code extension
> Install Latest version of the Azure Functions Core Tools.
> Azure storage account. You need an Azure subscription.
> Node.js version 10.x or 12.x of Node.js
1. Create New Project
Type Ctrl+Shift+P and type ‘Create’ to open Azure function options and select ‘Azure Functions: Create New Project…’
Next select the location where you want to create project and then language in which you want to proceed (We are selecting javascript).
To work with Durable functions in Node.js function app install the Durable function npm package.
> npm install durable-functions
2. Create First Function — Http starter function
Next step will be select the function which you want to create first. We are selecting ‘Durable Functions HTTP starter’ function as our first function.
Give appropriate name to your Http starter function and then select Authorization Level from 3 options (Anonymous, Function, Admin). We are selection Anonymous for now.
Here we go!!! Our first function got created.
Two files are created where function.json is your binding config file and index.js file is your main file.
In function.json you can specify the dynamic route which you want to expose to the client also you can specify the http methods which you want to allow.
In Index.js just call our next function which we are going to create for orchestration and provide the request payload to it. Also returning the status response which client can consume to check the process status.
3. Create Durable Functions Orchestrator
Again type Ctrl+Shift+P and type create to create function and now select ‘Azure Functions: Create Function…’
Next we have to select function same like we did for http starter but this time we are going to select ‘Durable Functions orchestrator’ and give appropriate name for our orchestrator function which will be called from starter function.
Here is the magic again our orchestrator function created.
Again two files got created function.json and index.js which are the main files of Azure function. Now in index.js file you can see we are going to call our Activity functions which we are creating next and returning the output of it by using context’s callActivity method.
As I mentioned earlier we can call Activity functions here parallelly or in chaining pattern or only once. You can pass parameters or request payload from context object to callActivity function as second parameter.
4. Create Durable Functions Activity
Let’s do same steps till selection of function from populated list and now select ‘Durable Functions activity’ and name your function as per your process or module.
Hooray!!! All base functions are created as per architecture we defined.
Activity function with name DurableFunctionsActivityFirst is created now.
In our activity functions we can write the logic, call the module services with db interactions or 3rd party services. This is the single purpose task where we can keep business logic of your API or process. We can access the parameters from context which we have paased to callActivity function in orchestrator.
Here I’m returning the output string after 1 minutes from service greet (It can be hours depends on our operations) so till its finish we’ll get status of our process as running.
Run the Durable function
To Run durable function locally you can press ‘F5’ or you can select from ‘Run’ => ‘Start Debugging’ option.
All of 3 functions started successfully locally.
Http Endpoint: http://localhost:7071/api/orchestrators/{functionName}
OK! Let’s give it a shot from Postman.
We have called our orchestrator via Http starter endpoint and got the check status response with instance id and with status code 202 (It means request accepted).
We are going to use statusQueryGetUri for now others have different purpose which you can explore in depth seperatly.
By hitting this status Uri you can check the status and output of your process.
Status uri contains instanceId, taskHub, connection & code.
When process is not completed you will get runtimeStatus as Running. As we can see in screenshot our process is not completed yet its running.
Runtime Status can be following:
Pending: When your process is in pending state.
Running: When process is in progress and taking time.
Failed: When process failed somewhere or got broke.
Completed: When process finished successfully.
Yippee!!!
Our process completed successfully with expected output. On the success runtimeStatus is Completed with Status Code 200.
Wrap-up
I hope in this blog post you have better understanding of use of Durable functions for long running APIs and what value it offer. With this architecture of backend you can implement polling mechanism at client side to avoid long running process problems and timeouts.