@breeztech/breez-sdk-spark 0.13.10-dev → 0.13.12-dev1

package/nodejs/mysql-tree-store/migrations.cjs

@@ -0,0 +1,221 @@
+/**
+ * Tree store migrations for MySQL 8.0+. Mirrors `postgres-tree-store/migrations.cjs`.
+ */
+
+const { TreeStoreError } = require("./errors.cjs");
+
+const TREE_MIGRATIONS_TABLE = "tree_schema_migrations";
+const MIGRATION_LOCK_NAME = "breez_mysql_tree_store_migration_lock";
+const MIGRATION_LOCK_TIMEOUT = 60;
+
+/**
+ * Runs a single migration step. Plain strings are run as-is; tagged objects
+ * (`{ op: 'dropPrimaryKey', table }`) are guarded against partial-apply replay
+ * by checking `information_schema` first. MySQL DDL implicitly commits, so
+ * if the migration crashes between two DDL statements the version row never
+ * gets recorded — and on retry, an unguarded DROP PRIMARY KEY would fail
+ * (`ER_CANT_DROP_FIELD_OR_KEY`) because the PK is already gone.
+ */
+async function runMigrationStep(conn, step) {
+  if (typeof step === "string") {
+    await conn.query(step);
+    return;
+  }
+  if (step.op === "dropPrimaryKey") {
+    const [rows] = await conn.query(
+      `SELECT COUNT(*) AS c FROM information_schema.table_constraints
+       WHERE table_schema = DATABASE()
+         AND table_name = ?
+         AND constraint_type = 'PRIMARY KEY'`,
+      [step.table]
+    );
+    if (rows[0].c > 0) {
+      await conn.query(`ALTER TABLE \`${step.table}\` DROP PRIMARY KEY`);
+    }
+    return;
+  }
+  throw new Error(`Unknown migration step op: ${JSON.stringify(step)}`);
+}
+
+class MysqlTreeStoreMigrationManager {
+  constructor(logger = null) {
+    this.logger = logger;
+  }
+
+  async migrate(pool, identity) {
+    const conn = await pool.getConnection();
+    try {
+      const [lockRows] = await conn.query(
+        "SELECT GET_LOCK(?, ?) AS acquired",
+        [MIGRATION_LOCK_NAME, MIGRATION_LOCK_TIMEOUT]
+      );
+      if (!lockRows || lockRows[0].acquired !== 1) {
+        throw new TreeStoreError(
+          `Failed to acquire tree store migration lock within ${MIGRATION_LOCK_TIMEOUT}s`
+        );
+      }
+
+      try {
+        await conn.query("START TRANSACTION");
+
+        await conn.query(`
+          CREATE TABLE IF NOT EXISTS \`${TREE_MIGRATIONS_TABLE}\` (
+            version INT PRIMARY KEY,
+            applied_at DATETIME(6) NOT NULL DEFAULT CURRENT_TIMESTAMP(6)
+          )
+        `);
+
+        const [versionRows] = await conn.query(
+          `SELECT COALESCE(MAX(version), 0) AS version FROM \`${TREE_MIGRATIONS_TABLE}\``
+        );
+        const currentVersion = versionRows[0].version;
+
+        const migrations = this._getMigrations(identity);
+
+        if (currentVersion >= migrations.length) {
+          await conn.query("COMMIT");
+          return;
+        }
+
+        for (let i = currentVersion; i < migrations.length; i++) {
+          const migration = migrations[i];
+          const version = i + 1;
+          for (const step of migration.sql) {
+            await runMigrationStep(conn, step);
+          }
+          await conn.query(
+            `INSERT INTO \`${TREE_MIGRATIONS_TABLE}\` (version) VALUES (?)`,
+            [version]
+          );
+        }
+
+        await conn.query("COMMIT");
+      } catch (error) {
+        await conn.query("ROLLBACK").catch(() => {});
+        throw new TreeStoreError(
+          `Tree store migration failed: ${error.message}`,
+          error
+        );
+      } finally {
+        await conn
+          .query("SELECT RELEASE_LOCK(?)", [MIGRATION_LOCK_NAME])
+          .catch(() => {});
+      }
+    } finally {
+      conn.release();
+    }
+  }
+
+  _getMigrations(identity) {
+    const idHex = Buffer.from(identity).toString("hex");
+    const idLit = `UNHEX('${idHex}')`;
+
+    return [
+      {
+        name: "Create tree store tables",
+        sql: [
+          `CREATE TABLE IF NOT EXISTS tree_reservations (
+            id VARCHAR(255) NOT NULL PRIMARY KEY,
+            purpose VARCHAR(64) NOT NULL,
+            pending_change_amount BIGINT NOT NULL DEFAULT 0,
+            created_at DATETIME(6) NOT NULL DEFAULT CURRENT_TIMESTAMP(6)
+          )`,
+          `CREATE TABLE IF NOT EXISTS tree_leaves (
+            id VARCHAR(255) NOT NULL PRIMARY KEY,
+            status VARCHAR(64) NOT NULL,
+            is_missing_from_operators TINYINT(1) NOT NULL DEFAULT 0,
+            reservation_id VARCHAR(255) NULL,
+            data JSON NOT NULL,
+            created_at DATETIME(6) NOT NULL DEFAULT CURRENT_TIMESTAMP(6),
+            added_at DATETIME(6) NOT NULL DEFAULT CURRENT_TIMESTAMP(6),
+            CONSTRAINT fk_tree_leaves_reservation FOREIGN KEY (reservation_id)
+                REFERENCES tree_reservations(id) ON DELETE SET NULL
+          )`,
+          `CREATE TABLE IF NOT EXISTS tree_spent_leaves (
+            leaf_id VARCHAR(255) NOT NULL PRIMARY KEY,
+            spent_at DATETIME(6) NOT NULL DEFAULT CURRENT_TIMESTAMP(6)
+          )`,
+          `CREATE INDEX idx_tree_leaves_available
+            ON tree_leaves(status, is_missing_from_operators)`,
+          `CREATE INDEX idx_tree_leaves_reservation ON tree_leaves(reservation_id)`,
+          `CREATE INDEX idx_tree_leaves_added_at ON tree_leaves(added_at)`,
+        ],
+      },
+      {
+        name: "Add swap status tracking",
+        sql: [
+          `CREATE TABLE IF NOT EXISTS tree_swap_status (
+            id INT NOT NULL PRIMARY KEY DEFAULT 1,
+            last_completed_at DATETIME(6) NULL,
+            CHECK (id = 1)
+          )`,
+          `INSERT INTO tree_swap_status (id) VALUES (1)
+            ON DUPLICATE KEY UPDATE id = id`,
+        ],
+      },
+      {
+        name: "Promote leaf value to BIGINT column with covering index",
+        sql: [
+          `ALTER TABLE tree_leaves
+            ADD COLUMN value BIGINT NOT NULL DEFAULT 0`,
+          `UPDATE tree_leaves
+            SET value = CAST(JSON_UNQUOTE(JSON_EXTRACT(data, '$.value')) AS UNSIGNED)
+            WHERE value = 0`,
+          `CREATE INDEX idx_tree_leaves_slim
+            ON tree_leaves(status, is_missing_from_operators, reservation_id, value)`,
+        ],
+      },
+      {
+        name: "Multi-tenant scoping: add user_id and rewrite primary keys / FKs",
+        sql: [
+          // Drop the existing FK so we can rewrite the parent PK.
+          `ALTER TABLE tree_leaves DROP FOREIGN KEY fk_tree_leaves_reservation`,
+
+          // tree_reservations: scope by user_id.
+          `ALTER TABLE tree_reservations ADD COLUMN user_id VARBINARY(33) NULL`,
+          `UPDATE tree_reservations SET user_id = ${idLit} WHERE user_id IS NULL`,
+          `ALTER TABLE tree_reservations MODIFY COLUMN user_id VARBINARY(33) NOT NULL`,
+          `ALTER TABLE tree_reservations DROP PRIMARY KEY, ADD PRIMARY KEY (user_id, id)`,
+
+          // tree_leaves: scope by user_id, rekey, re-add composite FK.
+          `ALTER TABLE tree_leaves ADD COLUMN user_id VARBINARY(33) NULL`,
+          `UPDATE tree_leaves SET user_id = ${idLit} WHERE user_id IS NULL`,
+          `ALTER TABLE tree_leaves MODIFY COLUMN user_id VARBINARY(33) NOT NULL`,
+          `ALTER TABLE tree_leaves DROP PRIMARY KEY, ADD PRIMARY KEY (user_id, id)`,
+          `ALTER TABLE tree_leaves
+             ADD CONSTRAINT fk_tree_leaves_reservation_user
+             FOREIGN KEY (user_id, reservation_id)
+             REFERENCES tree_reservations(user_id, id)`,
+          `DROP INDEX idx_tree_leaves_available ON tree_leaves`,
+          `DROP INDEX idx_tree_leaves_reservation ON tree_leaves`,
+          `DROP INDEX idx_tree_leaves_added_at ON tree_leaves`,
+          `DROP INDEX idx_tree_leaves_slim ON tree_leaves`,
+          `CREATE INDEX idx_tree_leaves_user_available
+             ON tree_leaves(user_id, status, is_missing_from_operators)`,
+          `CREATE INDEX idx_tree_leaves_user_reservation
+             ON tree_leaves(user_id, reservation_id)`,
+          `CREATE INDEX idx_tree_leaves_user_added_at ON tree_leaves(user_id, added_at)`,
+          `CREATE INDEX idx_tree_leaves_user_slim
+             ON tree_leaves(user_id, status, is_missing_from_operators, reservation_id, value)`,
+
+          // tree_spent_leaves: scope by user_id.
+          `ALTER TABLE tree_spent_leaves ADD COLUMN user_id VARBINARY(33) NULL`,
+          `UPDATE tree_spent_leaves SET user_id = ${idLit} WHERE user_id IS NULL`,
+          `ALTER TABLE tree_spent_leaves MODIFY COLUMN user_id VARBINARY(33) NOT NULL`,
+          `ALTER TABLE tree_spent_leaves DROP PRIMARY KEY, ADD PRIMARY KEY (user_id, leaf_id)`,
+
+          // tree_swap_status was a singleton (PK id=1, CHECK id=1). Drop the PK
+          // and the id column, then re-key by user_id.
+          { op: "dropPrimaryKey", table: "tree_swap_status" },
+          `ALTER TABLE tree_swap_status DROP COLUMN id`,
+          `ALTER TABLE tree_swap_status ADD COLUMN user_id VARBINARY(33) NULL`,
+          `UPDATE tree_swap_status SET user_id = ${idLit} WHERE user_id IS NULL`,
+          `ALTER TABLE tree_swap_status MODIFY COLUMN user_id VARBINARY(33) NOT NULL`,
+          `ALTER TABLE tree_swap_status ADD PRIMARY KEY (user_id)`,
+        ],
+      },
+    ];
+  }
+}
+
+module.exports = { MysqlTreeStoreMigrationManager };

