outlet-orm 5.5.3 → 6.0.0

package/src/Backup/BackupSocketServer.js

@@ -0,0 +1,347 @@
+/**
+ * BackupSocketServer
+ *
+ * A long-running TCP daemon that manages backup jobs for outlet-orm.
+ * Clients connect, send JSON commands, and receive JSON responses.
+ *
+ * Protocol: newline-delimited JSON (NDJSON) over TCP.
+ *
+ * ─── Client → Server commands ─────────────────────────────────────────
+ *  { "action": "schedule", "type": "full|partial|journal",
+ *    "config": { "intervalMs": 3600000, "tables": [...], "name": "...",
+ *                "format": "sql|json", "flush": false,
+ *                "encrypt": true, "encryptionPassword": "...", "saltLength": 6 } }
+ *
+ *  { "action": "stop",    "name": "job_name" }
+ *  { "action": "stopAll" }
+ *  { "action": "jobs" }
+ *  { "action": "run",    "type": "full|partial|journal",
+ *    "tables": [...], "options": { "format": "sql", "filename": "..." } }
+ *  { "action": "restore", "filePath": "/abs/path/to/backup.sql",
+ *    "options": { "encryptionPassword": "..." } }
+ *  { "action": "status" }
+ *  { "action": "ping" }
+ *
+ * ─── Server → Client responses ────────────────────────────────────────
+ *  { "ok": true,  "result": <any> }
+ *  { "ok": false, "error":  "message" }
+ *
+ * ─── Server → All clients (push events) ──────────────────────────────
+ *  { "event": "jobStart", "name": "...", "type": "..." }
+ *  { "event": "jobDone",  "name": "...", "type": "...", "filePath": "..." }
+ *  { "event": "jobError", "name": "...", "type": "...", "error": "..." }
+ *
+ * Usage:
+ *   const server = new BackupSocketServer(db, { port: 9119, backupPath: './database/backups' });
+ *   await server.listen();   // starts the daemon
+ *   // ...
+ *   await server.close();    // graceful shutdown
+ */
+
+'use strict';
+
+const net    = require('net');
+const events = require('events');
+const BackupManager   = require('./BackupManager');
+const BackupScheduler = require('./BackupScheduler');
+
+const DEFAULT_PORT = 9119;
+const DEFAULT_HOST = '127.0.0.1';
+
+class BackupSocketServer extends events.EventEmitter {
+  /**
+   * @param {import('../DatabaseConnection')} connection
+   * @param {object}  [options]
+   * @param {number}  [options.port=9119]
+   * @param {string}  [options.host='127.0.0.1']
+   * @param {string}  [options.backupPath]         Forwarded to BackupManager
+   * @param {boolean} [options.encrypt]            Default encryption for all jobs
+   * @param {string}  [options.encryptionPassword] Default encryption password
+   * @param {number}  [options.saltLength]         Default grain de sable length
+   */
+  constructor(connection, options = {}) {
+    super();
+    this.connection = connection;
+    this.port    = options.port || DEFAULT_PORT;
+    this.host    = options.host || DEFAULT_HOST;
+
+    this._managerOptions = {
+      backupPath         : options.backupPath,
+      encrypt            : options.encrypt,
+      encryptionPassword : options.encryptionPassword,
+      saltLength         : options.saltLength,
+    };
+
+    this.manager   = new BackupManager(connection, this._managerOptions);
+    this.scheduler = new BackupScheduler(connection, this._managerOptions);
+
+    /** @type {Set<net.Socket>} */
+    this._clients = new Set();
+    this._server  = null;
+    this._startTime = null;
+  }
+
+  // ─────────────────────────────────────────────────────────────────────────────
+  // Lifecycle
+  // ─────────────────────────────────────────────────────────────────────────────
+
+  /**
+   * Start the TCP server and begin accepting connections.
+   * @returns {Promise<void>}
+   */
+  listen() {
+    return new Promise((resolve, reject) => {
+      this._server = net.createServer((socket) => this._handleClient(socket));
+
+      this._server.on('error', (err) => {
+        this.emit('error', err);
+        reject(err);
+      });
+
+      this._server.listen(this.port, this.host, () => {
+        this._startTime = Date.now();
+        const addr = `${this.host}:${this.port}`;
+        console.log(`✓ BackupSocketServer listening on ${addr}`);
+        this.emit('listening', { host: this.host, port: this.port });
+        resolve();
+      });
+    });
+  }
+
+  /**
+   * Gracefully stop the server and all scheduled jobs.
+   * @returns {Promise<void>}
+   */
+  close() {
+    return new Promise((resolve) => {
+      this.scheduler.stopAll();
+
+      // Close all client connections
+      for (const sock of this._clients) {
+        try { sock.destroy(); } catch (_) { /* ignore */ }
+      }
+      this._clients.clear();
+
+      if (this._server) {
+        this._server.close(() => {
+          console.log('✓ BackupSocketServer closed');
+          this.emit('close');
+          resolve();
+        });
+      } else {
+        resolve();
+      }
+    });
+  }
+
+  /**
+   * Return server address info.
+   * @returns {{ host: string, port: number } | null}
+   */
+  address() {
+    if (!this._server) return null;
+    const addr = this._server.address();
+    return addr ? { host: addr.address, port: addr.port } : null;
+  }
+
+  // ─────────────────────────────────────────────────────────────────────────────
+  // Client handling
+  // ─────────────────────────────────────────────────────────────────────────────
+
+  /** @private */
+  _handleClient(socket) {
+    this._clients.add(socket);
+    let buffer = '';
+
+    socket.setEncoding('utf8');
+
+    socket.on('data', (chunk) => {
+      buffer += chunk;
+      // Messages are newline-delimited
+      const lines = buffer.split('\n');
+      buffer = lines.pop(); // keep incomplete last line
+
+      for (const line of lines) {
+        const trimmed = line.trim();
+        if (!trimmed) continue;
+        this._processMessage(socket, trimmed);
+      }
+    });
+
+    socket.on('close', () => {
+      this._clients.delete(socket);
+    });
+
+    socket.on('error', (err) => {
+      this._clients.delete(socket);
+      this.emit('clientError', err);
+    });
+  }
+
+  /** @private */
+  async _processMessage(socket, raw) {
+    let msg;
+    try {
+      msg = JSON.parse(raw);
+    } catch (_) {
+      this._send(socket, { ok: false, error: 'Invalid JSON' });
+      return;
+    }
+
+    try {
+      const result = await this._dispatch(msg);
+      this._send(socket, { ok: true, result });
+    } catch (err) {
+      this._send(socket, { ok: false, error: err.message || String(err) });
+    }
+  }
+
+  /** @private */
+  async _dispatch(msg) {
+    switch (msg.action) {
+
+    case 'ping':
+      return 'pong';
+
+    case 'status':
+      return {
+        uptime : this._startTime ? Date.now() - this._startTime : 0,
+        jobs   : this.scheduler.activeJobs(),
+        clients: this._clients.size,
+      };
+
+    case 'jobs':
+      return this.scheduler.activeJobs();
+
+    case 'schedule': {
+      const type   = msg.type;
+      const config = Object.assign({}, msg.config || {});
+
+      // Merge per-job encryption options with server defaults
+      const jobManagerOpts = this._buildManagerOptions(config);
+
+      // Use a mutable ref so callbacks always carry the final job name
+      // (which may be auto-generated if config.name was not provided)
+      const nameRef = { value: config.name || type };
+
+      // Wrap success/error to emit events to all connected clients
+      const originalOnSuccess = config.onSuccess;
+      const originalOnError   = config.onError;
+
+      config.onSuccess = (filePath) => {
+        this._broadcast({ event: 'jobDone', name: nameRef.value, type, filePath });
+        if (typeof originalOnSuccess === 'function') originalOnSuccess(filePath);
+      };
+      config.onError = (err) => {
+        this._broadcast({ event: 'jobError', name: nameRef.value, type, error: err.message });
+        if (typeof originalOnError === 'function') originalOnError(err);
+      };
+
+      // Create a dedicated scheduler with the right per-job manager options
+      const jobScheduler = this._buildScheduler(jobManagerOpts);
+      const name = jobScheduler.schedule(type, config);
+
+      // Update ref with actual name (covers auto-generated names)
+      nameRef.value = name;
+
+      // Persist the interval handle in the main scheduler so status/stop work
+      this.scheduler._jobs.set(name, jobScheduler._jobs.get(name));
+
+      this._broadcast({ event: 'jobStart', name, type });
+      return name;
+    }
+
+    case 'stop':
+      this.scheduler.stop(msg.name);
+      return true;
+
+    case 'stopAll':
+      this.scheduler.stopAll();
+      return true;
+
+    case 'run': {
+      const type    = msg.type;
+      const options = msg.options || {};
+      const tables  = msg.tables;
+      const runManagerOpts = this._buildManagerOptions(options);
+      const runManager = new BackupManager(this.connection, runManagerOpts);
+
+      let filePath;
+      if (type === 'full') {
+        filePath = await runManager.full(options);
+      } else if (type === 'partial') {
+        if (!Array.isArray(tables) || tables.length === 0) {
+          throw new Error("'tables' array is required for partial backup");
+        }
+        filePath = await runManager.partial(tables, options);
+      } else if (type === 'journal') {
+        filePath = await runManager.journal(options);
+      } else {
+        throw new Error(`Unknown backup type "${type}"`);
+      }
+      return filePath;
+    }
+
+    case 'restore': {
+      if (!msg.filePath) {
+        throw new Error("'filePath' is required for restore");
+      }
+      // Build a restore-capable manager (needs encryptionPassword if file is encrypted)
+      const restoreOpts = Object.assign({}, this._managerOptions, {
+        encrypt           : false,   // manager doesn't need to encrypt on restore
+        encryptionPassword: (msg.options && msg.options.encryptionPassword)
+          || this._managerOptions.encryptionPassword,
+      });
+      const restoreManager = new BackupManager(this.connection, restoreOpts);
+      return restoreManager.restore(msg.filePath, msg.options || {});
+    }
+
+    default:
+      throw new Error(`Unknown action "${msg.action}"`);
+    }
+  }
+
+  // ─────────────────────────────────────────────────────────────────────────────
+  // Helpers
+  // ─────────────────────────────────────────────────────────────────────────────
+
+  /** @private */
+  _send(socket, payload) {
+    if (socket.writable) {
+      socket.write(JSON.stringify(payload) + '\n');
+    }
+  }
+
+  /** @private */
+  _broadcast(payload) {
+    const line = JSON.stringify(payload) + '\n';
+    for (const sock of this._clients) {
+      if (sock.writable) sock.write(line);
+    }
+    this.emit('event', payload);
+  }
+
+  /**
+   * Build BackupManager options, merging server defaults with per-call overrides.
+   * @private
+   */
+  _buildManagerOptions(overrides = {}) {
+    return {
+      backupPath        : overrides.backupPath         || this._managerOptions.backupPath,
+      encrypt           : overrides.encrypt            != null ? overrides.encrypt            : this._managerOptions.encrypt,
+      encryptionPassword: overrides.encryptionPassword || this._managerOptions.encryptionPassword,
+      saltLength        : overrides.saltLength         != null ? overrides.saltLength         : this._managerOptions.saltLength,
+    };
+  }
+
+  /**
+   * Build a throw-away BackupScheduler with a given manager.
+   * @private
+   */
+  _buildScheduler(managerOptions) {
+    const s = new BackupScheduler(this.connection, managerOptions);
+    return s;
+  }
+}
+
+module.exports = BackupSocketServer;

