Split up configuration into introduce configuration that only add/updates things and a clearConfig / cleanup that removes everything that exists.

Generic handler

handler(function(event, [context], callback){}) (or λ(...))

Arguments:

• function(event, [context], callback) - hander function. Function accepts following arguments:
  • event - any type - event payload,
  • context (optional) - object - additional info
  • callback - function - callback function result callback(err, result).

const stdlib = require('@serverless/stdlib')();

exports.userFunc = stdlib.handler((event, callback) => {
  callback(new Error('not implemented'))  
});

Notes

• Ad #14 (comment) @dougmoscrop for now we will start with callback. I would like to have promise based version but we will start minimal.

• Ad #14 (comment) @ac360 context from global object is doable in AWS Lambda (because there is one execution per container). I'm not sure how this thing looks in GCF, Azure and IBM but it wouldn't assume that's true. So it's safer to have context object as a optional argument. Let me know what's your thoughts here.

If you are writing truly portable functions, then wouldn't an optional argument require writing logic at the beginning of every function to check if context was passed in?

Nope. Before calling user function we can check how many arguments it accepts and based on that we can pass 2 or 3 args.

exports.userFunc = stdlib.handler((event, callback) => {
  callback(new Error('not implemented'))  
});

exports.userFunc = stdlib.handler((event, context, callback) => {
  callback(new Error('not implemented'))  
});

Both will work. No need to do if.

Serverless framework already support different event sources (S3, APIG). Instead of explicitly calling callAsync it would be more flexible to provide a way to emit events (from within function) that other function can treat as an event source.

Example

serverless.yml:

functions:
  sendWelcomeEmail:
    events:
      - function: userCreated

Function sendWelcomeEmail is async called every time userCreated event is emitted from functions in the same service.

userCreate.js:

sdk.emit('userCreated', '[email protected]');

Optionally more advanced event source object can be defined:

functions:
  sendWelcomeEmail:
    events:
      - function:
        event: userCreated
        function: create # listen to userCreated events only emitted by create function

Possible enhancements

• enable minification
• direct imports of Ramda functions or replace Ramda
• replace isomorphic fetch with github's fetch polyfill

https://github.com/openwhisk/openwhisk-client-js has a method for invoking other functions so we can implement it using that.

Few questions:

• how to distinguish AWS Lambda from OpenWhisk? The most reliable way is to check if there is __OW_NAMESPACE env (or any other specific to OW).
• is https://github.com/openwhisk/openwhisk-client-js included by default in environment?

CC @jthomas

We could simplify the initializing and rename it.

If a SERVERLESS_APPLICATION_TOKEN environment variable is present, then it should be submitted as a header of the form Authorization: bearer <token> on any requests to the event gateway.

To provide users with an easy way to track if something is a cold start we should provide a stable SDK method they can use.

sdk.isColdStart()

will return true the first time and false for any other invocations in that same deployed lambda.

Goals:

• Create a single function handler for synchronous and asynchronous functions that works across all providers.
• Offer a better user experience.

Right now we pass the error messages to configure and console.log them. The result is that no info is printed. Instead we should get out the message from the errors.

It's not actually SDK.

Propositions:

• stdlib - require('@serverless/stdlib')
• lib - require('@serverless/lib')

cc @serverless/team

I want to unsubscribe an http event with the subscriptionId http-GET-%2Fhello.

Unfortunately I get the following error message back:

Error: Failed to unsubscribe the subscription http-GET-%2Fhello and couldn't parse error body.

Special characters like %2F are not problem for the Event Gateway (according to @mthenw). My assumption is that the fetch call translates %2F into / so that the requests here is translated to /v1/subscriptions/http-GET-/hello which erros out because the path is not valid on the event gateways side.

Almost the same as sync call method:

sdk.trigger('sendWelcomeEmail', '[email protected]', callback)

trigger(name, args, callback)

Parameters:

• name - string|array - function name(s)
• args - any type - arguments to pass to called function
• callback - function - takes err and result. callback parameter informs if trigger has been successfully submitted. It doesn't mean that function has been called.