package/nodejs/mysql-tree-store/package.json

@@ -0,0 +1,9 @@
+{
+  "dependencies": {
+    "mysql2": "^3.11.0"
+  },
+  "description": "Node.js MySQL tree store implementation for Breez SDK WASM (CommonJS)",
+  "main": "index.cjs",
+  "name": "@breez-sdk/mysql-tree-store",
+  "version": "1.0.0"
+}

package/nodejs/package.json

@@ -7,6 +7,11 @@
     "postgres-storage/",
     "postgres-tree-store/",
     "postgres-token-store/",
+    "postgres-session-manager/",
+    "mysql-storage/",
+    "mysql-tree-store/",
+    "mysql-token-store/",
+    "mysql-session-manager/",
     "index.js",
     "index.mjs"
   ],

package/nodejs/postgres-session-manager/errors.cjs

@@ -0,0 +1,13 @@
+// errors.cjs - Session manager error wrapper with cause chain support
+class SessionManagerError extends Error {
+    constructor(message, cause = null) {
+        super(message);
+        this.name = 'SessionManagerError';
+        this.cause = cause;
+        if (Error.captureStackTrace) {
+            Error.captureStackTrace(this, SessionManagerError);
+        }
+    }
+}
+
+module.exports = { SessionManagerError };

package/nodejs/postgres-session-manager/index.cjs

