@0xobelisk/graphql-server 1.2.0-pre.24

package/src/plugins/enhanced-server-manager.ts

@@ -0,0 +1,282 @@
+// Express server manager - using Express framework and PostgreSQL subscriptions
+
+import express, { Express, Request, Response } from 'express';
+import { createServer, Server as HttpServer } from 'http';
+import cors from 'cors';
+import { Pool } from 'pg';
+import { enhanceHttpServerWithSubscriptions } from 'postgraphile';
+import { subscriptionConfig, SubscriptionConfig } from '../config/subscription-config';
+import { systemLogger, serverLogger, logExpress } from '../utils/logger';
+import { createWelcomePage, WelcomePageConfig } from './welcome-page';
+import { createPlaygroundHtml, PostGraphileConfigOptions } from './postgraphile-config';
+import type { DynamicTable } from './database-introspector';
+
+export interface EnhancedServerConfig {
+  postgraphileMiddleware: any;
+  pgPool: Pool;
+  tableNames: string[];
+  databaseUrl: string;
+  allTables: DynamicTable[];
+  welcomeConfig: WelcomePageConfig;
+  postgraphileConfigOptions: PostGraphileConfigOptions;
+}
+
+export class EnhancedServerManager {
+  private config: SubscriptionConfig;
+  private app: Express | null = null;
+  private httpServer: HttpServer | null = null;
+
+  constructor() {
+    this.config = subscriptionConfig.getConfig();
+  }
+
+  // Create Express application
+  private createExpressApp(serverConfig: EnhancedServerConfig): Express {
+    const { postgraphileMiddleware, allTables, welcomeConfig, postgraphileConfigOptions } =
+      serverConfig;
+
+    const app = express();
+
+    // Middleware configuration
+    app.use(
+      cors({
+        origin: '*',
+        methods: ['GET', 'POST', 'OPTIONS'],
+        allowedHeaders: ['Content-Type', 'Authorization']
+      })
+    );
+
+    // Request logging middleware
+    app.use((req: Request, res: Response, next) => {
+      const startTime = Date.now();
+
+      res.on('finish', () => {
+        logExpress(req.method, req.path, res.statusCode, startTime, {
+          userAgent: req.get('user-agent')?.substring(0, 50)
+        });
+      });
+
+      next();
+    });
+
+    // Route configuration
+
+    // Root path - welcome page
+    app.get('/', (req: Request, res: Response) => {
+      res.set('Content-Type', 'text/html; charset=utf-8');
+      res.send(createWelcomePage(allTables, welcomeConfig));
+    });
+
+    // GraphQL Playground
+    app.get('/playground', (req: Request, res: Response) => {
+      res.set('Content-Type', 'text/html; charset=utf-8');
+      res.send(createPlaygroundHtml(postgraphileConfigOptions));
+    });
+
+    // Redirect old GraphiQL paths
+    app.get('/graphiql*', (req: Request, res: Response) => {
+      serverLogger.info('Redirecting old GraphiQL path', {
+        from: req.path,
+        to: '/playground'
+      });
+      res.redirect(301, '/playground');
+    });
+
+    // Health check endpoint
+    app.get('/health', (req: Request, res: Response) => {
+      res.json({
+        status: 'healthy',
+        subscriptions: this.getSubscriptionStatus(),
+        timestamp: new Date().toISOString()
+      });
+    });
+
+    // Subscription configuration endpoint
+    app.get('/subscription-config', (req: Request, res: Response) => {
+      res.json(subscriptionConfig.generateClientConfig());
+    });
+
+    // Configuration documentation endpoint
+    app.get('/subscription-docs', (req: Request, res: Response) => {
+      res.set('Content-Type', 'text/plain');
+      res.send(subscriptionConfig.generateDocumentation());
+    });
+
+    // PostGraphile middleware - mount at root path, let PostGraphile handle routing itself
+    app.use((req: Request, res: Response, next) => {
+      // Check if PostGraphile middleware exists
+      if (!postgraphileMiddleware) {
+        console.error('❌ PostGraphile middleware is null!');
+        if (req.path.startsWith('/graphql')) {
+          res.status(500).json({
+            error: 'PostGraphile middleware not properly initialized'
+          });
+          return;
+        }
+        next();
+        return;
+      }
+
+      try {
+        postgraphileMiddleware(req, res, next);
+      } catch (error) {
+        console.error('❌ PostGraphile middleware execution error:', error);
+        if (req.path.startsWith('/graphql')) {
+          res.status(500).json({
+            error: 'PostGraphile execution error',
+            details: error instanceof Error ? error.message : String(error)
+          });
+          return;
+        }
+        next();
+      }
+    });
+
+    // Error handling middleware
+    app.use((err: Error, req: Request, res: Response, next: express.NextFunction) => {
+      serverLogger.error('Express error handling', err, {
+        url: req.originalUrl,
+        method: req.method,
+        userAgent: req.get('user-agent')?.substring(0, 50)
+      });
+      res.status(500).send('Internal Server Error');
+    });
+
+    return app;
+  }
+
+  // Create and configure HTTP server
+  async createEnhancedServer(serverConfig: EnhancedServerConfig): Promise<HttpServer> {
+    const { postgraphileMiddleware } = serverConfig;
+
+    // Create Express application
+    this.app = this.createExpressApp(serverConfig);
+
+    // Create HTTP server
+    this.httpServer = createServer(this.app);
+
+    // Enable PostgreSQL subscriptions and WebSocket support
+    if (this.config.capabilities.pgSubscriptions) {
+      enhanceHttpServerWithSubscriptions(this.httpServer, postgraphileMiddleware, {
+        // Enable WebSocket transport
+        graphqlRoute: '/graphql'
+      });
+      systemLogger.info('✅ PostgreSQL subscriptions and WebSocket enabled', {
+        pgSubscriptions: this.config.capabilities.pgSubscriptions,
+        webSocket: true
+      });
+    }
+
+    serverLogger.info('🚀 Express server creation completed', {
+      framework: 'Express',
+      graphqlPort: this.config.graphqlPort,
+      capabilities: {
+        pgSubscriptions: this.config.capabilities.pgSubscriptions
+      },
+      recommendedMethod: 'pg-subscriptions'
+    });
+
+    return this.httpServer;
+  }
+
+  // Start server
+  async startServer(): Promise<void> {
+    if (!this.httpServer) {
+      throw new Error('Server not created, please call createEnhancedServer() first');
+    }
+
+    return new Promise((resolve, reject) => {
+      this.httpServer!.listen(this.config.graphqlPort, (err?: Error) => {
+        if (err) {
+          reject(err);
+          return;
+        }
+
+        this.logServerStatus();
+        resolve();
+      });
+    });
+  }
+
+  // Log server status
+  private logServerStatus() {
+    const clientConfig = subscriptionConfig.generateClientConfig();
+
+    serverLogger.info('🎉 Express GraphQL server started successfully!', {
+      port: this.config.graphqlPort,
+      framework: 'Express',
+      endpoints: {
+        home: `http://localhost:${this.config.graphqlPort}/`,
+        playground: `http://localhost:${this.config.graphqlPort}/playground`,
+        graphql: clientConfig.graphqlEndpoint,
+        subscription: clientConfig.subscriptionEndpoint,
+        health: `http://localhost:${this.config.graphqlPort}/health`,
+        config: `http://localhost:${this.config.graphqlPort}/subscription-config`,
+        docs: `http://localhost:${this.config.graphqlPort}/subscription-docs`
+      }
+    });
+
+    // Display main access links
+    console.log('\n' + '🌟'.repeat(30));
+    console.log('🏠 Homepage: ' + `http://localhost:${this.config.graphqlPort}/`);
+    console.log('🎮 Playground: ' + `http://localhost:${this.config.graphqlPort}/playground`);
+    console.log('🔗 GraphQL: ' + clientConfig.graphqlEndpoint);
+    console.log('📡 WebSocket: ' + clientConfig.subscriptionEndpoint);
+    console.log('🌟'.repeat(30) + '\n');
+  }
+
+  // Get subscription status
+  private getSubscriptionStatus() {
+    return {
+      enabled: this.config.capabilities.pgSubscriptions,
+      method: 'pg-subscriptions',
+      config: subscriptionConfig.generateClientConfig()
+    };
+  }
+
+  // Quick shutdown
+  async quickShutdown(): Promise<void> {
+    systemLogger.info('🛑 Starting quick shutdown of Express server...');
+
+    if (this.httpServer) {
+      this.httpServer.close();
+      systemLogger.info('✅ HTTP server closed');
+    }
+
+    systemLogger.info('🎯 Express server quick shutdown completed');
+  }
+
+  // Graceful shutdown
+  async gracefulShutdown(pgPool: Pool): Promise<void> {
+    systemLogger.info('🛑 Starting graceful shutdown of Express server...');
+
+    const shutdownPromises: Promise<void>[] = [];
+
+    // Close HTTP server
+    if (this.httpServer) {
+      shutdownPromises.push(
+        new Promise((resolve) => {
+          this.httpServer!.close(() => {
+            systemLogger.info('✅ HTTP server closed');
+            resolve();
+          });
+        })
+      );
+    }
+
+    // Close database connection pool
+    shutdownPromises.push(
+      pgPool.end().then(() => {
+        systemLogger.info('✅ Database connection pool closed');
+      })
+    );
+
+    try {
+      await Promise.all(shutdownPromises);
+      systemLogger.info('🎯 Express server graceful shutdown completed');
+    } catch (error) {
+      systemLogger.error('❌ Error occurred during shutdown process', error);
+      throw error;
+    }
+  }
+}