package/src/index.js

@@ -21,6 +21,13 @@ const MigrationManager = require('./Migrations/MigrationManager');
 const Seeder = require('./Seeders/Seeder');
 const SeederManager = require('./Seeders/SeederManager');
 
+// Backup
+const BackupManager      = require('./Backup/BackupManager');
+const BackupScheduler    = require('./Backup/BackupScheduler');
+const BackupEncryption   = require('./Backup/BackupEncryption');
+const BackupSocketServer = require('./Backup/BackupSocketServer');
+const BackupSocketClient = require('./Backup/BackupSocketClient');
+
 module.exports = {
   // Core
   Model,
@@ -51,5 +58,12 @@ module.exports = {
 
   // Seeders
   Seeder,
-  SeederManager
+  SeederManager,
+
+  // Backup
+  BackupManager,
+  BackupScheduler,
+  BackupEncryption,
+  BackupSocketServer,
+  BackupSocketClient
 };

package/types/index.d.ts

@@ -671,4 +671,229 @@ declare module 'outlet-orm' {
     run(target?: string | null): Promise<void>;
     runSeeder(seederRef: string): Promise<void>;
   }
+
+  // ==================== Backup ====================
+
+  export type BackupFormat = 'sql' | 'json';
+  export type BackupType   = 'full' | 'partial' | 'journal';
+  export type SaltLength   = 4 | 5 | 6;
+
+  /** Encryption options for backup files */
+  export interface EncryptionOptions {
+    /** Enable AES-256-GCM encryption (default: false) */
+    encrypt?: boolean;
+    /** Password used for key derivation (required when encrypt=true) */
+    encryptionPassword?: string;
+    /**
+     * Grain de sable (salt) length in characters.
+     * Must be 4, 5, or 6.  Default: 6.
+     */
+    saltLength?: SaltLength;
+  }
+
+  export interface BackupOptions extends EncryptionOptions {
+    /** Override the auto-generated filename */
+    filename?: string;
+    /** Output format – 'sql' (default) or 'json' */
+    format?: BackupFormat;
+  }
+
+  export interface JournalOptions extends EncryptionOptions {
+    /** Override the auto-generated filename */
+    filename?: string;
+    /** Clear the query log after writing the journal (default: false) */
+    flush?: boolean;
+  }
+
+  export interface RestoreOptions {
+    /**
+     * Password to decrypt an encrypted backup.
+     * Falls back to the BackupManager constructor password.
+     */
+    encryptionPassword?: string;
+  }
+
+  export interface RestoreResult {
+    /** Number of SQL statements executed */
+    statements: number;
+  }
+
+  export interface BackupManagerOptions extends EncryptionOptions {
+    /** Directory where backup files are written (default: './database/backups') */
+    backupPath?: string;
+  }
+
+  export interface ScheduleConfig extends EncryptionOptions {
+    /** Interval between backups in milliseconds (minimum: 1000) */
+    intervalMs: number;
+    /** Run once immediately when scheduled (default: false) */
+    runNow?: boolean;
+    /** Table names – required for 'partial' type */
+    tables?: string[];
+    /** Output format for full/partial backups */
+    format?: BackupFormat;
+    /** Auto-flush query log after each journal backup */
+    flush?: boolean;
+    /** Called with the file path after a successful backup */
+    onSuccess?: (filePath: string) => void;
+    /** Called with the error when a backup fails */
+    onError?: (error: Error) => void;
+    /** Optional unique job identifier (defaults to "<type>_<timestamp>") */
+    name?: string;
+  }
+
+  export class BackupManager {
+    constructor(connection: DatabaseConnection, options?: BackupManagerOptions);
+
+    /** Full backup – schema + data for every table. */
+    full(options?: BackupOptions): Promise<string>;
+    /** Partial backup – schema + data for the specified tables only. */
+    partial(tables: string[], options?: BackupOptions): Promise<string>;
+    /**
+     * Transaction-log backup – replayable DML statements from the query log.
+     * Requires DatabaseConnection.enableQueryLog() to be called beforehand.
+     */
+    journal(options?: JournalOptions): Promise<string>;
+    /** Restore a previously created SQL backup file (supports encrypted files). */
+    restore(filePath: string, options?: RestoreOptions): Promise<RestoreResult>;
+  }
+
+  export class BackupScheduler {
+    constructor(connection: DatabaseConnection, options?: BackupManagerOptions);
+
+    schedule(type: BackupType, config: ScheduleConfig): string;
+    stop(name: string): void;
+    stopAll(): void;
+    activeJobs(): string[];
+  }
+
+  // ==================== Backup Encryption ====================
+
+  export interface EncryptResult {
+    /** Full file content to write to disk */
+    encryptedContent: string;
+    /** The grain de sable (salt) that was generated */
+    salt: string;
+  }
+
+  export namespace BackupEncryption {
+    /**
+     * Encrypt a string payload with AES-256-GCM.
+     * @param plaintext    Content to encrypt
+     * @param password     Encryption password
+     * @param saltLength   Grain de sable length (4–6, default 6)
+     */
+    function encrypt(plaintext: string, password: string, saltLength?: SaltLength): EncryptResult;
+
+    /**
+     * Decrypt a previously encrypted backup payload.
+     * @param encryptedContent  Raw file content produced by encrypt()
+     * @param password          The same password used during encryption
+     */
+    function decrypt(encryptedContent: string, password: string): string;
+
+    /** Return true if the content looks like an outlet-orm encrypted backup. */
+    function isEncrypted(content: string): boolean;
+
+    /**
+     * Generate a random alphanumeric salt (grain de sable).
+     * @param length  4, 5, or 6 characters
+     */
+    function generateSalt(length?: SaltLength): string;
+  }
+
+  // ==================== Backup Socket Server ====================
+
+  export interface ServerOptions extends BackupManagerOptions {
+    /** TCP port to listen on (default: 9119) */
+    port?: number;
+    /** Host / IP to bind (default: '127.0.0.1') */
+    host?: string;
+  }
+
+  export interface ServerStatus {
+    uptime:  number;
+    jobs:    string[];
+    clients: number;
+  }
+
+  export interface ServerAddress {
+    host: string;
+    port: number;
+  }
+
+  export class BackupSocketServer {
+    constructor(connection: DatabaseConnection, options?: ServerOptions);
+
+    /** Start the TCP daemon. */
+    listen(): Promise<void>;
+    /** Gracefully stop the daemon and all scheduled jobs. */
+    close(): Promise<void>;
+    /** Return the bound address (null before listen). */
+    address(): ServerAddress | null;
+
+    on(event: 'listening', listener: (addr: ServerAddress) => void): this;
+    on(event: 'close',     listener: () => void): this;
+    on(event: 'error',     listener: (err: Error) => void): this;
+    on(event: 'event',     listener: (payload: Record<string, any>) => void): this;
+    on(event: string,      listener: (...args: any[]) => void): this;
+  }
+
+  // ==================== Backup Socket Client ====================
+
+  export interface ClientOptions {
+    /** TCP port of the server (default: 9119) */
+    port?: number;
+    /** Host of the server (default: '127.0.0.1') */
+    host?: string;
+    /** Timeout in ms waiting for a server reply (default: 30000) */
+    timeout?: number;
+  }
+
+  export interface RunOptions extends EncryptionOptions {
+    format?  : BackupFormat;
+    filename?: string;
+    flush?   : boolean;
+  }
+
+  export class BackupSocketClient {
+    constructor(options?: ClientOptions);
+
+    readonly connected: boolean;
+
+    connect():    Promise<void>;
+    disconnect(): Promise<void>;
+
+    ping():    Promise<'pong'>;
+    status():  Promise<ServerStatus>;
+    jobs():    Promise<string[]>;
+
+    schedule(type: BackupType, config: ScheduleConfig): Promise<string>;
+    stop(name: string):    Promise<boolean>;
+    stopAll():             Promise<boolean>;
+
+    /**
+     * Trigger a one-shot backup immediately.
+     * @param tables  Required for 'partial' type
+     */
+    run(type: BackupType, options?: RunOptions): Promise<string>;
+    run(type: 'partial', tables: string[], options?: RunOptions): Promise<string>;
+
+    /**
+     * Restore a previously created backup file on the server.
+     * Supports plain SQL and encrypted .enc files.
+     * @param filePath  Absolute path to the backup file (server-side)
+     * @param options   Supply encryptionPassword when the file is encrypted
+     */
+    restore(filePath: string, options?: RestoreOptions): Promise<RestoreResult>;
+
+    on(event: 'connect',     listener: () => void): this;
+    on(event: 'disconnect',  listener: () => void): this;
+    on(event: 'error',       listener: (err: Error) => void): this;
+    on(event: 'jobStart',    listener: (payload: { name: string; type: string }) => void): this;
+    on(event: 'jobDone',     listener: (payload: { name: string; type: string; filePath: string }) => void): this;
+    on(event: 'jobError',    listener: (payload: { name: string; type: string; error: string }) => void): this;
+    on(event: 'serverEvent', listener: (payload: Record<string, any>) => void): this;
+    on(event: string,        listener: (...args: any[]) => void): this;
+  }
 }