@valon-technologies/gestalt 0.0.1-alpha.1 → 0.0.1-alpha.11

package/src/runtime.ts

@@ -4,17 +4,22 @@ import { dirname, resolve } from "node:path";
 
 import { create } from "@bufbuild/protobuf";
 import { EmptySchema } from "@bufbuild/protobuf/wkt";
-import { Code, ConnectError, type ServiceImpl } from "@connectrpc/connect";
+import {
+  Code,
+  ConnectError,
+  type ConnectRouter,
+  type ServiceImpl,
+} from "@connectrpc/connect";
 import { connectNodeAdapter } from "@connectrpc/connect-node";
 
 import {
-  AuthProvider as AuthProviderService,
+  AuthenticationProvider as AuthenticationProviderService,
   AuthSessionSettingsSchema,
   AuthenticatedUserSchema,
   BeginLoginResponseSchema,
   type CompleteLoginRequest as AuthCompleteLoginRequest,
   type ValidateExternalTokenRequest,
-} from "../gen/v1/auth_pb.ts";
+} from "../gen/v1/authentication_pb.ts";
 import {
   Cache as CacheService,
   CacheDeleteManyResponseSchema,
@@ -53,23 +58,33 @@ import {
   type ConfigureProviderRequest,
 } from "../gen/v1/runtime_pb.ts";
 import { S3 as S3Service } from "../gen/v1/s3_pb.ts";
+import { WorkflowProvider as WorkflowProviderService } from "../gen/v1/workflow_pb.ts";
 import { errorMessage, type Request } from "./api.ts";
 import {
-  AuthProvider,
-  isAuthProvider,
+  AuthenticationProvider,
+  isAuthenticationProvider,
   type AuthenticatedUser,
 } from "./auth.ts";
 import { CacheProvider, isCacheProvider } from "./cache.ts";
 import { SecretsProvider, isSecretsProvider } from "./secrets.ts";
 import { catalogToYaml, type Catalog } from "./catalog.ts";
 import {
-  IntegrationProvider,
+  PluginProvider,
   connectionModeToProtoValue,
   connectionParamToProto,
-  isIntegrationProvider,
+  isPluginProvider,
 } from "./plugin.ts";
+import {
+  providerKindLabel,
+  resolveDefaultProviderExport,
+} from "./provider-kind.ts";
 import { type ProviderKind, slugName } from "./provider.ts";
 import { S3Provider, createS3Service, isS3Provider } from "./s3.ts";
+import {
+  WorkflowProvider,
+  createWorkflowProviderService,
+  isWorkflowProvider,
+} from "./workflow.ts";
 import {
   defaultProviderName,
   formatProviderTarget,
@@ -79,24 +94,134 @@ import {
   resolveProviderImportUrl,
 } from "./target.ts";
 
+/**
+ * Environment variable containing the Unix socket path for a running provider.
+ */
 export const ENV_PROVIDER_SOCKET = "GESTALT_PLUGIN_SOCKET";
+/**
+ * Environment variable containing the parent process ID supplied by the host.
+ */
 export const ENV_PROVIDER_PARENT_PID = "GESTALT_PLUGIN_PARENT_PID";
+/**
+ * Environment variable used to request static catalog generation.
+ */
 export const ENV_WRITE_CATALOG = "GESTALT_PLUGIN_WRITE_CATALOG";
-export const CURRENT_PROTOCOL_VERSION = 2;
+/**
+ * Environment variable used to request generated manifest metadata export.
+ */
+export const ENV_WRITE_MANIFEST_METADATA =
+  "GESTALT_PLUGIN_WRITE_MANIFEST_METADATA";
+/**
+ * Protocol version currently implemented by the TypeScript runtime.
+ */
+export const CURRENT_PROTOCOL_VERSION = 3;
+/**
+ * Command-line usage for the runtime entrypoint.
+ */
 export const USAGE = "usage: bun run runtime.ts ROOT PROVIDER_TARGET";
+export { createWorkflowProviderService } from "./workflow.ts";
 
+/**
+ * Parsed arguments for the runtime entrypoint.
+ */
 export type RuntimeArgs = {
   root: string;
   target: string;
 };
 
+/**
+ * Provider implementations supported by the runtime host.
+ */
 export type LoadedProvider =
-  | IntegrationProvider
-  | AuthProvider
+  | PluginProvider
+  | AuthenticationProvider
   | CacheProvider
   | SecretsProvider
-  | S3Provider;
+  | S3Provider
+  | WorkflowProvider;
+
+type ProviderRuntimeEntry = {
+  isProvider: (value: unknown) => value is LoadedProvider;
+  protoKind: ProtoProviderKind;
+  registerService: (router: ConnectRouter, provider: LoadedProvider) => void;
+};
+
+const PROVIDER_RUNTIME_ENTRIES: Partial<
+  Record<ProviderKind, ProviderRuntimeEntry>
+> = {
+  integration: {
+    isProvider: isPluginProvider as (value: unknown) => value is LoadedProvider,
+    protoKind: ProtoProviderKind.INTEGRATION,
+    registerService(router, provider) {
+      router.service(
+        IntegrationProviderService,
+        createProviderService(provider as PluginProvider),
+      );
+    },
+  },
+  authentication: {
+    isProvider:
+      isAuthenticationProvider as (value: unknown) => value is LoadedProvider,
+    protoKind: ProtoProviderKind.AUTHENTICATION,
+    registerService(router, provider) {
+      router.service(
+        AuthenticationProviderService,
+        createAuthenticationService(provider as AuthenticationProvider),
+      );
+    },
+  },
+  cache: {
+    isProvider: isCacheProvider as (value: unknown) => value is LoadedProvider,
+    protoKind: ProtoProviderKind.CACHE,
+    registerService(router, provider) {
+      router.service(
+        CacheService,
+        createCacheService(provider as CacheProvider),
+      );
+    },
+  },
+  secrets: {
+    isProvider: isSecretsProvider as (value: unknown) => value is LoadedProvider,
+    protoKind: ProtoProviderKind.SECRETS,
+    registerService(router, provider) {
+      router.service(
+        SecretsProviderService,
+        createSecretsService(provider as SecretsProvider),
+      );
+    },
+  },
+  s3: {
+    isProvider: isS3Provider as (value: unknown) => value is LoadedProvider,
+    protoKind: ProtoProviderKind.S3,
+    registerService(router, provider) {
+      router.service(S3Service, createS3Service(provider as S3Provider));
+    },
+  },
+  workflow: {
+    isProvider: isWorkflowProvider as (value: unknown) => value is LoadedProvider,
+    protoKind: ProtoProviderKind.WORKFLOW,
+    registerService(router, provider) {
+      router.service(
+        WorkflowProviderService,
+        createWorkflowProviderService(provider as WorkflowProvider),
+      );
+    },
+  },
+};
+
+function assertProtocolVersion(protocolVersion: number): void {
+  if (protocolVersion === CURRENT_PROTOCOL_VERSION) {
+    return;
+  }
+  throw new ConnectError(
+    `host requested protocol version ${protocolVersion}, provider requires ${CURRENT_PROTOCOL_VERSION}`,
+    Code.FailedPrecondition,
+  );
+}
 
+/**
+ * CLI entrypoint that loads a provider from source and starts serving it.
+ */
 export async function main(
   argv: string[] = process.argv.slice(2),
 ): Promise<number> {
@@ -112,6 +237,9 @@ export async function main(
   return 0;
 }
 
+/**
+ * Parses `gestalt-ts-runtime` CLI arguments.
+ */
 export function parseRuntimeArgs(argv: string[]): RuntimeArgs | undefined {
   if (argv.length !== 2) {
     return undefined;
@@ -122,87 +250,35 @@ export function parseRuntimeArgs(argv: string[]): RuntimeArgs | undefined {
   };
 }
 
+/**
+ * Loads any supported provider kind from a package root and optional target.
+ */
 export async function loadProviderFromTarget(
   root: string,
   rawTarget?: string,
 ): Promise<LoadedProvider> {
   const config = readPackageConfig(root);
-  const targetValue =
-    rawTarget?.trim() ||
-    formatProviderTarget(
-      config.providerTarget ?? readPackageProviderTarget(root),
-    );
-  const target = parseProviderTarget(targetValue);
+  const explicitTarget = rawTarget?.trim();
+  const target = explicitTarget
+    ? parseProviderTarget(explicitTarget)
+    : config.providerTarget ?? readPackageProviderTarget(root);
+  const targetValue = explicitTarget || formatProviderTarget(target);
   const module = await import(resolveProviderImportUrl(root, target));
   const candidate =
-    (target.exportName ? module[target.exportName] : undefined) ??
-    defaultProviderExport(module, target.kind);
+    (target.exportName ? Reflect.get(module, target.exportName) : undefined) ??
+    resolveDefaultProviderExport(module, target.kind);
 
   const defaultName =
     slugName(config.name ?? "") ||
     slugName(dirname(resolve(root, target.modulePath)));
-  switch (target.kind) {
-    case "integration": {
-      if (!isIntegrationProvider(candidate)) {
-        throw new Error(
-          `${targetValue} did not resolve to a Gestalt integration provider`,
-        );
-      }
-      candidate.resolveName(defaultName);
-      return candidate;
-    }
-    case "auth": {
-      if (!isAuthProvider(candidate)) {
-        throw new Error(
-          `${targetValue} did not resolve to a Gestalt auth provider`,
-        );
-      }
-      candidate.resolveName(defaultName);
-      return candidate;
-    }
-    case "cache": {
-      if (!isCacheProvider(candidate)) {
-        throw new Error(
-          `${targetValue} did not resolve to a Gestalt cache provider`,
-        );
-      }
-      candidate.resolveName(defaultName);
-      return candidate;
-    }
-    case "secrets": {
-      if (!isSecretsProvider(candidate)) {
-        throw new Error(
-          `${targetValue} did not resolve to a Gestalt secrets provider`,
-        );
-      }
-      candidate.resolveName(defaultName);
-      return candidate;
-    }
-    case "s3": {
-      if (!isS3Provider(candidate)) {
-        throw new Error(`${targetValue} did not resolve to a Gestalt s3 provider`);
-      }
-      candidate.resolveName(defaultName);
-      return candidate;
-    }
-    default:
-      throw new Error(
-        `TypeScript SDK does not yet support provider kind ${JSON.stringify(target.kind)}`,
-      );
-  }
-}
-
-export async function loadPluginFromTarget(
-  root: string,
-  rawTarget?: string,
-): Promise<IntegrationProvider> {
-  const provider = await loadProviderFromTarget(root, rawTarget);
-  if (!isIntegrationProvider(provider)) {
-    throw new Error("target did not resolve to an integration provider");
-  }
+  const provider = resolveLoadedProvider(candidate, target.kind, targetValue);
+  provider.resolveName(defaultName);
   return provider;
 }
 
+/**
+ * Runs a provider that has already been loaded into memory.
+ */
 export async function runLoadedProvider(
   provider: LoadedProvider,
   options: {
@@ -217,102 +293,41 @@ export async function runLoadedProvider(
   }
 
   const catalogPath = process.env[ENV_WRITE_CATALOG];
-  if (catalogPath) {
-    if (!isIntegrationProvider(provider)) {
+  const manifestMetadataPath = process.env[ENV_WRITE_MANIFEST_METADATA];
+  if (catalogPath || manifestMetadataPath) {
+    if (!isPluginProvider(provider)) {
       throw new Error(
-        "static catalog generation is only supported for integration providers",
+        "static catalog and manifest metadata generation are only supported for plugin providers",
       );
     }
-    writeFileSync(catalogPath, pluginCatalogYaml(provider), "utf8");
+    if (catalogPath) {
+      writeFileSync(catalogPath, catalogToYaml(provider.staticCatalog()), "utf8");
+    }
+    if (manifestMetadataPath && provider.supportsManifestMetadata()) {
+      provider.writeManifestMetadata(manifestMetadataPath);
+    }
     return;
   }
 
   await serve(provider);
 }
 
-export async function runLoadedPlugin(
-  plugin: IntegrationProvider,
-  options: {
-    root?: string;
-    pluginName?: string;
-  } = {},
-): Promise<void> {
-  const runtimeOptions: {
-    root?: string;
-    providerName?: string;
-  } = {};
-  if (options.root !== undefined) {
-    runtimeOptions.root = options.root;
-  }
-  if (options.pluginName !== undefined) {
-    runtimeOptions.providerName = options.pluginName;
-  }
-  await runLoadedProvider(plugin, runtimeOptions);
-}
-
+/**
+ * Runs a bundled provider export after validating its provider kind.
+ */
 export async function runBundledProvider(
   provider: unknown,
   kind: ProviderKind,
   providerName: string,
 ): Promise<void> {
-  let loaded: LoadedProvider;
-  switch (kind) {
-    case "integration":
-      if (!isIntegrationProvider(provider)) {
-        throw new Error(
-          "bundled target did not resolve to a Gestalt integration provider",
-        );
-      }
-      loaded = provider;
-      break;
-    case "auth":
-      if (!isAuthProvider(provider)) {
-        throw new Error(
-          "bundled target did not resolve to a Gestalt auth provider",
-        );
-      }
-      loaded = provider;
-      break;
-    case "cache":
-      if (!isCacheProvider(provider)) {
-        throw new Error(
-          "bundled target did not resolve to a Gestalt cache provider",
-        );
-      }
-      loaded = provider;
-      break;
-    case "secrets":
-      if (!isSecretsProvider(provider)) {
-        throw new Error(
-          "bundled target did not resolve to a Gestalt secrets provider",
-        );
-      }
-      loaded = provider;
-      break;
-    case "s3":
-      if (!isS3Provider(provider)) {
-        throw new Error("bundled target did not resolve to a Gestalt s3 provider");
-      }
-      loaded = provider;
-      break;
-    default:
-      throw new Error(
-        `TypeScript SDK does not yet support provider kind ${JSON.stringify(kind)}`,
-      );
-  }
-  loaded.name = slugName(providerName);
-  await runLoadedProvider(loaded, {
+  await runLoadedProvider(resolveLoadedProvider(provider, kind, "bundled target"), {
     providerName,
   });
 }
 
-export async function runBundledPlugin(
-  plugin: unknown,
-  pluginName: string,
-): Promise<void> {
-  await runBundledProvider(plugin, "integration", pluginName);
-}
-
+/**
+ * Starts serving a provider over the Gestalt Unix socket transport.
+ */
 export async function serve(provider: LoadedProvider): Promise<void> {
   const socketPath = process.env[ENV_PROVIDER_SOCKET];
   if (!socketPath) {
@@ -328,20 +343,7 @@ export async function serve(provider: LoadedProvider): Promise<void> {
     connect: false,
     routes(router) {
       router.service(ProviderLifecycle, createRuntimeService(provider));
-      if (isIntegrationProvider(provider)) {
-        router.service(
-          IntegrationProviderService,
-          createProviderService(provider),
-        );
-      } else if (isAuthProvider(provider)) {
-        router.service(AuthProviderService, createAuthService(provider));
-      } else if (isCacheProvider(provider)) {
-        router.service(CacheService, createCacheService(provider));
-      } else if (isS3Provider(provider)) {
-        router.service(S3Service, createS3Service(provider));
-      } else if (isSecretsProvider(provider)) {
-        router.service(SecretsProviderService, createSecretsService(provider));
-      }
+      registerProviderService(router, provider);
     },
   });
 
@@ -392,13 +394,18 @@ export async function serve(provider: LoadedProvider): Promise<void> {
   }
 }
 
+/**
+ * Adapts the provider lifecycle service used during startup and health checks.
+ *
+ * @internal
+ */
 export function createRuntimeService(
   provider: LoadedProvider,
 ): Partial<ServiceImpl<typeof ProviderLifecycle>> {
   return {
     async getProviderIdentity() {
       return create(ProviderIdentitySchema, {
-        kind: providerKindToProto(provider.kind),
+        kind: providerRuntimeEntry(provider.kind).protoKind,
         name: provider.name,
         displayName: provider.displayName,
         description: provider.description,
@@ -409,12 +416,7 @@ export function createRuntimeService(
       });
     },
     async configureProvider(request: ConfigureProviderRequest) {
-      if (request.protocolVersion !== CURRENT_PROTOCOL_VERSION) {
-        throw new ConnectError(
-          `host requested protocol version ${request.protocolVersion}, provider requires ${CURRENT_PROTOCOL_VERSION}`,
-          Code.FailedPrecondition,
-        );
-      }
+      assertProtocolVersion(request.protocolVersion);
       try {
         await provider.configureProvider(
           request.name,
@@ -451,9 +453,17 @@ export function createRuntimeService(
   };
 }
 
+/**
+ * Adapts a plugin provider to the shared protocol service implementation.
+ *
+ * @internal
+ */
 export function createProviderService(
-  provider: IntegrationProvider,
+  provider: LoadedProvider,
 ): Partial<ServiceImpl<typeof IntegrationProviderService>> {
+  if (!isPluginProvider(provider)) {
+    throw new Error("provider is not a plugin provider");
+  }
   return {
     getMetadata() {
       return create(ProviderMetadataSchema, {
@@ -478,6 +488,7 @@ export function createProviderService(
       });
     },
     async startProvider(request: StartProviderRequest) {
+      assertProtocolVersion(request.protocolVersion);
       try {
         await provider.configureProvider(
           request.name,
@@ -503,6 +514,7 @@ export function createProviderService(
             request.token,
             request.connectionParams,
             request.context,
+            request.invocationToken,
           ),
         ),
       );
@@ -542,9 +554,15 @@ export function createProviderService(
   };
 }
 
-export function createAuthService(
-  provider: AuthProvider,
-): Partial<ServiceImpl<typeof AuthProviderService>> {
+/**
+ * Adapts an authentication provider to the shared protocol service
+ * implementation.
+ *
+ * @internal
+ */
+export function createAuthenticationService(
+  provider: AuthenticationProvider,
+): Partial<ServiceImpl<typeof AuthenticationProviderService>> {
   return {
     async beginLogin(request) {
       const response = await provider.beginLogin({
@@ -557,7 +575,7 @@ export function createAuthService(
       });
       if (!response) {
         throw new ConnectError(
-          "auth provider returned nil response",
+          "authentication provider returned nil response",
           Code.Internal,
         );
       }
@@ -576,7 +594,7 @@ export function createAuthService(
       });
       if (!user) {
         throw new ConnectError(
-          "auth provider returned nil user",
+          "authentication provider returned nil user",
           Code.Internal,
         );
       }
@@ -585,7 +603,7 @@ export function createAuthService(
     async validateExternalToken(request: ValidateExternalTokenRequest) {
       if (!provider.supportsExternalTokenValidation()) {
         throw new ConnectError(
-          "auth provider does not support external token validation",
+          "authentication provider does not support external token validation",
           Code.Unimplemented,
         );
       }
@@ -598,7 +616,7 @@ export function createAuthService(
     async getSessionSettings() {
       if (!provider.supportsSessionSettings()) {
         throw new ConnectError(
-          "auth provider does not expose session settings",
+          "authentication provider does not expose session settings",
           Code.Unimplemented,
         );
       }
@@ -610,6 +628,11 @@ export function createAuthService(
   };
 }
 
+/**
+ * Adapts a cache provider to the shared protocol service implementation.
+ *
+ * @internal
+ */
 export function createCacheService(
   provider: CacheProvider,
 ): Partial<ServiceImpl<typeof CacheService>> {
@@ -674,6 +697,11 @@ export function createCacheService(
   };
 }
 
+/**
+ * Adapts a secrets provider to the shared protocol service implementation.
+ *
+ * @internal
+ */
 export function createSecretsService(
   provider: SecretsProvider,
 ): Partial<ServiceImpl<typeof SecretsProviderService>> {
@@ -687,14 +715,11 @@ export function createSecretsService(
   };
 }
 
-export function pluginCatalogYaml(plugin: IntegrationProvider): string {
-  return catalogToYaml(plugin.staticCatalog());
-}
-
 function providerRequest(
   token: string,
   connectionParams: Record<string, string>,
   requestContext?: ProtoRequestContext,
+  invocationToken = "",
 ): Request {
   const subject = requestContext?.subject;
   const credential = requestContext?.credential;
@@ -720,43 +745,44 @@ function providerRequest(
       policy: access?.policy ?? "",
       role: access?.role ?? "",
     },
+    workflow: {
+      ...(requestContext?.workflow ?? {}),
+    },
+    invocationToken,
   };
 }
 
-function providerKindToProto(kind: ProviderKind): ProtoProviderKind {
-  switch (kind) {
-    case "integration":
-      return ProtoProviderKind.INTEGRATION;
-    case "auth":
-      return ProtoProviderKind.AUTH;
-    case "cache":
-      return ProtoProviderKind.CACHE;
-    case "secrets":
-      return ProtoProviderKind.SECRETS;
-    case "s3":
-      return ProtoProviderKind.S3;
-    case "telemetry":
-      return ProtoProviderKind.TELEMETRY;
-    default:
-      return ProtoProviderKind.UNSPECIFIED;
+function providerRuntimeEntry(
+  kind: ProviderKind,
+): ProviderRuntimeEntry {
+  const entry = PROVIDER_RUNTIME_ENTRIES[kind];
+  if (!entry) {
+    throw new Error(
+      `TypeScript SDK does not yet support provider kind ${JSON.stringify(kind)}`,
+    );
   }
+  return entry;
 }
 
-function defaultProviderExport(module: Record<string, unknown>, kind: ProviderKind): unknown {
-  switch (kind) {
-    case "integration":
-      return module.provider ?? module.plugin ?? module.default;
-    case "auth":
-      return module.auth ?? module.provider ?? module.default;
-    case "cache":
-      return module.cache ?? module.provider ?? module.default;
-    case "secrets":
-      return module.secrets ?? module.provider ?? module.default;
-    case "s3":
-      return module.s3 ?? module.provider ?? module.default;
-    case "telemetry":
-      return module.telemetry ?? module.provider ?? module.default;
+function resolveLoadedProvider(
+  candidate: unknown,
+  kind: ProviderKind,
+  source: string,
+): LoadedProvider {
+  const entry = providerRuntimeEntry(kind);
+  if (!entry.isProvider(candidate)) {
+    throw new Error(
+      `${source} did not resolve to a Gestalt ${providerKindLabel(kind)}`,
+    );
   }
+  return candidate;
+}
+
+function registerProviderService(
+  router: ConnectRouter,
+  provider: LoadedProvider,
+): void {
+  providerRuntimeEntry(provider.kind).registerService(router, provider);
 }
 
 function objectFromUnknown(value: unknown): Record<string, unknown> {