@@ -0,0 +1,165 @@
+/**
+ * CommonJS implementation for Node.js PostgreSQL Session Manager.
+ *
+ * Implements the JS-side `SessionManager` interface consumed by the Breez
+ * SDK WASM bindings: `getSession(serviceIdentityKey)` returns the cached
+ * session for the (tenant, service) pair or `null` when not found, and
+ * `setSession(serviceIdentityKey, session)` upserts a session.
+ *
+ * Tenant identity is bound at construction so multiple tenants can share
+ * a single Postgres database without leaking sessions across tenants.
+ */
+
+let pg;
+try {
+  const mainModule = require.main;
+  if (mainModule) {
+    pg = mainModule.require("pg");
+  } else {
+    pg = require("pg");
+  }
+} catch (error) {
+  try {
+    pg = require("pg");
+  } catch (fallbackError) {
+    throw new Error(
+      `pg not found. Please install it in your project: npm install pg@^8.18.0\n` +
+        `Original error: ${error.message}\nFallback error: ${fallbackError.message}`
+    );
+  }
+}
+
+const { SessionManagerError } = require("./errors.cjs");
+const { SessionManagerMigrationManager } = require("./migrations.cjs");
+
+class PostgresSessionManager {
+  /**
+   * @param {import('pg').Pool} pool
+   * @param {Buffer|Uint8Array} identity - 33-byte secp256k1 compressed pubkey
+   *   identifying the tenant. All reads and writes are scoped by this.
+   * @param {object} [logger]
+   */
+  constructor(pool, identity, logger = null) {
+    if (!identity || identity.length !== 33) {
+      throw new SessionManagerError(
+        "tenant identity (33-byte secp256k1 pubkey) is required"
+      );
+    }
+    this.pool = pool;
+    this.identity = Buffer.from(identity);
+    this.logger = logger;
+  }
+
+  async initialize() {
+    try {
+      const migrationManager = new SessionManagerMigrationManager(this.logger);
+      await migrationManager.migrate(this.pool);
+      return this;
+    } catch (error) {
+      throw new SessionManagerError(
+        `Failed to initialize PostgreSQL session manager: ${error.message}`,
+        error
+      );
+    }
+  }
+
+  async close() {
+    if (this.pool) {
+      await this.pool.end();
+      this.pool = null;
+    }
+  }
+
+  /**
+   * Returns the cached session for the given service identity key, or `null`
+   * if no session is cached. The Rust adapter maps `null` to
+   * `SessionManagerError::NotFound`.
+   * @param {string} serviceIdentityKey - hex-encoded 33-byte secp256k1 pubkey
+   * @returns {Promise<{token: string, expiration: number} | null>}
+   */
+  async getSession(serviceIdentityKey) {
+    const serviceKey = _decodePubkey(serviceIdentityKey);
+    try {
+      const { rows } = await this.pool.query(
+        `SELECT token, expiration FROM sessions
+         WHERE user_id = $1 AND service_identity_key = $2`,
+        [this.identity, serviceKey]
+      );
+      if (rows.length === 0) {
+        return null;
+      }
+      const row = rows[0];
+      return {
+        token: row.token,
+        expiration: Number(row.expiration),
+      };
+    } catch (error) {
+      throw new SessionManagerError(
+        `Failed to read session: ${error.message}`,
+        error
+      );
+    }
+  }
+
+  /**
+   * Upserts a session for the given service identity key.
+   * @param {string} serviceIdentityKey - hex-encoded 33-byte secp256k1 pubkey
+   * @param {{token: string, expiration: number}} session
+   */
+  async setSession(serviceIdentityKey, session) {
+    const serviceKey = _decodePubkey(serviceIdentityKey);
+    try {
+      await this.pool.query(
+        `INSERT INTO sessions (user_id, service_identity_key, token, expiration)
+         VALUES ($1, $2, $3, $4)
+         ON CONFLICT (user_id, service_identity_key)
+         DO UPDATE SET token = EXCLUDED.token, expiration = EXCLUDED.expiration`,
+        [this.identity, serviceKey, session.token, session.expiration]
+      );
+    } catch (error) {
+      throw new SessionManagerError(
+        `Failed to write session: ${error.message}`,
+        error
+      );
+    }
+  }
+}
+
+function _decodePubkey(hex) {
+  if (typeof hex !== "string" || hex.length !== 66) {
+    throw new SessionManagerError(
+      "service_identity_key must be a 66-character hex-encoded 33-byte pubkey"
+    );
+  }
+  return Buffer.from(hex, "hex");
+}
+
+/**
+ * Convenience factory: creates a pool from a Pool config and returns an
+ * initialized `PostgresSessionManager`. Most callers should use
+ * `createPostgresSessionManagerWithPool` instead so the pool can be shared
+ * across stores.
+ */
+async function createPostgresSessionManager(poolConfig, identity, logger = null) {
+  const pool = new pg.Pool(poolConfig);
+  const manager = new PostgresSessionManager(pool, identity, logger);
+  await manager.initialize();
+  return manager;
+}
+
+/**
+ * Wraps an existing pool — useful when sharing the pool with the storage,
+ * tree store, and token store implementations.
+ */
+async function createPostgresSessionManagerWithPool(pool, identity, logger = null) {
+  const manager = new PostgresSessionManager(pool, identity, logger);
+  await manager.initialize();
+  return manager;
+}
+
+module.exports = {
+  PostgresSessionManager,
+  createPostgresSessionManager,
+  createPostgresSessionManagerWithPool,
+  SessionManagerError,
+};

