Programming Model
Fusebit functions are lightweight and stateless pieces of Node.js code that execute as a result of a request from your application backend, or based on a cron schedule. Functions are packaged as Node.js modules, which makes them easy to manage and distribute. At its most basic, a function looks like this:
module.exports = async (ctx) => {
return { body: 'Hello world!' };
};
The interface returns the result (as specified below) directly or a properly formed Promise, and indicates an error by throwing an exception:
module.exports = async (ctx) => {
throw new Error('Failure');
};
Context object
The function receives incoming parameters through the ctx
object.
The ctx
parameter contains useful information about the invocation of the function:
accountId
- your Fusebit account idsubscriptionId
- your Fusebit subscription idboundaryId
- the id of the Fusebit boundary, which this function is a part offunctionId
- the id of the Fusebit function being executedconfiguration
- an object containing any application settings and secrets you specifymethod
- the method of invocation for this incoming callGET
,POST
,PUT
,DELETE
and other HTTP methodsCRON
in case the function was invoked on a schedule by the Fusebit cron service
baseUrl
- (only for non-scheduled invocations) the function base URL, for examplehttps://stage.us-west-2.fusebit.io/v1/run/sub-ab9d9113ea353241/my-boundary/my-function
url
- (only for non-scheduled invocations) the request URL, including the path and query parameters, for example/run/sub-ab9d9113ea353241/my-boundary/my-function/foo/bar?abc=def
path
- (only for non-scheduled invocations) the request path, which is the part of theurl
following thebaseUrl
, and excluding query parameters, for example/foo/bar
query
- (only for non-scheduled invocations) an object representing the request query stringheaders
- (only for non-scheduled invocations) an object representing the request headersbody
- (only for non-scheduled invocations) an object representing the request bodyfusebit.functionAccessToken
- an access token to Fusebit APIs supplied to the function by the Fusebit Platform following the parameters in the function specification.fusebit.caller.permissions
andfusebit.caller.accessToken
- authenticated and authorized caller's permissions and access token, depending on the security requirements in the function specification.
Result object
The function is expected to return, either as the second parameter in the callback or as the return value of the asynchronous function, an object with the following properties:
status
(optional; default:200
) - set that to the HTTP status code you would like to return with your responsebody
(optional) - the JSON you would like to return with your responsebodyEncoding
(optional; default:application/json
) - specifies the format that thebody
parameter should be considered.headers
(optional) - specifies additional headers to include in the HTTP response
If no response at all is provided, then a 200 OK
response is generated with a 0 length body payload. Otherwise, the default behavior encodes a body
as JSON. If HTML is desired, it is very easy to encode body
as a base64
encoded string:
module.exports = async (ctx) => {
return html('<b>Hello</b> World');
};
function html(body, headers, options) {
return {
...options,
headers: {
...headers,
'Content-Type': 'text/html',
},
bodyEncoding: 'base64',
body: Buffer.from(body).toString('base64'),
};
}
Callback interface
A callback-based interface is also offered, which exposes following signature to the Fusebit framework:
module.exports = (ctx, cb) => {
cb(null, { body: 'result' });
};
Upon completion, the cb(error, result)
callback is invoked, passing an Error as the first parameter and result
, as specified above, as the second.
- If your function completes successfully, set the error parameter to
null
so your callback looks like this:cb(null, { body: 'Hello world!' });
. This will result in a HTTP 200 response with JSON in body of the response. - If your function encounters an error, set the error parameter and omit the second parameter. Your callback will look like this:
cb(new Error('Something went wrong!'));
. This will result in a HTTP 500 response with the error serialized as JSON in the body of the response. - Failing to call
cb
from inside your function will result in it being terminated after a timeout period. - The return value of the traditional callback interface is ignored.
Using NPM packages
Fusebit allows use of any public npm package. Add the reference to the package you need in package.json
as you normally would during Node.js development, more details here. This can be done via the built-in Fusebit editor, the CLI, or via API. For example:
{
"dependencies": { "is-thirteen": "*" }
}
Then, reference and use the module in your function:
const is = require('is-thirteen');
module.exports = async (ctx) => {
return { body: is(13).thirteen() };
};
Application settings
Frequently, you want to keep certain application settings and secrets outside of the code of your function. Fusebit provides a dedicated feature for this, which also ensures they are safely encrypted at rest. To access these settings via the editor go to Settings
> Application
in the nav bar. Settings are simply key/value pairs like so
API_KEY=KMQCHHWL8tNwTXzHjpViC)Mz
You can reference this value from with the code of your function via ctx.configuration.API_KEY
.
Scheduled execution
Sometimes you need a Fusebit function to execute on a pre-set scheduled cadence, as opposed to in response to a request from your application. The Fusebit cron service enables you to easily set that up. Enabling and configuring scheduled executions can be done in the Fusebit editor by going to Settings
> Schedule
. You can then specify your preferred execution schedule in standard cron format. For example, specifying the following will cause your function to execute every day at 5AM UTC time.
cron=0 5 * * *
If you would like to specify the schedule relative to a different timezone, you can do so as follows (list of timezone identifiers is available here):
timezone=US/Pacific
cron=0 22 * * Fri
The above will cause your function to execute at 10pm every Friday, US Pacific time. To disable scheduled execution, simply clear or comment out the above and hit Save
.
Sometimes you may want to secure a scheduled function so it can only be called by the cron service, and not by an external HTTP request. That is easy to accomplish using the following pattern
module.exports = async (ctx) => {
if (ctx.method !== 'CRON') {
throw new Error('Not authorized');
}
// Code here can only be invoked by cron
};
Custom programming models
In some cases, the default function signature described so far in this document may not be the best fit for your scenario. For example, if the function is being invoked in the context of a lead generation workflow, you may wish to surface a more structured programming interface, for example:
module.exports = (lead) => {
if (lead.value > 5000) {
lead.status = 'VIP';
} else {
throw new Error('Not a VIP!');
}
};
Note how in this example, the generic ctx
context object has been replaced by a more tailored lead
object, and the callback model has been simplified. This can be accomplished in Fusebit following a few easy steps:
-
Create a new file in the Fusebit editor for the specialized interface (let's assume
onNewLead.js
in the above example) -
In the
index.js
file, transform the incoming data and callonNewLead.js
:const onNewLead = require('./onNewLead.js'); module.exports = async (ctx) => { return onNewLead(ctx.body, ctx.configuration); };
-
Since the
index.js
file is no longer relevant to your end users, you can hide it from the Fusebit editor. When calling thecreateEditor
method in your client application, pass the following to theeditor
property:{ "navigationPanel": { "hideFiles": ["index.js"] } }
Updated 19 days ago