@underpostnet/cyberia 3.2.80

package/src/db/DataBaseProvider.js

@@ -0,0 +1,213 @@
+import { MongooseDB } from './mongo/MongooseDB.js';
+import { loggerFactory } from '../server/logger.js';
+import { getCapVariableName } from '../client/components/core/CommonJs.js';
+import { resolveHostKeyContext } from '../server/conf.js';
+import Underpost from '../index.js';
+
+/**
+ * Module for managing and loading various database connections (e.g., Mongoose, MariaDB).
+ * @module src/db/DataBaseProvider.js
+ * @namespace DataBaseProviderService
+ */
+
+const logger = loggerFactory(import.meta);
+
+/**
+ * @class
+ * @alias DataBaseProviderService
+ * @memberof DataBaseProviderService
+ * @classdesc Service for loading, managing, and accessing multiple database connections
+ * based on application configuration (host, path, provider type).
+ */
+class DataBaseProviderService {
+  /**
+   * Internal storage for database connection instances, keyed by host+path.
+   * @type {object.<string, object>}
+   * @method
+   */
+  static #instance = {};
+
+  /**
+   * Retrieves the internal instance storage for direct access (used for backward compatibility).
+   * @returns {object.<string, object>} The internal connection instance map.
+   */
+  static get instance() {
+    return this.#instance;
+  }
+
+  /**
+   * Retrieves a loaded provider bucket for a context.
+   * @param {{host?: string, path?: string}|string} [context={ host: '', path: '' }] - Context object or key.
+   * @param {string} [provider='mongoose'] - Provider name.
+   * @returns {{models: object, connection: object, close: Function, dbSignature?: string}} Provider bucket.
+   * @throws {Error} When the provider is not loaded for the context.
+   */
+  static getProvider(context = { host: '', path: '' }, provider = 'mongoose') {
+    const key = resolveHostKeyContext(context);
+    const entry = this.#instance[key]?.[provider];
+
+    if (!entry) throw new Error(`Database provider not loaded for context "${key}" (${provider})`);
+    return entry;
+  }
+
+  /**
+   * Returns the raw DB connection object for a context/provider.
+   * @param {{host?: string, path?: string}|string} [context={ host: '', path: '' }] - Context object or key.
+   * @param {string} [provider='mongoose'] - Provider name.
+   * @returns {object} Provider connection object.
+   */
+  static getConnection(context = { host: '', path: '' }, provider = 'mongoose') {
+    return this.getProvider(context, provider).connection;
+  }
+
+  /**
+   * Resolves a loaded model by name for a given context/provider.
+   * @param {string} modelName - API/model identifier.
+   * @param {{host?: string, path?: string}|string} [context={ host: '', path: '' }] - Context object or key.
+   * @param {string} [provider='mongoose'] - Provider name.
+   * @returns {object} Loaded model instance.
+   * @throws {Error} When the model is not loaded for the context.
+   */
+  static getModel(modelName, context = { host: '', path: '' }, provider = 'mongoose') {
+    const models = this.getProvider(context, provider).models || {};
+    const normalizedModelName = getCapVariableName(modelName);
+
+    // First try direct key (supports callers passing exact model names).
+    let model = models?.[modelName];
+    if (!model) {
+      model = models?.[normalizedModelName];
+    }
+
+    if (!model) {
+      // Final fallback: case-insensitive comparison without separators.
+      const target = String(modelName || '')
+        .replaceAll('-', '')
+        .replaceAll('_', '')
+        .replaceAll(' ', '')
+        .toLowerCase();
+      const resolvedModelName = Object.keys(models).find(
+        (key) => key.replaceAll('_', '').replaceAll(' ', '').toLowerCase() === target,
+      );
+      if (resolvedModelName) model = models[resolvedModelName];
+    }
+
+    if (!model) {
+      throw new Error(`Model not loaded for context "${resolveHostKeyContext(context)}": ${normalizedModelName}`);
+    }
+
+    return model;
+  }
+
+  /**
+   * Builds a minimal dispatcher bound to a specific context/provider.
+   * @param {{host?: string, path?: string}|string} [context={ host: '', path: '' }] - Context object or key.
+   * @param {string} [provider='mongoose'] - Provider name.
+   * @returns {{getConnection: () => object, getModel: (modelName: string) => object}} Bound accessor helpers.
+   */
+  static getDispatcher(context = { host: '', path: '' }, provider = 'mongoose') {
+    return {
+      getConnection: () => this.getConnection(context, provider),
+      getModel: (modelName) => this.getModel(modelName, context, provider),
+    };
+  }
+
+  /**
+   * Builds a stable signature used to detect provider configuration changes.
+   * @param {object} [db={}] - Database configuration object.
+   * @returns {string} Stringified signature for change detection.
+   */
+  static buildDbSignature(db = {}) {
+    return JSON.stringify({
+      authSource: db.authSource || '',
+      host: db.host || '',
+      name: db.name || '',
+      provider: db.provider || '',
+      replicaSet: db.replicaSet || '',
+    });
+  }
+
+  /**
+   * Loads and initializes a database provider based on the configuration.
+   * If the connection is already loaded for the given host/path, it returns the existing instance.
+   *
+   * @async
+   * @param {object} [options] - Configuration for the database connection.
+   * @param {Array<string>} [options.apis=[]] - List of APIs whose models should be loaded (for Mongoose).
+   * @param {string} [options.host=''] - The host part of the application context (e.g., domain).
+   * @param {string} [options.path=''] - The path part of the application context.
+   * @param {object} [options.db={}] - The specific database configuration object.
+   * @param {string} options.db.provider - The name of the database provider ('mongoose', 'mariadb', etc.).
+   * @param {string} options.db.host - The database server host.
+   * @param {string} options.db.name - The database name.
+   * @returns {Promise<object|undefined>} A promise that resolves to the initialized provider object
+   * or `undefined` on error or if the provider is already loaded.
+   */
+  static async load(options = { apis: [], host: '', path: '', db: {} }) {
+    try {
+      const { apis, host, path, db } = options;
+      const key = resolveHostKeyContext({ host, path });
+      const dbSignature = DataBaseProviderService.buildDbSignature(db);
+
+      if (!this.#instance[key]) this.#instance[key] = {};
+      if (!db) return undefined;
+
+      const currentProvider = this.#instance[key][db.provider];
+      if (currentProvider && currentProvider.dbSignature === dbSignature) return currentProvider;
+
+      if (currentProvider && currentProvider.close) {
+        await currentProvider.close();
+        delete this.#instance[key][db.provider];
+      }
+
+      // logger.info(`Load ${db.provider} provider`, key);
+      switch (db.provider) {
+        case 'mongoose':
+          {
+            const conn = await MongooseDB.connect(db);
+            this.#instance[key][db.provider] = {
+              dbSignature,
+              models: await MongooseDB.loadModels({ conn, apis }),
+              connection: conn,
+              close: async () => {
+                return await new Promise((resolve) => {
+                  this.#instance[key][db.provider].connection.close().then(() => {
+                    // logger.info('Mongoose connection is disconnected', db);
+                    return resolve();
+                  });
+                });
+              },
+            };
+          }
+          break;
+        default:
+          break;
+      }
+      return this.#instance[key][db.provider];
+    } catch (error) {
+      // Sanitize options to prevent credential exposure in logs
+      const safeOptions = {
+        apis: options.apis,
+        host: options.host,
+        path: options.path,
+        db: options.db
+          ? {
+              provider: options.db.provider,
+              name: options.db.name ? '***' : undefined,
+              host: options.db.host ? '***' : undefined,
+              user: options.db.user ? '***' : undefined,
+              password: options.db.password ? '***' : undefined,
+            }
+          : {},
+      };
+      logger.error(error.message, { safeOptions });
+      if (Underpost.env.isInsideContainer()) Underpost.env.set('container-status', 'error');
+      return undefined;
+    }
+  }
+}
+
+export {
+  DataBaseProviderService as DataBaseProviderClass,
+  DataBaseProviderService as default,
+  DataBaseProviderService,
+};

