@tdxvolt/volt-client-grpc 0.1.0

package/src/volt-client.js

@@ -0,0 +1,491 @@
+import debug from "debug";
+import EventEmitter from "events";
+import {VoltCrypto} from "./volt-crypto.js";
+import path from "path";
+import {getServiceDescriptors} from "./proto-utils.js";
+import {createClient as createGrpcClient} from "./grpc-utils.js";
+import {
+  bindInternal,
+  connectInternal,
+  fetchVoltConfig,
+  getVoltAPIClientInternal,
+  unaryCall,
+} from "./volt-client-internal.js";
+import fs from "fs";
+import GRPCCall from "./grpc-call.js";
+
+const {readFile} = fs.promises;
+const log = debug("volt-client-grpc:volt-client");
+
+export class VoltClient extends EventEmitter {
+  /**
+   * @param {object} grpc - an instance of the grpc module (see https://www.npmjs.com/package/grpc)
+   */
+  constructor(grpc) {
+    super();
+
+    if (!grpc) {
+      throw new Error("invalid arguments, grpc is required");
+    }
+    this._grpc = grpc;
+    this._cachedClient = null;
+    this._cachedRemoteClient = null;
+    this._session = null;
+    this._config = null;
+    this._options = null;
+    this._voltConnection = null;
+  }
+
+  get config() {
+    return this._config;
+  }
+
+  get crypto() {
+    return this._crypto;
+  }
+
+  get grpc() {
+    return this._grpc;
+  }
+
+  get options() {
+    return this._options;
+  }
+
+  /**
+   * Initialises a binding and connection to the volt.
+   * @param {string} [config] - the location of the Volt configuration file, or a configuration object
+   */
+  async initialise(config, extras = {}) {
+    try {
+      if (!config) {
+        throw new Error("configPath argument is required to be a non-empty string");
+      }
+
+      let configPath;
+      let configJSON;
+      if (typeof config === "string") {
+        configPath = path.resolve(config);
+        log("Attempt to load config from file %s", configPath);
+        try {
+          const configContents = await readFile(new URL(configPath, import.meta.url));
+          configJSON = JSON.parse(configContents);
+        } catch (err) {
+          log("failure loading config file %s [%s]", configPath, err.message);
+          throw new Error(`failed to load configuration - check JSON format in ${configPath}`);
+        }
+      } else if (typeof config === "object") {
+        configJSON = config;
+      } else {
+        throw new Error("config must be either a file path or a config object");
+      }
+
+      if (!configJSON || typeof configJSON !== "object") {
+        throw new Error("config argument is required to be an object");
+      }
+
+      if (!configJSON.client_name || typeof configJSON.client_name !== "string") {
+        throw new Error("client_name property required in config");
+      }
+
+      this._config = {...configJSON, ...extras};
+
+      if (this._config.volt_did && !this._config.volt) {
+        // No Volt configuration, attempt to discover it via the given DID.
+        const didConfig = await fetchVoltConfig.call(this, this._config.volt_did);
+        log("resolved config from DID: %s", JSON.stringify(didConfig, null, 2));
+        this._config = {...this._config, ...didConfig};
+      }
+
+      this._options = this._config.volt;
+
+      if (!this._options || typeof this._options !== "object") {
+        throw new Error("configuration is missing the 'volt' object");
+      }
+
+      if (!this._options.id || typeof this._options.id !== "string") {
+        throw new Error("'id' property is missing in Volt configuration");
+      }
+
+      this._crypto = new VoltCrypto(this._config, configPath);
+
+      await this._crypto.initialise();
+
+      if (!this.isRemote) {
+        // If we're not connecting via a tunnel, we must have the address and CA.
+        if (!this._options.local_address || typeof this._options.local_address !== "string") {
+          throw new Error("'local_address' property missing in Volt configuration");
+        }
+
+        if (!this._options.ca_pem || typeof this._options.ca_pem !== "string") {
+          throw new Error("'ca_pPem' property missing in Volt configuration");
+        }
+      }
+
+      let isBound;
+      if (!this._crypto._cryptoCache.cert) {
+        // No certificate present in the cache yet => we need to bind.
+        try {
+          isBound = await bindInternal.call(this);
+        } catch (bindErr) {
+          if (bindErr.message === "invalid arguments") {
+            // This is usually the result of a missing challenge signature or credential.
+            log("failure binding to Volt - did you supply a challenge code or verified credential?");
+            throw bindErr;
+          }
+        }
+      } else {
+        isBound = true;
+      }
+
+      if (!isBound) {
+        // This is usually because of request being denied.
+        throw new Error("Volt binding failed");
+      }
+
+      return Promise.resolve();
+    } catch (err) {
+      log("Failure starting Volt client [%s]", err.message);
+      throw err;
+    }
+  }
+
+  initialiseAndConnect(configPath, extras = {}) {
+    return this.initialise(configPath, extras)
+      .then(() => {
+        return connectInternal.call(this);
+      })
+      .catch((err) => {
+        log("startAndConnect failure: %s", err.message);
+        return Promise.reject(err);
+      });
+  }
+
+  /**
+   * Creates a GRPC client for the given Volt service description.
+   *
+   * Automatically handles remote connections.
+   *
+   * n.b. for this javascript client Protobuf definitions should conform to the recommended
+   * structure, which is that a package proto file resides in a folder path that matches the
+   * package name, and services contained in the package are named in in Pascal Case and using
+   * the suffix 'API'. For example the WebcamControlAPI in package tdx.volt_api.webcam.v1 should reside
+   * in a protobuf file at tdx/api/webcam/v1/webcam_control_api.proto
+   *
+   * @param {object} service a service description.
+   * @param {object} descriptors the service descriptors, must be specified unless the service
+   * packages are well-known Volt APIs.
+   */
+  createServiceClient(service, descriptors) {
+    const pkg = service.service_description.service_api;
+
+    let serviceDescriptors;
+    if (!descriptors) {
+      serviceDescriptors = {};
+      pkg.forEach((svc) => {
+        log("adding service %s to service client", svc);
+        const packageDescriptors = getServiceDescriptors(this._grpc, svc);
+        serviceDescriptors = {...serviceDescriptors, ...packageDescriptors};
+      });
+    } else {
+      serviceDescriptors = descriptors;
+    }
+
+    if (this.isRemote) {
+      if (!this._crypto.cache.tunnel_address) {
+        throw new Error("Remote connection enabled but no tunnel address - have you called start()?");
+      }
+
+      // In remote mode => create a client using the discovered tunnel address **and** passing the service reourceId
+      return createGrpcClient(
+        this._grpc,
+        serviceDescriptors,
+        this._crypto.cache.tunnel_address,
+        this._crypto.cache,
+        false,
+        service.volt_id,
+        service.id
+      );
+    } else {
+      return createGrpcClient(
+        this._grpc,
+        serviceDescriptors,
+        service.service_description.local_address,
+        this._crypto.cache
+      );
+    }
+  }
+
+  get isRemote() {
+    return (this._config.cloud_host || this._config.tunnel_host) && this._options.id;
+  }
+
+  get isVoltTunnel() {
+    return this.isRemote && this._config.tunnel_host;
+  }
+
+  connect() {
+    return connectInternal.call(this);
+  }
+
+  disconnect() {
+    if (this._voltConnection) {
+      this._voltConnection.disconnect();
+      this._voltConnection = null;
+    }
+  }
+
+  getVoltAPIClient() {
+    return getVoltAPIClientInternal.call(this);
+  }
+
+  /**
+   * Request resource access.
+   * @param {*} targetResourceId
+   * @param {*} accessType - see vault.proto for enum values.
+   */
+  async RequestAccessBlocking(targetResourceId, accessType = "VOLT_ACCESS_READ") {
+    try {
+      const accessRequest = {
+        access: accessType,
+        resource_id: targetResourceId,
+      };
+
+      // This will block while the request is pending.
+      // TODO - implement streamed rpc on volt? Not sure there is a need really...
+      const pollInterval = 10000;
+      let decision = "";
+      do {
+        if (decision) {
+          await new Promise((resolve) => setTimeout(resolve, pollInterval));
+        }
+        const accessResponse = await this.RequestAccess(accessRequest);
+        decision = accessResponse.decision;
+        log("access decision: %s", decision);
+      } while (decision === "POLICY_DECISION_PROMPT" || decision === "POLICY_DECISION_PENDING");
+
+      log("requestResourceAccess result is %j", decision);
+      return decision === "POLICY_DECISION_PERMIT";
+    } catch (err) {
+      log("failure requesting resource access [%s]", err.message);
+      return Promise.reject(err);
+    }
+  }
+
+  /**
+   * VoltAPI - resource management
+   */
+
+  CanAccessResource(request) {
+    return unaryCall.call(this, "CanAccessResource", request);
+  }
+
+  DeleteResource(request) {
+    return unaryCall.call(this, "DeleteResource", request);
+  }
+
+  DiscoverServices(request) {
+    return unaryCall.call(this, "DiscoverServices", request);
+  }
+
+  GetResource(request) {
+    return unaryCall.call(this, "GetResource", request);
+  }
+
+  GetResources(request) {
+    return unaryCall.call(this, "GetResources", request);
+  }
+
+  GetResourceAncestors(request) {
+    return unaryCall.call(this, "GetResourceAncestors", request);
+  }
+
+  GetResourceDescendants(request) {
+    return unaryCall.call(this, "GetResourceDescendants", request);
+  }
+
+  RequestAccess(request) {
+    return unaryCall.call(this, "RequestAccess", request);
+  }
+
+  SaveResource(request) {
+    return unaryCall.call(this, "SaveResource", request);
+  }
+
+  SaveResourceAttribute(request) {
+    return unaryCall.call(this, "SaveResourceAttribute", request);
+  }
+
+  SetServiceStatus(request) {
+    return unaryCall.call(this, "SetServiceStatus", request);
+  }
+
+  /**
+   * VoltAPI - volt management
+   */
+
+  Bind(request) {
+    return unaryCall.call(this, "Bind", request);
+  }
+
+  DeleteAccess(request) {
+    return unaryCall.call(this, "DeleteAccess", request);
+  }
+
+  DeleteVolt(request) {
+    return unaryCall.call(this, "DeleteVolt", request);
+  }
+
+  GetAccess(request) {
+    return unaryCall.call(this, "GetAccess", request);
+  }
+
+  GetBindings(request) {
+    return unaryCall.call(this, "GetBindings", request);
+  }
+
+  GetIdentities(request) {
+    return unaryCall.call(this, "GetIdentities", request);
+  }
+
+  GetIdentity(request) {
+    return unaryCall.call(this, "GetIdentity", request);
+  }
+
+  GetIdentityToken(request) {
+    return unaryCall.call(this, "GetIdentityToken", request);
+  }
+
+  GetPolicy(request) {
+    return unaryCall.call(this, "GetPolicy", request);
+  }
+
+  GetSettings(request) {
+    return unaryCall.call(this, "GetSettings", request);
+  }
+
+  SaveAccess(request) {
+    return unaryCall.call(this, "SaveAccess", request);
+  }
+
+  SaveCloudConnection(request) {
+    return unaryCall.call(this, "SaveCloudConnection", request);
+  }
+
+  SaveIdentity(request) {
+    return unaryCall.call(this, "SaveIdentity", request);
+  }
+
+  SaveSettings(request) {
+    return unaryCall.call(this, "SaveSettings", request);
+  }
+
+  SetAccessRequestDecision(request) {
+    return unaryCall.call(this, "SetAccessRequestDecision", request);
+  }
+
+  SetBindingDecision(request) {
+    return unaryCall.call(this, "SetBindingDecision", request);
+  }
+
+  Shutdown(request) {
+    return unaryCall.call(this, "Shutdown", request);
+  }
+
+  SignVerify(request) {
+    return unaryCall.call(this, "SignVerify", request);
+  }
+
+  /**
+   * FileAPI
+   */
+  GetFileDescendants(request) {
+    return unaryCall.call(this, "GetFileDescendants", request);
+  }
+
+  /**
+   * Asynchronous file download
+   * @param {*} request
+   * @returns stream
+   */
+  DownloadFile(request) {
+    const grpcClient = this.getVoltAPIClient();
+
+    return new Promise((resolve, reject) => {
+      const meta = this._crypto.getIdentityMetadata(this._grpc, this._options.id, this.isRemote);
+      resolve(grpcClient.DownloadFile(request, meta.metadata));
+    }).catch((err) => {
+      log("error during %s [%s]", method, err.message);
+      return Promise.reject(err);
+    });
+  }
+
+  UploadFile(request, callback) {
+    const grpcClient = this.getVoltAPIClient();
+
+    const uploadCall = new GRPCCall(this, "UploadFile", "METHOD_TYPE_BIDI");
+    return uploadCall.start(grpcClient, request, callback);
+  }
+
+  /**
+   * Synchronous file download
+   * @param {*} request
+   * @returns file buffer, base64 encoded
+   */
+  DownloadFileSync(request) {
+    const grpcClient = this.getVoltAPIClient();
+
+    const blocks = [];
+
+    const call = new GRPCCall(this, "DownloadFile", "METHOD_TYPE_SERVER_STREAM");
+    call.start(grpcClient, request, (err, response) => {
+      if (err) {
+        return call.reject(err);
+      }
+
+      switch (response.payload) {
+        case "block":
+          blocks.push(response.block);
+          break;
+        case "status":
+          if (response.status.message) {
+            return call.reject(new Error(response.status.message));
+          } else {
+            // Non-error response status => do nothing and wait for the stream to end.
+          }
+          break;
+        default:
+          log("unrecognised response payload %s", response.payload);
+          break;
+      }
+    });
+
+    return call
+      .wait()
+      .then(() => {
+        log("Download finished");
+        return {buffer: Buffer.concat(blocks).toString("base64")};
+      })
+      .catch((err) => {
+        log("error during DownloadFile [%s]", err.message);
+        return Promise.reject(err);
+      });
+  }
+
+  /**
+   * WireAPI
+   */
+  PublishWire(request, callback) {
+    const grpcClient = this.getVoltAPIClient();
+
+    const publishCall = new GRPCCall(this, "PublishWire", "METHOD_TYPE_CLIENT_STREAM");
+    return publishCall.start(grpcClient, request, callback);
+  }
+
+  SubscribeWire(request, callback) {
+    const grpcClient = this.getVoltAPIClient();
+
+    const subscribeCall = new GRPCCall(this, "SubscribeWire", "METHOD_TYPE_BIDI");
+    return subscribeCall.start(grpcClient, request, callback);
+  }
+}

