@mostajs/polyglot-bridge

Pont HTTP↔JDBC universel — atteignez n'importe quel SGBD via son driver JDBC (JAR) depuis Node.js, sans driver npm natif.

Auteur : Dr Hamid MADANI [email protected] Licence : AGPL-3.0-or-later

Beaucoup de SGBD n'ont pas de bon driver npm (HSQLDB, DB2, SAP HANA, Sybase, MS Access, Informix, Teradata…) mais tous ont un driver JDBC. Ce paquet lance un process Java mince (MostaJdbcBridge) qui charge le JAR JDBC et expose une petite API HTTP (/query, /health) ; votre code Node lui parle en HTTP. Le JAR fait le travail, Node pilote.

Extrait du moteur de pont de @mostajs/orm, généralisé en module autonome avec un registry de drivers extensible.

Pourquoi

• 🌉 N'importe quel SGBD JDBC depuis Node, sans binding natif.
• 🧩 Registry extensible : registerDriver() pour ajouter MS Access (UCanAccess), Snowflake, Informix… sans patcher le paquet.
• ♻️ Multi-ponts : un pont par driver/URI, ports incrémentaux, réutilisation cross-contexte (scan /health), fichiers PID, nettoyage des orphelins.
• 🪶 Compile-free : exécution source-launcher Java 11+ (java --source 11 … MostaJdbcBridge.java), aucune compilation.

Prérequis

• Node.js ≥ 20
• Java (JDK) 11+ sur le PATH (java --version)
• Le JAR du driver JDBC ciblé, déposé dans jar_files/ (ou MOSTA_JAR_DIR)

Installation

npm install @mostajs/polyglot-bridge
# puis déposez le JAR du driver, ex. :
#   mkdir -p jar_files && cp ~/Downloads/hsqldb.jar jar_files/

Démarrage rapide

import { BridgeManager } from '@mostajs/polyglot-bridge';

const mgr = BridgeManager.getInstance();
const bridge = await mgr.getOrCreate('hsqldb', 'hsqldb:hsql://localhost:9001/mydb');

// SELECT → tableau d'objets ; INSERT/UPDATE/DELETE/DDL → { changes }
await bridge.process.query('CREATE TABLE t (id INTEGER PRIMARY KEY, name VARCHAR(50))');
await bridge.process.query('INSERT INTO t (id, name) VALUES (?, ?)', [1, 'alpha']);
const rows = await bridge.process.query('SELECT id, name FROM t');   // [{ ID: 1, NAME: 'alpha' }]

await mgr.stopAll();

Ajouter un driver (extensibilité)

import { registerDriver, BridgeManager } from '@mostajs/polyglot-bridge';

registerDriver('access', {
  jarPrefix: 'ucanaccess',                       // → ucanaccess*.jar dans jar_files/
  jdbcUrlTemplate: 'jdbc:ucanaccess://{db}',
  defaultPort: 0, defaultUser: '', defaultPassword: '',
  driverClass: 'net.ucanaccess.jdbc.UcanaccessDriver',
  label: 'Microsoft Access (UCanAccess)',
});

const bridge = await BridgeManager.getInstance()
  .getOrCreate('access', 'access:///chemin/vers/base.accdb');

Drivers fournis par défaut : hsqldb · oracle · db2 · sybase · hana · access.

Microsoft Access (UCanAccess) — driver fichier, multi-JAR

Access n'a ni host ni port (la « base » est un fichier .accdb/.mdb) et UCanAccess est multi-JAR. Les deux cas sont gérés nativement (fileBased + companionJarPrefixes).

# Déposer dans jar_files/ les JARs UCanAccess (téléchargeables sur SourceForge) :
#   ucanaccess-5.x.x.jar  jackcess-x.jar  hsqldb-x.jar  commons-lang3-x.jar  commons-logging-x.jar

import { BridgeManager } from '@mostajs/polyglot-bridge';

const mgr = BridgeManager.getInstance();
// Ouvre un fichier existant…
const a = await mgr.getOrCreate('access', 'access:///data/contacts.accdb');
// …ou en crée un neuf :
const b = await mgr.getOrCreate('access', 'access:///data/new.accdb?newDatabaseVersion=V2010');

await b.process.query('CREATE TABLE contacts (id COUNTER PRIMARY KEY, name TEXT(50))');
await b.process.query('INSERT INTO contacts (name) VALUES (?)', ['Ada']);
const rows = await b.process.query('SELECT name FROM contacts');

Le classpath complet (driver + compagnons) est assemblé automatiquement via BridgeProcess.buildClasspath(). Les JARs compagnons absents sont ignorés (best-effort).

API

| Export | Rôle | |---|---| | BridgeManager | Singleton multi-ponts : getOrCreate(driver, uri, opts?), stop(key), stopAll(), list(), has(key). | | BridgeProcess | Un process pont : start(), query(sql, params?), stop(), statiques findJar() / findJarByPrefix() / isAvailable() / buildClasspath(). | | registerDriver / unregisterDriver / getDriverInfo / hasDriver / listDrivers / DEFAULT_DRIVERS | Registry de drivers. | | parseUri / composeJdbcUrl | URI ↔ composants ↔ URL JDBC. | | listJarFiles / saveJarFile / deleteJarFile / getDriverJarStatus / detectDriverFromJar | Gestion des JARs. |

Variables d'environnement

| Var | Défaut | Rôle | |---|---|---| | MOSTA_JAR_DIR | ./jar_files | Dossier des JARs JDBC | | MOSTA_BRIDGE_JAVA | bridge/MostaJdbcBridge.java (du paquet) | Chemin du moteur Java | | MOSTA_BRIDGE_PORT_BASE | 8765 | Port HTTP de base du pont | | MOSTA_BRIDGE_PORT_INCREMENT | true | Auto-incrémente le port si occupé | | MOSTA_BRIDGE_AUTOSTART | true | false → ne lance pas le process (démarrage manuel) | | MOSTA_BRIDGE_MAX_RETRIES | 3 | Anti-boucle de redémarrage |

Architecture

Node  ──HTTP──▶  MostaJdbcBridge (Java)  ──JDBC──▶  SGBD
 (votre code)     -cp driver.jar                    (HSQLDB, DB2, …)

Le moteur Java (bridge/MostaJdbcBridge.java) est embarqué dans le paquet et lancé en mode source-launcher (pas de compilation). BridgeProcess gère un process ; BridgeManager en orchestre plusieurs.

Tests

npm test        # unitaires (registry/uri) + intégration e2e HSQLDB (si Java + jar présents)

Né d'un croisement de domaines : le pont reprend l'esprit du LSP (un process qui parle un protocole standardisé à n'importe quel client) et des sidecars de service mesh, appliqué à l'accès aux bases de données.