@valon-technologies/gestalt 0.0.1-alpha.1

package/src/cache.ts

@@ -0,0 +1,304 @@
+import { connect } from "node:net";
+
+import { createClient, type Client } from "@connectrpc/connect";
+import { createGrpcTransport } from "@connectrpc/connect-node";
+
+import { Cache as CacheService } from "../gen/v1/cache_pb.ts";
+import { RuntimeProvider, type RuntimeProviderOptions } from "./provider.ts";
+import type { MaybePromise } from "./api.ts";
+
+const ENV_CACHE_SOCKET = "GESTALT_CACHE_SOCKET";
+
+export interface CacheEntry {
+  key: string;
+  value: Uint8Array;
+}
+
+export interface CacheSetOptions {
+  ttlMs?: number;
+}
+
+export interface CacheProviderOptions extends RuntimeProviderOptions {
+  get: (key: string) => MaybePromise<Uint8Array | null | undefined>;
+  set: (
+    key: string,
+    value: Uint8Array,
+    options?: CacheSetOptions,
+  ) => MaybePromise<void>;
+  delete: (key: string) => MaybePromise<boolean>;
+  touch: (key: string, ttlMs: number) => MaybePromise<boolean>;
+  getMany?: (keys: string[]) => MaybePromise<Record<string, Uint8Array>>;
+  setMany?: (
+    entries: CacheEntry[],
+    options?: CacheSetOptions,
+  ) => MaybePromise<void>;
+  deleteMany?: (keys: string[]) => MaybePromise<number | bigint>;
+}
+
+export function cacheSocketEnv(name?: string): string {
+  const trimmed = name?.trim() ?? "";
+  if (!trimmed) {
+    return ENV_CACHE_SOCKET;
+  }
+  return `${ENV_CACHE_SOCKET}_${trimmed.replace(/[^A-Za-z0-9]/gu, "_").toUpperCase()}`;
+}
+
+export class Cache {
+  private readonly client: Client<typeof CacheService>;
+
+  constructor(name?: string) {
+    const envName = cacheSocketEnv(name);
+    const socketPath = process.env[envName];
+    if (!socketPath) {
+      throw new Error(`cache: ${envName} is not set`);
+    }
+
+    const transport = createGrpcTransport({
+      baseUrl: "http://localhost",
+      nodeOptions: {
+        createConnection: () => connect(socketPath),
+      },
+    });
+    this.client = createClient(CacheService, transport);
+  }
+
+  async get(key: string): Promise<Uint8Array | undefined> {
+    const response = await this.client.get({
+      key,
+    });
+    if (!response.found) {
+      return undefined;
+    }
+    return cloneBytes(response.value);
+  }
+
+  async getMany(keys: string[]): Promise<Record<string, Uint8Array>> {
+    const response = await this.client.getMany({
+      keys: [...keys],
+    });
+    return entriesToRecord(response.entries);
+  }
+
+  async set(
+    key: string,
+    value: Uint8Array,
+    options?: CacheSetOptions,
+  ): Promise<void> {
+    const ttl = toProtoDuration(options?.ttlMs);
+    await this.client.set({
+      key,
+      value: cloneBytes(value),
+      ...(ttl ? { ttl } : {}),
+    });
+  }
+
+  async setMany(
+    entries: Iterable<CacheEntry>,
+    options?: CacheSetOptions,
+  ): Promise<void> {
+    const ttl = toProtoDuration(options?.ttlMs);
+    await this.client.setMany({
+      entries: cloneEntries(entries),
+      ...(ttl ? { ttl } : {}),
+    });
+  }
+
+  async delete(key: string): Promise<boolean> {
+    const response = await this.client.delete({
+      key,
+    });
+    return response.deleted;
+  }
+
+  async deleteMany(keys: string[]): Promise<number | bigint> {
+    const response = await this.client.deleteMany({
+      keys: [...keys],
+    });
+    return toJsInt(response.deleted);
+  }
+
+  async touch(key: string, ttlMs: number): Promise<boolean> {
+    const ttl = toProtoDuration(ttlMs);
+    const response = await this.client.touch({
+      key,
+      ...(ttl ? { ttl } : {}),
+    });
+    return response.touched;
+  }
+}
+
+export class CacheProvider extends RuntimeProvider {
+  readonly kind = "cache" as const;
+
+  private readonly getHandler: CacheProviderOptions["get"];
+  private readonly setHandler: CacheProviderOptions["set"];
+  private readonly deleteHandler: CacheProviderOptions["delete"];
+  private readonly touchHandler: CacheProviderOptions["touch"];
+  private readonly getManyHandler: CacheProviderOptions["getMany"];
+  private readonly setManyHandler: CacheProviderOptions["setMany"];
+  private readonly deleteManyHandler: CacheProviderOptions["deleteMany"];
+
+  constructor(options: CacheProviderOptions) {
+    super(options);
+    this.getHandler = options.get;
+    this.setHandler = options.set;
+    this.deleteHandler = options.delete;
+    this.touchHandler = options.touch;
+    this.getManyHandler = options.getMany;
+    this.setManyHandler = options.setMany;
+    this.deleteManyHandler = options.deleteMany;
+  }
+
+  async get(key: string): Promise<Uint8Array | undefined> {
+    const value = await this.getHandler(key);
+    if (value == null) {
+      return undefined;
+    }
+    return cloneBytes(value);
+  }
+
+  async getMany(keys: string[]): Promise<Record<string, Uint8Array>> {
+    if (this.getManyHandler) {
+      return cloneRecord(await this.getManyHandler([...keys]));
+    }
+    const values = createCacheRecord();
+    for (const key of keys) {
+      const value = await this.get(key);
+      if (value !== undefined) {
+        values[key] = cloneBytes(value);
+      }
+    }
+    return values;
+  }
+
+  async set(
+    key: string,
+    value: Uint8Array,
+    options?: CacheSetOptions,
+  ): Promise<void> {
+    await this.setHandler(key, cloneBytes(value), cloneSetOptions(options));
+  }
+
+  async setMany(
+    entries: Iterable<CacheEntry>,
+    options?: CacheSetOptions,
+  ): Promise<void> {
+    if (this.setManyHandler) {
+      await this.setManyHandler(cloneEntries(entries), cloneSetOptions(options));
+      return;
+    }
+    for (const entry of entries) {
+      await this.set(entry.key, entry.value, options);
+    }
+  }
+
+  async delete(key: string): Promise<boolean> {
+    return await this.deleteHandler(key);
+  }
+
+  async deleteMany(keys: string[]): Promise<number | bigint> {
+    if (this.deleteManyHandler) {
+      return await this.deleteManyHandler([...keys]);
+    }
+    let deleted = 0;
+    const seen = new Set<string>();
+    for (const key of keys) {
+      if (seen.has(key)) {
+        continue;
+      }
+      seen.add(key);
+      if (await this.delete(key)) {
+        deleted += 1;
+      }
+    }
+    return deleted;
+  }
+
+  async touch(key: string, ttlMs: number): Promise<boolean> {
+    return await this.touchHandler(key, ttlMs);
+  }
+}
+
+export function defineCacheProvider(options: CacheProviderOptions): CacheProvider {
+  return new CacheProvider(options);
+}
+
+export function isCacheProvider(value: unknown): value is CacheProvider {
+  return (
+    value instanceof CacheProvider ||
+    (typeof value === "object" &&
+      value !== null &&
+      "kind" in value &&
+      (value as { kind?: unknown }).kind === "cache" &&
+      "get" in value &&
+      "set" in value &&
+      "delete" in value &&
+      "touch" in value)
+  );
+}
+
+function cloneBytes(value: Uint8Array | ArrayBuffer): Uint8Array {
+  if (value instanceof Uint8Array) {
+    return new Uint8Array(value);
+  }
+  return new Uint8Array(value);
+}
+
+function cloneEntries(entries: Iterable<CacheEntry>): CacheEntry[] {
+  return [...entries].map((entry) => ({
+    key: entry.key,
+    value: cloneBytes(entry.value),
+  }));
+}
+
+function cloneRecord(entries: Record<string, Uint8Array>): Record<string, Uint8Array> {
+  const cloned = createCacheRecord();
+  for (const [key, value] of Object.entries(entries)) {
+    cloned[key] = cloneBytes(value);
+  }
+  return cloned;
+}
+
+function cloneSetOptions(options?: CacheSetOptions): CacheSetOptions | undefined {
+  if (!options || options.ttlMs === undefined) {
+    return undefined;
+  }
+  return {
+    ttlMs: options.ttlMs,
+  };
+}
+
+function entriesToRecord(
+  entries: ReadonlyArray<{ key: string; found: boolean; value: Uint8Array }>,
+): Record<string, Uint8Array> {
+  const values = createCacheRecord();
+  for (const entry of entries) {
+    if (!entry.found) {
+      continue;
+    }
+    values[entry.key] = cloneBytes(entry.value);
+  }
+  return values;
+}
+
+function createCacheRecord(): Record<string, Uint8Array> {
+  return Object.create(null) as Record<string, Uint8Array>;
+}
+
+function toProtoDuration(ttlMs: number | undefined): { seconds: bigint; nanos: number } | undefined {
+  if (ttlMs === undefined || !Number.isFinite(ttlMs) || ttlMs <= 0) {
+    return undefined;
+  }
+  const wholeMs = Math.trunc(ttlMs);
+  const seconds = Math.trunc(wholeMs / 1000);
+  const nanos = Math.trunc((wholeMs % 1000) * 1_000_000);
+  return {
+    seconds: BigInt(seconds),
+    nanos,
+  };
+}
+
+function toJsInt(value: bigint): number | bigint {
+  const asNumber = Number(value);
+  return Number.isSafeInteger(asNumber) ? asNumber : value;
+}

