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

package/src/plugins/README.md

@@ -0,0 +1,123 @@
+# 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. 

package/src/plugins/all-fields-filter-plugin.ts

@@ -0,0 +1,158 @@
+import { Plugin } from 'postgraphile';
+
+// All fields filter plugin - ensure all fields support filtering
+export const AllFieldsFilterPlugin: Plugin = (builder) => {
+  // Extend filter input type, add filter support for all fields
+  builder.hook('GraphQLInputObjectType:fields', (fields, build, context) => {
+    const {
+      scope: { isPgConnectionFilter, pgIntrospection: table }
+    } = context;
+
+    // Only handle connection filters
+    if (!isPgConnectionFilter || !table || table.kind !== 'class') {
+      return fields;
+    }
+
+    const enhancedFields = { ...fields };
+
+    // Add filters for each field of the table
+    table.attributes.forEach((attr: any) => {
+      const fieldName = build.inflection.column(attr);
+
+      // Skip fields that already exist
+      if (enhancedFields[fieldName]) {
+        return;
+      }
+
+      // Determine filter type based on field type
+      let filterType;
+      const pgType = attr.type;
+
+      // Special handling for BigInt type
+      if (pgType.name === 'int8' || pgType.name === 'bigint') {
+        // For BigInt type, try to use StringFilter (because BigInt is represented as string in GraphQL)
+        filterType = build.getTypeByName('StringFilter');
+      } else {
+        // Map PostgreSQL types to GraphQL filter types
+        switch (pgType.category) {
+          case 'S': // String type
+            filterType = build.getTypeByName('StringFilter');
+            break;
+          case 'N': // Numeric type
+            if (pgType.name.includes('int')) {
+              filterType = build.getTypeByName('IntFilter');
+            } else {
+              filterType = build.getTypeByName('FloatFilter');
+            }
+            break;
+          case 'B': // Boolean type
+            filterType = build.getTypeByName('BooleanFilter');
+            break;
+          case 'D': // Date/time type
+            filterType = build.getTypeByName('DatetimeFilter');
+            break;
+          default:
+            // For other types, use string filter as default
+            filterType = build.getTypeByName('StringFilter');
+        }
+      }
+
+      // If specific filter type not found, use string filter
+      if (!filterType) {
+        filterType = build.getTypeByName('StringFilter');
+      }
+
+      // Add field filter
+      if (filterType) {
+        enhancedFields[fieldName] = {
+          type: filterType,
+          description: `Filter by the object's \`${attr.name}\` field.`
+        };
+      }
+    });
+
+    return enhancedFields;
+  });
+
+  // Ensure sorting options are generated for all fields
+  builder.hook('GraphQLEnumType:values', (values, build, context) => {
+    const {
+      scope: { isPgRowSortEnum, pgIntrospection: table }
+    } = context;
+
+    if (!isPgRowSortEnum || !table || table.kind !== 'class') {
+      return values;
+    }
+
+    const enhancedValues = { ...values };
+
+    // Add ASC and DESC sorting options for each field
+    table.attributes.forEach((attr: any) => {
+      const columnName = build.inflection.column(attr);
+      const enumName = build.inflection.constantCase(columnName);
+
+      // Add ascending sort
+      const ascKey = `${enumName}_ASC`;
+      if (!enhancedValues[ascKey]) {
+        enhancedValues[ascKey] = {
+          value: {
+            alias: `${attr.name.toLowerCase()}_ASC`,
+            specs: [[attr.name, true]]
+          },
+          description: `Sorts by ${attr.name} in ascending order.`
+        };
+      }
+
+      // Add descending sort
+      const descKey = `${enumName}_DESC`;
+      if (!enhancedValues[descKey]) {
+        enhancedValues[descKey] = {
+          value: {
+            alias: `${attr.name.toLowerCase()}_DESC`,
+            specs: [[attr.name, false]]
+          },
+          description: `Sorts by ${attr.name} in descending order.`
+        };
+      }
+    });
+
+    return enhancedValues;
+  });
+
+  // Extend condition filters to support all fields
+  builder.hook('GraphQLInputObjectType:fields', (fields, build, context) => {
+    const {
+      scope: { isPgCondition, pgIntrospection: table }
+    } = context;
+
+    if (!isPgCondition || !table || table.kind !== 'class') {
+      return fields;
+    }
+
+    const enhancedFields = { ...fields };
+
+    // Add condition filters for each field
+    table.attributes.forEach((attr: any) => {
+      const fieldName = build.inflection.column(attr);
+
+      // Skip fields that already exist
+      if (enhancedFields[fieldName]) {
+        return;
+      }
+
+      // Get GraphQL type
+      const gqlType = build.pgGetGqlTypeByTypeIdAndModifier(attr.typeId, attr.typeModifier);
+
+      if (gqlType) {
+        enhancedFields[fieldName] = {
+          type: gqlType,
+          description: `Checks for equality with the object's \`${attr.name}\` field.`
+        };
+      }
+    });
+
+    return enhancedFields;
+  });
+};
+
+export default AllFieldsFilterPlugin;

