feat: add global settings for application configuration and enable Swagger documentation control

Author: JasonKrik

services/backend/GLOBAL_SETTINGS.md

@@ -692,6 +692,16 @@ When the server starts:
 | `github.oauth.callback_url` | `'http://localhost:3000/api/auth/github/callback'` | ❌ | ❌ | OAuth callback URL |
 | `github.oauth.scope` | `'user:email'` | ❌ | ❌ | OAuth requested scopes |
 
+#### Global Settings (Group ID: `global`)
+
+| Key | Default | Required | Encrypted | Description |
+|-----|---------|----------|-----------|-------------|
+| `global.page_url` | `'http://localhost:5173'` | ❌ | ❌ | Base URL for the application frontend |
+| `global.send_mail` | `'false'` | ❌ | ❌ | Enable or disable email sending functionality |
+| `global.enable_login` | `'true'` | ❌ | ❌ | Enable or disable all login functionality |
+| `global.enable_email_registration` | `'true'` | ❌ | ❌ | Enable or disable email registration |
+| `global.enable_swagger_docs` | `'true'` | ❌ | ❌ | Enable or disable Swagger API documentation endpoint (/documentation) |
+
 ### Helper Methods
 
 The system provides helper methods for retrieving complete configurations:

services/backend/src/global-settings/global.ts

@@ -40,6 +40,14 @@ export const globalSettings: GlobalSettingsModule = {
       description: 'Enable or disable email registration',
       encrypted: false,
       required: false
+    },
+    {
+      key: 'global.enable_swagger_docs',
+      defaultValue: true,
+      type: 'boolean',
+      description: 'Enable or disable Swagger API documentation endpoint (/documentation)',
+      encrypted: false,
+      required: false
     }
   ]
 };

services/backend/src/server.ts

@@ -24,6 +24,8 @@ import {
   getDbStatus
 } from './db'
 import { GlobalSettingsInitService } from './global-settings'
+import { GlobalSettings } from './global-settings/helpers';
+import { GlobalSettingsService } from './services/globalSettingsService'; // Import the service
 import type SqliteDriver from 'better-sqlite3'; // For type checking in onClose
 import type { FastifyInstance } from 'fastify'
 
@@ -145,19 +147,85 @@ export const createServer = async () => {
   });
   server.log.info('@fastify/cookie registered.');
 