package/src/catalog.ts

@@ -0,0 +1,188 @@
+import { writeFileSync } from "node:fs";
+
+import YAML from "yaml";
+
+import type { Schema } from "./schema.ts";
+
+export interface CatalogParameter {
+  name: string;
+  type: string;
+  description?: string;
+  required?: boolean;
+  default?: unknown;
+}
+
+export interface CatalogSchema {
+  type: string;
+  description?: string;
+  default?: unknown;
+  properties?: Record<string, CatalogSchema>;
+  required?: string[];
+  items?: CatalogSchema;
+}
+
+export interface CatalogOperation {
+  id: string;
+  method: string;
+  title?: string;
+  description?: string;
+  parameters?: CatalogParameter[];
+  inputSchema?: CatalogSchema;
+  outputSchema?: CatalogSchema;
+  tags?: string[];
+  readOnly?: boolean;
+  visible?: boolean;
+  allowedRoles?: string[];
+}
+
+export interface Catalog {
+  name?: string;
+  displayName?: string;
+  description?: string;
+  iconSvg?: string;
+  operations: CatalogOperation[];
+}
+
+export function schemaToParameters(
+  schema: Schema<unknown> | undefined,
+): CatalogParameter[] {
+  if (!schema?.fields) {
+    return [];
+  }
+  return Object.entries(schema.fields).map(([name, field]) => {
+    const parameter: CatalogParameter = {
+      name,
+      type: field.catalogType,
+    };
+    if (field.description) {
+      parameter.description = field.description;
+    }
+    if (field.required) {
+      parameter.required = true;
+    }
+    if (field.defaultValue !== undefined) {
+      parameter.default = field.defaultValue;
+    }
+    return parameter;
+  });
+}
+
+export function schemaToCatalogSchema(
+  schema: Schema<unknown> | undefined,
+): CatalogSchema | undefined {
+  if (!schema) {
+    return undefined;
+  }
+  const output: CatalogSchema = {
+    type: schema.catalogType,
+  };
+  if (schema.description) {
+    output.description = schema.description;
+  }
+  if (schema.defaultValue !== undefined) {
+    output.default = schema.defaultValue;
+  }
+  if (schema.fields) {
+    const properties: Record<string, CatalogSchema> = {};
+    const required: string[] = [];
+    for (const [name, field] of Object.entries(schema.fields)) {
+      properties[name] = schemaToCatalogSchema(field)!;
+      if (field.required) {
+        required.push(name);
+      }
+    }
+    output.properties = properties;
+    if (required.length > 0) {
+      output.required = required;
+    }
+  }
+  if (schema.item) {
+    output.items = schemaToCatalogSchema(schema.item)!;
+  }
+  return output;
+}
+
+export function catalogToJson(
+  catalog: Catalog | Record<string, unknown> | null | undefined,
+): string {
+  if (!catalog) {
+    return "";
+  }
+  return JSON.stringify(toCatalogJsonObject(catalog));
+}
+
+export function catalogToYaml(
+  catalog: Catalog | Record<string, unknown>,
+): string {
+  return YAML.stringify(toCatalogJsonObject(catalog));
+}
+
+export function writeCatalogYaml(
+  path: string,
+  catalog: Catalog | Record<string, unknown>,
+): void {
+  writeFileSync(path, catalogToYaml(catalog), "utf8");
+}
+
+function toCatalogJsonObject(
+  catalog: Catalog | Record<string, unknown>,
+): Record<string, unknown> {
+  if (!("operations" in catalog) || !Array.isArray(catalog.operations)) {
+    return {
+      ...catalog,
+    };
+  }
+
+  const typedCatalog = catalog as Catalog;
+  const output: Record<string, unknown> = {
+    operations: typedCatalog.operations.map((operation) => {
+      const serialized: Record<string, unknown> = {
+        id: operation.id,
+        method: operation.method,
+      };
+      if (operation.title) {
+        serialized.title = operation.title;
+      }
+      if (operation.description) {
+        serialized.description = operation.description;
+      }
+      if (operation.parameters && operation.parameters.length > 0) {
+        serialized.parameters = operation.parameters;
+      }
+      if (operation.inputSchema !== undefined) {
+        serialized.inputSchema = operation.inputSchema;
+      }
+      if (operation.outputSchema !== undefined) {
+        serialized.outputSchema = operation.outputSchema;
+      }
+      if (operation.tags && operation.tags.length > 0) {
+        serialized.tags = operation.tags;
+      }
+      if (operation.readOnly !== undefined) {
+        serialized.readOnly = operation.readOnly;
+      }
+      if (operation.visible !== undefined) {
+        serialized.visible = operation.visible;
+      }
+      if (operation.allowedRoles && operation.allowedRoles.length > 0) {
+        serialized.allowedRoles = operation.allowedRoles;
+      }
+      return serialized;
+    }),
+  };
+
+  if (typedCatalog.name) {
+    output.name = typedCatalog.name;
+  }
+  if (typedCatalog.displayName) {
+    output.displayName = typedCatalog.displayName;
+  }
+  if (typedCatalog.description) {
+    output.description = typedCatalog.description;
+  }
+  if (typedCatalog.iconSvg) {
+    output.iconSvg = typedCatalog.iconSvg;
+  }
+
+  return output;
+}

