NodeJS client

This document illustrates how to use the nodeJS client library to communicate with a Volt via grpc.

Install packages

Two packages are required by nodeJS tdx Volt clients, @tdxvolt/volt-client-grpc and @grpc/grpc-js.

To install the @tdxvolt/volt-client-grpc and @grpc/grpc-js packages:

npm install @tdxvolt/volt-client-grpc @grpc/grpc-js

Configuration

In order to be able to initialise a connection to a Volt, you will need to obtain a client configuration.

How your web application obtains or stores the client configuration is not discussed here, needless to say you need to be careful not to expose keys or other sensitive data. For the purposes of this document, we assume the configuration is stored in a local file.

Initialisation

Begin by creating a tdx Volt client instance:

import grpc from "@grpc/grpc-js";
import { VoltClient } from "@tdxvolt/volt-client-grpc";

const client = new VoltClient(grpc);

Initialise the tdx Volt instance with the configuration JSON:

const configPath = "./volt-config.json";
await client.initialise(configPath);

Once initialised successfully, you can issue any API call.

Refer to the API documentation for details of the method names and corresponding request and response messages. Each API method expects a JSON object representing the request as input, and returns a JSON object as indicated by the response message type. The JSON representation of the protobuf message format is intuitive.

If you see deprecation warnings along the lines of `Setting the TLS ServerName to an IP address is not permitted by RFC 6066` you can safely ignore them for the time being. See also this github issue.

Unary calls

All unary calls return a promise that will either resolve with a JSON response object matching that defined by the API protobuf, or reject if there is a problem with the grpc transport or an error status on the response object.

The example below is a complete snippet showing how we retrieve the immediate descendants of the Volt root resource:

import grpc from "@grpc/grpc-js";
import { VoltClient } from "@tdxvolt/volt-client-grpc";

const configPath = "./volt.config.json";

// Create and initialise the client.
let client = new VoltClient(grpc);
client
  .initialise(configPath)
  .then(() => {
    // Get all resources in our home folder.
    return client.GetResourceDescendants({
      resource_id: client.config.credential.identity_did,
      depth: 1,
    });
  })
  .then((response) => {
    console.log(response);
  })
  .catch((err) => {
    console.error("failure: [%s]", err.message);
  })
  .finally(() => {
    console.log("finished");
  });

Streaming calls

The promise model does not fit well with streaming calls since they are long-lived.

For this reason, all streaming calls (client streaming, server streaming, and bi-directional streaming) return a call object that is used to manage the call.

The call object emits events as interactions with the underlying websocket occur, and there are 3 events of interest:

• “error” emitted when an error occurs on the call
• “data” emitted when a response is received from the Volt
• “end” emitted when the call ends

Below is a complete snippet demonstrating how to subscribe to a wire:

import grpc from "@grpc/grpc-js";
import { VoltClient } from "@tdxvolt/volt-client-grpc";

const configPath = "./volt.config.json";

// Create and initialise the client.
const client = new VoltClient(grpc);
client
  .initialise(configPath)
  .then(() => {
    // Issue a subscription request.
    const sub = client.SubscribeWire({ wire_id: "@wire" });

    // Register to receive 'data' events.
    sub.on("data", (response) => {
      if (response.status) {
        // If the response has a status, then it is an error.
        console.log(`Response error: ${response.status.message}`);
      } else {
        // Received a chunk of data from the wire.
        console.log(Buffer.from(response.chunk, "base64").toString());
      }
    });

    // Register to receive 'error' events.
    sub.on("error", (err) => {
      console.log(err.message);
    });

    // Register to receive 'end' events.
    sub.on("end", () => {
      console.log("subscription ended");
    });
  })
  .catch((err) => {
    console.error("failure: [%s]", err.message);
  });