package/nodejs/postgres-session-manager/migrations.cjs

@@ -0,0 +1,126 @@
+/**
+ * Database Migration Manager for Breez SDK PostgreSQL Session Manager.
+ *
+ * Uses a session_schema_migrations table + pg_advisory_xact_lock to safely
+ * run migrations from concurrent processes. Mirrors the schema produced by
+ * the Rust `PostgresSessionManager`.
+ */
+
+const { SessionManagerError } = require("./errors.cjs");
+
+/**
+ * Advisory lock ID for session-manager migrations.
+ * Uses a different lock ID from the storage / tree store / token store
+ * migrations to avoid contention. Derived from ASCII bytes of "SESN"
+ * (0x5345534E).
+ */
+const MIGRATION_LOCK_ID = "1397245774"; // 0x5345534E as decimal string
+
+class SessionManagerMigrationManager {
+  constructor(logger = null) {
+    this.logger = logger;
+  }
+
+  /**
+   * Run all pending migrations inside a single transaction with an advisory
+   * lock.
+   * @param {import('pg').Pool} pool
+   */
+  async migrate(pool) {
+    const client = await pool.connect();
+    try {
+      await client.query("BEGIN");
+      await client.query(`SELECT pg_advisory_xact_lock(${MIGRATION_LOCK_ID})`);
+
+      await client.query(`
+        CREATE TABLE IF NOT EXISTS session_schema_migrations (
+          version INTEGER PRIMARY KEY,
+          applied_at TIMESTAMPTZ DEFAULT NOW()
+        )
+      `);
+
+      const versionResult = await client.query(
+        "SELECT COALESCE(MAX(version), 0) AS version FROM session_schema_migrations"
+      );
+      const currentVersion = versionResult.rows[0].version;
+
+      const migrations = this._getMigrations();
+
+      if (currentVersion >= migrations.length) {
+        this._log(
+          "info",
+          `Session manager database is up to date (version ${currentVersion})`
+        );
+        await client.query("COMMIT");
+        return;
+      }
+
+      this._log(
+        "info",
+        `Migrating session manager database from version ${currentVersion} to ${migrations.length}`
+      );
+
+      for (let i = currentVersion; i < migrations.length; i++) {
+        const migration = migrations[i];
+        const version = i + 1;
+        this._log(
+          "debug",
+          `Running session manager migration ${version}: ${migration.name}`
+        );
+
+        for (const sql of migration.sql) {
+          await client.query(sql);
+        }
+
+        await client.query(
+          "INSERT INTO session_schema_migrations (version) VALUES ($1)",
+          [version]
+        );
+      }
+
+      await client.query("COMMIT");
+      this._log(
+        "info",
+        "Session manager database migration completed successfully"
+      );
+    } catch (error) {
+      await client.query("ROLLBACK").catch(() => {});
+      throw new SessionManagerError(
+        `Session manager migration failed: ${error.message}`,
+        error
+      );
+    } finally {
+      client.release();
+    }
+  }
+
+  _log(level, message) {
+    if (this.logger && typeof this.logger.log === "function") {
+      this.logger.log({ line: message, level });
+    } else if (level === "error") {
+      console.error(`[SessionManagerMigrationManager] ${message}`);
+    }
+  }
+
+  /**
+   * Migrations matching the Rust PostgresSessionManager schema exactly.
+   */
+  _getMigrations() {
+    return [
+      {
+        name: "Create sessions table",
+        sql: [
+          `CREATE TABLE IF NOT EXISTS sessions (
+            user_id BYTEA NOT NULL,
+            service_identity_key BYTEA NOT NULL,
+            token TEXT NOT NULL,
+            expiration BIGINT NOT NULL,
+            PRIMARY KEY (user_id, service_identity_key)
+          )`,
+        ],
+      },
+    ];
+  }
+}
+
+module.exports = { SessionManagerMigrationManager };

package/nodejs/postgres-session-manager/package.json

@@ -0,0 +1,9 @@
+{
+  "dependencies": {
+    "pg": "^8.18.0"
+  },
+  "description": "Node.js PostgreSQL session manager implementation for Breez SDK WASM (CommonJS)",
+  "main": "index.cjs",
+  "name": "@breez-sdk/postgres-session-manager",
+  "version": "1.0.0"
+}