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

package/src/invoker.ts

@@ -0,0 +1,160 @@
+import { connect } from "node:net";
+
+import type { JsonObject, JsonValue } from "@bufbuild/protobuf";
+import { createClient, type Client } from "@connectrpc/connect";
+import { createGrpcTransport } from "@connectrpc/connect-node";
+
+import { PluginInvoker as PluginInvokerService } from "../gen/v1/plugin_pb.ts";
+import type { OperationResult, Request } from "./api.ts";
+
+export const ENV_PLUGIN_INVOKER_SOCKET = "GESTALT_PLUGIN_INVOKER_SOCKET";
+
+export interface PluginInvokeOptions {
+  connection?: string;
+  instance?: string;
+}
+
+export interface PluginInvocationGrant {
+  plugin: string;
+  operations?: string[];
+  surfaces?: string[];
+  allOperations?: boolean;
+}
+
+export interface PluginGraphQLInvokeOptions extends PluginInvokeOptions {
+  variables?: Record<string, unknown>;
+}
+
+export class PluginInvoker {
+  private readonly client: Client<typeof PluginInvokerService>;
+  private readonly invocationToken: string;
+
+  constructor(request: Request);
+  constructor(invocationToken: string);
+  constructor(requestOrToken: Request | string) {
+    this.invocationToken = normalizeInvocationToken(requestOrToken);
+
+    const socketPath = process.env[ENV_PLUGIN_INVOKER_SOCKET];
+    if (!socketPath) {
+      throw new Error(`plugin invoker: ${ENV_PLUGIN_INVOKER_SOCKET} is not set`);
+    }
+
+    const transport = createGrpcTransport({
+      baseUrl: "http://localhost",
+      nodeOptions: {
+        createConnection: () => connect(socketPath),
+      },
+    });
+    this.client = createClient(PluginInvokerService, transport);
+  }
+
+  async invoke(
+    plugin: string,
+    operation: string,
+    params: Record<string, unknown> = {},
+    options?: PluginInvokeOptions,
+  ): Promise<OperationResult> {
+    const response = await this.client.invoke({
+      invocationToken: this.invocationToken,
+      plugin,
+      operation,
+      params: toJsonObject(params),
+      connection: options?.connection ?? "",
+      instance: options?.instance ?? "",
+    });
+    return {
+      status: response.status,
+      body: response.body,
+    };
+  }
+
+  async invokeGraphQL(
+    plugin: string,
+    document: string,
+    options?: PluginGraphQLInvokeOptions,
+  ): Promise<OperationResult> {
+    const trimmedDocument = document.trim();
+    if (!trimmedDocument) {
+      throw new Error("plugin invoker: graphql document is required");
+    }
+
+    const response = await this.client.invokeGraphQL({
+      invocationToken: this.invocationToken,
+      plugin,
+      document: trimmedDocument,
+      ...(options?.variables
+        ? { variables: toJsonObject(options.variables) }
+        : {}),
+      connection: options?.connection ?? "",
+      instance: options?.instance ?? "",
+    });
+    return {
+      status: response.status,
+      body: response.body,
+    };
+  }
+
+  async exchangeInvocationToken(options?: {
+    grants?: PluginInvocationGrant[];
+    ttlSeconds?: number;
+  }): Promise<string> {
+    const response = await this.client.exchangeInvocationToken({
+      parentInvocationToken: this.invocationToken,
+      grants: (options?.grants ?? [])
+        .map((grant) => ({
+          plugin: grant.plugin.trim(),
+          operations: (grant.operations ?? [])
+            .map((operation) => operation.trim())
+            .filter(Boolean),
+          surfaces: (grant.surfaces ?? [])
+            .map((surface) => surface.trim().toLowerCase())
+            .filter(Boolean),
+          allOperations: grant.allOperations ?? false,
+        }))
+        .filter((grant) => grant.plugin.length > 0),
+      ttlSeconds: BigInt(Math.max(0, options?.ttlSeconds ?? 0)),
+    });
+    return response.invocationToken;
+  }
+}
+
+function normalizeInvocationToken(requestOrToken: Request | string): string {
+  const invocationToken =
+    typeof requestOrToken === "string"
+      ? requestOrToken
+      : requestOrToken.invocationToken;
+  const trimmed = invocationToken.trim();
+  if (!trimmed) {
+    throw new Error("plugin invoker: invocation token is not available");
+  }
+  return trimmed;
+}
+
+function toJsonObject(params: Record<string, unknown>): JsonObject {
+  const output: JsonObject = {};
+  for (const [key, value] of Object.entries(params ?? {})) {
+    if (value === undefined) {
+      continue;
+    }
+    output[key] = toJsonValue(value);
+  }
+  return output;
+}
+
+function toJsonValue(value: unknown): JsonValue {
+  if (
+    value === null ||
+    typeof value === "string" ||
+    typeof value === "number" ||
+    typeof value === "boolean"
+  ) {
+    return value as JsonValue;
+  }
+  if (Array.isArray(value)) {
+    return value.map((entry) => toJsonValue(entry));
+  }
+  if (typeof value === "object") {
+    return toJsonObject(value as Record<string, unknown>);
+  }
+  throw new Error("plugin invoker: params must be JSON-serializable");
+}

