@graphoria/server 0.1.0

package/src/configuration/index.ts

@@ -0,0 +1,138 @@
+import { isFunction, isPlainObject } from "es-toolkit";
+import { z } from "zod";
+
+import type { Configuration } from "../types/configuration";
+import type { Env } from "../types/env";
+
+import { logger } from "../logging";
+import type { GetSchemaReturn } from "./getSchemas";
+
+import { operation } from "../config";
+import { getDatabasesStructure, sourcesForEachRole } from "../databases";
+import { resolveRemoteRESTApis } from "../remoteREST";
+import { resolveRemoteSchemas } from "../remoteSchemas";
+import {
+  createOneToBooleanMSSQL,
+  createYAndNToBooleanMSSQL,
+  virtualColumnExpression,
+  virtualColumnFunction,
+} from "../types/configuration";
+import { getSchema, getSchemas } from "./getSchemas";
+import { generateOpenAPI } from "./rest/generateOpenAPI";
+
+export const loadConfiguration = async (config: string): Promise<Configuration> => {
+  try {
+    // Dynamic import of the TypeScript file
+    const configModule = await import(config);
+
+    if (isFunction(configModule?.default)) {
+      return configModule.default({
+        z,
+        operation,
+        createOneToBooleanMSSQL,
+        createYAndNToBooleanMSSQL,
+        virtualColumnExpression,
+        virtualColumnFunction,
+      });
+    } else if (isPlainObject(configModule.default)) {
+      return configModule.default as Configuration;
+    }
+
+    throw new Error("Invalid configuration module");
+  } catch (error) {
+    logger("configuration").error({ err: error }, "failed to import configuration");
+
+    throw new Error("Configuration could not be loaded");
+  }
+};
+
+export const analyzeConfiguration = async (configuration: Configuration, options: Env) => {
+  const log = logger("configuration");
+  log.info("starting configuration analysis");
+
+  // Use pre-calculated enabledDatabases from configuration parsing
+  const enabledDatabases = configuration.enabledDatabases;
+
+  const [{ tables, storedProcedures }, resolvedRemoteSchemas, resolvedRemoteREST] =
+    await Promise.all([
+      getDatabasesStructure(enabledDatabases, configuration.auth),
+      resolveRemoteSchemas(configuration.remoteSchemas ?? []),
+      resolveRemoteRESTApis(configuration.remoteREST ?? []),
+    ]);
+
+  const operationsWithRestEndpoints = Object.fromEntries(
+    Object.entries(configuration.operations).filter(([, operationConfig]) => operationConfig.rest),
+  );
+
+  const sourcesByPermission = sourcesForEachRole(
+    tables,
+    storedProcedures,
+    configuration.queues,
+    operationsWithRestEndpoints,
+    {
+      [options.anonymousRole]: {
+        tables: [],
+        storedProcedures: [],
+        queues: [],
+        operations: [],
+        remoteSchemas: [],
+        remoteREST: [],
+      },
+      ...(configuration.auth.permissions ?? {}),
+      superadmin: {
+        tables: "ALL",
+        storedProcedures: "ALL",
+        queues: "ALL",
+        operations: "ALL",
+        remoteSchemas: "ALL",
+        remoteREST: "ALL",
+      },
+    },
+    resolvedRemoteSchemas,
+    resolvedRemoteREST,
+  );
+
+  const { superadmin, ...others } = sourcesByPermission;
+
+  const superadminSchema = getSchema(
+    superadmin,
+    configuration.auth,
+    null,
+    configuration.ai?.enabled ?? false,
+  );
+
+  const schemas: Record<string, GetSchemaReturn> = {
+    superadmin: superadminSchema,
+    ...getSchemas(others, configuration.auth, superadminSchema.handlers.gql),
+  };
+
+  const jsonOpenApi = generateOpenAPI({
+    title: configuration.name,
+    version: configuration.version,
+    schema: schemas.superadmin,
+    options,
+    remoteRESTApis: schemas.superadmin.remoteRESTApis,
+    ai: configuration.ai?.enabled ? { path: configuration.ai.endpoint ?? "/ai" } : undefined,
+  });
+
+  log.info(
+    {
+      roles: Object.keys(schemas).length,
+      tables: tables.length,
+      storedProcedures: storedProcedures.length,
+      remoteSchemas: resolvedRemoteSchemas.length,
+      remoteREST: resolvedRemoteREST.length,
+    },
+    "configuration analysis complete",
+  );
+
+  return {
+    databases: enabledDatabases,
+    roles: schemas,
+    openapi: jsonOpenApi,
+    queues: configuration.queues,
+    auth: configuration.auth,
+  };
+};
+
+export type AnalyzedConfiguration = Awaited<ReturnType<typeof analyzeConfiguration>>;

package/src/configuration/rest/generateOpenAPI.ts

