{"__v":42,"_id":"5724e45cfda3c70e005b89c6","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":["57899d797a572c0e00120258"],"next":{"pages":[],"description":""},"createdAt":"2016-04-30T16:59:08.674Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"results":{"codes":[]},"settings":"","auth":"required","params":[],"url":""},"isReference":false,"order":4,"body":"# Contents\n\n* [Installation](#section-installation)\n* [Using third-party libraries](#section-using-third-party-libraries)\n* [Defining regular (non-streaming) methods](#section-defining-regular-non-streaming-methods)\n* [Defining streaming methods](#section-defining-streaming-methods)\n* [Class: `Stream`](#section--bookmark-class-stream-)\n\n# Installation\n\nIn order to build Node-based Lever services, there is no need to install any external library. You simply define a JavaScript module which exports the methods that you want to expose as part of the service's API. The methods are simply JavaScript functions which are called whenever the respective methods are invoked.\n\nMethods that start with `_` are considered internal (even if they are exported by the module) and are ignored by Lever.\n\nTo use Node as the method handler, set the `jsEntry` property in `lever.json` to the name of the module where the methods are implemented. Example\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n  \\\"name\\\": \\\"exampleService\\\",\\n  \\\"jsEntry\\\": \\\"service.js\\\"\\n}\",\n      \"language\": \"json\",\n      \"name\": \"lever.json\"\n    }\n  ]\n}\n[/block]\n# Using third-party libraries\n\nYou are free to use any third-party JavaScript library as part of your service implementation. If the libraries contain non-JavaScript sources (such as C++ Node bindings, it recommended to install the dependencies in a Lever container before deploying the service (along with `node_modules`) onto Lever. To achieve this, use the following (rather than the usual `npm install`).\n\n```bash\n$ docker run --rm -it --user=root -v \"$PWD\":/leveros/custcode leveros/levercontainer:latest npm install\n```\n\nAn example of a library that requires this procedure is our own [`leveros` client library](doc:node-client-api).\n\n# Defining regular (non-streaming) methods\n\nFor non-streaming methods, the signature of each function is\n\n:arrow-right: `module.exports.<method> = function ([resource], [args...], callback)`\n\nWhere\n\n* **<method>** is the name of the method.\n* **resource** is a string representing the name of the resource invoked, if any. This argument is not provided if the resource is not set or is `\"\"`.\n* **args...** are the individual invokation arguments of the method. If the method takes JSON args, then each arg will be available here, in decoded form. If the method takes byte args, then a single arg, of type `Buffer` will be provided.\n* **callback** is the invokation async callback that needs to be called to send back a response (or an error).\n\nA very basic example of such a method is as follows.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"module.exports.sayHello = function (arg1, arg2, callback) {\\n  callback(null, \\\"Method invoked with args \\\" + arg1 + \\\" and \\\" + arg2 + \\\".\\\");\\n};\",\n      \"language\": \"javascript\",\n      \"name\": \"service.js\"\n    },\n    {\n      \"code\": \"{\\n  \\\"name\\\": \\\"exampleService\\\",\\n  \\\"jsEntry\\\": \\\"service.js\\\"\\n}\",\n      \"language\": \"json\",\n      \"name\": \"lever.json\"\n    }\n  ]\n}\n[/block]\n# Defining streaming methods\n\nFor streaming methods, the signature of each function is\n\n:arrow-right: `module.exports.<method> = function (stream, [resource], [args...])`\n\nWhere\n\n* **<method>** is the name of the method. For streaming methods, the name **must** end with `Chan` or `_chan`.\n* **stream** is an instance of a `Stream` object (see below). This object is used to communicate with the client.\n* **resource** is a string representing the name of the resource invoked, if any. This argument is not provided if the resource is not set or is `\"\"`.\n* **args...** are the individual invokation arguments of the method. If the method takes JSON args, then each arg will be available here, in decoded form. If the method takes byte args, then a single arg, of type `Buffer` is provided.\n\nA very basic example of such a method is as follows.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"module.exports.helloChan = function (stream, salutation) {\\n  // This is invoked on errors.\\n  stream.on('error', function (error) {\\n    console.log(error);\\n    stream.end();\\n  });\\n  // This is invoked on each message received from the client.\\n  stream.on('data', function (msg) {\\n    stream.write(salutation + \\\", \\\" + msg.name + \\\"!\\\");\\n  });\\n  // This is invoked when the client stops sending.\\n  stream.on('end', function () {\\n    stream.end();\\n  });\\n};\",\n      \"language\": \"javascript\",\n      \"name\": \"service.js\"\n    },\n    {\n      \"code\": \"{\\n  \\\"name\\\": \\\"exampleService\\\",\\n  \\\"jsEntry\\\": \\\"service.js\\\"\\n}\",\n      \"language\": \"json\",\n      \"name\": \"lever.json\"\n    }\n  ]\n}\n[/block]\n# :bookmark: Class: `Stream`\n\nAn instance of the `Stream` class is passed as the first parameter to streaming method handlers. It is used to send and receive messages to/from the client.\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 server receives a message from the client.\n\n### :arrow-lower-right: Event: `end`\n\nEmitted when the client closes its end of the stream. Even though the client will no longer send messages, the server may yet continue to send messages for the client to consume.\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 client has sent an error or there was a problem with the underlying connection.\n\n### :arrow-right: `end()`\n\nEnds the invokation. After this method is called, the server will no longer send or receive messages to/from the client.\n\n### :arrow-right: `write(message)`\n\nSends a message to the client. The message can be either a serializable JavaScript value or a `Buffer` object.","excerpt":"This page describes the API for building Node-based services","slug":"node-server-api","type":"basic","title":"Node Server API"}

Node Server API

This page describes the API for building Node-based services

# Contents * [Installation](#section-installation) * [Using third-party libraries](#section-using-third-party-libraries) * [Defining regular (non-streaming) methods](#section-defining-regular-non-streaming-methods) * [Defining streaming methods](#section-defining-streaming-methods) * [Class: `Stream`](#section--bookmark-class-stream-) # Installation In order to build Node-based Lever services, there is no need to install any external library. You simply define a JavaScript module which exports the methods that you want to expose as part of the service's API. The methods are simply JavaScript functions which are called whenever the respective methods are invoked. Methods that start with `_` are considered internal (even if they are exported by the module) and are ignored by Lever. To use Node as the method handler, set the `jsEntry` property in `lever.json` to the name of the module where the methods are implemented. Example [block:code] { "codes": [ { "code": "{\n \"name\": \"exampleService\",\n \"jsEntry\": \"service.js\"\n}", "language": "json", "name": "lever.json" } ] } [/block] # Using third-party libraries You are free to use any third-party JavaScript library as part of your service implementation. If the libraries contain non-JavaScript sources (such as C++ Node bindings, it recommended to install the dependencies in a Lever container before deploying the service (along with `node_modules`) onto Lever. To achieve this, use the following (rather than the usual `npm install`). ```bash $ docker run --rm -it --user=root -v "$PWD":/leveros/custcode leveros/levercontainer:latest npm install ``` An example of a library that requires this procedure is our own [`leveros` client library](doc:node-client-api). # Defining regular (non-streaming) methods For non-streaming methods, the signature of each function is :arrow-right: `module.exports.<method> = function ([resource], [args...], callback)` Where * **<method>** is the name of the method. * **resource** is a string representing the name of the resource invoked, if any. This argument is not provided if the resource is not set or is `""`. * **args...** are the individual invokation arguments of the method. If the method takes JSON args, then each arg will be available here, in decoded form. If the method takes byte args, then a single arg, of type `Buffer` will be provided. * **callback** is the invokation async callback that needs to be called to send back a response (or an error). A very basic example of such a method is as follows. [block:code] { "codes": [ { "code": "module.exports.sayHello = function (arg1, arg2, callback) {\n callback(null, \"Method invoked with args \" + arg1 + \" and \" + arg2 + \".\");\n};", "language": "javascript", "name": "service.js" }, { "code": "{\n \"name\": \"exampleService\",\n \"jsEntry\": \"service.js\"\n}", "language": "json", "name": "lever.json" } ] } [/block] # Defining streaming methods For streaming methods, the signature of each function is :arrow-right: `module.exports.<method> = function (stream, [resource], [args...])` Where * **<method>** is the name of the method. For streaming methods, the name **must** end with `Chan` or `_chan`. * **stream** is an instance of a `Stream` object (see below). This object is used to communicate with the client. * **resource** is a string representing the name of the resource invoked, if any. This argument is not provided if the resource is not set or is `""`. * **args...** are the individual invokation arguments of the method. If the method takes JSON args, then each arg will be available here, in decoded form. If the method takes byte args, then a single arg, of type `Buffer` is provided. A very basic example of such a method is as follows. [block:code] { "codes": [ { "code": "module.exports.helloChan = function (stream, salutation) {\n // This is invoked on errors.\n stream.on('error', function (error) {\n console.log(error);\n stream.end();\n });\n // This is invoked on each message received from the client.\n stream.on('data', function (msg) {\n stream.write(salutation + \", \" + msg.name + \"!\");\n });\n // This is invoked when the client stops sending.\n stream.on('end', function () {\n stream.end();\n });\n};", "language": "javascript", "name": "service.js" }, { "code": "{\n \"name\": \"exampleService\",\n \"jsEntry\": \"service.js\"\n}", "language": "json", "name": "lever.json" } ] } [/block] # :bookmark: Class: `Stream` An instance of the `Stream` class is passed as the first parameter to streaming method handlers. It is used to send and receive messages to/from the client. ### :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 server receives a message from the client. ### :arrow-lower-right: Event: `end` Emitted when the client closes its end of the stream. Even though the client will no longer send messages, the server may yet continue to send messages for the client to consume. ### :arrow-lower-right: Event: `error` * `error`. The `Error` received. Emitted when there is an error with the stream. Either the client has sent an error or there was a problem with the underlying connection. ### :arrow-right: `end()` Ends the invokation. After this method is called, the server will no longer send or receive messages to/from the client. ### :arrow-right: `write(message)` Sends a message to the client. The message can be either a serializable JavaScript value or a `Buffer` object.