package/src/manifest-metadata.ts

@@ -0,0 +1,101 @@
+import { writeFileSync } from "node:fs";
+
+import YAML from "yaml";
+
+export type HTTPSecuritySchemeType =
+  | "slack_signature"
+  | "apiKey"
+  | "http"
+  | "none";
+
+export type HTTPIn = "header" | "query";
+
+export type HTTPAuthScheme = "basic" | "bearer";
+
+export interface HTTPSecretRef {
+  env?: string;
+  secret?: string;
+}
+
+export interface HTTPSecurityScheme {
+  type?: HTTPSecuritySchemeType;
+  description?: string;
+  name?: string;
+  in?: HTTPIn;
+  scheme?: HTTPAuthScheme;
+  secret?: HTTPSecretRef;
+}
+
+export interface HTTPMediaType {}
+
+export interface HTTPRequestBody {
+  required?: boolean;
+  content?: Record<string, HTTPMediaType>;
+}
+
+export interface HTTPAck {
+  status?: number;
+  headers?: Record<string, string>;
+  body?: any;
+}
+
+export interface HTTPBinding {
+  path: string;
+  method: string;
+  requestBody?: HTTPRequestBody;
+  security: string;
+  target: string;
+  ack?: HTTPAck;
+}
+
+export interface PluginManifestMetadata {
+  securitySchemes?: Record<string, HTTPSecurityScheme>;
+  http?: Record<string, HTTPBinding>;
+}
+
+export function hasPluginManifestMetadata(
+  metadata: PluginManifestMetadata | null | undefined,
+): boolean {
+  return !!(
+    metadata &&
+    ((metadata.securitySchemes &&
+      Object.keys(metadata.securitySchemes).length > 0) ||
+      (metadata.http && Object.keys(metadata.http).length > 0))
+  );
+}
+
+export function manifestMetadataToYaml(
+  metadata: PluginManifestMetadata | Record<string, unknown>,
+): string {
+  return YAML.stringify(toManifestMetadataJsonObject(metadata));
+}
+
+export function writeManifestMetadataYaml(
+  path: string,
+  metadata: PluginManifestMetadata | Record<string, unknown>,
+): void {
+  writeFileSync(path, manifestMetadataToYaml(metadata), "utf8");
+}
+
+function toManifestMetadataJsonObject(
+  metadata: PluginManifestMetadata | Record<string, unknown>,
+): Record<string, unknown> {
+  if (!("securitySchemes" in metadata) && !("http" in metadata)) {
+    return {
+      ...metadata,
+    };
+  }
+
+  const typedMetadata = metadata as PluginManifestMetadata;
+  const output: Record<string, unknown> = {};
+  if (
+    typedMetadata.securitySchemes &&
+    Object.keys(typedMetadata.securitySchemes).length > 0
+  ) {
+    output.securitySchemes = typedMetadata.securitySchemes;
+  }
+  if (typedMetadata.http && Object.keys(typedMetadata.http).length > 0) {
+    output.http = typedMetadata.http;
+  }
+  return output;
+}

package/src/plugin.ts

@@ -7,6 +7,15 @@ import {
   schemaToParameters,
   writeCatalogYaml,
 } from "./catalog.ts";
