Link Search Menu Expand Document

Making Custom Functions

Need to do something more than what’s supported by Direktiv? You can do just about anything by making your own custom functions to run as Functions. To make things easier Direktiv makes its Functions automatically from Docker images, but you can’t just run any Docker image. In this article you’ll learn how to make a Direktiv-compatible Docker image.

Functions

Direktiv functions are only meant to be run for short lengths to time. They’re meant to take some input, do something, optionally generate some output, and then return. To enforce this Direktiv will pull the plug on any instance that runs too long, and this timeout is separate from any timeouts defined in a workflow definition. In general each function is one http request from start to end.

Input Data

The input data comes as post request data for each call to this function. The format is usually JSON but depending on your workflow it can be any data. It is the function-author’s responsibility to load this data and extract useful information from it. Input validation is optional, but encouraged.

Output Data

Data generated by the function should be returned as a response to that request, also usually as JSON.

Reporting Errors

If something goes wrong a function can report an error to the calling workflow instance by adding HTTP headers to the response. If these headers are populated the execution of the function will be considered a failure regardless of what’s stored in response data.

The headers to report errors are: Direktiv-ErrorCode and Direktiv-ErrorMessage. If an error message is defined without defining an error code the calling workflow instance will be marked as “crashed” without exposing any helpful information, so it’s important to always define both. Errors raised by functions are always ‘catchable’ by their error codes.

Here are sample error headers:

  "Direktiv-ErrorCode": "myapp.input",
  "Direktiv-ErrorMessage": "Missing 'customerId' property in JSON input."

Example

Have a look at the source code for one of the functions we’ve used a lot in these articles:

https://github.com/vorteil/direktiv-apps/blob/master/request/main.go

FAQs & Other Information

Function Logs

Logging for functions is a simple HTTP POST or GET request to the address:

 http://localhost:8889/log?aid=$ACTIONID.

If POST is used the body of the request is getting logged for GET requests add a log request parameter. The important parameter is $ACTIONID. Each requests gets an action id which identifies the workflow instance. This parameter has to be passed back to attach the log to the instance. This information is passed in as in the initial request (Direktiv-ActionID).

Networking

Direktiv configures the network so that functions can reach out to the internet and receive responses. In general functions have no externally routable IP address. Internal networking policies will be implemented in the next releases.


Copyright © 2021 Vorteil.io.