From e87e57791024824bb19830c66b9f3d2eaed6d629 Mon Sep 17 00:00:00 2001
From: Peter Somogyvari <peter.somogyvari@accenture.com>
Date: Tue, 19 Mar 2024 10:03:43 -0700
Subject: [PATCH] feat(core-api): add IPluginGrpcService type & user-defined
 type guard

1. This will be used by the upcoming functionality of the API server that
allows all plugins to register their own gRPC services as part of the API
server's own gRPC service.
2. The above mechanism will largely be the same conceptually as the one
we have for HTTP and SocketIO endpoints already.
3. It is optional for plugins to implement gRPC services and therefore
the interface is a standalone one instead of being baked into the more
generic IPluginWebService interface for example.

Signed-off-by: Peter Somogyvari <peter.somogyvari@accenture.com>
---
 .../grpc-service/i-plugin-grpc-service.ts     | 62 +++++++++++++++++++
 .../src/main/typescript/public-api.ts         |  4 ++
 2 files changed, 66 insertions(+)
 create mode 100644 packages/cactus-core-api/src/main/typescript/plugin/grpc-service/i-plugin-grpc-service.ts

diff --git a/packages/cactus-core-api/src/main/typescript/plugin/grpc-service/i-plugin-grpc-service.ts b/packages/cactus-core-api/src/main/typescript/plugin/grpc-service/i-plugin-grpc-service.ts
new file mode 100644
index 0000000000..ca9d331e69
--- /dev/null
+++ b/packages/cactus-core-api/src/main/typescript/plugin/grpc-service/i-plugin-grpc-service.ts
@@ -0,0 +1,62 @@
+import type {
+  ServiceDefinition,
+  UntypedServiceImplementation,
+} from "@grpc/grpc-js";
+
+/**
+ * Implementers of this interface are responsible for providing a gRPC service
+ * that can be dynamically registered at runtime by the API server.
+ *
+ * It describes what methods a class (plugin) needs to implement
+ * in order to be able to operate as a Cacti gRPC service (e.g. expose its
+ * functionality through gRPC not just HTTP or SocketIO)
+ *
+ * @see {IPluginWebService}
+ * @see {ApiServer}
+ */
+export interface IPluginGrpcService {
+  /**
+   * Used by the API server and/or automated test cases when hooking up this
+   * plugin instance into a gRPC Server object.
+   *
+   * The returned pair of service
+   * definition and implementation objects are passed in to the `.addService()`
+   * method of the `Server` object of the `@grpc/grpc-js` library.
+   *
+   * @see {ServiceDefinition}
+   * @see {IGrpcSvcDefAndImplPair}
+   */
+  createGrpcSvcDefAndImplPairs(
+    opts: unknown,
+  ): Promise<Array<IGrpcSvcDefAndImplPair>>;
+}
+
+/**
+ * A wrapper object that contains both the the definition and the implementation
+ * objects of a gRPC service that a plugin can implement to expose it's functionality
+ * over gRPC.
+ */
+export interface IGrpcSvcDefAndImplPair {
+  readonly definition: ServiceDefinition;
+  readonly implementation: UntypedServiceImplementation;
+}
+
+/**
+ * Custom (user-defined) Typescript type-guard that verifies at runtime whether
+ * `x` is an implementation of {IPluginGrpcService} or not.
+ *
+ * @param x Literally any object or value that you'd want to verify for having
+ * the right method(s) implemented in-order to qualify as an implementer of the
+ * {IPluginGrpcService} interface.
+ *
+ * The {ApiServer} uses this to filter the total list of plugins down to the ones
+ * that have gRPC services of their own and then hook those up at runtime.
+ *
+ * @returns `true` if `x` does implement {IPluginGrpcService} `false` otherwise.
+ */
+export function isIPluginGrpcService(x: unknown): x is IPluginGrpcService {
+  return (
+    !!x &&
+    typeof (x as IPluginGrpcService).createGrpcSvcDefAndImplPairs === "function"
+  );
+}
diff --git a/packages/cactus-core-api/src/main/typescript/public-api.ts b/packages/cactus-core-api/src/main/typescript/public-api.ts
index fcc684feaa..97ad96a597 100755
--- a/packages/cactus-core-api/src/main/typescript/public-api.ts
+++ b/packages/cactus-core-api/src/main/typescript/public-api.ts
@@ -44,3 +44,7 @@ export {
 } from "./client/i-verifier";
 
 export { ISendRequestResultV1 } from "./plugin/ledger-connector/i-send-request-response-v1";
+
+export { IPluginGrpcService } from "./plugin/grpc-service/i-plugin-grpc-service";
+export { IGrpcSvcDefAndImplPair } from "./plugin/grpc-service/i-plugin-grpc-service";
+export { isIPluginGrpcService } from "./plugin/grpc-service/i-plugin-grpc-service";