User Guide

Understanding the Eventnplatform

Introduction


Eventn is a cloud platform that lets companies rapidly build and scale serverless HTTP microservices. New microservices can be created with a single click or API call and each microservice provides all of the required components needed to support advanced data-driven and analytical use cases.

Anatomy of a Microservice

Each microservice provides the following components:

  • A secure, internet facing REST resource accessible athttps://service.eventn.com/[--service-name--]
  • A sandboxed JavaScript GET function that is executed by making an HTTP GET request
  • A sandboxed JavaScript POST function executed by making an HTTP POST request
  • A MySQL datastoretable used for data persistence

Node.js Version

The Eventn platform currently supports Node.js v8.2.1.

Architecture


Eventn is hosted using Amazon's EC2 service utilizing High Availability through multiple AWS geographic regions and multiple Availability Zones. The Eventn platform elastically scales to support changing workloads automatically.

API Overview


The Eventn API exclusively supports JSON for all requests and responses.

Separation Of Concerns

It is important to note that each microservice is accessed using a different API URI depending upon the required action:

URIPurpose
api.eventn.comUsed for service management i.e. service creation, JavaScript function updates etc.
service.eventn.comUsed for service execution i.e. sending data to the service or receiving analytics from the service.
For all service management tasks,api.eventn.comis used and for service execution (sending data to and receiving data from the service)service.eventn.comis used. Likewise, authentication is also separated. Whereas authenticating againstapi.eventn.comuses an expiring token that must be re-generated,service.eventn.comuses a static token that is generated once along with the service. Read more about authentication.

Program Model


Service Function Execution

Each microservice provides an asynchronousPOSTfunction and a synchronousGETfunction. These functions are executed by initiating an HTTP request using their respective methods. This environment provides freedom to not only use all JavaScript features, but also ECMAScript 2015 (ES6) features available in Node.js (v7.x). Additionally, Eventn also supports a set of selected NPM modules.

It is worth noting that the response behavior of each request type differs. When making an HTTPPOSTrequest with an associated data payload, requests are queued and a success message returned immediately. ForGETrequests, the HTTP request connection is kept open until the service execution is complete.

GET Function

To execute the GET function for a specific service, invoke an HTTP GET request toservice.eventn.com/{SERVICE_NAME}. For example:

curl -H "Content-Type: application/json" \
-H "Authorization: Bearer {SERVICE_TOKEN}" \
https://service.eventn.com/{SERVICE_NAME}

POST Function

To execute the POST function for a specific service, invoke an HTTP POST request toservice.eventn.com/{SERVICE_NAME}. For example:

curl -H "Content-Type: application/json" \
-H "Authorization: Bearer 2630feb6-dc1a-4c8d-a7b1-b6a2bf0a248f" \
-X POST -d '{"Hello":"World"}' \
https://service.eventn.com/{SERVICE_ID}

Function Limits

  • Timeouts -POSTandGETfunctions must execute within 10 seconds or a timeout will occur and an error will be logged.

Function Patterns

Service functions support a promise interface for cleaner async flow control. Functions must:

  • Assign a function tomodule.exportsexporting a function (a named function will deliver a more useful stack trace)
  • Return a promise or any value other thanundefined

Promise Example

module.exports = function onGet(context, request) {
   return Promise.resolve("foo");
}

Function Arguments

A service will be called withcontextandrequestarguments.

Context

The context argument is an object containing functions or statics provided by the Eventn platform.

  • context.stores- an object containing any database connections. See Store Adapters
  • context.id- a shorthand helper to reference the service name

Request

The request argument is an object containing properties of therequestand is used to reference the following objects:

request.payload

An object containing the parsed JSON sent via HTTP POST (empty for GET). For example, consider a POST request with the following body payload:

{
  "foo": {
    "bar": 123
  }
}
The value ofbarwould be accessed using:request.payload.foo.bar.

request.query

An object containing the query parameters of a request. For example, consider a GET request:

https://service.eventn.com/{service_id}?foo=1
The value offoowould be accessed using:request.query.foo.

Default Functions

