@tdxvolt/volt-client-grpc 0.14.61 → 0.15.0

package/package.json

@@ -3,7 +3,7 @@
   "publishConfig": {
     "access": "public"
   },
-  "version": "0.14.61",
+  "version": "0.15.0",
   "description": "tdx Volt library for nodejs clients",
   "type": "module",
   "exports": {

package/protobuf/tdx/volt_api/volt/v1/file_api.proto

@@ -8,7 +8,7 @@ import "tdx/volt_api/volt/v1/file.proto";
 // The File API exposes basic file management functions.
 service FileAPI {
 
-  // A server-stream to download contents from a file resource.
+  // Download from file resource.
   rpc DownloadFile(DownloadFileRequest) returns (stream DownloadFileResponse);
 
   // Get file resource metadata.

package/protobuf/tdx/volt_api/volt/v1/volt_api.proto

@@ -787,8 +787,10 @@ message InvokeRequest {
   // Indicates the client has ended the invocation.
   bool client_end = 6;
 
+  // Reserved for internal use.
   uint32 hop_index = 7;
 
+  // Reserved for internal use.
   string target_service_id = 8;
 }
 

package/protobuf/tdx/volt_api/volt/v1/wire_api.proto

@@ -6,7 +6,7 @@ import "tdx/volt_api/volt/v1/status.proto";
 
 // The Wire API allows clients to subscribe and publish to Volt wire resources.
 service WireAPI {
-  // Establishes a bi-directional streaming call to the wire resource.
+  // Establishes a client-streaming call to the wire resource.
   rpc PublishWire(stream PublishWireRequest) returns (stream PublishWireResponse);
 
   // Establishes a bi-directional streaming call to the wire resource.

package/src/grpc-call.js

@@ -10,16 +10,31 @@ function _prepareInvokeRequest(
   method,
   methodType = "METHOD_TYPE_UNARY",
 ) {
-  const meta = this._voltClient.credential.getIdentityMetadata(
+  const isServiceRelayed =
+    this._service?.service_description.host_type ===
+    "SERVICE_HOST_TYPE_RELAYED";
+
+  // Use the service's host client id and public key if the service is relayed.
+  const methodToken = this._voltClient.credential.getIdentityMetadata(
     this._voltClient.grpc,
-    this._voltClient.voltConfig.id,
-    this._voltClient.isRemote,
+    this._service?.service_description.host_client_id ||
+      this._voltClient.voltConfig.id,
+    this._service?.service_description.host_public_key ||
+      this._voltClient.credential.voltPublicKey,
+    true,
   );
+
   let invokeRequest;
   let callMethod = method;
 
-  if (this._voltClient.isVoltRelay) {
+  if (this._voltClient.isVoltRelay || isServiceRelayed) {
+    //
+    // If the volt connection is via a relay (or the target service is relayed),
+    // we wrap the rpc in a RemoteRequest message and send it via a call to Invoke().
+    //
     let requestPayload;
+
+    // Serialise the rpc request.
     if (request) {
       requestPayload = this._grpcClient[method].requestSerialize(request);
     } else if (request !== null) {
@@ -28,45 +43,61 @@ function _prepareInvokeRequest(
       log("explicit empty request payload");
     }
 
-    const tunnelMethod = this._grpcClient.Tunnel;
+    // Use this placeholder to serialise the relay request wrapper.
+    const voltGrpcClient = this._voltClient.getVoltAPIClient();
+    const tunnelMethod = voltGrpcClient.Tunnel;
 
     const tunnelResp = {
       method_invoke: {
         method_name: this._grpcClient[method].path,
         method_type: methodType,
-        token: meta.token,
+        token: methodToken.token,
         request: requestPayload,
       },
     };
 
-    const invokePayload = VoltCredential.aesEncrypt(
-      tunnelMethod.responseSerialize(tunnelResp),
-      meta.sharedKey.key,
-      meta.sharedKey.iv,
-    );
+    let targetFingerprint = [];
+    let invokePayload;
+    if (this._voltClient.isVoltRelay || isServiceRelayed) {
+      // When sending via a relay we need to encrypt the payload.
+      invokePayload = VoltCredential.aesEncrypt(
+        tunnelMethod.responseSerialize(tunnelResp),
+        methodToken.sharedKey.key,
+        methodToken.sharedKey.iv,
+      );
+    } else {
+      invokePayload = tunnelMethod.responseSerialize(tunnelResp);
+    }
 
-    log("target volt is %s", this._voltClient.credential.voltFingerprint);
+    if (this._voltClient.isVoltRelay) {
+      targetFingerprint.push(this._voltClient.credential.voltFingerprint);
+    }
+
+    if (isServiceRelayed) {
+      // Add another relay hop if the target service is relayed.
+      log("target service is relayed");
+      targetFingerprint.push(
+        this._service.service_description.host_fingerprint,
+      );
+    }
+
+    log("target is %j", targetFingerprint);
 
     invokeRequest = {
-      identity_fingerprint: this._voltClient.credential.voltFingerprint,
+      target_fingerprint: targetFingerprint,
+      token: methodToken.token,
       payload: invokePayload,
+      target_service_id: isServiceRelayed ? this._service.id : undefined,
     };
 
+    // Replace the target method with a call to Invoke on the relay Volt.
     callMethod = "Invoke";
-  } else if (this._voltClient.isRemote && meta.sharedKey.key) {
-    const requestPayload =
-      this._grpcClient[method].requestSerializeOriginal(request);
-    invokeRequest = VoltCredential.aesEncrypt(
-      requestPayload,
-      meta.sharedKey.key,
-      meta.sharedKey.iv,
-    );
   } else {
     invokeRequest = request;
   }
 
   return {
-    meta,
+    meta: methodToken,
     method: callMethod,
     methodName: method,
     request: invokeRequest,
@@ -76,10 +107,16 @@ function _prepareInvokeRequest(
 function _preparePayloadRequest(request, invokeInfo) {
   let payloadRequest;
 
-  if (this._voltClient.isVoltRelay) {
+  const isServiceRelayed =
+    this._service?.service_description.host_type ===
+    "SERVICE_HOST_TYPE_RELAYED";
+
+  if (this._voltClient.isVoltRelay || isServiceRelayed) {
     const requestPayload =
       this._grpcClient[invokeInfo.methodName].requestSerialize(request);
-    const tunnelMethod = this._grpcClient.Tunnel;
+
+    const voltGrpcClient = this._voltClient.getVoltAPIClient();
+    const tunnelMethod = voltGrpcClient.Tunnel;
 
     const tunnelResp = {
       method_payload: {
@@ -96,14 +133,6 @@ function _preparePayloadRequest(request, invokeInfo) {
     payloadRequest = {
       payload: invokePayload,
     };
-  } else if (this._voltClient.isRemote && invokeInfo.meta.sharedKey.key) {
-    const requestPayload =
-      this._grpcClient[invokeInfo.methodName].requestSerializeOriginal(request);
-    payloadRequest = VoltCredential.aesEncrypt(
-      requestPayload,
-      invokeInfo.meta.sharedKey.key,
-      invokeInfo.meta.sharedKey.iv,
-    );
   } else {
     payloadRequest = request;
   }
@@ -112,21 +141,39 @@ function _preparePayloadRequest(request, invokeInfo) {
 }
 
 function _parseResponse(method, meta, response) {
+  // log("parseResponse for %s", this._methodName);
   let invokeResponse = {};
 
-  if (this._voltClient.isVoltRelay) {
+  const isServiceRelayed =
+    this._service?.service_description.host_type ===
+    "SERVICE_HOST_TYPE_RELAYED";
+
+  if (this._voltClient.isVoltRelay || isServiceRelayed) {
     if (response.payload) {
-      const decryptedPayload = VoltCredential.aesDecrypt(
-        response.payload,
-        meta.sharedKey.key,
-        meta.sharedKey.iv,
-      );
-      const tunnelMethod = this._grpcClient.Tunnel;
+      let decryptedPayload;
+      if (meta.sharedKey.key) {
+        decryptedPayload = VoltCredential.aesDecrypt(
+          response.payload,
+          meta.sharedKey.key,
+          meta.sharedKey.iv,
+        );
+      } else {
+        decryptedPayload = response.payload;
+      }
+
+      const tunnelMethod = this._voltClient.getVoltAPIClient().Tunnel;
       const responsePayload = tunnelMethod.requestDeserialize(decryptedPayload);
       if (responsePayload.payload === "method_payload") {
-        invokeResponse.payload = this._grpcClient[method].responseDeserialize(
-          responsePayload.method_payload.payload,
-        );
+        try {
+          invokeResponse.payload = this._grpcClient[method].responseDeserialize(
+            responsePayload.method_payload.payload,
+          );
+        } catch (err) {
+          log("failure deserialising payload for %s", this._methodName);
+          throw new Error(
+            "failure deserialising payload - check protobuf definition matches with data being sent",
+          );
+        }
       } else if (responsePayload.payload === "method_end") {
         invokeResponse = responsePayload.method_end;
       } else {
@@ -166,17 +213,22 @@ function _parseResponse(method, meta, response) {
 }
 
 export default class GRPCCall extends EventEmitter {
-  constructor(voltClient, methodName, methodType) {
+  constructor(voltClient, methodName, methodType, service = undefined) {
     super();
     this._methodName = methodName;
     this._methodType = methodType;
     this._call = null;
     this._voltClient = voltClient;
+    this._service = service;
   }
 
   start(grpcClient, request) {
     this._grpcClient = grpcClient;
 
+    if (typeof this._grpcClient[this._methodName] !== "function") {
+      throw new Error(`method not found: '${this._methodName}'`);
+    }
+
     this._initialRequest = _prepareInvokeRequest.call(
       this,
       request,
@@ -184,13 +236,18 @@ export default class GRPCCall extends EventEmitter {
       this._methodType,
     );
 
-    if (!this._grpcClient[this._initialRequest.method]) {
-      return reject(
-        new Error(`method not found: '${this._initialRequest.method}'`),
-      );
+    const isServiceRelayed =
+      this._service?.service_description.host_type ===
+      "SERVICE_HOST_TYPE_RELAYED";
+
+    let callClient;
+    if (this._voltClient.isVoltRelay || isServiceRelayed) {
+      callClient = this._voltClient.getVoltAPIClient();
+    } else {
+      callClient = this._grpcClient;
     }
 
-    this._call = this._grpcClient[this._initialRequest.method](
+    this._call = callClient[this._initialRequest.method](
       this._initialRequest.meta.metadata,
     );
 
@@ -223,7 +280,11 @@ export default class GRPCCall extends EventEmitter {
           log("method id is %s", parsedResponse.methodId);
         }
       } catch (err) {
-        log("failure processing connect response: %s", err.message);
+        log(
+          "failure processing %s call response: %s",
+          this._methodName,
+          err.message,
+        );
         this.emit("error", err);
       }
     });

package/src/grpc-utils.js

@@ -16,7 +16,7 @@ export function createClient(
   credentials,
   noSerialise,
   voltId,
-  serviceId,
+  serviceId
 ) {
   let grpcCredentials;
   if (credentials) {
@@ -30,7 +30,7 @@ export function createClient(
       grpcCredentials = grpc.credentials.createSsl(
         tlsOptions.ca,
         tlsOptions.key,
-        tlsOptions.cert,
+        tlsOptions.cert
       );
     } else {
       // Cache has no private key, this implies we are connecting without supplying a client certificate.
@@ -92,7 +92,7 @@ const grpcWrap = (api) => {
   // Support class instances and PoJos
   const isClass = api.constructor !== Object;
   const iterate = Object.getOwnPropertyNames(
-    isClass ? api.constructor.prototype : api,
+    isClass ? api.constructor.prototype : api
   );
 
   // Wrap each method on the api.
@@ -106,7 +106,7 @@ const grpcWrap = (api) => {
         // Enforce promise results.
         if (!(resultPromise?.then && resultPromise?.catch)) {
           throw new Error(
-            `implementation methods must return a Promise [${name}]`,
+            `implementation methods must return a Promise [${name}]`
           );
         }
 
@@ -143,7 +143,7 @@ class GrpcServer {
       "grpc.http2.max_pings_without_data": 0,
       "grpc.keepalive_permit_without_calls": 1,
       "grpc.http2.min_ping_interval_without_data_ms": 250,
-      "grpc.http2.max_ping_strikes": 0,
+      "grpc.http2.max_ping_strikes": 0
     });
 
     if (tlsOptions) {
@@ -153,7 +153,7 @@ class GrpcServer {
         caList.push(tlsOption.ca);
         certChains.push({
           private_key: tlsOption.key,
-          cert_chain: tlsOption.cert,
+          cert_chain: tlsOption.cert
         });
       });
 
@@ -164,7 +164,7 @@ class GrpcServer {
         // The certificate chain(s) we present to the client.
         certChains,
         // Flag indicating if we insist on a client certificate.
-        requireClientCert,
+        requireClientCert
       );
     } else {
       this._credentials = grpc.ServerCredentials.createInsecure();
@@ -216,7 +216,7 @@ export function createServer(
   serviceDescriptors,
   routes,
   cryptoCache,
-  requireClientCert,
+  requireClientCert
 ) {
   let tlsOptions;
   if (cryptoCache) {
@@ -227,7 +227,7 @@ export function createServer(
     serviceDescriptors,
     routes,
     tlsOptions,
-    requireClientCert,
+    requireClientCert
   };
   return new GrpcServer(serverArgs);
 }

package/src/proto-utils.js

@@ -2,6 +2,7 @@ import protoLoader from "@grpc/proto-loader";
 import lodash from "lodash";
 import { dirname, join } from "path";
 import { fileURLToPath } from "url";
+import { writeFileSync, mkdirSync } from "fs";
 
 const { get: getProp, snakeCase } = lodash;
 const __dirname = dirname(fileURLToPath(import.meta.url));
@@ -17,23 +18,23 @@ const defaultLoaderOptions = {
   includeDirs: [defaultProtoPath],
 };
 
-const getProtoDescriptors = (grpc, protoPath, opts) => {
+function getProtoDescriptors(grpc, protoPath, opts) {
   const definition = protoLoader.loadSync(
     protoPath,
     opts || defaultLoaderOptions,
   );
   const descriptors = grpc.loadPackageDefinition(definition);
   return descriptors;
-};
+}
 
-const getProtoService = (descriptors, servicePath) => {
+function getProtoService(descriptors, servicePath) {
   const serviceDef = getProp(descriptors, servicePath);
   if (serviceDef?.service) {
     return serviceDef.service;
   } else {
     return null;
   }
-};
+}
 
 function getServiceDescriptorsFromPath(
   grpc,
@@ -41,8 +42,30 @@ function getServiceDescriptorsFromPath(
   servicePackageName,
   opts,
 ) {
+  if (!opts) {
+    opts = { ...defaultLoaderOptions };
+    opts.includeDirs = [protoPath];
+  }
+
+  // Extract the package components of the service proto package. The package name should be of the
+  // fully qualified proto path, e.g. tdx.volt_api.webcam.v1.WebcamControlAPI.
+  const protoServiceComponents = servicePackageName.split(".");
+
+  // The service name is the last component of the path.
+  const protoServiceName = protoServiceComponents.pop();
+
+  // The actual file name should match the snake case of the service name.
+  const protoFileName = `${snakeCase(protoServiceName).toLowerCase()}.proto`;
+
+  // The path to the proto file should match each component of the package name.
+  const serviceProtoPath = join(
+    protoPath,
+    ...protoServiceComponents,
+    protoFileName,
+  );
+
   let serviceDescriptors;
-  const descriptors = getProtoDescriptors(grpc, protoPath, opts);
+  const descriptors = getProtoDescriptors(grpc, serviceProtoPath, opts);
   if (descriptors) {
     serviceDescriptors = getProtoService(descriptors, servicePackageName);
   }
@@ -90,7 +113,16 @@ function getProtoDescriptorMethods(protoDescriptor) {
   return methods;
 }
 
+function createServiceProtobufFiles(service, protoPath) {
+  for (let protoFile of service.service_description.proto_file) {
+    const filePath = join(protoPath, protoFile.file_path);
+    mkdirSync(dirname(filePath), { recursive: true });
+    writeFileSync(filePath, protoFile.protobuf);
+  }
+}
+
 export {
+  createServiceProtobufFiles,
   getServiceDescriptors,
   getProtoDescriptors,
   getProtoDescriptorMethods,