From ab97fa72876ffe0ee4381aeb5449262e839a25ce Mon Sep 17 00:00:00 2001 From: Max Fang Date: Thu, 3 Aug 2017 16:18:15 -0700 Subject: [PATCH] docs: Javascript gRPC streaming examples & complete guide --- docs/grpc/javascript.md | 132 +++++++++++++++++++++++++++++++--------- 1 file changed, 104 insertions(+), 28 deletions(-) diff --git a/docs/grpc/javascript.md b/docs/grpc/javascript.md index fbbd979c..c37b0266 100644 --- a/docs/grpc/javascript.md +++ b/docs/grpc/javascript.md @@ -1,13 +1,13 @@ # How to write a simple `lnd` client in Javascript using `node.js` -First, you'll need to initialize a simple nodejs project: +### Setup and Installation +First, you'll need to initialize a simple nodejs project: ``` npm init (or npm init -f if you want to use the default values without prompt) ``` Then you need to install the Javascript grpc library dependency: - ``` npm install grpc --save ``` @@ -18,35 +18,34 @@ at least somewhere reachable by your Javascript code). The `rpc.proto` file is [located in the `lnrpc` directory of the `lnd` sources](https://github.com/lightningnetwork/lnd/blob/master/lnrpc/rpc.proto). -In order to allow the auto code generated to compile the protos succucsfully, +In order to allow the auto code generated to compile the protos successfully, you'll need to comment out the following line: ``` //import "google/api/annotations.proto"; ``` -Let's now write some Javascript code that simply displays the `getinfo` command -result on the console: +#### Imports and Client + +Every time you work with Javascript gRPC, you will have to import `grpc`, load +`rpc.proto`, and create a connection to your client like so: ```js var grpc = require('grpc'); - var lnrpcDescriptor = grpc.load("rpc.proto"); - var lnrpc = lnrpcDescriptor.lnrpc; - var lightning = new lnrpc.Lightning('localhost:10009', grpc.credentials.createInsecure()); - -lightning.getInfo({}, function(err, response) { - console.log('GetInfo:', response); -}); - ``` -You just have to lauch your newly created Javascript file `getinfo.js` using -`nodejs`: +### Examples -``` -node getinfo.js +Let's walk through some examples of Javascript gRPC clients. + +#### Simple RPC + +```js +> lightning.getInfo({}, function(err, response) { + console.log('GetInfo:', response); + }); ``` You should get something like this in your console: @@ -55,19 +54,96 @@ You should get something like this in your console: GetInfo: { identity_pubkey: '03c892e3f3f077ea1e381c081abb36491a2502bc43ed37ffb82e264224f325ff27', alias: '', num_pending_channels: 0, - num_active_channels: 0, - num_peers: 0, - block_height: 1087612, - block_hash: '000000000000024b2acc37958b15010057c6abc0a48f83c8dd67034bee2cb823', - synced_to_chain: true, - testnet: true } + num_active_channels: 1, + num_peers: 1, + block_height: 1006, + block_hash: '198ba1dc43b4190e507fa5c7aea07a74ec0009a9ab308e1736dbdab5c767ff8e', + synced_to_chain: false, + testnet: false, + chains: [ 'bitcoin' ] } ``` +#### Response-streaming RPC + +```js +var call = lightning.subscribeInvoices({}); +call.on('data', function(invoice) { + console.log(invoice); +}) +.on('end', function() { + // The server has finished sending +}) +.on('status', function(status) { + // Process status + console.log("Current status" + status); +}); +``` +Now, create an invoice for your node at `localhost:10009` and send a payment to +it. Your Javascript console should display the details of the recently satisfied +invoice. + +#### Bidirectional-streaming RPC + +This example has a few dependencies: +```shell +npm install --save async lodash bytebuffer +``` + +You can run the following in your shell or put it in a program and run it like +`node script.js` + +```js +// Load some libraries specific to this example +var async = require('async'); +var _ = require('lodash'); +var ByteBuffer = require('bytebuffer'); + +var dest_pubkey = ; +var dest_pubkey_bytes = ByteBuffer.fromHex(dest_pubkey); + +// Set a listener on the bidirectional stream +var call = lightning.sendPayment(); +call.on('data', function(payment) { + console.log("Payment sent:"); + console.log(payment); +}); +call.on('end', function() { + // The server has finished + console.log("END"); +}); + +// You can send single payments like this +call.write({ dest: dest_pubkey_bytes, amt: 6969 }); + +// Or send a bunch of them like this +function paymentSender(destination, amount) { + return function(callback) { + console.log("Sending " + amount + " satoshis"); + console.log("To: " + destination); + call.write({ + dest: destination, + amt: amount + }); + _.delay(callback, 2000); + }; +} +var payment_senders = []; +for (var i = 0; i < 10; i++) { + payment_senders[i] = paymentSender(dest_pubkey_bytes, 100); +} +async.series(payment_senders, function() { + call.end(); +}); + +``` +This example will send a payment of 100 satoshis every 2 seconds. + +### Conclusion + With the above, you should have all the `lnd` related `gRPC` dependencies -installed locally in your local project. In order to get up to speed with -`protofbuf` usage from Javascript, see [this official `protobuf` reference for +installed locally in your project. In order to get up to speed with `protofbuf` +usage from Javascript, see [this official `protobuf` reference for Javascript](https://developers.google.com/protocol-buffers/docs/reference/javascript-generated). Additionally, [this official gRPC -resource](http://www.grpc.io/docs/tutorials/basic/node.html) details how to -drive `gRPC` from `node.js` including the basics of making RPC calls, streaming -RPC's (bi-directional and uni-directional), etc. +resource](http://www.grpc.io/docs/tutorials/basic/node.html) provides more +details around how to drive `gRPC` from `node.js`.