Function

Function nodes execute functional code when they receive a message. They can output new messages to further nodes and respond to calling nodes.

Message Formats

There are no expectations on the format of input, output, or response messages. Although messages must generally be JSON compatible, Buffers and Error objects may be transmitted and received in their native form.

Environment

  • Runtime: Node.js, .NET Core, or Python (version 3)
  • Networking Out: The function can make any outbound TCP network connections except to port 25 as an anti-spam measure
  • Networking In: Inbound network connections are blocked, but nodes may handle HTTP requests via the Rest Api node
  • Scratch Space: 500 MB of space is available for use in /tmp

Compute Power, Memory, and Bandwidth limits

The memory allocated to the function process can be configured from 128 MB to 1,536 MB. Compute power and bandwidth increase in proportion to the memory limit.

Errors

The following conditions will generate an error:

  • Uncaught exception
  • Execution timeout
  • Node.js
    • Returned Promise is rejected or done callback is called with a truthy error argument
    • Process exits before finishing handling the message (i.e. before the done callback is called or a returned Promise is resolved or rejected)
  • .NET
    • Handler throws an exception
    • Returned Task is canceled or faults
  • Python
    • Handler raises an exception

Errors are propagated in one of two ways:

  • If the Function was called synchronously by another Function node, the error is sent back to the calling Function node.
  • In all other cases, the error is emitted out of the Errors node if one exists in the stack.

Settings

Name

A label used for the node in the canvas and for the location of the source code inside the git repository for the stack. The source code for a function can be found in /Stackery/functions/<name>.

Outputs

The number of output ports. Messages are output to nodes connected to a port.

Timeout

The maximum amount of time the function can spend executing in response to a message, ranging from one to 300 seconds (five minutes). An error will be generated if the timeout is reached before the function completes handling the message.

Memory

The amount of memory allocated to the function process, ranging from 128 MB to 1.5 GB. This setting also affects compute power and bandwidth limits.

Runtime

The runtime of the function. Can be either Node.js, .NET, or Python.

Source

The location of the source code. If the location is set to Stackery, the source code for the function resides within the Git repo for the stack in /Stackery/functions/<name>. If the location is set to Git, the source code is pulled from an external Git repo.

index.js / Handler.cs / handler.py

The main index.js (Node.js), Handler.cs (.NET), or handler.py (Python) file may be edited if the source of the code is kept in the Git repo for the stack.

Repo

The repo setting defines the location of the code when the source is set to Git. The repository must be publicly accessible over HTTPS, though basic authentication is supported.

Environment Variables

A list of environment variables. Values may be set statically or referenced from Configuration Stores.

Node.js Runtime

Handler

The signature of the handler function exported by the index.js file is:

function handler(message[, done])

The first argument, message, is the message received by the node. The function will execute until either the done function is invoked or a Promise returned by the handler is resolved or rejected.

Using Promises

When the handler function returns a value other than undefined, the handler is assumed to be operating with Promise semantics.

Under Promise semantics, if the returned value is a Promise, the runtime will wait until the Promise is resolved or rejected. Resolved data will be used as the message responded back to the calling node. Rejected data will be treated as an error.

Returned values other than Promises will be handled as response messages to calling nodes.

Using The Callback

When using the done callback, the handler function must return undefined. This can be easily accomplished by not returning a value. When the function is finished handling the message, the done callback is called:

function done(err, response)

If err is truthy its value will be treated as an error and the response value will be ignored. If err is falsey the response value will be responded back to the calling node.

Outputting messages

To output a message, first import the stackery module:

const stackery = require('stackery')

The stackery module exports an output function that can be used to output messages. The signature of the output function is:

function output(message[, options[, callback]])

The output function will output the message specified by the message argument. The callback argument, if provided, will be invoked when the message has been output. The function returns a Promise that resolves once the message has been transmitted and a response has been received.

By default, messages will be output to the first (0th) port. To output messages to other ports, set the port option to the port number.