package/src/volt-connection.js

@@ -0,0 +1,157 @@
+/* eslint-disable no-use-before-define */
+/* eslint-disable no-underscore-dangle */
+import debug from "debug";
+import EventEmitter from "events";
+import GRPCCall from "./grpc-call.js";
+
+const log = debug("volt-client-grpc:volt-connection");
+
+function _cleanUp(immediateReconnect) {
+  this._session = false;
+
+  if (this._pingTimer) {
+    clearTimeout(this._pingTimer);
+    this._pingTimer = 0;
+  }
+
+  if (this._pingTimeoutTimer) {
+    clearTimeout(this._pingTimeoutTimer);
+    this._pingTimeoutTimer = 0;
+  }
+
+  if (!this._dying && (immediateReconnect || (this._autoRetry && !this._reconnectTimer))) {
+    this._reconnectTimer = setTimeout(
+      () => {
+        this._reconnectTimer = 0;
+        _doConnect.call(this);
+      },
+      immediateReconnect ? 0 : this._reconnectInterval
+    );
+  }
+
+  if (this.call && this.call.writable) {
+    this.call.end();
+  }
+}
+
+function _connectionTimeoutHandler() {
+  log("server timed out");
+  this.emit("connected", false);
+  _cleanUp.call(this);
+}
+
+function _doConnect() {
+  this.call = new GRPCCall(this._voltClient, "Connect", "METHOD_TYPE_BIDI");
+
+  const grpcClient = this._voltClient.getVoltAPIClient();
+  const helloPayload = {
+    hello: {},
+  };
+
+  this.call.start(grpcClient, helloPayload, (err, response) => {
+    if (err) {
+      log("error on connection stream [%s]", err.message);
+      _cleanUp.call(this);
+      this.emit("error", err);
+    } else {
+      switch (response.payload) {
+        case "ping": {
+          log("pinged");
+
+          // Received ping response from server => clear timeout.
+          if (this._pingTimeoutTimer) {
+            clearTimeout(this._pingTimeoutTimer);
+          }
+
+          // Schedule the next ping.
+          _startPingTimer.call(this);
+          break;
+        }
+        case "hello":
+          if (!this._session) {
+            this._session = true;
+            this.emit("connected", this._session);
+          }
+          break;
+        case "evt":
+          log("received event %s", response.evt.event_type);
+          this.emit("evt", response.evt);
+          break;
+        default:
+          log("unimplemented connect response payload: %s", response.payload);
+          break;
+      }
+    }
+  });
+
+  this.call
+    .wait()
+    .then(() => {
+      if (this._session) {
+        this.emit("connected", false);
+      }
+    })
+    .catch((err) => {
+      log("unexpected error on connect call [%s]", err.message);
+    })
+    .finally(() => {
+      _cleanUp.call(this);
+    });
+
+  _startPingTimer.call(this);
+}
+
+function _startPingTimer() {
+  if (this._pingTimer) {
+    log("ping timer running");
+    return;
+  }
+
+  this._pingTimer = setTimeout(() => {
+    // Send next ping to server.
+    const request = {ping: {timestamp: Date.now()}};
+
+    log("pinging Volt");
+    this.call.write(request);
+
+    this._pingTimer = 0;
+
+    // Schedule a timeout if we don't hear back from the server.
+    if (this._pingTimeoutTimer) {
+      clearTimeout(this._pingTimeoutTimer);
+    }
+
+    this._pingTimeoutTimer = setTimeout(_connectionTimeoutHandler.bind(this), this._timeoutInterval);
+  }, this._pingInterval);
+}
+
+export default class VoltConnection extends EventEmitter {
+  constructor(voltClient, grpc, options = {}) {
+    super();
+
+    this._grpc = grpc;
+    this._autoRetry = options.autoReconnect === undefined ? true : !!options.autoReconnect;
+    this._dying = false;
+    this._voltClient = voltClient;
+    this._options = options;
+    this._pingTimer = 0;
+    this._pingTimeoutTimer = 0;
+    this._session = false;
+    this._pingInterval = options.pingInterval || 10000;
+    this._reconnectInterval = options.reconnectInterval || 5000;
+    this._timeoutInterval = options.timeoutInterval || 60000;
+  }
+
+  connect(throwOnFail) {
+    if (throwOnFail) {
+      return _doConnect.call(this);
+    } else {
+      return Promise.resolve(_cleanUp.call(this, true));
+    }
+  }
+
+  disconnect() {
+    this._dying = true;
+    _cleanUp.call(this);
+  }
+}