Once a service has been created (by sending an HTTPPOST request tohttps://api.eventn.com/service), default functions are created for both GET and POST as follows:

GET Function

The default GET function simply returns the number of rows within the service data store, executing the SQLselect count(*) FROM STORE;

function onGet(context) {
    return context.stores.default().table().count();
}

module.exports = onGet;

POST Function

The default POST function inserts the POST payload in to the data store.

function onPost(context, request) {
  return context.stores
    .default()
    .table()
    .insert({ data: JSON.stringify(request.payload) });
}

module.exports = onPost;

NPM Modules

Eventn supports a subset of NPM modules selected for analytical and data processing use cases. NPM modules are referenced within functions as expected usingrequire, for example:

const ss = require("simple-statistics");
function onGet(context) {
    return ss.variance([1,2,3,4,5]);
}
module.exports = onGet;

The below NPM modules are available for use. Please contact us to add support for additional modules.


Database Persistence


Eventn supports two types of database persistence: remote and local:

  • Remote Database - connect to any PostgreSQL, MS SQL, MariaDB or MySQL database.
  • Local Database - low latency, MySQL backed Eventn data store. A table is automatically created and securely associated with every service.

Store Adapters

Thecontext.storesobject contains store adapter functions that are used to connect to a database. These functions hold the connection details to a database and can be referenced from within a microservice. To connect to a remote database simple create a new store function (POSTtohttps://api.eventn.com/store). See Accessing A Remote Database below for an example.

Knex Query Builder

Eventn embeds the Knex SQL query builder. The Knex query builder is the interface used for building and executing standard SQL queries, such asSELECT,INSERTandUPDATE. A store adapter function returns the Knex interface.

Remote Database Stores

Eventn currently supports the following store adapter types:

  • MySQL (and compatible e.g. MemSQL)
  • PostgreSQL
  • MariaDB
  • Microsoft SQL Server

Accessing A Remote Database

To create a remote database connection simply create a newstore adapterfunction by making aPOSTrequest tohttps://api.eventn.com/store. As part of this request, anameproperty is specified e.g. "foo". Upon success, thecontext.stores.foo()function is then available for use from any microservice.

Creating A Store Adapter

Make aPOSTrequest tohttps://api.eventn.com/store. The following is an example POST body containing the connection details to a MySQL database:

{
  "adapter_type": "mysql",
  "name": "warehouse",
  "default_table": "sales",
  "connection_string": "mysql://db_user:password@myhost:3306/demo"
}

An example CURL request:

curl -H "Content-Type: application/json" \
-H "Authorization: Bearer [VALID_TOKEN]" \
-X POST -d '{ "adapter_type": "mysql", "name": "warehouse", "default_table": "sales", "connection_string": "mysql://db_user:password@myhost:3306/demo"}' /
https://api.eventn.com/store

Read more aboutPOST /storewithin the API Reference documentation.

Store Adapter Usage

The store adapter function can then be used within any Eventn microservice to access one or more databases. Simply reference the function using thenameproperty specified when creating the store. In the example above we used "warehouse". Thewarehouse()function can then be called specifying a table name:

return context.stores.warehouse("sales").count();

Accessing Query Builder and DB Interfaces

When a store adapter function is called with a table name (as shown above), the Knex query builder interface is returned. Alternatively, if the table name is omitted from the store function, the top-level Knex DB interface is returned. This provides flexibility to call any top-level methods such as.raw():

return context.stores.warehouse().raw('select count(*) from sales');

Default Table

Each store adapter function also supports an optional default table. This is simply a shorthand way to reference a pre-defined table. To set a default table, include thedefault_tablekey/value when creating the store function i.e. callingPOST /store. See the API Reference for further details. The default table can then be used by calling thetable()method as follows:

return context.stores.warehouse().table().select();

Local Stores

Eventn provides an optional, inbuilt MySQL database offering support for JSON, geospatial as well as relational data types. When a new microservice is created, an associated MySQL user and table is automatically generated with the appropriate secure permissions granted.

Accessing A Local Database

To access the local service table, each service automatically provides adefault()store adapter function. This is simply a shorthand way to reference the table and is used in conjunction with thetable()method:

return context.stores.default().table().count();

Alternatively the function name can also be used when calling thedefault()store adapter function. Note the table name is the same as the service name:

return context.stores.default("SV_PK7C2MTLC").count();

Default Table

MySQL Version

The Eventn platform currently supports MySQL v5.7.11.

Default Schema

Upon service creation, a default data store is automatically created. Each store has the following default schema:

ColumnTypeDefault ValueNullablePrivileges
idBIGINT(10)-NOselect,insert,update
ts_createdtimestampCURRENT_TIMESTAMPNOselect,insert,update
dataJSON-NOselect,insert,update