When outputting to other Function nodes the waitFor option can be used to specify the condition under which the promise is resolved or the callback is called. The default is to wait until the other Function node has processed the message and provided a response. When setting the waitFor option to 'TRANSMISSION', the promise will resolve or the callback will be called as soon as the other Function has been successfully invoked.

Dependencies

Functions can have dependencies on other files and packages. Within the function code directory local dependencies can be added as individual files and package dependencies can be added via a package.json file. Production dependencies specified in a package.json file are installed when the stack is deployed.

Logging

Messages may be logged using the standard Node.js console facilities. These messages may be viewed in AWS CloudWatch by selecting the node in the deployment status tab and navigating to the Logs link in the info sidebar.

.NET Core Runtime

Handler

The .NET Core runtime expects a handler method to be present that resembles the following signature:

namespace StackeryFunction
{
    public class Handler
    {
        public Stackery.RestApiExpectedResponse handler(Stackery.RestApiMessage message)
        {
            return new Stackery.RestApiExpectedResponse();
        }
    }
}

The message argument and returned response object are serialized from JSON using Json.NET. In the above example, the message and response are Stackery Rest Api objects, but any serializable types may be used.

The handler can also return Task objects for asynchronous processing.

The Stackery .NET Core runtime looks for a Handler class in the StackeryFunction namespace within a StackeryFunction assembly. The runtime creates an instance of the Handler class, then invokes its handler method when messages are sent to the Function node.

Outputting Messages

The Stackery package provides utilities for outputting messages. Here’s an example:

using Stackery;
using static Stackery.OutputUtils;

namespace StackeryFunction
{
    public class Handler
    {
        public async Task<dynamic> handler(dynamic message)
        {
            var runTaskMessage = new DockerServiceRunTaskMessage();

            var responses = await Output<DockerServiceRunTaskResponse>(runTaskMessage);

            return responses[0];
        }
    }
}

The Output method will output the message passed in. When sending to Function and Stream nodes the message is converted to JSON using Json.NET. Messages sent to other node types have static types that should be used. For example, Stackery.DockerServiceRunTaskMessage should be used for sending a message to a Docker Service node.

By default, messages will be output to the first (0th) port. To output messages to other ports, set the port parameter to the port number.

Dependencies

Functions can have dependencies on other files and packages. Within the function code directory local dependencies can be added as individual files and package dependencies can be added to the Stackery.csproj file. Package dependencies specified in the Stackery.csproj file are installed when the stack is deployed.

Logging

Messages may be logged using the standard Console methods. These messages may be viewed in AWS CloudWatch by selecting the node in the deployment status tab and navigating to the Logs link in the info sidebar.

Python Runtime

Handler

The Python runtime expects the handler.py file to export a handler function with the following signature:

def handler(message)

The only argument, message, is the message received by the node. The function will execute until the handler function returns with a response.

Outputting Messages

To output a message, first import the stackery module:

import stackery

The stackery module exports an output function that can be used to output messages. The signature of the output function is:

output(message, port=0, wait_for=None, **kwargs)

The output function will output the message specified by the message argument.

By default, messages will be output to the first (0th) port. To output messages to other ports, set the port parameter to the port number.

When outputting to other Function nodes the wait_for parameter can be used to specify the condition under which the response should return. The default is to wait until the other Function node has processed the message and provided a response. When setting the wait_for argument to stackery.WaitFor.TRANSMISSION, the response will be returned as soon as the other Function has been successfully invoked.

Dependencies

Functions can have dependencies on other files and packages. Within the function code directory local dependencies can be added as individual files and package dependencies can be added via a requirements.txt file. Dependencies specified in a requirements.txt file are installed when the stack is deployed.

Logging

Messages may be logged using the standard Python logging methods. These messages may be viewed in AWS CloudWatch by selecting the node in the deployment status tab and navigating to the Logs link in the info sidebar.

Referenceable Properties

The following properties may be referenced by Function and Docker Service nodes:

Property Value Example
id Cloud Service Identifier arn:aws:lambda:us-east-1:0123456789012:function:stackery-298374238-api

Try Stackery For Free

Gain control and visibility of your serverless operations from architecture design to application deployment and infrastructure monitoring.