@breeztech/breez-sdk-spark 0.19.0 → 0.20.0-dev1

package/itest/helpers/lnurl-fixture.js

@@ -0,0 +1,229 @@
+'use strict'
+
+// LNURL server fixture driven through the docker CLI, mirroring the Rust
+// harness (crates/breez-sdk/cli/tests/harness/lnurl.rs). Shares the
+// breez-lnurl-built image tag: whichever runner builds it first wins. To
+// force a rebuild: `docker image rm breez-lnurl-built:latest`.
+
+const net = require('net')
+const path = require('path')
+const { execFile, execFileSync } = require('child_process')
+const { promisify } = require('util')
+
+const execFileAsync = promisify(execFile)
+
+const IMAGE = 'breez-lnurl-built:latest'
+const POSTGRES_IMAGE = 'postgres:16-alpine'
+const HTTP_PORT = 8080
+const POSTGRES_PORT = 5432
+const START_TIMEOUT_MS = 120_000
+const WORKSPACE_ROOT = path.join(__dirname, '../../../..')
+
+/** @returns {boolean} whether the docker daemon is reachable */
+function dockerAvailable() {
+  try {
+    execFileSync('docker', ['version'], { stdio: 'ignore' })
+    return true
+  } catch {
+    return false
+  }
+}
+
+async function docker(args, opts = {}) {
+  const { stdout } = await execFileAsync('docker', args, { maxBuffer: 64 * 1024 * 1024, ...opts })
+  return stdout
+}
+
+async function buildImageIfMissing() {
+  try {
+    await docker(['image', 'inspect', IMAGE])
+    return
+  } catch {
+    // Image missing: build it.
+  }
+  console.error(`building ${IMAGE} (first run only, this can take several minutes)`)
+  await docker([
+    'build',
+    '-f',
+    path.join(WORKSPACE_ROOT, 'crates/breez-sdk/lnurl/Dockerfile'),
+    '-t',
+    IMAGE,
+    '--build-arg',
+    'CARGO_FEATURES=dev',
+    WORKSPACE_ROOT
+  ])
+}
+
+/** @returns {Promise<number>} host port the container port was published to */
+async function publishedPort(containerId, containerPort) {
+  const portOutput = await docker(['port', containerId, `${containerPort}/tcp`])
+  return Number(portOutput.split('\n')[0].trim().split(':').pop())
+}
+
+/**
+ * Resolves once something answers HTTP on `port`. Any status answers the
+ * question, so this only checks that a response came back. HTTP/1.0 so the
+ * server closes the connection when it is done.
+ */
+function httpResponds(port) {
+  return new Promise((resolve, reject) => {
+    const socket = net.connect(port, '127.0.0.1')
+    let response = ''
+    socket.setTimeout(5000)
+    socket.on('connect', () => socket.write('GET /health HTTP/1.0\r\nHost: localhost\r\n\r\n'))
+    socket.on('data', (chunk) => {
+      response += chunk
+    })
+    socket.on('end', () =>
+      response.startsWith('HTTP/') ? resolve() : reject(new Error('no HTTP response'))
+    )
+    socket.on('timeout', () => socket.destroy(new Error('timed out')))
+    socket.on('error', reject)
+  })
+}
+
+class LnurlFixture {
+  /** @param {string} containerId @param {string} httpUrl @param {string} postgresContainerId */
+  constructor(containerId, httpUrl, postgresContainerId) {
+    this.containerId = containerId
+    this.httpUrl = httpUrl
+    // Backing database. Postgres is the server's only supported backend.
+    this.postgresContainerId = postgresContainerId
+  }
+
+  static async start() {
+    await buildImageIfMissing()
+    const fixture = new LnurlFixture('', '', '')
+    try {
+      const postgresOutput = await docker([
+        'run',
+        '-d',
+        // All interfaces rather than 127.0.0.1: the lnurl server reaches this
+        // from inside its own container through the host gateway, which on
+        // Linux is the bridge address and not loopback.
+        '-p',
+        '0.0.0.0:0:5432',
+        '-e', 'POSTGRES_PASSWORD=postgres',
+        POSTGRES_IMAGE
+      ])
+      fixture.postgresContainerId = postgresOutput.trim()
+      await fixture.waitForPostgres()
+      const dbPort = await publishedPort(fixture.postgresContainerId, POSTGRES_PORT)
+
+      const runOutput = await docker([
+        'run',
+        '-d',
+        '-p',
+        '127.0.0.1:0:8080',
+        '--add-host',
+        'host.docker.internal:host-gateway',
+        '-e', 'BREEZ_LNURL_NETWORK=regtest',
+        '-e', 'BREEZ_LNURL_AUTO_MIGRATE=true',
+        '-e', `BREEZ_LNURL_DB_URL=postgres://postgres:postgres@host.docker.internal:${dbPort}/postgres`,
+        '-e', 'BREEZ_LNURL_LOG_LEVEL=lnurl=trace,info',
+        '-e', 'BREEZ_LNURL_DOMAINS=',
+        '-e', 'BREEZ_LNURL_SCHEME=http',
+        '-e', 'BREEZ_LNURL_NSEC=nsec1qqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqsmhltgl',
+        '-e', 'BREEZ_LNURL_MIN_SENDABLE=1000',
+        '-e', 'BREEZ_LNURL_MAX_SENDABLE=1000000000',
+        '-e', 'BREEZ_LNURL_DEV_DONT_USE_LNURL_INCLUDE_SPARK_ADDRESS=false',
+        IMAGE
+      ])
+      fixture.containerId = runOutput.trim()
+
+      const port = await publishedPort(fixture.containerId, HTTP_PORT)
+      await fixture.waitForHttp(port)
+      fixture.httpUrl = `http://127.0.0.1:${port}`
+      return fixture
+    } catch (e) {
+      fixture.stop()
+      throw e
+    }
+  }
+
+  /**
+   * Readiness cannot be taken from the logs: the server's startup line is
+   * printed before it migrates the database and binds, and it logs nothing
+   * afterwards. Nor is reaching the port enough, since docker's proxy accepts
+   * connections there from the moment the container starts and closes them
+   * again while nothing is listening inside.
+   */
+  async waitForHttp(port) {
+    const deadline = Date.now() + START_TIMEOUT_MS
+    for (;;) {
+      try {
+        await httpResponds(port)
+        return
+      } catch {
+        // Not serving yet.
+      }
+      await this.ensureRunning(this.containerId, 'lnurl server')
+      if (Date.now() >= deadline) {
+        const logs = await this.logs(this.containerId)
+        throw new Error(`lnurl server did not serve HTTP within ${START_TIMEOUT_MS}ms:\n${logs}`)
+      }
+      await new Promise((resolve) => setTimeout(resolve, 250))
+    }
+  }
+
+  async waitForPostgres() {
+    const deadline = Date.now() + START_TIMEOUT_MS
+    for (;;) {
+      try {
+        // Probe TCP explicitly: while initialising, the image's entrypoint
+        // runs a temporary socket-only server that the default `pg_isready`
+        // check would accept as ready.
+        await docker([
+          'exec', this.postgresContainerId,
+          'pg_isready', '-h', '127.0.0.1', '-U', 'postgres'
+        ])
+        return
+      } catch {
+        // Not accepting connections yet.
+      }
+      await this.ensureRunning(this.postgresContainerId, 'postgres')
+      if (Date.now() >= deadline) {
+        throw new Error(`postgres did not accept connections within ${START_TIMEOUT_MS}ms`)
+      }
+      await new Promise((resolve) => setTimeout(resolve, 250))
+    }
+  }
+
+  /**
+   * Fail with the container's logs once it has exited. A container that dies
+   * on startup otherwise surfaces only as a readiness timeout, or as an
+   * unrelated docker error, neither of which names the real cause.
+   */
+  async ensureRunning(containerId, name) {
+    const state = await docker(['inspect', '-f', '{{.State.Running}}', containerId])
+    if (state.trim() === 'true') {
+      return
+    }
+    throw new Error(`${name} container exited before it was ready:\n${await this.logs(containerId)}`)
+  }
+
+  async logs(containerId) {
+    try {
+      // docker logs writes to both stdout and stderr; check both.
+      const { stdout, stderr } = await execFileAsync('docker', ['logs', containerId])
+      return stdout + stderr
+    } catch (e) {
+      return `failed to read container logs: ${e.message}`
+    }
+  }
+
+  stop() {
+    for (const containerId of [this.containerId, this.postgresContainerId]) {
+      if (!containerId) {
+        continue
+      }
+      try {
+        execFileSync('docker', ['rm', '-f', containerId], { stdio: 'ignore' })
+      } catch {
+        // Container may already be gone.
+      }
+    }
+  }
+}
+
+module.exports = { LnurlFixture, dockerAvailable }

