Node Client API

This page describes the API for the Node client library

❗️

Important

The Node client is not compatible with browsers. Please use the HTTP API to invoke Lever methods from the browser.

The Node client library can be used to invoke Lever methods either from within a Lever service or from outside Lever altogether.

Contents

• Installation
• Usage example
• Class: leveros.Client
• Class: Endpoint
• Class: Stream

Installation

Installation for use outside Lever

Bash

$ npm install leveros

Installation for use within Lever

Bash

$ docker run --rm -it --user=root -v "$PWD":/leveros/custcode leveros/levercontainer:latest npm install leveros

The installation procedure is special for Lever because the library depends on grpc which contains C++ extensions for node. These need to be compiled on the OS it will run on. As Lever containers are Docker containers (namely containers based on the ubuntu image), the above command installs the library while running in the same container it will run on Lever.

To use the library, simply

JavaScript

require('leveros');

Usage example

A simple, intuitive example of how the client can be used to invoke a method is as follows

client.js

var leveros = require('leveros');

var client = new leveros.Client();
var service = client.service('myenv.example.com', 'myService');
service.invoke(
  'myMethod', 'first arg', {another: 'arg', as: 'an object'},
  function (error, reply) {
    console.log(reply);
	});

Below you will find detailed API reference for the client library.

🔖 Class: leveros.Client

This class represents a Lever client that can be used to invoke Lever methods. The client manages a pool of connections underneath such that repeated invokations to the same environment are efficient.

To obtain a leveros.Client, simply instantiate one with new leveros.Client().

🆕 constructor()

Creates a new Lever client.

#️⃣ forceHost (string)

If different from a falsy value, forceHost property instructs the client to always connect to the given host, regardless of the environment being accessed. This is useful when using the client to access Lever in development, without setting the hostname of Lever to dev.lever or making it listen on port 80.

Typically this property is set to process.env.LEVEROS_IP_PORT, such that the env var will be set when testing in development and unset when used in production.

Example

client.js

var leveros = require('leveros');
var client = new leveros.Client();
client.forceHost = process.env.LEVEROS_IP_PORT;

➡️ service(env, service)

• env is the remote environment to connect to. If env is null, then the same environment as the current service is used (assuming this client is used within a Lever service).
• service is the service within environment env to connect to.
• returns Endpoint.

Returns an Endpoint which can be used to invoke methods belonging to service service under environment env.

➡️ resource(env, service, resource)

• env is the remote environment to connect to. If env is null, then the same environment as the current service is used (assuming this client is used within a Lever service).
• service is the service within environment env to connect to.
• resource is the resource being invoked.
• returns Endpoint.

Returns an Endpoint which can be used to invoke methods on the resource resource, belonging to service service under environment env.

➡️ invokeURL(url, [args...], callback)

• url is the Lever URL of the env/service/method to invoke. The URL can be either absolute or relative.
• args... are the invokation arguments of the method.
• callback is the asynchronous callback of the method.

Invokes a regular (non-streaming) Lever method using a given Lever URL.

➡️ invokeChanURL(url, [args...], callback)

• url is the Lever URL of the env/service/method to invoke. The URL can be either absolute or relative.
• args... are the invokation arguments of the method.
• callback is the asynchronous callback of the method.

Invokes a streaming Lever method using a given Lever URL. The callback's reply is an instance of Stream (see below).

🔖 Class: Endpoint

An instance of Endpoint is returned when calling Client.service(...) or Client.resource(...). Endpoint can be used to invoke Lever methods within the context provided when calling the above functions.

➡️ invoke(method, [args...], callback)

• method is the Lever method to invoke.
• args... are the invokation arguments of the method.
• callback is the asynchronous callback of the method.

Invokes a regular (non-streaming) Lever method.

➡️ invokeChan(method, [args...], callback)

• method is the streaming Lever method to invoke.
• args... are the invokation arguments of the method.
• callback is the asynchronous callback of the method.

Invokes a streaming Lever method. The callback's reply is an instance of Stream (see below).

🔖 Class: Stream

An instance of the Stream class is passed as the reply (second) parameter to streaming method callbacks. It is used to send and receive messages to/from the service.

↘️ Event: data

• message. If the message is of type JSON, then this will be the decoded message. If the message if of type bytes, then this will be a instance of Buffer containing the bytes.

Emitted when the client receives a message from the service.

↘️ Event: end

Emitted when the service closes its end of the stream. The client can no longer send or receive messages to/from the service as part of the invokation at this point.

↘️ Event: error

• error. The Error received.

Emitted when there is an error with the stream. Either the service has sent an error or there was a problem with the underlying connection.

➡️ end()

Ends the sending part of the invokation. After this method is called, the client can no longer send messages, but it can continue to receive from the service.

➡️ write(message)

Sends a message to the service. The message can be either a serializable JavaScript value or a Buffer object.