-  // Register Swagger for API documentation
+  await registerFastifyPlugins(server) // Existing plugin registrations
+  
+  // Register favicon after Swagger to exclude it from documentation
+  const fastifyFavicon = await import('fastify-favicon');
+  await server.register(fastifyFavicon.default, {
+    path: '../shared/public/img',
+    name: 'favicon.ico',
+    maxAge: 604800
+  })
+
+  // Register the global authentication hook
+  // This hook will run on every request to populate request.user and request.session
+  server.addHook('onRequest', authHook);
+  server.log.info('Global auth hook registered.');
+
+  // Create and configure the plugin manager
+  const isDevelopment = process.env.NODE_ENV !== 'production';
+  const pluginManager = new PluginManager({
+    paths: [
+      process.env.PLUGINS_PATH || (isDevelopment 
+        ? path.join(process.cwd(), 'src', 'plugins')
+        : path.join(__dirname, 'plugins')),
+    ],
+    plugins: {}
+  })
+  
+  pluginManager.setApp(server); // Set app early for plugins that might need it
+
+  // Discover available plugins first
+  await pluginManager.discoverPlugins();
+  
+  // Register plugin table definitions (populates inputPluginTableDefinitions in db/index.ts)
+  // This must happen before initializeDatabase, which generates the actual schema
+  registerPluginTables(pluginManager.getAllPlugins());
+
+  // Initialize database-dependent services
+  await initializeDatabaseDependentServices(server, pluginManager);
+
+  // Conditionally register Swagger for API documentation
+  // This is placed after DB & global settings initialization to ensure settings are available
+  let swaggerEnabled: boolean;
+  if ((server as any).db === null) {
+    server.log.info('Database not available. Enabling Swagger documentation by default during setup phase.');
+    swaggerEnabled = true;
+  } else {
+    try {
+      server.log.info('Database is available. Checking "global.enable_swagger_docs" setting.');
+      swaggerEnabled = await GlobalSettings.getBoolean('global.enable_swagger_docs', true);
+      // The log message below was removed as it's covered by more specific logs later.
+    } catch (error) {
+      server.log.error('Error fetching "global.enable_swagger_docs" setting. Defaulting to true.', error);
+      swaggerEnabled = true;
+    }
+  }
+
+  // Always register Swagger and SwaggerUI. Access will be controlled by the preHandler.
+  // The swaggerEnabled variable is now only used for an initial log message.
+  if (swaggerEnabled) {
+    server.log.info('Initial check: Swagger documentation will be attempted to register. Access controlled by preHandler.');
+  } else {
+    server.log.info('Initial check: Swagger documentation was disabled by setting at startup, but routes will still be registered. Access controlled by preHandler.');
+  }
+
+  const host = process.env.HOST || 'localhost';
+  const port = process.env.PORT || '3000';
+  const serverUrl = `http://${host}:${port}`;
+
   await server.register(fastifySwagger, {
     openapi: {
       openapi: '3.0.0',
       info: {
         title: 'DeployStack Backend API',
         description: 'API documentation for DeployStack Backend',
-        version: '0.20.5'
+        version: '0.20.5' // We need to make this dynamic from package.json
       },
       servers: [
         {
-          url: 'http://localhost:3000',
-          description: 'Development server'
+          url: serverUrl,
+          description: process.env.NODE_ENV === 'development' ? 'Development server' : 'Server'
         }
       ],
       components: {
@@ -181,11 +249,39 @@ export const createServer = async () => {
     },
     uiHooks: {
       onRequest: function (_request, _reply, next) { next() },
-      preHandler: function (_request, _reply, next) { next() }
+      preHandler: async function (request, reply, next) {
+        // On-the-fly check for swagger documentation
+        let showSwagger = true; // Default to true if setting is missing or error occurs
+        if ((request.server as any).db !== null) {
+          try {
+            await GlobalSettings.refreshCaches(); // Attempt to refresh any underlying caches
+            const setting = await GlobalSettingsService.get('global.enable_swagger_docs');
+            if (setting && typeof setting.value === 'string') {
+              const valueLower = setting.value.toLowerCase();
+              showSwagger = !(valueLower === 'false' || valueLower === '0' || valueLower === 'no' || valueLower === 'off' || valueLower === 'disabled');
+            } else {
+              // If setting is not found or value is not a string, default to true (as per defaultValue in global.ts)
+              showSwagger = true; 
+            }
+            request.server.log.info(`Swagger UI access check (using Service): "global.enable_swagger_docs" is ${showSwagger}. Raw value: ${setting ? setting.value : 'Not found'}`);
+          } catch (err) {
+            request.server.log.error('Error fetching "global.enable_swagger_docs" with Service in preHandler. Defaulting to show Swagger.', err);
+            showSwagger = true;
+          }
+        } else {
+          request.server.log.info('Swagger UI access check: Database not available, showing Swagger UI by default.');
+          showSwagger = true;
+        }
+
+        if (!showSwagger) {
+          reply.code(404).send({ error: 'Not Found', message: 'API documentation is disabled.' });
+        } else {
+          next();
+        }
+      }
     },
     staticCSP: true,
     transformStaticCSP: (header) => header,
-    // eslint-disable-next-line @typescript-eslint/no-unused-vars
     transformSpecification: (swaggerObject, _request, _reply) => {
       // Remove favicon route from the API specification
       if (swaggerObject.paths && swaggerObject.paths['/favicon.ico']) {
@@ -195,45 +291,9 @@ export const createServer = async () => {
     },
     transformSpecificationClone: true
   });
-  server.log.info('Swagger documentation registered at /documentation');
-
-  await registerFastifyPlugins(server) // Existing plugin registrations
-  
-  // Register favicon after Swagger to exclude it from documentation
-  const fastifyFavicon = await import('fastify-favicon');
-  await server.register(fastifyFavicon.default, {
-    path: '../shared/public/img',
-    name: 'favicon.ico',
-    maxAge: 604800
-  })
-
-  // Register the global authentication hook
-  // This hook will run on every request to populate request.user and request.session
-  server.addHook('onRequest', authHook);
-  server.log.info('Global auth hook registered.');
-
-  // Create and configure the plugin manager
-  const isDevelopment = process.env.NODE_ENV !== 'production';
-  const pluginManager = new PluginManager({
-    paths: [
-      process.env.PLUGINS_PATH || (isDevelopment 
-        ? path.join(process.cwd(), 'src', 'plugins')
-        : path.join(__dirname, 'plugins')),
-    ],
-    plugins: {}
-  })
-  
-  pluginManager.setApp(server); // Set app early for plugins that might need it
-
-  // Discover available plugins first
-  await pluginManager.discoverPlugins();
-  
-  // Register plugin table definitions (populates inputPluginTableDefinitions in db/index.ts)
-  // This must happen before initializeDatabase, which generates the actual schema
-  registerPluginTables(pluginManager.getAllPlugins());
-
-  // Initialize database-dependent services
-  await initializeDatabaseDependentServices(server, pluginManager);
+    // Log registration; preHandler will control access dynamically
+    server.log.info('Swagger documentation routes registered at /documentation. Access is dynamically controlled by the "global.enable_swagger_docs" setting via a preHandler.');
+  // The `else` block related to initial swaggerEnabled check is no longer needed here as routes are always registered.
 
   // Initialize plugins (routes, hooks, etc.)
   // This should happen after DB and other core services are ready (or known to be unavailable)