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

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

@@ -0,0 +1,314 @@
+// 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;
+  private pgPool: Pool | 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());
+    });
+
+    // Add connection pool status endpoint
+    app.get('/pool-status', (req, res) => {
+      if (this.pgPool) {
+        const poolStatus = {
+          totalCount: this.pgPool.totalCount,
+          idleCount: this.pgPool.idleCount,
+          waitingCount: this.pgPool.waitingCount,
+          maxConnections: this.pgPool.options.max || 'Not set',
+          minConnections: this.pgPool.options.min || 'Not set'
+        };
+
+        res.json({
+          status: 'ok',
+          connectionPool: poolStatus,
+          strategy: 'single-pool-unified',
+          operations: ['query', 'mutation', 'subscription'],
+          timestamp: new Date().toISOString(),
+          uptime: process.uptime(),
+          memory: process.memoryUsage()
+        });
+      } else {
+        res.status(503).json({
+          status: 'error',
+          message: 'Connection pool not available'
+        });
+      }
+    });
+
+    // 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, pgPool } = serverConfig;
+
+    // Store pool references for monitoring
+    this.pgPool = pgPool;
+
+    // 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 @@
+// Unified export entry point for plugins
+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,182 @@
+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[];
+  // Additional configuration from CLI
+  disableQueryLog: boolean;
+  enableQueryLog: boolean;
+  queryTimeout: number;
+}
+
+// Create PostGraphile configuration
+export function createPostGraphileConfig(options: PostGraphileConfigOptions) {
+  const { port, nodeEnv, graphqlEndpoint, enableSubscriptions, enableCors, availableTables } =
+    options;
+
+  // Build GraphQL and WebSocket endpoint URLs
+  const baseUrl = `http://localhost:${port}`;
+  const _graphqlUrl = `${baseUrl}${graphqlEndpoint}`;
+  const _subscriptionUrl =
+    enableSubscriptions === 'true' ? `ws://localhost:${port}${graphqlEndpoint}` : undefined;
+
+  // Create plugin hook to support WebSocket and subscriptions
+  const pluginHook = makePluginHook([PgPubSub]);
+
+  const config = {
+    // Basic configuration - disable default GraphiQL
+    graphiql: false,
+    enhanceGraphiql: false,
+    showErrorStack: nodeEnv === 'development',
+    extendedErrors: nodeEnv === 'development' ? ['hint', 'detail', 'errcode'] : [],
+
+    // Feature configuration - enable subscriptions
+    subscriptions: enableSubscriptions === 'true',
+    live: enableSubscriptions === 'true', // Enable live functionality to support subscriptions
+    enableQueryBatching: true,
+    enableCors: enableCors === 'true',
+
+    // Add plugin hook to support WebSocket
+    pluginHook,
+
+    // Disable all mutation functionality - only keep queries and subscriptions
+    disableDefaultMutations: true,
+
+    // Schema configuration
+    dynamicJson: true,
+    setofFunctionsContainNulls: false,
+    ignoreRBAC: false,
+    ignoreIndexes: true,
+
+    // Log control configuration
+    // Control SQL query logs through CLI parameters
+    disableQueryLog:
+      options.disableQueryLog || (nodeEnv === 'production' && !options.enableQueryLog),
+
+    // Enable query execution plan explanation (development environment only)
+    allowExplain: nodeEnv === 'development',
+
+    // Monitor PostgreSQL changes (development environment only)
+    watchPg: nodeEnv === 'development',
+
+    // GraphQL query timeout setting
+    queryTimeout: options.queryTimeout,
+
+    // GraphQL endpoint - explicitly specify route
+    graphqlRoute: graphqlEndpoint,
+    graphiqlRoute: '/graphiql', // GraphiQL interface route
+
+    // Add custom plugins
+    appendPlugins: [
+      QueryFilterPlugin, // Must execute before SimpleNamingPlugin
+      PgSimplifyInflectorPlugin, // Simplify field names, remove ByXxxAndYyy suffixes
+      SimpleNamingPlugin, // Fixed field loss issue
+      ConnectionFilterPlugin,
+      AllFieldsFilterPlugin
+    ],
+
+    // Advanced configuration options for Connection Filter plugin
+    graphileBuildOptions: {
+      // Enable logical operators (and, or, not)
+      connectionFilterLogicalOperators: true,
+
+      // Enable relationship filtering
+      connectionFilterRelations: true,
+
+      // Enable computed column filtering
+      connectionFilterComputedColumns: true,
+
+      // Enable array filtering
+      connectionFilterArrays: true,
+
+      // Enable function filtering
+      connectionFilterSetofFunctions: true,
+
+      // Allow null input and empty object input
+      connectionFilterAllowNullInput: true,
+      connectionFilterAllowEmptyObjectInput: true
+    },
+
+    // Only include detected tables
+    includeExtensionResources: false,
+
+    // Exclude unnecessary tables
+    ignoreTable: (tableName: string) => {
+      // If no tables detected, allow all tables
+      if (availableTables.length === 0) {
+        return false;
+      }
+      // Otherwise only include detected tables
+      return !availableTables.includes(tableName);
+    },
+
+    // Export schema (development environment)
+    exportGqlSchemaPath: nodeEnv === 'development' ? 'sui-indexer-schema.graphql' : undefined
+  };
+
+  // If subscriptions are enabled, add additional PostgreSQL subscription configuration
+  if (enableSubscriptions === 'true') {
+    return {
+      ...config,
+      // Use dedicated subscription connection pool
+      ownerConnectionString: options.databaseUrl,
+
+      // WebSocket configuration
+      websocketMiddlewares: [],
+
+      // PostgreSQL settings - optimized for long-running subscriptions
+      pgSettings: {
+        statement_timeout: '0', // No timeout for subscription queries
+        idle_in_transaction_session_timeout: '0', // Allow long transactions
+        default_transaction_isolation: 'read committed'
+      },
+
+      // Retry on connection failure
+      retryOnInitFail: true,
+
+      // Performance optimization for subscriptions
+      pgDefaultRole: undefined,
+      jwtSecret: undefined,
+
+      // Additional configuration for development environment
+      ...(nodeEnv === 'development' && {
+        queryCache: false, // Disable cache for real-time data
+        allowExplain: true
+      })
+    };
+  }
+
+  return config;
+}
+
+// Export enhanced playground HTML generator
+export function createPlaygroundHtml(options: PostGraphileConfigOptions): string {
+  const { graphqlEndpoint, enableSubscriptions, availableTables } = options;
+
+  // Use relative URLs so playground connects to the same domain as the server
+  const graphqlUrl = graphqlEndpoint;
+  const subscriptionUrl = enableSubscriptions === 'true' ? graphqlEndpoint : undefined;
+
+  return createEnhancedPlayground({
+    url: graphqlUrl,
+    subscriptionUrl,
+    title: 'Sui Indexer GraphQL Playground',
+    subtitle: `Powerful GraphQL API | ${availableTables.length} tables discovered | ${
+      enableSubscriptions === 'true'
+        ? 'Real-time subscriptions supported'
+        : 'Real-time subscriptions disabled'
+    }`
+  })(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;