package/src/plugins/database-introspector.ts

@@ -0,0 +1,126 @@
+import { Pool } from 'pg';
+
+// Database table structure interface
+export interface TableField {
+  field_name: string;
+  field_type: string;
+  field_index: number | null;
+  is_key: boolean;
+}
+
+export interface DynamicTable {
+  table_name: string;
+  fields: TableField[];
+}
+
+// Scan database table structure
+export class DatabaseIntrospector {
+  constructor(private pool: Pool, private schema: string = 'public') {}
+
+  // Get all dynamically created store_* tables
+  async getStoreTables(): Promise<string[]> {
+    const result = await this.pool.query(
+      `
+			SELECT table_name 
+			FROM information_schema.tables 
+			WHERE table_schema = $1 
+				AND table_name LIKE 'store_%'
+			ORDER BY table_name
+		`,
+      [this.schema]
+    );
+
+    return result.rows.map((row) => row.table_name);
+  }
+
+  // Get system tables (dubhe related tables)
+  async getSystemTables(): Promise<string[]> {
+    const result = await this.pool.query(
+      `
+			SELECT table_name 
+			FROM information_schema.tables 
+			WHERE table_schema = $1 
+				AND (table_name = 'table_fields')
+			ORDER BY table_name
+		`,
+      [this.schema]
+    );
+
+    return result.rows.map((row) => row.table_name);
+  }
+
+  // Get dynamic table field information from table_fields table
+  async getDynamicTableFields(tableName: string): Promise<TableField[]> {
+    // Extract table name (remove store_ prefix)
+    const baseTableName = tableName.replace('store_', '');
+
+    const result = await this.pool.query(
+      `
+			SELECT field_name, field_type, field_index, is_key
+			FROM table_fields 
+			WHERE table_name = $1
+			ORDER BY is_key DESC, field_index ASC
+		`,
+      [baseTableName]
+    );
+
+    return result.rows;
+  }
+
+  // Get field information from system tables
+  async getSystemTableFields(tableName: string): Promise<TableField[]> {
+    const result = await this.pool.query(
+      `
+			SELECT 
+				column_name as field_name,
+				data_type as field_type,
+				ordinal_position as field_index,
+				CASE WHEN column_name = 'entity_id' THEN true ELSE false END as is_key
+			FROM information_schema.columns 
+			WHERE table_schema = $1 AND table_name = $2
+			ORDER BY ordinal_position
+		`,
+      [this.schema, tableName]
+    );
+
+    return result.rows;
+  }
+
+  // Get complete information for all tables
+  async getAllTables(): Promise<DynamicTable[]> {
+    const storeTables = await this.getStoreTables();
+    const systemTables = await this.getSystemTables();
+    const allTables: DynamicTable[] = [];
+
+    // Process dynamic tables
+    for (const tableName of storeTables) {
+      const fields = await this.getDynamicTableFields(tableName);
+      allTables.push({
+        table_name: tableName,
+        fields
+      });
+    }
+
+    // Process system tables
+    for (const tableName of systemTables) {
+      const fields = await this.getSystemTableFields(tableName);
+      allTables.push({
+        table_name: tableName,
+        fields
+      });
+    }
+
+    return allTables;
+  }
+
+  // Test database connection
+  async testConnection(): Promise<boolean> {
+    try {
+      await this.pool.query('SELECT NOW() as current_time');
+      return true;
+    } catch (error) {
+      console.error('Database connection test failed:', error);
+      return false;
+    }
+  }
+}