Currently there is no way to provide configurable retry logic. It's worth to read how it's solved in AWS (http://docs.aws.amazon.com/lambda/latest/dg/retries-on-errors.html).

Implement SDK.call method that takes the name of a function and invokes that function through the AWS SDK

Handler (#15) should also expose context object. context should provide a way to get runtime information (in some cases they can be request/event bounded).

API proposition:

• isColdStart
• provider
• memoryLimit
• getCurrentDuration()

I'm not sure if we should provide methods or fields. Things like memory or provider are pretty static. No need to provide getter for them.

• Link to the event gateway
• restructure to optimze for newcomers

PR #52

• create a handful tests with various functions and subscriptions

1. The primary exports of the library are stdlib().handler() and stdlib.call(). In one of these, there is a function invocation stdlib(), and in the other a singleton object reference stdlib. This inconsistency does not clearly communicate anything semantic.
   
   It would be better for stdlib always to be used as a static/singleton container for stdlib methods, with the functionality now served by stdlib() as a method call being moved into a method within the stdlib namespace. @mthenw suggests stdlib.use()

2. The term call is inconsistent with the CLI and other documented features of the framework which use the term invoke to describe the same operation. We ought to rename this method.

The FDK should work equivalently in back-end and front-end applications. The test suite currently runs within the node runtime, but should also cover headless Chrome usage to ensure isomorphic operation.

Right now the plan is to follow callback pattern. We might want to provide a way to return promise from each method or even make them promise-based only.

cc @nikgraf @eahefnawy @pmuens

The current spec outlines the emit function signature as the following

gateway.emit({
  event: "userCreated",
  data: JSON.stringify({ name: "Austen" }),
})

This verbose signature is good as there are additional properties we may want to add like the meta property etc as the gateway matures. serverless/event-gateway#179

However, it may be nice to offer a shorthand signature in some cases where all you're doing is sending events with some simple data payload.

gateway.emit('some.event.type', {
  'i': 'am data'
})

Having a "standard" function handler for serverless function provides following benefits:

• no need to change code when deploying function to different providers,
• providing common logic (like e.g. decrypting secrets from KMS),
• keeping things simple.

Research

AWS Lambda

One type of function handler:

exports.myHandler = function(event, context, callback) {
   ...
}

• event – AWS Lambda uses this parameter to pass in event data to the handler.
• context – AWS Lambda uses this parameter to provide your handler the runtime information of the Lambda function that is executing. For more information, see The Context Object (Node.js).
• callback – You can use the optional callback to return information to the caller, otherwise return value is null. For more information, see Using the Callback Parameter.

In case of API Gateway event specified structure and specified structure is expected in callback.

http://docs.aws.amazon.com/lambda/latest/dg/nodejs-prog-model-handler.html

Google Cloud Functions

Two types of function handler, one for HTTP functions, another for background functions. HTTP function handler accepts express-like arguments (req & res).

exports.helloHttp = function helloHttp (req, res) {
  res.send(`Hello ${req.body.name || 'World'}!`);
};

https://cloud.google.com/functions/docs/writing/http

Background function handler accepts event and callback arguments.

exports.helloBackground = function helloBackground (event, callback) {
  callback(null, `Hello ${event.data.name || 'World'}!`);
};

https://cloud.google.com/functions/docs/writing/background

Azure Function

One type of function handler:

module.exports = function(context) {
    // function logic goes here :)
};

context object differes between regular functions and functions triggered by HTTP request.

In case of regular functions context object has a bindings property with myInput & myOutput which can be used for getting input args and setting result.

In case of HTTP func there are req & res objects under context.

https://docs.microsoft.com/en-us/azure/azure-functions/functions-reference-node

Proposition

We should provide two handlers. One generic handler and one for HTTP triggered functions.

Generic handler

In case of generic handler I would follow AWS Lambda definition. But as we want to abstract provider specific stuff, context object would be different that context object from AWS Lambda. Still, raw AWS Lambda context object should be accessible under e.g. AWSContext key in stdlib's context. As context object in most case it not needed in handler logic (and it doesn't occur in GCF) it's an optional argument.

handler(function(event, [context], callback){}) (or λ(...))

Arguments:

• function(event, [context], callback) - hander function. Function accepts following arguments:
  • event - any type - event payload,
  • context (optional) - object - additional info
  • callback - function - callback function result callback(err, result).

const stdlib = require('@serverless/stdlib')();

exports.userFunc = stdlib.handler((event, context, callback) => {
  callback(new Error('not implemented'))  
});

// or

exports.userFunc = stdlib.λ((event, context, callback) => {
  callback(new Error('not implemented'))
});

HTTP handler

http is a handler for HTTP triggered functions. This handler takes function that accepts two arguments (express-like req & res)

http(function(event, [context], callback){})

Arguments:

• function(req, res) - HTTP hander function. Function accepts following arguments:
  • req - express Request object
  • res - express Response object

Example:

const stdlib = require('@serverless/stdlib')();

exports.userFunc = stdlib.http((req, res) => {
  res.status(200).end();
});

cc @nikgraf @pmuens @ac360 @eahefnawy @DavidWells

call method should allow calling multiple functions at the same time. name parameter should accept both string and array (similar to async.paralell).

Example:

sdk.call([‘validateEmail’, ‘validateName’], user, function (err, results) {})

In case of calling multiple functions callback results object has keys corresponding to names of called functions.

Example:

sdk.call([‘validateEmail’, ‘validateName’], user, function (err, result) {
// result == {validateEmail: true, validateName: false}
})

In case of error in one of the functions err is returned and calls to other functions are discarded.

The documentation mentions that subscribe method should return an object in the following format { subscriptionId, event, functionId}. But it doesn't atm.

Would be nice if some of the naming was less verbose and kept a bit more simple.
createEventGatewayClient -> gateway
createSubscription -> subscribe
removeSubscription -> unsubscribe

It hasn't been done with #2.

Function call has to accept optional options object with timeout.