@@ -0,0 +1,361 @@
+import type { OpenAPIV3_1 } from "openapi-types";
+import type { SelectionAnalysis } from "../../analyzeQuery/types";
+import type { GetSchemaReturn } from "../../configuration/getSchemas";
+import type { RemoteRESTResolved } from "../../remoteREST/types";
+import type { Env } from "../../types/env";
+
+import { convertFromZod, errors } from "./openApiErrors";
+
+const processSelections = (
+  schema: GetSchemaReturn,
+  name: string,
+  selections: SelectionAnalysis[] = [],
+) =>
+  selections.reduce<Record<string, unknown>>((acc, field) => {
+    const type = schema.getColumnTypeForOpenApi(name, field.name);
+
+    if (field.isArray) {
+      acc[field.alias || field.name] = {
+        type: "array",
+        items: {
+          type: "object",
+          properties: processSelections(schema, field.name, field.selections),
+          required: (field.selections ?? [])
+            .filter((f) => f.isRequired)
+            .map((f) => f.alias || f.name),
+        },
+      };
+    } else {
+      acc[field.alias || field.name] = field.selections
+        ? {
+            type: "object",
+            properties: processSelections(schema, field.name, field.selections),
+            required: field.selections.filter((f) => f.isRequired).map((f) => f.alias || f.name),
+          }
+        : { type };
+    }
+
+    return acc;
+  }, {});
+
+type GenerateOpenAPIParams = {
+  title?: string;
+  version?: string;
+  schema: GetSchemaReturn;
+  options: Env;
+  remoteRESTApis?: RemoteRESTResolved[];
+  /** When set, adds the admin-only AI agent endpoint to the spec. */
+  ai?: { path: string };
+};
+
+export const getTags = (url: string) => {
+  if (url.startsWith("/auth")) return ["Auth"];
+
+  return ["Data"];
+};
+
+export const generateOpenAPI = ({
+  title = "REST API",
+  version = "1.0.0",
+  schema,
+  options,
+  remoteRESTApis = [],
+  ai,
+}: GenerateOpenAPIParams): OpenAPIV3_1.Document => {
+  // Build remote REST paths and schemas
+  const remotePaths: Record<string, OpenAPIV3_1.PathItemObject> = {};
+  const remoteSchemas: Record<string, OpenAPIV3_1.SchemaObject> = {};
+  const remoteTags: OpenAPIV3_1.TagObject[] = [];
+
+  for (const rr of remoteRESTApis) {
+    Object.assign(remotePaths, rr.openApiPaths);
+    Object.assign(remoteSchemas, rr.openApiSchemas);
+    remoteTags.push({
+      name: rr.prefix,
+      description: `Remote REST API: ${rr.config.name}`,
+    });
+  }
+
+  return {
+    openapi: "3.1.0",
+    info: {
+      title,
+      version,
+    },
+    servers: [
+      {
+        url: `${options.prefix}${options.restApiPrefix}`,
+        description: "Development server",
+      },
+    ],
+    tags: [
+      {
+        name: "Auth",
+        description: "Authentication endpoints",
+      },
+      {
+        name: "Data",
+        description: "Data endpoints",
+      },
+      ...(ai
+        ? [
+            {
+              name: "AI",
+              description: "AI agent — natural-language → database Q&A (admin-secret only)",
+            },
+          ]
+        : []),
+      ...remoteTags,
+    ],
+    components: {
+      schemas: { ...errors, ...remoteSchemas },
+      securitySchemes: {
+        "HTTP Bearer Token": {
+          description: "HTTP authentication with bearer token",
+          type: "http",
+          scheme: "bearer",
+          bearerFormat: "JWT",
+        },
+        "Admin Secret": {
+          description: "API key authentication via custom header",
+          type: "apiKey",
+          in: "header",
+          name: "x-admin-secret",
+        },
+      },
+    },
+    paths: {
+      ...Object.entries(schema.handlers.rest.operationsEnhanced).reduce<
+        Record<string, Record<string, unknown>>
+      >((acc, [key, value]) => {
+        // Skip if neither queryStructure nor responseSchema is available
+        if (!value.queryStructure && !value.output) {
+          return acc;
+        }
+
+        // Build response schema: from responseSchema (custom handler) or queryStructure (query-based)
+        const responseDataSchema = value.output
+          ? convertFromZod(value.output)
+          : (() => {
+              const fields = value.queryStructure!.operations[0].fields;
+              return {
+                type: "object" as const,
+                properties: fields.reduce<Record<string, unknown>>((acc, field) => {
+                  if (field.isArray) {
+                    acc[field.alias || field.name] = {
+                      type: "array",
+                      items: {
+                        type: "object",
+                        properties: processSelections(schema, field.name, field.selections!),
+                        required: (field.selections ?? [])
+                          .filter((f) => f.isRequired)
+                          .map((f) => f.alias || f.name),
+                      },
+                    };
+                  } else {
+                    acc[field.alias || field.name] = {
+                      type: "object",
+                      properties: processSelections(schema, field.name, field.selections!),
+                      required: (field.selections ?? [])
+                        .filter((f) => f.isRequired)
+                        .map((f) => f.alias || f.name),
+                    };
+                  }
+                  return acc;
+                }, {}),
+                required: fields.filter((f) => f.isRequired).map((f) => f.alias || f.name),
+              };
+            })();
+
+        const hasParameters = value.input;
+
+        const pathParametersPOJO = convertFromZod(value.rest!.pathParams!);
+        const queryParametersPOJO = convertFromZod(value.rest!.queryParams!);
+        const bodyParametersPOJO = convertFromZod(value.rest!.body!);
+
+        const hasBody = Object.keys(bodyParametersPOJO.properties ?? {}).length > 0;
+
+        const finalPath = value.rest!.path.replace(/:(\w+)/g, "{$1}");
+
+        return {
+          ...acc,
+          [finalPath]: {
+            ...acc[finalPath],
+            [value.rest!.method!.toLowerCase()]: {
+              tags: getTags(value.rest!.path),
+              summary: key,
+              description: value.description,
+              operationId: key,
+              parameters: [
+                ...(Object.entries(
+                  pathParametersPOJO.properties ?? ({} as OpenAPIV3_1.SchemaObject),
+                ).map(([key, { type }]) => ({
+                  name: key,
+                  in: "path",
+                  required: true,
+                  schema: {
+                    type,
+                  },
+                })) ?? []),
+                ...Object.entries(
+                  queryParametersPOJO.properties ?? ({} as OpenAPIV3_1.SchemaObject),
+                ).map(([key, { type, required }]) => ({
+                  name: key,
+                  in: "query",
+                  required,
+                  schema: {
+                    type,
+                  },
+                })),
+              ],
+              ...(hasBody && ["POST", "PUT", "PATCH"].includes(value.rest!.method!)
+                ? {
+                    requestBody: {
+                      content: {
+                        "application/json": {
+                          schema: {
+                            type: "object",
+                            properties: Object.entries(
+                              bodyParametersPOJO.properties ?? ({} as OpenAPIV3_1.SchemaObject),
+                            ).reduce<
+                              Record<
+                                string,
+                                {
+                                  type: string;
+                                }
+                              >
+                            >((acc, [key, value]) => {
+                              acc[key] = value;
+
+                              return acc;
+                            }, {}),
+                            required: bodyParametersPOJO.required,
+                          },
+                        },
+                      },
+                    },
+                  }
+                : {}),
+              responses: {
+                200: {
+                  description: "Successful response",
+                  content: {
+                    "application/json": {
+                      schema: {
+                        type: "object",
+                        properties: {
+                          data: responseDataSchema,
+                        },
+                      },
+                    },
+                  },
+                },
+                ...(hasParameters
+                  ? {
+                      "400": {
+                        description: "Validation error",
+                        content: {
+                          "application/json": {
+                            schema: {
+                              $ref: "#/components/schemas/ValidationError",
+                            },
+                          },
+                        },
+                      },
+                    }
+                  : {}),
+                "401": {
+                  description: "Unauthorized",
+                  content: {
+                    "application/json": {
+                      schema: {
+                        $ref: "#/components/schemas/UnauthorizedError",
+                      },
+                    },
+                  },
+                },
+                "403": {
+                  description: "Forbidden",
+                  content: {
+                    "application/json": {
+                      schema: { $ref: "#/components/schemas/ForbiddenError" },
+                    },
+                  },
+                },
+                "404": {
+                  description: "Not found",
+                  content: {
+                    "application/json": {
+                      schema: { $ref: "#/components/schemas/NotFoundError" },
+                    },
+                  },
+                },
+              },
+            },
+          },
+        };
+      }, {}),
+      ...(ai
+        ? {
+            [ai.path]: {
+              post: {
+                tags: ["AI"],
+                summary: "Ask the AI agent",
+                description:
+                  "Send a natural-language question about the database. The agent discovers relevant tables, runs read-only GraphQL queries, and returns an answer. Requires admin secret.",
+                operationId: "askAI",
+                security: [{ "Admin Secret": [] }],
+                requestBody: {
+                  required: true,
+                  content: {
+                    "application/json": {
+                      schema: {
+                        type: "object",
+                        properties: {
+                          prompt: {
+                            type: "string",
+                            description: "Natural-language question about the database",
+                          },
+                        },
+                        required: ["prompt"],
+                      },
+                    },
+                  },
+                },
+                responses: {
+                  "200": {
+                    description: "Agent answer",
+                    content: {
+                      "application/json": {
+                        schema: {
+                          type: "object",
+                          properties: { answer: { type: "string" } },
+                        },
+                      },
+                    },
+                  },
+                  "400": {
+                    description: "Bad request",
+                    content: {
+                      "application/json": {
+                        schema: { $ref: "#/components/schemas/ValidationError" },
+                      },
+                    },
+                  },
+                  "404": {
+                    description: "Not found (missing admin secret)",
+                    content: {
+                      "application/json": {
+                        schema: { $ref: "#/components/schemas/NotFoundError" },
+                      },
+                    },
+                  },
+                },
+              },
+            },
+          }
+        : {}),
+      ...remotePaths,
+    },
+  };
+};