package/src/index.ts

@@ -0,0 +1,182 @@
+export {
+  connectionParam,
+  ok,
+  response,
+  responseBrand,
+  request,
+  type Access,
+  type MaybePromise,
+  type Credential,
+  type OperationResult,
+  type Request,
+  type Response,
+  type Subject,
+} from "./api.ts";
+export {
+  catalogToJson,
+  catalogToYaml,
+  schemaToCatalogSchema,
+  schemaToParameters,
+  writeCatalogYaml,
+  type Catalog,
+  type CatalogOperation,
+  type CatalogParameter,
+  type CatalogSchema,
+} from "./catalog.ts";
+export {
+  buildPluginBinary,
+  buildProviderBinary,
+  bunBuildCommand,
+  bunTarget,
+  parseBuildArgs,
+} from "./build.ts";
+export {
+  defineAuthProvider,
+  isAuthProvider,
+  type AuthenticatedUser,
+  type AuthProviderOptions,
+  type AuthSessionSettings,
+  type BeginLoginRequest,
+  type BeginLoginResponse,
+  type CompleteLoginRequest,
+} from "./auth.ts";
+export {
+  Cache,
+  CacheProvider,
+  cacheSocketEnv,
+  defineCacheProvider,
+  isCacheProvider,
+  type CacheEntry,
+  type CacheProviderOptions,
+  type CacheSetOptions,
+} from "./cache.ts";
+export {
+  defineSecretsProvider,
+  isSecretsProvider,
+  type SecretsProviderOptions,
+} from "./secrets.ts";
+export {
+  Plugin,
+  connectionModeToProtoValue,
+  connectionParamToProto,
+  defineIntegrationProvider,
+  definePlugin,
+  isIntegrationProvider,
+  operation,
+  type ConnectionMode,
+  type ConnectionParamDefinition,
+  type IntegrationProviderOptions,
+  type OperationDefinition,
+  type OperationOptions,
+  type PluginDefinitionOptions,
+  type SessionCatalog,
+  type SessionCatalogHandler,
+} from "./plugin.ts";
+export {
+  RuntimeProvider,
+  isRuntimeProvider,
+  slugName,
+  type CloseHandler,
+  type ConfigureHandler,
+  type HealthCheckHandler,
+  type ProviderKind,
+  type ProviderMetadata,
+  type RuntimeProviderOptions,
+  type WarningsHandler,
+} from "./provider.ts";
+export {
+  array,
+  boolean,
+  type InferSchema,
+  integer,
+  number,
+  object,
+  optional,
+  s,
+  string,
+  type Schema,
+  type SchemaOptions,
+} from "./schema.ts";
+export {
+  CURRENT_PROTOCOL_VERSION,
+  ENV_PROVIDER_PARENT_PID,
+  ENV_PROVIDER_SOCKET,
+  ENV_WRITE_CATALOG,
+  createAuthService,
+  createCacheService,
+  createSecretsService,
+  createProviderService,
+  createRuntimeService,
+  loadPluginFromTarget,
+  loadProviderFromTarget,
+  main as runtimeMain,
+  parseRuntimeArgs,
+  pluginCatalogYaml,
+  runBundledPlugin,
+  runBundledProvider,
+  runLoadedPlugin,
+  runLoadedProvider,
+  serve,
+} from "./runtime.ts";
+export {
+  defaultPluginName,
+  defaultProviderName,
+  formatModuleTarget,
+  formatProviderTarget,
+  parseModuleTarget,
+  parseProviderTarget,
+  readPackageConfig,
+  readPackagePluginTarget,
+  readPackageProviderTarget,
+  resolvePluginImportUrl,
+  resolvePluginModulePath,
+  resolveProviderImportUrl,
+  resolveProviderModulePath,
+  type ModuleTarget,
+  type PackageConfig,
+  type ProviderTarget,
+} from "./target.ts";
+export {
+  IndexedDB,
+  ObjectStore,
+  Index,
+  Cursor,
+  CursorDirection,
+  NotFoundError,
+  AlreadyExistsError,
+  ColumnType,
+  indexedDBSocketEnv,
+  type Record,
+  type KeyRange,
+  type ColumnSchema,
+  type IndexSchema,
+  type ObjectStoreSchema,
+  type OpenCursorOptions,
+} from "./indexeddb.ts";
+export {
+  S3,
+  S3Object,
+  S3Provider,
+  S3InvalidRangeError,
+  S3NotFoundError,
+  S3PreconditionFailedError,
+  PresignMethod,
+  createS3Service,
+  defineS3Provider,
+  isS3Provider,
+  s3SocketEnv,
+  type ByteRange,
+  type CopyOptions,
+  type ListOptions,
+  type ListPage,
+  type ObjectMeta,
+  type ObjectRef,
+  type PresignOptions,
+  type PresignResult,
+  type ProviderReadResult,
+  type ReadOptions,
+  type ReadResult,
+  type S3BodySource,
+  type S3ProviderOptions,
+  type WriteOptions,
+} from "./s3.ts";