package/src/db/mariadb/MariaDB.js

@@ -0,0 +1,72 @@
+import { createPool } from 'mariadb';
+import Underpost from '../../index.js';
+import { loggerFactory } from '../../server/logger.js';
+
+/**
+ * Module for interacting with MariaDB/MySQL databases using the mariadb connector.
+ * @module src/db/MariaDB.js
+ * @namespace MariaDBService
+ */
+
+const logger = loggerFactory(import.meta);
+
+/**
+ * @class
+ * @alias MariaDBService
+ * @memberof MariaDBService
+ * @classdesc Provides a simplified interface for executing queries against a MariaDB/MySQL database
+ * using a connection pool, ensuring connection management (acquisition and release).
+ *
+ * Connection credentials are resolved in the following order:
+ * 1. Explicit values passed in the `options` parameter.
+ * 2. Environment variables (`MARIADB_HOST`, `MARIADB_PORT`, `MARIADB_USER`, `MARIADB_PASSWORD`).
+ * 3. Safe built-in defaults (`127.0.0.1`, `3306`, `root`, empty password).
+ */
+class MariaDBService {
+  /**
+   * Executes a SQL query against the MariaDB database.
+   *
+   * @async
+   * @param {object} options - The database connection and query options.
+   * @param {string} [options.host] - The database host. Falls back to `process.env.MARIADB_HOST` then `'127.0.0.1'`.
+   * @param {number} [options.port] - The database port. Falls back to `process.env.MARIADB_PORT` then `3306`.
+   * @param {string} [options.user] - The database user. Falls back to `process.env.MARIADB_USER` then `'root'`.
+   * @param {string} [options.password] - The database password. Falls back to `process.env.MARIADB_PASSWORD` then `''`.
+   * @param {string} options.query - The SQL query string to execute.
+   * @returns {Promise<any>} The result of the database query.
+   */
+  async query(options) {
+    const { host, port, user, password, query } = options;
+    const pool = createPool({
+      host: 'host' in options ? host : process.env.MARIADB_HOST || '127.0.0.1',
+      port: 'port' in options ? port : parseInt(process.env.MARIADB_PORT, 10) || 3306,
+      user: 'user' in options ? user : process.env.MARIADB_USER || 'root',
+      password: 'password' in options ? password : process.env.MARIADB_PASSWORD || '',
+    });
+    let conn, result;
+    try {
+      conn = await pool.getConnection();
+      result = await conn.query(query, { supportBigNumbers: true, bigNumberStrings: true });
+      logger.info('query');
+      console.log(result);
+    } catch (error) {
+      logger.error('MariaDB query failed', { error: error.message });
+      if (Underpost.env.isInsideContainer()) Underpost.env.set('container-status', 'error');
+    } finally {
+      if (conn) conn.release(); // release to pool
+      await pool.end();
+    }
+
+    return result;
+  }
+}
+
+/**
+ * Singleton instance of the MariaDBService class for backward compatibility.
+ * @alias MariaDB
+ * @memberof MariaDBService
+ * @type {MariaDBService}
+ */
+const MariaDB = new MariaDBService();
+
+export { MariaDB, MariaDBService as MariaDBClass };