{"__v":29,"_id":"5724e3fd2ad0bc170012280b","category":{"__v":0,"_id":"5723f854110e570e00486c7a","project":"5723ead0fda3c70e005b88e5","version":"5723eaebeae5090e00ee61f1","sync":{"url":"","isSync":false},"reference":false,"createdAt":"2016-04-30T00:12:04.115Z","from_sync":false,"order":2,"slug":"http-api","title":"Reference"},"parentDoc":null,"project":"5723ead0fda3c70e005b88e5","user":"5723ea8efda3c70e005b88e3","version":{"__v":3,"_id":"5723eaebeae5090e00ee61f1","project":"5723ead0fda3c70e005b88e5","createdAt":"2016-04-29T23:14:51.190Z","releaseDate":"2016-04-29T23:14:51.190Z","categories":["5723eaebeae5090e00ee61f2","5723f854110e570e00486c7a","572a28f6d10a200e00b1cb14"],"is_deprecated":false,"is_hidden":false,"is_beta":true,"is_stable":true,"codename":"","version_clean":"0.1.0","version":"0.1"},"updates":["57899d587a572c0e00120257"],"next":{"pages":[],"description":""},"createdAt":"2016-04-30T16:57:33.619Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"results":{"codes":[]},"settings":"","auth":"required","params":[],"url":""},"isReference":false,"order":3,"body":"[block:callout]\n{\n  \"type\": \"danger\",\n  \"title\": \"Important\",\n  \"body\": \"The Node client is not compatible with browsers. Please use the [HTTP API](doc:http-api) to invoke Lever methods from the browser.\"\n}\n[/block]\nThe Node client library can be used to invoke Lever methods either from within a Lever service or from outside Lever altogether.\n\n# Contents\n\n* [Installation](#section-installation)\n* [Usage example](#section-usage-example)\n* [Class: `leveros.Client`](#section--bookmark-class-leveros-client-)\n* [Class: `Endpoint`](#section--bookmark-class-endpoint-)\n* [Class: `Stream`](#section--bookmark-class-stream-)\n\n# Installation\n\nInstallation for use outside Lever\n\n```bash\n$ npm install leveros\n```\n\nInstallation for use within Lever\n\n```bash\n$ docker run --rm -it --user=root -v \"$PWD\":/leveros/custcode leveros/levercontainer:latest npm install leveros\n```\n\nThe 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.\n\nTo use the library, simply\n\n```javascript\nrequire('leveros');\n```\n\n# Usage example\n\nA simple, intuitive example of how the client can be used to invoke a method is as follows\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"var leveros = require('leveros');\\n\\nvar client = new leveros.Client();\\nvar service = client.service('myenv.example.com', 'myService');\\nservice.invoke(\\n  'myMethod', 'first arg', {another: 'arg', as: 'an object'},\\n  function (error, reply) {\\n    console.log(reply);\\n\\t});\",\n      \"language\": \"javascript\",\n      \"name\": \"client.js\"\n    }\n  ]\n}\n[/block]\nBelow you will find detailed API reference for the client library.\n\n# :bookmark: Class: `leveros.Client`\n\nThis 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.\n\nTo obtain a `leveros.Client`, simply instantiate one with `new leveros.Client()`.\n\n### :new: `constructor()`\n\nCreates a new Lever client.\n\n### :hash: `forceHost` (string)\n\nIf 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`.\n\nTypically 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.\n\nExample\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"var leveros = require('leveros');\\nvar client = new leveros.Client();\\nclient.forceHost = process.env.LEVEROS_IP_PORT;\",\n      \"language\": \"javascript\",\n      \"name\": \"client.js\"\n    }\n  ]\n}\n[/block]\n### :arrow-right: `service(env, service)`\n\n* **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).\n* **service** is the service within environment `env` to connect to.\n*  **returns** `Endpoint`.\n\nReturns an `Endpoint` which can be used to invoke methods belonging to service `service` under environment `env`.\n\n### :arrow-right: `resource(env, service, resource)`\n\n* **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).\n* **service** is the service within environment `env` to connect to.\n* **resource** is the resource being invoked.\n*  **returns** `Endpoint`.\n\nReturns an `Endpoint` which can be used to invoke methods on the resource `resource`, belonging to service `service` under environment `env`.\n\n### :arrow-right: `invokeURL(url, [args...], callback)`\n\n* **url** is the Lever URL of the env/service/method to invoke. The URL can be either absolute or relative.\n* **args...** are the invokation arguments of the method.\n* **callback** is the asynchronous callback of the method.\n\nInvokes a regular (non-streaming) Lever method using a given Lever URL.\n\n### :arrow-right: `invokeChanURL(url, [args...], callback)`\n\n* **url** is the Lever URL of the env/service/method to invoke. The URL can be either absolute or relative.\n* **args...** are the invokation arguments of the method.\n* **callback** is the asynchronous callback of the method.\n\nInvokes a streaming Lever method using a given Lever URL. The `callback`'s reply is an instance of  `Stream` (see below).\n\n# :bookmark: Class: `Endpoint`\n\nAn 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.\n\n### :arrow-right: `invoke(method, [args...], callback)`\n\n* **method** is the Lever method to invoke.\n* **args...** are the invokation arguments of the method.\n* **callback** is the asynchronous callback of the method.\n\nInvokes a regular (non-streaming) Lever method.\n\n### :arrow-right: `invokeChan(method, [args...], callback)`\n\n* **method** is the streaming Lever method to invoke.\n* **args...** are the invokation arguments of the method.\n* **callback** is the asynchronous callback of the method.\n\nInvokes a streaming Lever method. The `callback`'s reply is an instance of  `Stream` (see below).\n\n# :bookmark: Class: `Stream`\n\nAn 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.\n\n### :arrow-lower-right: Event: `data`\n\n* `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.\n\nEmitted when the client receives a message from the service.\n\n### :arrow-lower-right: Event: `end`\n\nEmitted 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.\n\n### :arrow-lower-right: Event: `error`\n\n* `error`. The `Error` received.\n\nEmitted when there is an error with the stream. Either the service has sent an error or there was a problem with the underlying connection.\n\n### :arrow-right: `end()`\n\nEnds 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.\n\n### :arrow-right: `write(message)`\n\nSends a message to the service. The message can be either a serializable JavaScript value or a `Buffer` object.","excerpt":"This page describes the API for the Node client library","slug":"node-client-api","type":"basic","title":"Node Client API"}

Node Client API

This page describes the API for the Node client library

[block:callout] { "type": "danger", "title": "Important", "body": "The Node client is not compatible with browsers. Please use the [HTTP API](doc:http-api) to invoke Lever methods from the browser." } [/block] The Node client library can be used to invoke Lever methods either from within a Lever service or from outside Lever altogether. # Contents * [Installation](#section-installation) * [Usage example](#section-usage-example) * [Class: `leveros.Client`](#section--bookmark-class-leveros-client-) * [Class: `Endpoint`](#section--bookmark-class-endpoint-) * [Class: `Stream`](#section--bookmark-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 [block:code] { "codes": [ { "code": "var leveros = require('leveros');\n\nvar client = new leveros.Client();\nvar service = client.service('myenv.example.com', 'myService');\nservice.invoke(\n 'myMethod', 'first arg', {another: 'arg', as: 'an object'},\n function (error, reply) {\n console.log(reply);\n\t});", "language": "javascript", "name": "client.js" } ] } [/block] Below you will find detailed API reference for the client library. # :bookmark: 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()`. ### :new: `constructor()` Creates a new Lever client. ### :hash: `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 [block:code] { "codes": [ { "code": "var leveros = require('leveros');\nvar client = new leveros.Client();\nclient.forceHost = process.env.LEVEROS_IP_PORT;", "language": "javascript", "name": "client.js" } ] } [/block] ### :arrow-right: `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`. ### :arrow-right: `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`. ### :arrow-right: `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. ### :arrow-right: `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). # :bookmark: 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. ### :arrow-right: `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. ### :arrow-right: `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). # :bookmark: 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. ### :arrow-lower-right: 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. ### :arrow-lower-right: 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. ### :arrow-lower-right: 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. ### :arrow-right: `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. ### :arrow-right: `write(message)` Sends a message to the service. The message can be either a serializable JavaScript value or a `Buffer` object.