+import {
+  type HTTPAck,
+  type HTTPBinding,
+  type HTTPRequestBody,
+  type HTTPSecurityScheme,
+  type PluginManifestMetadata,
+  hasPluginManifestMetadata,
+  writeManifestMetadataYaml,
+} from "./manifest-metadata.ts";
 import {
   errorMessage,
   type MaybePromise,
@@ -18,13 +27,18 @@ import {
 import { RuntimeProvider, type RuntimeProviderOptions } from "./provider.ts";
 import type { Schema } from "./schema.ts";
 
+/**
+ * How a plugin provider expects to authenticate or connect.
+ */
 export type ConnectionMode =
   | "unspecified"
   | "none"
   | "user"
-  | "identity"
-  | "either";
+  | "identity";
 
+/**
+ * Metadata for a single connection parameter exposed by a provider.
+ */
 export interface ConnectionParamDefinition {
   required?: boolean;
   description?: string;
@@ -33,6 +47,9 @@ export interface ConnectionParamDefinition {
   field?: string;
 }
 
+/**
+ * Operation definition accepted by {@link operation} and {@link definePlugin}.
+ */
 export interface OperationOptions<In, Out> {
   id: string;
   method?: string;
@@ -47,27 +64,43 @@ export interface OperationOptions<In, Out> {
   handler: (input: In, request: Request) => MaybePromise<Out | Response<Out>>;
 }
 
+/**
+ * Normalized plugin operation definition.
+ */
 export interface OperationDefinition<In, Out> extends OperationOptions<
   In,
   Out
 > {}
 
+/**
+ * Session-specific catalog payload returned by a provider at runtime.
+ */
 export type SessionCatalog = Catalog | Record<string, unknown>;
+
+/**
+ * Callback used to resolve a catalog for an authenticated request context.
+ */
 export type SessionCatalogHandler = (
   request: Request,
 ) => MaybePromise<SessionCatalog | null | undefined>;
 
+/**
+ * Runtime hooks required to implement a plugin provider.
+ */
 export interface PluginDefinitionOptions extends RuntimeProviderOptions {
   connectionMode?: ConnectionMode;
   authTypes?: string[];
   connectionParams?: Record<string, ConnectionParamDefinition>;
+  securitySchemes?: Record<string, HTTPSecurityScheme>;
+  http?: Record<string, HTTPBinding>;
   iconSvg?: string;
   operations: Array<OperationDefinition<any, any>>;
   sessionCatalog?: SessionCatalogHandler;
 }
 
-export type IntegrationProviderOptions = PluginDefinitionOptions;
-
+/**
+ * Normalizes a plugin operation definition.
+ */
 export function operation<In, Out>(
   options: OperationOptions<In, Out>,
 ): OperationDefinition<In, Out> {
@@ -82,18 +115,41 @@ export function operation<In, Out>(
   };
 }
 
-export class IntegrationProvider extends RuntimeProvider {
+/**
+ * Plugin provider implementation consumed by the Gestalt runtime.
+ *
+ * @example
+ * ```ts
+ * import { definePlugin, ok, operation, s } from "@valon-technologies/gestalt";
+ *
+ * export const plugin = definePlugin({
+ *   displayName: "Example Provider",
+ *   operations: [
+ *     operation({
+ *       id: "ping",
+ *       method: "GET",
+ *       readOnly: true,
+ *       input: s.object({ name: s.string({ default: "World" }) }),
+ *       output: s.object({ message: s.string() }),
+ *       async handler(input) {
+ *         return ok({ message: `Hello, ${input.name}` });
+ *       },
+ *     }),
+ *   ],
+ * });
+ * ```
+ */
+export class PluginProvider extends RuntimeProvider {
   readonly kind = "integration" as const;
   readonly iconSvg: string;
   readonly connectionMode: ConnectionMode;
   readonly authTypes: string[];
   readonly connectionParams: Record<string, ConnectionParamDefinition>;
+  readonly securitySchemes: Record<string, HTTPSecurityScheme>;
+  readonly http: Record<string, HTTPBinding>;
 
   private readonly sessionCatalogHandler: SessionCatalogHandler | undefined;
-  private readonly operations = new Map<
-    string,
-    OperationDefinition<any, any>
-  >();
+  private readonly operations = new Map<string, OperationDefinition<any, any>>();
 
   constructor(options: PluginDefinitionOptions) {
     super(options);
@@ -101,38 +157,41 @@ export class IntegrationProvider extends RuntimeProvider {
     this.connectionMode = options.connectionMode ?? "unspecified";
     this.authTypes = [...(options.authTypes ?? [])];
     this.connectionParams = normalizeConnectionParams(options.connectionParams);
+    this.securitySchemes = normalizeHTTPSecuritySchemes(options.securitySchemes);
+    this.http = normalizeHTTPBindings(options.http);
     this.sessionCatalogHandler = options.sessionCatalog;
 
-    for (const entry of options.operations) {
-      const id = entry.id.trim();
-      if (!id) {
+    for (const rawEntry of options.operations) {
+      const entry = operation(rawEntry);
+      if (!entry.id) {
         throw new Error("operation id is required");
       }
-      if (this.operations.has(id)) {
-        throw new Error(`duplicate operation id ${JSON.stringify(id)}`);
+      if (this.operations.has(entry.id)) {
+        throw new Error(`duplicate operation id ${JSON.stringify(entry.id)}`);
       }
-      this.operations.set(id, {
-        ...entry,
-        id,
-        method: normalizeMethod(entry.method),
-        title: entry.title?.trim() ?? "",
-        description: entry.description?.trim() ?? "",
-        allowedRoles: normalizeAllowedRoles(entry.allowedRoles),
-        tags: [...(entry.tags ?? [])],
-      });
+      this.operations.set(entry.id, entry);
     }
   }
 
+  /**
+   * Reports whether the provider exposes a session-specific catalog.
+   */
   supportsSessionCatalog(): boolean {
     return this.sessionCatalogHandler !== undefined;
   }
 
+  /**
+   * Resolves a catalog for the current request context, if configured.
+   */
   async catalogForRequest(
     request: Request,
   ): Promise<SessionCatalog | null | undefined> {
     return await this.sessionCatalogHandler?.(request);
   }
 
+  /**
+   * Returns the static catalog emitted during provider startup.
+   */
   staticCatalog(): Catalog {
     const catalog: Catalog = {
       operations: [...this.operations.values()].map<CatalogOperation>(
@@ -197,14 +256,55 @@ export class IntegrationProvider extends RuntimeProvider {
     return catalog;
   }
 
+  /**
+   * Writes the provider's static catalog to disk as YAML.
+   */
   writeCatalog(path: string): void {
     writeCatalogYaml(path, this.staticCatalog());
   }
 
+  /**
+   * Returns the static catalog serialized as JSON.
+   */
   catalogJson(): string {
     return catalogToJson(this.staticCatalog());
   }
 
+  /**
+   * Returns generated manifest-backed HTTP/security metadata for the provider.
+   */
+  staticManifestMetadata(): PluginManifestMetadata {
+    const metadata: PluginManifestMetadata = {};
+    if (Object.keys(this.securitySchemes).length > 0) {
+      metadata.securitySchemes = cloneHTTPSecuritySchemes(this.securitySchemes);
+    }
+    if (Object.keys(this.http).length > 0) {
+      metadata.http = cloneHTTPBindings(this.http);
+    }
+    return metadata;
+  }
+
+  /**
+   * Reports whether the provider emits manifest metadata in addition to catalog metadata.
+   */
+  supportsManifestMetadata(): boolean {
+    return hasPluginManifestMetadata(this.staticManifestMetadata());
+  }
+
+  /**
+   * Writes generated manifest metadata to disk as YAML.
+   */
+  writeManifestMetadata(path: string): void {
+    const metadata = this.staticManifestMetadata();
+    if (!hasPluginManifestMetadata(metadata)) {
+      return;
+    }
+    writeManifestMetadataYaml(path, metadata);
+  }
+
+  /**
+   * Executes an operation against validated input and request metadata.
+   */
   async execute(
     operationId: string,
     params: Record<string, unknown>,
@@ -244,25 +344,23 @@ export class IntegrationProvider extends RuntimeProvider {
   }
 }
 
-export const Plugin = IntegrationProvider;
-
-export function defineIntegrationProvider(
-  options: PluginDefinitionOptions,
-): IntegrationProvider {
-  return new IntegrationProvider(options);
-}
-
+/**
+ * Creates a plugin provider.
+ */
 export function definePlugin(
   options: PluginDefinitionOptions,
-): IntegrationProvider {
-  return new IntegrationProvider(options);
+): PluginProvider {
+  return new PluginProvider(options);
 }
 
-export function isIntegrationProvider(
+/**
+ * Runtime type guard for plugin providers loaded from user modules.
+ */
+export function isPluginProvider(
   value: unknown,
-): value is IntegrationProvider {
+): value is PluginProvider {
   return (
-    value instanceof IntegrationProvider ||
+    value instanceof PluginProvider ||
     (typeof value === "object" &&
       value !== null &&
       "kind" in value &&
@@ -298,6 +396,121 @@ function normalizeConnectionParams(
   return output;
 }
 
+function normalizeHTTPSecuritySchemes(
+  input: Record<string, HTTPSecurityScheme> | undefined,
+): Record<string, HTTPSecurityScheme> {
+  const output: Record<string, HTTPSecurityScheme> = {};
+  for (const [key, value] of Object.entries(input ?? {})) {
+    output[key] = cloneHTTPSecurityScheme(value);
+  }
+  return output;
+}
+
+function cloneHTTPSecuritySchemes(
+  input: Record<string, HTTPSecurityScheme>,
+): Record<string, HTTPSecurityScheme> {
+  const output: Record<string, HTTPSecurityScheme> = {};
+  for (const [key, value] of Object.entries(input)) {
+    output[key] = cloneHTTPSecurityScheme(value);
+  }
+  return output;
+}
+
+function cloneHTTPSecurityScheme(value: HTTPSecurityScheme): HTTPSecurityScheme {
+  const output: HTTPSecurityScheme = {};
+  if (value.type !== undefined) {
+    output.type = value.type;
+  }
+  if (value.description !== undefined) {
+    output.description = value.description;
+  }
+  if (value.name !== undefined) {
+    output.name = value.name;
+  }
+  if (value.in !== undefined) {
+    output.in = value.in;
+  }
+  if (value.scheme !== undefined) {
+    output.scheme = value.scheme;
+  }
+  if (value.secret) {
+    output.secret = {
+      ...value.secret,
+    };
+  }
+  return output;
+}
+
+function normalizeHTTPBindings(
+  input: Record<string, HTTPBinding> | undefined,
+): Record<string, HTTPBinding> {
+  const output: Record<string, HTTPBinding> = {};
+  for (const [key, value] of Object.entries(input ?? {})) {
+    output[key] = cloneHTTPBinding(value);
+  }
+  return output;
+}
+
+function cloneHTTPBindings(
+  input: Record<string, HTTPBinding>,
+): Record<string, HTTPBinding> {
+  const output: Record<string, HTTPBinding> = {};
+  for (const [key, value] of Object.entries(input)) {
+    output[key] = cloneHTTPBinding(value);
+  }
+  return output;
+}
+
+function cloneHTTPBinding(value: HTTPBinding): HTTPBinding {
+  const output: HTTPBinding = {
+    path: value.path,
+    method: value.method,
+    security: value.security,
+    target: value.target,
+  };
+  if (value.requestBody) {
+    output.requestBody = cloneHTTPRequestBody(value.requestBody);
+  }
+  if (value.ack) {
+    output.ack = cloneHTTPAck(value.ack);
+  }
+  return output;
+}
+
+function cloneHTTPRequestBody(value: HTTPRequestBody): HTTPRequestBody {
+  const output: HTTPRequestBody = {};
+  if (value.required !== undefined) {
+    output.required = value.required;
+  }
+  if (value.content) {
+    output.content = {};
+    for (const key of Object.keys(value.content)) {
+      output.content[key] = {};
+    }
+  }
+  return output;
+}
+
+function cloneHTTPAck(value: HTTPAck): HTTPAck {
+  const output: HTTPAck = {};
+  if (value.status !== undefined) {
+    output.status = value.status;
+  }
+  if (value.headers) {
+    output.headers = {
+      ...value.headers,
+    };
+  }
+  if (value.body !== undefined) {
+    output.body = cloneHTTPBodyValue(value.body);
+  }
+  return output;
+}
+
+function cloneHTTPBodyValue<T>(value: T): T {
+  return structuredClone(value);
+}
+
 function isResponse(value: unknown): value is Response<unknown> {
   if (typeof value !== "object" || value === null) {
     return false;
@@ -353,6 +566,9 @@ function errorResult(status: number, message: string): OperationResult {
   };
 }
 
+/**
+ * Converts a connection mode into the shared protocol enum value.
+ */
 export function connectionModeToProtoValue(mode: ConnectionMode): number {
   switch (mode) {
     case "none":
@@ -361,14 +577,15 @@ export function connectionModeToProtoValue(mode: ConnectionMode): number {
       return 2;
     case "identity":
       return 3;
-    case "either":
-      return 4;
     case "unspecified":
     default:
       return 0;
   }
 }
 
+/**
+ * Converts a connection parameter definition into protocol wire metadata.
+ */
 export function connectionParamToProto(value: ConnectionParamDefinition): {
   required?: boolean;
   description?: string;