package/itest/helpers/scenario.js

@@ -0,0 +1,444 @@
+'use strict'
+
+// JS runner for the shared behavioral scenarios in
+// crates/breez-sdk/cli/tests/scenarios/. It drives the wasm CLI port (which
+// consumes the locally built npm package) the same way the Rust harness
+// drives the Rust CLI: piped stdin, a bogus-command marker after every step,
+// and casing/tag-tolerant JSON assertions. Mirror of
+// crates/breez-sdk/cli/tests/harness/{session,assert,engine}.rs.
+
+const fs = require('fs')
+const os = require('os')
+const path = require('path')
+const { spawn } = require('child_process')
+
+const { fundAddress } = require('./faucet')
+const { LnurlFixture } = require('./lnurl-fixture')
+
+const WASM_CLI_DIR = path.join(
+  __dirname,
+  '../../../../crates/breez-sdk/bindings/examples/cli/langs/wasm'
+)
+const SCENARIOS_DIR = path.join(__dirname, '../../../../crates/breez-sdk/cli/tests/scenarios')
+
+// Marker-wait ceiling for a single command; longer waits use scenario-level
+// retry. Same values as the Rust harness.
+const STEP_TIMEOUT_MS = 120_000
+const QUIESCE_MS = 200
+const POLL_MS = 100
+
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms))
+}
+
+// --------------------------------------------------------------------------
+// Tolerant JSON assertions (mirror of harness/assert.rs)
+// --------------------------------------------------------------------------
+
+/**
+ * Strip echoed REPL prompts from line starts (mirror of the Rust harness;
+ * some CLI ports echo the prompt with no trailing newline).
+ *
+ * @param {string} chunk
+ * @returns {string}
+ */
+function stripPrompts(chunk) {
+  return chunk
+    .split('\n')
+    .map((line) => {
+      for (;;) {
+        const match = /^breez-spark-cli \[(regtest|mainnet)\]> /.exec(line)
+        if (!match) {
+          return line
+        }
+        line = line.slice(match[0].length)
+      }
+    })
+    .join('\n')
+}
+
+/**
+ * Extract the JSON documents a transcript chunk contains. A document starts
+ * at a line whose first column is `{` or `[` and ends when the accumulated
+ * lines parse.
+ *
+ * @param {string} chunk
+ * @returns {any[]}
+ */
+function extractJsonDocs(chunk) {
+  const docs = []
+  let acc = null
+  for (const line of chunk.split('\n')) {
+    if (acc !== null) {
+      acc += line
+      try {
+        docs.push(JSON.parse(acc))
+        acc = null
+      } catch {
+        acc += '\n'
+      }
+    } else if (line.startsWith('{') || line.startsWith('[')) {
+      try {
+        docs.push(JSON.parse(line))
+      } catch {
+        acc = line + '\n'
+      }
+    }
+  }
+  return docs
+}
+
+/** Lowercase and strip underscores so all casings compare equal. */
+function normalize(s) {
+  return s.toLowerCase().replaceAll('_', '')
+}
+
+/**
+ * Resolve a dot-separated path against a JSON value. Object keys match after
+ * normalization; numeric segments index arrays. An enum-tag segment matches
+ * either an externally tagged wrapper key (descends) or a `type` field on
+ * the current object (stays in place).
+ *
+ * @param {any} root
+ * @param {string} pathExpr - dot-separated; the empty path addresses the
+ *   document itself
+ * @returns {any} the value, or undefined when the path does not resolve
+ */
+function lookupPath(root, pathExpr) {
+  if (pathExpr === '') {
+    return root
+  }
+  let current = root
+  for (const segment of pathExpr.split('.')) {
+    const wanted = normalize(segment)
+    if (Array.isArray(current)) {
+      const index = Number.parseInt(segment, 10)
+      if (Number.isNaN(index) || index >= current.length) {
+        return undefined
+      }
+      current = current[index]
+    } else if (current !== null && typeof current === 'object') {
+      const key = Object.keys(current).find((k) => normalize(k) === wanted)
+      if (key !== undefined) {
+        current = current[key]
+      } else if (typeof current.type === 'string' && normalize(current.type) === wanted) {
+        // Tag-style enum: the segment names the variant of the object
+        // itself; the fields live alongside the tag.
+      } else {
+        return undefined
+      }
+    } else {
+      return undefined
+    }
+  }
+  return current
+}
+
+/** Render a JSON value the way a scenario writes it. */
+function valueToString(value) {
+  return typeof value === 'string' ? value : JSON.stringify(value)
+}
+
+function asNumber(value) {
+  if (typeof value === 'number') {
+    return value
+  }
+  if (typeof value === 'string' && value.trim() !== '') {
+    const n = Number(value)
+    return Number.isNaN(n) ? undefined : n
+  }
+  return undefined
+}
+
+/**
+ * Check one expect_json matcher against the value found at its path.
+ * Matcher forms: bare value (tolerant equality), {gte: n}, {exists: bool}.
+ *
+ * @param {any} matcher
+ * @param {any} found - undefined when the path did not resolve
+ */
+function checkMatcher(matcher, found) {
+  if (matcher !== null && typeof matcher === 'object' && !Array.isArray(matcher)) {
+    if (typeof matcher.exists === 'boolean') {
+      const exists = found !== undefined && found !== null
+      if (exists !== matcher.exists) {
+        throw new Error(`expected exists=${matcher.exists}, value was ${JSON.stringify(found)}`)
+      }
+      return
+    }
+    if (matcher.gte !== undefined) {
+      const floor = asNumber(matcher.gte)
+      if (floor === undefined) {
+        throw new Error(`gte bound is not numeric: ${matcher.gte}`)
+      }
+      const actual = asNumber(found)
+      if (actual === undefined) {
+        throw new Error(`expected a number >= ${floor}, value was ${JSON.stringify(found)}`)
+      }
+      if (actual < floor) {
+        throw new Error(`expected >= ${floor}, got ${actual}`)
+      }
+      return
+    }
+  }
+
+  if (found === undefined) {
+    throw new Error('path not found in output')
+  }
+  const expected = valueToString(matcher).toLowerCase()
+  const actual = valueToString(found).toLowerCase()
+  if (expected !== actual) {
+    throw new Error(`expected '${expected}', got '${actual}'`)
+  }
+}
+
+// --------------------------------------------------------------------------
+// Variable interpolation (mirror of harness/mod.rs)
+// --------------------------------------------------------------------------
+
+/** Replace every ${name} in input; unknown variables fail loudly. */
+function interpolate(input, vars) {
+  return input.replaceAll(/\$\{([^}]*)\}/g, (_, name) => {
+    if (!(name in vars)) {
+      throw new Error(`unknown variable '\${${name}}' in '${input}'`)
+    }
+    return vars[name]
+  })
+}
+
+// --------------------------------------------------------------------------
+// CLI session (mirror of harness/session.rs)
+// --------------------------------------------------------------------------
+
+class CliSession {
+  /**
+   * @param {string} dataDir
+   * @param {string[]} extraArgs
+   */
+  constructor(dataDir, extraArgs) {
+    this.child = spawn(
+      process.execPath,
+      ['src/main.js', '--data-dir', dataDir, ...extraArgs],
+      { cwd: WASM_CLI_DIR, stdio: ['pipe', 'pipe', 'pipe'] }
+    )
+    this.transcript = ''
+    this.cursor = 0
+    this.stepCounter = 0
+    for (const stream of [this.child.stdout, this.child.stderr]) {
+      stream.setEncoding('utf8')
+      stream.on('data', (data) => {
+        this.transcript += data
+      })
+    }
+  }
+
+  /**
+   * Run one command with its scripted stdin answers and return the
+   * transcript chunk it produced.
+   *
+   * @param {string} cmd
+   * @param {string[]} stdinLines
+   * @returns {Promise<string>}
+   */
+  async runStep(cmd, stdinLines) {
+    this.stepCounter += 1
+    const marker = `__step_end_${this.stepCounter}__`
+    const input = [cmd, ...stdinLines, marker].join('\n') + '\n'
+    this.child.stdin.write(input)
+
+    const deadline = Date.now() + STEP_TIMEOUT_MS
+    let markerPos
+    for (;;) {
+      markerPos = this.transcript.indexOf(marker, this.cursor)
+      if (markerPos !== -1) {
+        break
+      }
+      if (Date.now() >= deadline) {
+        throw new Error(
+          `timed out after ${STEP_TIMEOUT_MS}ms waiting for step to finish; ` +
+            `output so far:\n${this.transcript.slice(this.cursor)}`
+        )
+      }
+      await sleep(POLL_MS)
+    }
+
+    // Wait for the marker error's trailing lines to land, then consume
+    // everything up to the current end of transcript.
+    let stableLength = this.transcript.length
+    for (;;) {
+      await sleep(QUIESCE_MS)
+      if (this.transcript.length === stableLength) {
+        break
+      }
+      stableLength = this.transcript.length
+    }
+
+    // The chunk ends at the start of the line carrying the marker error.
+    const chunkEnd = this.transcript.lastIndexOf('\n', markerPos)
+    const chunk = this.transcript.slice(this.cursor, Math.max(chunkEnd, this.cursor))
+    this.cursor = stableLength
+    return chunk
+  }
+
+  /** Ask the CLI to exit and wait for the process to finish. */
+  async close() {
+    this.child.stdin.write('exit\n')
+    const exited = await Promise.race([
+      new Promise((resolve) => this.child.once('exit', () => resolve(true))),
+      sleep(30_000).then(() => false)
+    ])
+    if (!exited) {
+      this.child.kill('SIGKILL')
+      throw new Error("CLI did not exit within 30s of 'exit'")
+    }
+  }
+
+  kill() {
+    this.child.kill('SIGKILL')
+  }
+}
+
+// --------------------------------------------------------------------------
+// Scenario engine (mirror of harness/engine.rs)
+// --------------------------------------------------------------------------
+
+/** Check a step's expectations against its chunk; returns captured vars. */
+function evaluate(chunk, step, vars) {
+  chunk = stripPrompts(chunk)
+  const docs = extractJsonDocs(chunk)
+  const last = docs.length > 0 ? docs[docs.length - 1] : undefined
+
+  for (const [pathExpr, matcher] of Object.entries(step.expect_json ?? {})) {
+    const resolved = typeof matcher === 'string' ? interpolate(matcher, vars) : matcher
+    try {
+      checkMatcher(resolved, last === undefined ? undefined : lookupPath(last, pathExpr))
+    } catch (e) {
+      throw new Error(`expect_json '${pathExpr}' failed: ${e.message}`)
+    }
+  }
+
+  for (const needle of step.expect_contains ?? []) {
+    const resolved = interpolate(needle, vars)
+    if (!chunk.includes(resolved)) {
+      throw new Error(`expect_contains '${resolved}' not found in step output`)
+    }
+  }
+
+  const captured = {}
+  for (const [name, pathExpr] of Object.entries(step.capture ?? {})) {
+    const value = last === undefined ? undefined : lookupPath(last, pathExpr)
+    if (value === undefined) {
+      throw new Error(`capture '${name}': path '${pathExpr}' not found`)
+    }
+    captured[name] = valueToString(value)
+  }
+  return captured
+}
+
+async function runCmdStep(cli, step, vars) {
+  const cmd = interpolate(step.cmd, vars)
+  const stdinLines = (step.stdin ?? []).map((l) => interpolate(l, vars))
+  const deadline = step.retry ? Date.now() + step.retry.timeout_secs * 1000 : undefined
+  const intervalMs = (step.retry?.interval_secs ?? 5) * 1000
+
+  for (;;) {
+    const chunk = await cli.runStep(cmd, stdinLines)
+    try {
+      Object.assign(vars, evaluate(chunk, step, vars))
+      return
+    } catch (e) {
+      if (deadline !== undefined && Date.now() < deadline) {
+        console.error(`step '${cmd}' not satisfied yet (${e.message}), retrying`)
+        await sleep(intervalMs)
+      } else {
+        throw new Error(`step '${cmd}' failed: ${e.message}\nstep output:\n${chunk}`)
+      }
+    }
+  }
+}
+
+/**
+ * Run one scenario JSON (already parsed). Fixture and requirement gating is
+ * the caller's job; this assumes they are met.
+ *
+ * @param {object} scenario
+ */
+async function runScenario(scenario) {
+  const vars = {}
+  const fixtures = []
+  const walletDirs = new Map()
+  try {
+    for (const fixture of scenario.fixtures ?? []) {
+      if (fixture === 'lnurl') {
+        const lnurl = await LnurlFixture.start()
+        vars.lnurl_url = lnurl.httpUrl
+        fixtures.push(lnurl)
+      } else {
+        throw new Error(`unknown fixture '${fixture}'`)
+      }
+    }
+
+    for (const [sessionIndex, session] of scenario.sessions.entries()) {
+      let dir = walletDirs.get(session.wallet)
+      if (dir === undefined) {
+        dir = fs.mkdtempSync(path.join(os.tmpdir(), 'breez-cli-scenario-'))
+        walletDirs.set(session.wallet, dir)
+      }
+      const extraArgs = (session.extra_args ?? []).map((a) => interpolate(a, vars))
+      const cli = new CliSession(dir, extraArgs)
+      try {
+        for (const [stepIndex, step] of session.steps.entries()) {
+          try {
+            if (step.faucet_fund) {
+              const address = interpolate(step.faucet_fund.address, vars)
+              const txid = await fundAddress(address, step.faucet_fund.amount_sats)
+              console.error(
+                `faucet funded ${address} with ${step.faucet_fund.amount_sats} sats: ${txid}`
+              )
+            } else {
+              await runCmdStep(cli, step, vars)
+            }
+          } catch (e) {
+            e.message =
+              `scenario '${scenario.name}', session ${sessionIndex} ` +
+              `(wallet '${session.wallet}'), step ${stepIndex}: ${e.message}`
+            throw e
+          }
+        }
+      } catch (e) {
+        cli.kill()
+        throw e
+      }
+      await cli.close()
+    }
+  } finally {
+    for (const fixture of fixtures) {
+      fixture.stop()
+    }
+    for (const dir of walletDirs.values()) {
+      fs.rmSync(dir, { recursive: true, force: true })
+    }
+  }
+}
+
+/** List scenario files as [name, parsed] pairs, sorted by name. */
+function loadScenarios() {
+  return fs
+    .readdirSync(SCENARIOS_DIR)
+    .filter((f) => f.endsWith('.json'))
+    .sort()
+    .map((f) => [
+      path.basename(f, '.json'),
+      JSON.parse(fs.readFileSync(path.join(SCENARIOS_DIR, f), 'utf8'))
+    ])
+}
+
+module.exports = {
+  WASM_CLI_DIR,
+  checkMatcher,
+  extractJsonDocs,
+  interpolate,
+  loadScenarios,
+  lookupPath,
+  runScenario
+}