package/src/plugins/index.ts

@@ -0,0 +1,9 @@
+// 插件统一导出入口
+export * from './database-introspector';
+export * from './welcome-page';
+export * from './postgraphile-config';
+export * from './query-filter';
+export * from './simple-naming';
+export * from './all-fields-filter-plugin';
+export * from './enhanced-server-manager';
+export * from './enhanced-playground';

package/src/plugins/postgraphile-config.ts

@@ -0,0 +1,226 @@
+import { QueryFilterPlugin } from './query-filter';
+import { SimpleNamingPlugin } from './simple-naming';
+import { AllFieldsFilterPlugin } from './all-fields-filter-plugin';
+import { createEnhancedPlayground } from './enhanced-playground';
+import ConnectionFilterPlugin from 'postgraphile-plugin-connection-filter';
+import PgSimplifyInflectorPlugin from '@graphile-contrib/pg-simplify-inflector';
+import { makePluginHook } from 'postgraphile';
+import PgPubSub from '@graphile/pg-pubsub';
+
+export interface PostGraphileConfigOptions {
+  port: string | number;
+  nodeEnv: string;
+  graphqlEndpoint: string;
+  enableSubscriptions: string;
+  enableCors: string;
+  databaseUrl: string;
+  availableTables: string[];
+}
+
+// 创建 PostGraphile 配置
+export function createPostGraphileConfig(options: PostGraphileConfigOptions) {
+  const { port, nodeEnv, graphqlEndpoint, enableSubscriptions, enableCors, availableTables } =
+    options;
+
+  // 构建GraphQL和WebSocket端点URL
+  const baseUrl = `http://localhost:${port}`;
+  const graphqlUrl = `${baseUrl}${graphqlEndpoint}`;
+  const subscriptionUrl =
+    enableSubscriptions === 'true' ? `ws://localhost:${port}${graphqlEndpoint}` : undefined;
+
+  // 创建插件钩子以支持WebSocket和订阅
+  const pluginHook = makePluginHook([PgPubSub]);
+
+  const config = {
+    // 基础配置 - 关闭默认GraphiQL
+    graphiql: false,
+    enhanceGraphiql: false,
+    showErrorStack: nodeEnv === 'development',
+    extendedErrors: nodeEnv === 'development' ? ['hint', 'detail', 'errcode'] : [],
+
+    // 功能配置 - 启用订阅
+    subscriptions: enableSubscriptions === 'true',
+    live: enableSubscriptions === 'true', // 启用live功能以支持订阅
+    enableQueryBatching: true,
+    enableCors: enableCors === 'true',
+
+    // 添加插件钩子以支持WebSocket
+    pluginHook,
+
+    // 禁用所有mutation功能 - 只保留查询和订阅
+    disableDefaultMutations: true,
+
+    // Schema 配置
+    dynamicJson: true,
+    setofFunctionsContainNulls: false,
+    ignoreRBAC: false,
+    ignoreIndexes: true,
+
+    // 日志控制配置
+    // 通过环境变量控制SQL查询日志: DISABLE_QUERY_LOG=true 禁用查询日志
+    disableQueryLog:
+      process.env.DISABLE_QUERY_LOG === 'true' ||
+      (nodeEnv === 'production' && process.env.ENABLE_QUERY_LOG !== 'true'),
+
+    // 启用查询执行计划解释（仅开发环境）
+    allowExplain: nodeEnv === 'development',
+
+    // 监控PostgreSQL变化（仅开发环境）
+    watchPg: nodeEnv === 'development',
+
+    // GraphQL查询超时设置
+    queryTimeout: parseInt(process.env.QUERY_TIMEOUT || '30000'),
+
+    // GraphQL 端点 - 明确指定路由
+    graphqlRoute: graphqlEndpoint,
+    graphiqlRoute: '/graphiql', // GraphiQL界面路由
+
+    // 添加自定义插件
+    appendPlugins: [
+      QueryFilterPlugin, // 必须在SimpleNamingPlugin之前执行
+      PgSimplifyInflectorPlugin, // 简化字段名，去掉ByXxxAndYyy后缀
+      SimpleNamingPlugin, // 已修复字段丢失问题
+      ConnectionFilterPlugin,
+      AllFieldsFilterPlugin
+    ],
+
+    // Connection Filter 插件的高级配置选项
+    graphileBuildOptions: {
+      // 启用所有支持的操作符
+      connectionFilterAllowedOperators: [
+        'isNull',
+        'equalTo',
+        'notEqualTo',
+        'distinctFrom',
+        'notDistinctFrom',
+        'lessThan',
+        'lessThanOrEqualTo',
+        'greaterThan',
+        'greaterThanOrEqualTo',
+        'in',
+        'notIn',
+        'like',
+        'notLike',
+        'ilike',
+        'notIlike',
+        'similarTo',
+        'notSimilarTo',
+        'includes',
+        'notIncludes',
+        'includesInsensitive',
+        'notIncludesInsensitive',
+        'startsWith',
+        'notStartsWith',
+        'startsWithInsensitive',
+        'notStartsWithInsensitive',
+        'endsWith',
+        'notEndsWith',
+        'endsWithInsensitive',
+        'notEndsWithInsensitive'
+      ],
+
+      // 支持所有字段类型的过滤 - 明确允许所有类型
+      connectionFilterAllowedFieldTypes: [
+        'String',
+        'Int',
+        'Float',
+        'Boolean',
+        'ID',
+        'Date',
+        'Time',
+        'Datetime',
+        'JSON',
+        'BigInt'
+      ],
+
+      // 启用逻辑操作符 (and, or, not)
+      connectionFilterLogicalOperators: true,
+
+      // 启用关系过滤
+      connectionFilterRelations: true,
+
+      // 启用计算列过滤
+      connectionFilterComputedColumns: true,
+
+      // 启用数组过滤
+      connectionFilterArrays: true,
+
+      // 启用函数过滤
+      connectionFilterSetofFunctions: true,
+
+      // 允许空输入和空对象输入
+      connectionFilterAllowNullInput: true,
+      connectionFilterAllowEmptyObjectInput: true
+    },
+
+    // 只包含检测到的表
+    includeExtensionResources: false,
+
+    // 排除不需要的表
+    ignoreTable: (tableName: string) => {
+      // 如果没有检测到任何表，允许所有表
+      if (availableTables.length === 0) {
+        return false;
+      }
+      // 否则只包含检测到的表
+      return !availableTables.includes(tableName);
+    },
+
+    // 导出 schema（开发环境）
+    exportGqlSchemaPath: nodeEnv === 'development' ? 'sui-indexer-schema.graphql' : undefined
+  };
+
+  // 如果启用订阅，添加额外的PostgreSQL订阅配置
+  if (enableSubscriptions === 'true') {
+    return {
+      ...config,
+      // 使用专用数据库连接用于订阅
+      ownerConnectionString: options.databaseUrl,
+
+      // WebSocket配置
+      websocketMiddlewares: [],
+
+      // PostgreSQL设置 - 为订阅优化
+      pgSettings: {
+        statement_timeout: '30s',
+        // 为订阅设置适当的事务隔离级别
+        default_transaction_isolation: 'read committed'
+      },
+
+      // 连接失败时重试
+      retryOnInitFail: true,
+
+      // 性能优化
+      pgDefaultRole: undefined,
+      jwtSecret: undefined,
+
+      // 开发环境的额外配置
+      ...(nodeEnv === 'development' && {
+        queryCache: true,
+        allowExplain: true
+      })
+    };
+  }
+
+  return config;
+}
+
+// 导出增强版playground的HTML生成器
+export function createPlaygroundHtml(options: PostGraphileConfigOptions): string {
+  const { port, graphqlEndpoint, enableSubscriptions, availableTables } = options;
+
+  // 构建GraphQL和WebSocket端点URL
+  const baseUrl = `http://localhost:${port}`;
+  const graphqlUrl = `${baseUrl}${graphqlEndpoint}`;
+  const subscriptionUrl =
+    enableSubscriptions === 'true' ? `ws://localhost:${port}${graphqlEndpoint}` : undefined;
+
+  return createEnhancedPlayground({
+    url: graphqlUrl,
+    subscriptionUrl,
+    title: 'Sui Indexer GraphQL Playground',
+    subtitle: `强大的GraphQL API | 已发现 ${availableTables.length} 个表 | ${
+      enableSubscriptions === 'true' ? '支持实时订阅' : '实时订阅已禁用'
+    }`
+  })(null as any, null as any, {});
+}

