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

package/src/cli.ts

@@ -0,0 +1,232 @@
+#!/usr/bin/env node
+
+import yargs, { Argv } from 'yargs';
+import { hideBin } from 'yargs/helpers';
+import * as dotenv from 'dotenv';
+import { startServer, ServerConfig } from './server';
+import { systemLogger } from './utils/logger';
+import packageJson from '../package.json';
+
+// Load environment variables
+dotenv.config();
+
+// Helper function to get environment variable or default value
+const getEnvOrDefault = (envKey: string, defaultValue: string): string => {
+  return process.env[envKey] || defaultValue;
+};
+
+const getBooleanEnvOrDefault = (envKey: string, defaultValue: boolean): boolean => {
+  const envValue = process.env[envKey];
+  if (envValue === undefined) return defaultValue;
+  return envValue.toLowerCase() === 'true';
+};
+
+interface StartArgs {
+  // Basic server configuration
+  port: string;
+  'database-url': string;
+  schema: string;
+  endpoint: string;
+  cors: boolean;
+  subscriptions: boolean;
+  env: string;
+
+  // Debug configuration
+  debug: boolean;
+
+  // Performance configuration
+  'query-timeout': number;
+  'max-connections': number;
+  'heartbeat-interval': number;
+  'enable-metrics': boolean;
+
+  // Subscription capabilities
+  'enable-live-queries': boolean;
+  'enable-pg-subscriptions': boolean;
+  'enable-native-websocket': boolean;
+  'realtime-port'?: number;
+}
+
+interface _HealthArgs {
+  url: string;
+}
+
+interface _InitArgs {
+  output: string;
+}
+
+const cli = yargs(hideBin(process.argv))
+  .scriptName('dubhe-graphql-server')
+  .usage('$0 <command> [options]')
+  .version(packageJson.version)
+  .help('help')
+  .alias('h', 'help')
+  .alias('v', 'version')
+  .demandCommand(1, 'You need to specify a command')
+  .recommendCommands()
+  .strict();
+
+// Start command
+cli.command(
+  'start',
+  'Start GraphQL server',
+  (yargs: Argv) => {
+    return (
+      yargs
+        .option('port', {
+          alias: 'p',
+          type: 'string',
+          default: getEnvOrDefault('PORT', '4000'),
+          describe: 'Server port (env: PORT)'
+        })
+        .option('database-url', {
+          alias: 'd',
+          type: 'string',
+          default: getEnvOrDefault(
+            'DATABASE_URL',
+            'postgres://postgres:postgres@127.0.0.1:5432/postgres'
+          ),
+          describe: 'Database connection URL (env: DATABASE_URL)'
+        })
+        .option('schema', {
+          alias: 's',
+          type: 'string',
+          default: getEnvOrDefault('PG_SCHEMA', 'public'),
+          describe: 'PostgreSQL schema name (env: PG_SCHEMA)'
+        })
+        .option('endpoint', {
+          alias: 'e',
+          type: 'string',
+          default: getEnvOrDefault('GRAPHQL_ENDPOINT', '/graphql'),
+          describe: 'GraphQL endpoint path (env: GRAPHQL_ENDPOINT)'
+        })
+        .option('cors', {
+          type: 'boolean',
+          default: getBooleanEnvOrDefault('ENABLE_CORS', true),
+          describe: 'Enable CORS (env: ENABLE_CORS)'
+        })
+        .option('subscriptions', {
+          type: 'boolean',
+          default: getBooleanEnvOrDefault('ENABLE_SUBSCRIPTIONS', true),
+          describe: 'Enable GraphQL subscriptions (env: ENABLE_SUBSCRIPTIONS)'
+        })
+        .option('env', {
+          type: 'string',
+          default: getEnvOrDefault('NODE_ENV', 'development'),
+          choices: ['development', 'production'],
+          describe: 'Environment mode (env: NODE_ENV)'
+        })
+        // Debug configuration
+        .option('debug', {
+          type: 'boolean',
+          default: getBooleanEnvOrDefault('DEBUG', false),
+          describe: 'Enable debug mode (verbose logging + query logs) (env: DEBUG)'
+        })
+        // Performance configuration
+        .option('query-timeout', {
+          type: 'number',
+          default: parseInt(getEnvOrDefault('QUERY_TIMEOUT', '30000')),
+          describe: 'GraphQL query timeout in milliseconds (env: QUERY_TIMEOUT)'
+        })
+        .option('max-connections', {
+          type: 'number',
+          default: parseInt(getEnvOrDefault('MAX_CONNECTIONS', '1000')),
+          describe: 'Maximum database connections (env: MAX_CONNECTIONS)'
+        })
+        .option('heartbeat-interval', {
+          type: 'number',
+          default: parseInt(getEnvOrDefault('HEARTBEAT_INTERVAL', '30000')),
+          describe: 'WebSocket heartbeat interval in milliseconds (env: HEARTBEAT_INTERVAL)'
+        })
+        .option('enable-metrics', {
+          type: 'boolean',
+          default: getBooleanEnvOrDefault('ENABLE_METRICS', false),
+          describe: 'Enable performance metrics (env: ENABLE_METRICS)'
+        })
+        // Subscription capabilities
+        .option('enable-live-queries', {
+          type: 'boolean',
+          default: getBooleanEnvOrDefault('ENABLE_LIVE_QUERIES', true),
+          describe: 'Enable GraphQL live queries (env: ENABLE_LIVE_QUERIES)'
+        })
+        .option('enable-pg-subscriptions', {
+          type: 'boolean',
+          default: getBooleanEnvOrDefault('ENABLE_PG_SUBSCRIPTIONS', true),
+          describe: 'Enable PostgreSQL subscriptions (env: ENABLE_PG_SUBSCRIPTIONS)'
+        })
+        .option('enable-native-websocket', {
+          type: 'boolean',
+          default: getBooleanEnvOrDefault('ENABLE_NATIVE_WEBSOCKET', true),
+          describe: 'Enable native WebSocket support (env: ENABLE_NATIVE_WEBSOCKET)'
+        })
+        .option('realtime-port', {
+          type: 'number',
+          default: process.env.REALTIME_PORT ? parseInt(process.env.REALTIME_PORT) : undefined,
+          describe: 'Realtime WebSocket port (env: REALTIME_PORT)'
+        })
+
+        .example(
+          '$0 start -p 4000 -d postgres://user:pass@localhost/db',
+          'Start server with custom port and database'
+        )
+        .example(
+          '$0 start --no-cors --no-subscriptions',
+          'Start server with CORS and subscriptions disabled'
+        )
+        .example('$0 start --debug', 'Start server in debug mode (verbose logging + notifications)')
+        .example(
+          '$0 start --debug --enable-metrics',
+          'Start server in debug mode with performance metrics'
+        )
+    );
+  },
+  async (argv: StartArgs) => {
+    try {
+      systemLogger.info('🚀 Starting Dubhe GraphQL server via CLI...', {
+        port: argv.port,
+        schema: argv.schema,
+        endpoint: argv.endpoint,
+        environment: argv.env
+      });
+
+      // Build server configuration object
+      const serverConfig: ServerConfig = {
+        // Basic server configuration
+        port: argv.port,
+        databaseUrl: argv['database-url'],
+        schema: argv.schema,
+        endpoint: argv.endpoint,
+        cors: argv.cors,
+        subscriptions: argv.subscriptions,
+        env: argv.env,
+
+        // Debug configuration (explicit control)
+        debug: argv.debug,
+
+        // Performance configuration
+        queryTimeout: argv['query-timeout'],
+        maxConnections: argv['max-connections'],
+        heartbeatInterval: argv['heartbeat-interval'],
+
+        // Subscription capabilities
+        enableLiveQueries: argv['enable-live-queries'],
+        enablePgSubscriptions: argv['enable-pg-subscriptions'],
+        enableNativeWebSocket: argv['enable-native-websocket'],
+        realtimePort: argv['realtime-port'],
+
+        // Debug configuration (notifications only in development or when debug is enabled)
+        debugNotifications: argv.debug || argv.env === 'development',
+        enableMetrics: argv['enable-metrics']
+      };
+
+      // Pass configuration object directly to startServer
+      await startServer(serverConfig);
+    } catch (error: unknown) {
+      systemLogger.error('Failed to start server via CLI', error);
+      process.exit(1);
+    }
+  }
+);
+
+// Parse command line arguments
+cli.parse();