package/src/plugins/enhanced-playground.ts

@@ -0,0 +1,105 @@
+// Enhanced GraphQL Playground plugin
+// Provides better visual experience based on GraphiQL and Explorer plugin
+
+import type { IncomingMessage, ServerResponse } from 'http';
+
+export interface PlaygroundOptions {
+  url: string;
+  subscriptionUrl?: string;
+  title?: string;
+  subtitle?: string;
+}
+
+export function createEnhancedPlayground(
+  options: PlaygroundOptions
+): (req: IncomingMessage, res: ServerResponse, config?: any) => string {
+  return (_req: IncomingMessage, _res: ServerResponse, _config?: any) => {
+    return `
+    
+            <!--
+ *  Copyright (c) 2021 GraphQL Contributors
+ *  All rights reserved.
+ *
+ *  This source code is licensed under the license found in the
+ *  LICENSE file in the root directory of this source tree.
+-->
+<!doctype html>
+<html lang="en">
+  <head>
+    <title>Dubhe Playground</title>
+    <style>
+      body {
+        height: 100%;
+        margin: 0;
+        width: 100%;
+        overflow: hidden;
+      }
+
+      #graphiql {
+        height: 100vh;
+      }
+
+      :global(.graphiql-explorer-root > div:first-child) {
+        /* Remove the 2nd horizontal scroll bar */
+        overflow: hidden !important;
+      }
+    </style>
+    <!--
+      This GraphiQL example depends on Promise and fetch, which are available in
+      modern browsers, but can be "polyfilled" for older browsers.
+      GraphiQL itself depends on React DOM.
+      If you do not want to rely on a CDN, you can host these files locally or
+      include them directly in your favored resource bundler.
+    -->
+    <script
+      crossorigin
+      src="https://unpkg.com/react@18/umd/react.production.min.js"
+    ></script>
+    <script
+      crossorigin
+      src="https://unpkg.com/react-dom@18/umd/react-dom.production.min.js"
+    ></script>
+    <!--
+      These two files can be found in the npm module, however you may wish to
+      copy them directly into your environment, or perhaps include them in your
+      favored resource bundler.
+     -->
+    <script
+      src="https://unpkg.com/graphiql/graphiql.min.js"
+      type="application/javascript"
+    ></script>
+    <link rel="stylesheet" href="https://unpkg.com/graphiql/graphiql.min.css" />
+    <!--
+      These are imports for the GraphIQL Explorer plugin.
+     -->
+    <script
+      src="https://unpkg.com/@graphiql/plugin-explorer/dist/index.umd.js"
+      crossorigin
+    ></script>
+
+    <link
+      rel="stylesheet"
+      href="https://unpkg.com/@graphiql/plugin-explorer/dist/style.css"
+    />
+  </head>
+
+  <body>
+    <div id="graphiql">Loading...</div>
+    <script>
+      const root = ReactDOM.createRoot(document.getElementById('graphiql'));
+      const fetcher = GraphiQL.createFetcher(${JSON.stringify(options)});
+      const explorerPlugin = GraphiQLPluginExplorer.explorerPlugin({
+        showAttribution: true,
+      });
+      root.render(
+        React.createElement(GraphiQL, {
+          fetcher,
+          defaultEditorToolsVisibility: true,
+          plugins: [explorerPlugin],
+        }),
+      );
+    </script>
+  </body>
+</html>`;
+  };
+}