package/src/plugins/query-filter.ts

@@ -0,0 +1,50 @@
+// PostGraphile plugin for filtering queries
+import { Plugin } from 'postgraphile';
+
+// Query filter plugin - only keep useful table-related queries
+export const QueryFilterPlugin: Plugin = (builder) => {
+  // Filter query fields
+  builder.hook('GraphQLObjectType:fields', (fields, build, context) => {
+    const {
+      scope: { isRootQuery }
+    } = context;
+
+    if (!isRootQuery) {
+      return fields;
+    }
+
+    // Define query types to keep
+    const allowedQueries = new Set<string>();
+
+    // Get all table-related queries
+    Object.keys(fields).forEach((fieldName) => {
+      // Keep PostGraphile required system fields
+      if (['query', 'nodeId', 'node'].includes(fieldName)) {
+        allowedQueries.add(fieldName);
+      }
+
+      // Keep store table-related queries
+      if (fieldName.match(/^(allStore|store)/i)) {
+        allowedQueries.add(fieldName);
+      }
+
+      // Keep table_fields table queries
+      if (fieldName.match(/^(allTable|table)/i)) {
+        allowedQueries.add(fieldName);
+      }
+    });
+
+    // Filter fields, only keep allowed queries
+    const filteredFields: typeof fields = {};
+    Object.keys(fields).forEach((fieldName) => {
+      if (allowedQueries.has(fieldName)) {
+        filteredFields[fieldName] = fields[fieldName];
+      }
+    });
+
+    // console.log('🔍 Filtered query fields:', Object.keys(filteredFields));
+    return filteredFields;
+  });
+};
+
+export default QueryFilterPlugin;