package/src/config/subscription-config.ts

@@ -0,0 +1,243 @@
+// Subscription configuration manager - supports dynamic configuration for three subscription modes
+
+export interface SubscriptionCapabilities {
+  liveQueries: boolean;
+  pgSubscriptions: boolean;
+  nativeWebSocket: boolean;
+}
+
+export interface SubscriptionConfig {
+  // Basic configuration
+  enableSubscriptions: boolean;
+
+  // Capability configuration
+  capabilities: SubscriptionCapabilities;
+
+  // Database configuration detection
+  walLevel: 'minimal' | 'replica' | 'logical';
+
+  // Port configuration
+  graphqlPort: number;
+  websocketPort?: number;
+
+  // Performance configuration
+  maxConnections: number;
+  heartbeatInterval: number;
+
+  // Debug configuration
+  enableNotificationLogging: boolean;
+  enablePerformanceMetrics: boolean;
+}
+
+// Subscription configuration input parameter interface
+export interface SubscriptionConfigInput {
+  enableSubscriptions: boolean;
+  databaseUrl: string;
+  port: string;
+  enableLiveQueries?: boolean;
+  enablePgSubscriptions?: boolean;
+  enableNativeWebSocket?: boolean;
+  realtimePort?: string;
+  maxConnections?: string;
+  heartbeatInterval?: string;
+  debugNotifications?: boolean;
+  enableMetrics?: boolean;
+}
+
+export class SubscriptionConfigManager {
+  private config: SubscriptionConfig;
+
+  constructor(configInput: SubscriptionConfigInput) {
+    this.config = this.parseConfigInput(configInput);
+  }
+
+  // Parse configuration from input parameters
+  private parseConfigInput(input: SubscriptionConfigInput): SubscriptionConfig {
+    const enableSubscriptions = input.enableSubscriptions;
+
+    // Auto-detect WAL level (in actual applications, query through database)
+    const walLevel = this.detectWalLevel(input.databaseUrl);
+
+    // Determine capabilities based on input parameters - default enable all features when subscriptions are enabled
+    const capabilities: SubscriptionCapabilities = {
+      liveQueries:
+        enableSubscriptions && input.enableLiveQueries !== false && walLevel === 'logical',
+
+      pgSubscriptions: enableSubscriptions && input.enablePgSubscriptions !== false,
+
+      nativeWebSocket: enableSubscriptions && input.enableNativeWebSocket !== false
+    };
+
+    return {
+      enableSubscriptions,
+      capabilities,
+      walLevel,
+
+      graphqlPort: parseInt(input.port),
+      websocketPort: input.realtimePort ? parseInt(input.realtimePort) : undefined,
+
+      maxConnections: parseInt(input.maxConnections || '1000'),
+      heartbeatInterval: parseInt(input.heartbeatInterval || '30000'),
+
+      enableNotificationLogging: input.debugNotifications === true,
+      enablePerformanceMetrics: input.enableMetrics === true
+    };
+  }
+
+  // Detect database WAL level
+  private detectWalLevel(_databaseUrl?: string): 'minimal' | 'replica' | 'logical' {
+    // In actual applications should query database
+    // SELECT setting FROM pg_settings WHERE name = 'wal_level';
+
+    // Currently return default value
+    return 'replica';
+  }
+
+  // Get current configuration
+  getConfig(): SubscriptionConfig {
+    return { ...this.config };
+  }
+
+  // Get recommended subscription method
+  getRecommendedSubscriptionMethod(): string {
+    if (this.config.capabilities.liveQueries) {
+      return 'live-queries';
+    } else if (this.config.capabilities.pgSubscriptions) {
+      return 'pg-subscriptions';
+    } else if (this.config.capabilities.nativeWebSocket) {
+      return 'native-websocket';
+    } else {
+      return 'none';
+    }
+  }
+
+  // Generate client configuration
+  generateClientConfig() {
+    const baseUrl = `http://localhost:${this.config.graphqlPort}`;
+
+    return {
+      graphqlEndpoint: `${baseUrl}/graphql`,
+      subscriptionEndpoint:
+        this.config.capabilities.pgSubscriptions || this.config.capabilities.liveQueries
+          ? `ws://localhost:${this.config.graphqlPort}/graphql`
+          : undefined,
+      nativeWebSocketEndpoint: this.config.capabilities.nativeWebSocket
+        ? `ws://localhost:${this.config.websocketPort || this.config.graphqlPort}`
+        : undefined,
+      capabilities: this.config.capabilities,
+      recommendedMethod: this.getRecommendedSubscriptionMethod()
+    };
+  }
+
+  // Generate PostGraphile configuration - simplified version, only keep listen subscriptions
+  generatePostGraphileConfig() {
+    return {
+      subscriptions: this.config.enableSubscriptions,
+      live: false, // Disable live queries, only use listen subscriptions
+      simpleSubscriptions: this.config.capabilities.pgSubscriptions,
+
+      // Performance configuration - optimized for listen subscriptions
+      pgSettings: {
+        statement_timeout: '30s',
+        default_transaction_isolation: 'read committed'
+      },
+
+      // Monitoring configuration
+      allowExplain: this.config.enablePerformanceMetrics,
+      disableQueryLog: !this.config.enableNotificationLogging
+    };
+  }
+
+  // Generate environment variable documentation
+  generateDocumentation(): string {
+    return `
+# 📡 Subscription System Configuration Guide
+
+## Basic Configuration
+enableSubscriptions=${
+      this.config.enableSubscriptions
+    }         # Enable/disable subscription features
+
+## Capability Configuration (optional, auto-detect by default)
+enableLiveQueries=${
+      this.config.capabilities.liveQueries
+    }           # Enable @live directive (requires wal_level=logical)
+enablePgSubscriptions=${
+      this.config.capabilities.pgSubscriptions
+    }       # Enable PostgreSQL subscriptions 
+enableNativeWebSocket=${this.config.capabilities.nativeWebSocket}       # Enable native WebSocket
+
+## Port Configuration
+port=${this.config.graphqlPort}                          # GraphQL port
+realtimePort=${
+      this.config.websocketPort || 'undefined'
+    }                 # Native WebSocket port (optional)
+
+## Performance Configuration
+maxConnections=${this.config.maxConnections}  # Maximum connections
+heartbeatInterval=${this.config.heartbeatInterval}  # Heartbeat interval (ms)
+
+## Debug Configuration
+debugNotifications=${this.config.enableNotificationLogging}         # Notification logging
+enableMetrics=${this.config.enablePerformanceMetrics} # Performance metrics
+
+## Current Configuration Status:
+- Subscription Features: ${this.config.enableSubscriptions ? '✅ Enabled' : '❌ Disabled'}
+- Live Queries: ${this.config.capabilities.liveQueries ? '✅ Available' : '❌ Not Available'}
+- PG Subscriptions: ${
+      this.config.capabilities.pgSubscriptions ? '✅ Available' : '❌ Not Available'
+    }  
+- Native WebSocket: ${
+      this.config.capabilities.nativeWebSocket ? '✅ Available' : '❌ Not Available'
+    }
+- WAL Level: ${this.config.walLevel}
+- Recommended Method: ${this.getRecommendedSubscriptionMethod()}
+		`;
+  }
+}
+
+// Export singleton instance - lazy initialization
+let _subscriptionConfigInstance: SubscriptionConfigManager | null = null;
+
+export const subscriptionConfig = {
+  getConfig(): SubscriptionConfig {
+    if (!_subscriptionConfigInstance) {
+      throw new Error(
+        'Subscription config not initialized. Call refresh() first with configuration.'
+      );
+    }
+    return _subscriptionConfigInstance.getConfig();
+  },
+
+  generateClientConfig() {
+    if (!_subscriptionConfigInstance) {
+      throw new Error(
+        'Subscription config not initialized. Call refresh() first with configuration.'
+      );
+    }
+    return _subscriptionConfigInstance.generateClientConfig();
+  },
+
+  generatePostGraphileConfig() {
+    if (!_subscriptionConfigInstance) {
+      throw new Error(
+        'Subscription config not initialized. Call refresh() first with configuration.'
+      );
+    }
+    return _subscriptionConfigInstance.generatePostGraphileConfig();
+  },
+
+  generateDocumentation(): string {
+    if (!_subscriptionConfigInstance) {
+      throw new Error(
+        'Subscription config not initialized. Call refresh() first with configuration.'
+      );
+    }
+    return _subscriptionConfigInstance.generateDocumentation();
+  },
+
+  // Initialize/refresh configuration with input parameters
+  refresh(configInput: SubscriptionConfigInput) {
+    _subscriptionConfigInstance = new SubscriptionConfigManager(configInput);
+  }
+};

package/src/index.ts

@@ -0,0 +1,11 @@
+// import { startServer } from './server';
+// import { systemLogger } from './utils/logger';
+
+// // // Start application
+// // systemLogger.info('🚀 Starting Sui Indexer GraphQL Server (Express Architecture)...', {
+// //   nodeVersion: process.version,
+// //   platform: process.platform,
+// //   pid: process.pid
+// // });
+
+// // startServer();

package/src/plugins/README.md

@@ -0,0 +1,138 @@
+# GraphQL Server Plugin Architecture
+
+This directory contains various functional module plugins for the Sui Indexer GraphQL server, using modular design for easy management and extension.
+
+## 📁 Plugin Structure
+
+### Core Plugins
+
+#### `database-introspector.ts` - Database Introspector
+
+- **Function**: Scan and analyze database table structure
+- **Main Class**: `DatabaseIntrospector`
+- **Responsibilities**:
+  - Get store\_\* dynamic tables
+  - Get system tables (dubhe related)
+  - Get field information from table_fields
+  - Test database connection
+  - Output table structure logs
+
+#### `welcome-page.ts` - Welcome Page Generator
+
+- **Function**: Generate server homepage
+- **Main Function**: `createWelcomePage()`
+- **Responsibilities**:
+  - Display server status and configuration information
+  - Show detected data tables
+  - Provide navigation links and usage guides
+  - Responsive design and beautiful interface
+
+#### `postgraphile-config.ts` - PostGraphile Configuration Generator
+
+- **Function**: Create PostGraphile configuration
+- **Main Function**: `createPostGraphileConfig()`
+- **Responsibilities**:
+  - Configure GraphQL endpoints and features
+  - Integrate enhanced Playground
+  - Set up subscriptions and real-time queries
+  - Optimize performance parameters
+
+#### `subscription-manager.ts` - Subscription Manager
+
+- **Function**: Manage GraphQL subscription features
+- **Main Class**: `SubscriptionManager`
+- **Responsibilities**:
+  - Load @graphile/pg-pubsub plugin
+  - Configure custom subscription plugins
+  - Error handling and fallback solutions
+  - Output subscription status information
+
+#### `server-manager.ts` - Server Manager
+
+- **Function**: Manage HTTP and WebSocket servers
+- **Main Class**: `ServerManager`
+- **Responsibilities**:
+  - Create and configure HTTP server
+  - Start real-time subscription server
+  - Database change monitoring
+  - Graceful shutdown handling
+
+#### `enhanced-playground.ts` - Enhanced GraphQL Playground
+
+- **Function**: Provide modern GraphQL IDE
+- **Main Function**: `createEnhancedPlayground()`
+- **Responsibilities**:
+  - Visual Schema Explorer
+  - Code export functionality
+  - Modern UI interface
+  - Keyboard shortcuts support
+
+## 🔧 Usage
+
+### Unified Import
+
+```typescript
+import {
+  DatabaseIntrospector,
+  createPostGraphileConfig,
+  SubscriptionManager,
+  ServerManager,
+  WelcomePageConfig
+} from './plugins';
+```
+
+### Typical Usage Flow
+
+1. **Database Scanning**: Use `DatabaseIntrospector` to get table structure
+2. **Subscription Configuration**: Load plugins through `SubscriptionManager`
+3. **Configuration Generation**: Create configuration using `createPostGraphileConfig`
+4. **Server Startup**: Manage server lifecycle through `ServerManager`
+
+## 🎯 Design Advantages
+
+### Modular Design
+
+- Each plugin has a single clear responsibility
+- Easy to test and maintain individually
+- Supports independent upgrades and replacements
+
+### Type Safety
+
+- Complete TypeScript support
+- Clear interface definitions
+- Compile-time error checking
+
+### Extensibility
+
+- Plugin architecture easy to extend
+- Supports custom plugin development
+- Flexible and adjustable configuration
+
+### Error Handling
+
+- Graceful error degradation
+- Detailed log output
+- Fault isolation protection
+
+## 📈 Extension Guide
+
+### Adding New Plugins
+
+1. Create new file in `plugins/` directory
+2. Export main interfaces and classes
+3. Add export in `index.ts`
+4. Update main entry file to use
+
+### Custom Configuration
+
+- Pass configuration through environment variables
+- Use interfaces to define configuration structure
+- Support runtime dynamic configuration
+
+### Plugin Integration
+
+- Follow unified error handling patterns
+- Use consistent log formats
+- Maintain interface compatibility
+
+This architecture makes the GraphQL server more modular, maintainable, and provides a solid foundation for future feature extensions.