package/src/plugins/simple-naming.ts

@@ -0,0 +1,105 @@
+import { Plugin } from 'postgraphile';
+
+export const SimpleNamingPlugin: Plugin = (builder) => {
+  // Rename query fields
+  builder.hook('GraphQLObjectType:fields', (fields, build, context) => {
+    const {
+      scope: { isRootQuery }
+    } = context;
+
+    if (!isRootQuery) {
+      return fields;
+    }
+
+    // Create renamed field mapping
+    const renamedFields: typeof fields = {};
+    const originalFieldNames = Object.keys(fields);
+
+    console.log('🔍 Original field list:', originalFieldNames);
+
+    // For tracking rename mapping
+    const renameMap: Record<string, string> = {};
+
+    originalFieldNames.forEach((fieldName) => {
+      let newFieldName = fieldName;
+
+      // Remove "all" prefix, but keep system fields
+      if (
+        fieldName.startsWith('all') &&
+        !['allRows', 'allTableFields'].includes(fieldName) // Extend reserved list
+      ) {
+        // allStoreAccounts -> storeAccounts
+        // allStoreEncounters -> storeEncounters
+        newFieldName = fieldName.replace(/^all/, '');
+        // First letter to lowercase, maintain camelCase
+        if (newFieldName.length > 0) {
+          newFieldName = newFieldName.charAt(0).toLowerCase() + newFieldName.slice(1);
+        }
+      }
+
+      // Remove "store" prefix (note lowercase s, because it's already processed above)
+      if (newFieldName.startsWith('store') && newFieldName !== 'store') {
+        // storeAccounts -> accounts
+        // storeAccount -> account
+        // storeEncounters -> encounters
+        // storeEncounter -> encounter
+        const withoutStore = newFieldName.replace(/^store/, '');
+        // First letter to lowercase, maintain camelCase
+        if (withoutStore.length > 0) {
+          const finalName = withoutStore.charAt(0).toLowerCase() + withoutStore.slice(1);
+
+          // Check if field name conflict will occur
+          if (!renamedFields[finalName] && !originalFieldNames.includes(finalName)) {
+            newFieldName = finalName;
+          }
+          // If conflict, keep original name (remove all but keep store)
+        }
+      }
+
+      // Check if final field name will conflict
+      if (renamedFields[newFieldName]) {
+        console.warn(`⚠️ Field name conflict: ${newFieldName}, keeping original name ${fieldName}`);
+        newFieldName = fieldName; // Keep original name to avoid conflict
+      }
+
+      renameMap[fieldName] = newFieldName;
+      renamedFields[newFieldName] = fields[fieldName];
+    });
+
+    const renamedCount = Object.entries(renameMap).filter(
+      ([old, newName]) => old !== newName
+    ).length;
+    const finalFieldNames = Object.keys(renamedFields);
+
+    console.log('🔄 Field rename statistics:', {
+      'Original field count': originalFieldNames.length,
+      'Final field count': finalFieldNames.length,
+      'Renamed field count': renamedCount
+    });
+
+    if (renamedCount > 0) {
+      console.log(
+        '📝 Rename mapping:',
+        Object.entries(renameMap)
+          .filter(([old, newName]) => old !== newName)
+          .reduce((acc, [old, newName]) => ({ ...acc, [old]: newName }), {})
+      );
+    }
+
+    // Ensure field count is not lost
+    if (finalFieldNames.length !== originalFieldNames.length) {
+      console.error(
+        '❌ Fields lost! Original:',
+        originalFieldNames.length,
+        'Final:',
+        finalFieldNames.length
+      );
+      // If fields are lost, return original fields to avoid breakage
+      return fields;
+    }
+
+    return renamedFields;
+  });
+};
+
+export default SimpleNamingPlugin;