trac-msb 0.2.18 → 0.2.20

package/rpc/utils/helpers.js

@@ -1,99 +1,79 @@
 import b4a from "b4a"
 import { operationToPayload } from "../../src/utils/applyOperations.js"
 import { isHexString } from "../../src/utils/helpers.js"; 
-
-export class ValidationError extends Error {
-  constructor(message) {
-    super(message);
-    this.name = "ValidationError";
-  }
-}
-
-export class BroadcastError extends Error {
-  constructor(message) {
-    super(message);
-    this.name = "BroadcastError";
-  }
-}
-
-export class NotFoundError extends Error {
-  constructor(message) {
-    super(message);
-    this.name = "NotFoundError";
-  }
-}
+import { ValidationError } from "../../src/utils/errors.js";
 
 export function decodeBase64Payload(base64) {
-  let decodedPayloadString
-  try {
-    decodedPayloadString = b4a.from(base64, "base64").toString("utf-8")
-  } catch (err) {
-    throw new ValidationError("Failed to decode base64 payload.")
-  }
+    let decodedPayloadString
+    try {
+        decodedPayloadString = b4a.from(base64, "base64").toString("utf-8")
+    } catch {
+        throw new ValidationError("Failed to decode base64 payload.")
+    }
 
-  try {
-    return JSON.parse(decodedPayloadString)
-  } catch (err) {
-    throw new ValidationError("Decoded payload is not valid JSON.")
-  }
+    try {
+        return JSON.parse(decodedPayloadString)
+    } catch {
+        throw new ValidationError("Decoded payload is not valid JSON.")
+    }
 }
 
 export function isBase64(str) {
-  const base64Regex =
+    const base64Regex =
     /^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/
-  return base64Regex.test(str)
+    return base64Regex.test(str)
 }
 
 export function validatePayloadStructure(payload) {
-  if (
-    typeof payload !== "object" ||
+    if (
+        typeof payload !== "object" ||
     payload === null ||
     typeof payload.type !== "number" ||
     typeof payload.address !== "string" ||
     !["txo", "tro"].some((key) => key in payload && typeof payload[key] === "object")
-  ) {
-    throw new ValidationError("Invalid payload structure.")
-  }
+    ) {
+        throw new ValidationError("Invalid payload structure.")
+    }
 }
 
 export function sanitizeTransferPayload(payload) {
-  const operationKey = operationToPayload(payload.type);
+    const operationKey = operationToPayload(payload.type);
 
-  if (operationKey !== 'tro' && operationKey !== 'txo') {
-    throw new ValidationError('Payload is not a transfer/transaction operation.');
-  }
+    if (operationKey !== 'tro' && operationKey !== 'txo') {
+        throw new ValidationError('Payload is not a transfer/transaction operation.');
+    }
 
-  const operation = payload[operationKey];
-  if (payload.address && typeof payload.address === "string") {
-    payload.address = payload.address.trim()
-  }
+    const operation = payload[operationKey];
+    if (payload.address && typeof payload.address === "string") {
+        payload.address = payload.address.trim()
+    }
 
-  if (operation && typeof operation === "object") {
-    for (const [key, value] of Object.entries(operation)) {
-      if (typeof value === "string") {
-        let sanitized = value.trim()
+    if (operation && typeof operation === "object") {
+        for (const [key, value] of Object.entries(operation)) {
+            if (typeof value === "string") {
+                let sanitized = value.trim()
 
-        // normalize hex-like strings
-        if (/^[0-9A-F]+$/i.test(sanitized)) {
-          sanitized = sanitized.toLowerCase()
-        }
+                // normalize hex-like strings
+                if (/^[0-9A-F]+$/i.test(sanitized)) {
+                    sanitized = sanitized.toLowerCase()
+                }
 
-        payload[operationKey][key] = sanitized
-      }
+                payload[operationKey][key] = sanitized
+            }
+        }
     }
-  }
 
-  return payload
+    return payload
 }
 
 export function sanitizeBulkPayloadsRequestBody(body) {
-  const cleanBody = body
-    .replace(/^\uFEFF/, '')
-    .replace(/\r/g, '')
-    .replace(/\0/g, '')
-    .trim();
+    const cleanBody = body
+        .replace(/^\uFEFF/, '')
+        .replace(/\r/g, '')
+        .replace(/\0/g, '')
+        .trim();
 
-  return JSON.parse(cleanBody);
+    return JSON.parse(cleanBody);
 }
 
 export function isValidTxHash(hash) {
@@ -102,4 +82,4 @@ export function isValidTxHash(hash) {
 
 export function hasSpacesInUrl(url) {
     return url.includes('%20') || url.includes(' ');
-}
+}

package/scripts/pear-runner.js

@@ -0,0 +1,170 @@
+import { spawn, spawnSync } from 'node:child_process';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const SIGNAL_EXIT_CODES = new Map([
+    ['SIGHUP', 129],
+    ['SIGINT', 130],
+    ['SIGQUIT', 131],
+    ['SIGTERM', 143]
+]);
+
+const projectDirectory = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const workerEntrypoint = path.join(projectDirectory, 'msb.mjs');
+
+export const parsePearMajor = output => {
+    const semver = output.match(/\bSemVer\s*=\s*(\d+)\.\d+\.\d+\b/i);
+    if (semver) {
+        return Number(semver[1]);
+    }
+
+    const summary = output.match(/\/\s*v(\d+)\.\d+\.\d+\b/i);
+    return summary ? Number(summary[1]) : null;
+};
+
+export const detectPearMajor = (runCommand = spawnSync) => {
+    const result = runCommand('pear', ['-v'], {
+        encoding: 'utf8',
+        stdio: ['ignore', 'pipe', 'pipe']
+    });
+
+    if (result.error?.code === 'ENOENT') {
+        return null;
+    }
+
+    if (result.error) {
+        throw new Error(`Could not check the installed Pear version: ${result.error.message}`);
+    }
+
+    const output = `${result.stdout ?? ''}\n${result.stderr ?? ''}`;
+
+    if (result.status !== 0) {
+        throw new Error('Could not determine the installed Pear major version from `pear -v`.');
+    }
+
+    return parsePearMajor(output);
+};
+
+const exitCodeFor = (code, signal) => {
+    if (Number.isInteger(code)) {
+        return code;
+    }
+
+    return SIGNAL_EXIT_CODES.get(signal) ?? 1;
+};
+
+export const runWithPearV2 = (
+    args,
+    spawnProcess = spawn
+) => new Promise((resolve, reject) => {
+    const child = spawnProcess('pear', ['run', '.', ...args], {
+        cwd: projectDirectory,
+        env: process.env,
+        stdio: 'inherit'
+    });
+
+    child.once('error', reject);
+    child.once('exit', (code, signal) => resolve(exitCodeFor(code, signal)));
+});
+
+const pipeWorkerStdio = (worker, hostProcess) => {
+    if (worker.stdin && hostProcess.stdin?.pipe) {
+        hostProcess.stdin.pipe(worker.stdin);
+    }
+    if (worker.stdout?.pipe && hostProcess.stdout) {
+        worker.stdout.pipe(hostProcess.stdout);
+    }
+    if (worker.stderr?.pipe && hostProcess.stderr) {
+        worker.stderr.pipe(hostProcess.stderr);
+    }
+};
+
+export const runWithPearV3 = async (
+    args,
+    {
+        loadPearRuntime = () => import('pear-runtime'),
+        hostProcess = process
+    } = {}
+) => {
+    let PearRuntime;
+
+    try {
+        const pearRuntimeModule = await loadPearRuntime();
+        PearRuntime = pearRuntimeModule.default ?? pearRuntimeModule;
+    } catch (error) {
+        throw new Error(
+            'Pear v3 requires the pear-runtime dependency. Run npm install before starting MSB.',
+            { cause: error }
+        );
+    }
+
+    const worker = PearRuntime.run(workerEntrypoint, args);
+    pipeWorkerStdio(worker, hostProcess);
+
+    return new Promise((resolve, reject) => {
+        let requestedSignal = null;
+        const signalListeners = [];
+
+        const cleanup = () => {
+            for (const [signal, listener] of signalListeners) {
+                hostProcess.removeListener(signal, listener);
+            }
+
+            if (worker.stdin && hostProcess.stdin?.unpipe) {
+                hostProcess.stdin.unpipe(worker.stdin);
+            }
+        };
+
+        for (const signal of SIGNAL_EXIT_CODES.keys()) {
+            const listener = () => {
+                if (requestedSignal !== null) {
+                    return;
+                }
+
+                requestedSignal = signal;
+                worker.destroy();
+            };
+
+            signalListeners.push([signal, listener]);
+            hostProcess.once(signal, listener);
+        }
+
+        worker.once('error', error => {
+            cleanup();
+            reject(error);
+        });
+        worker.once('exit', (code, signal) => {
+            cleanup();
+            resolve(exitCodeFor(code, requestedSignal ?? signal));
+        });
+    });
+};
+
+export const run = async (
+    args = process.argv.slice(2),
+    {
+        detectVersion = detectPearMajor,
+        runPearV2 = runWithPearV2,
+        runPearV3 = runWithPearV3
+    } = {}
+) => {
+    const major = detectVersion();
+
+    if (major !== null && major < 3) {
+        return runPearV2(args);
+    }
+
+    return runPearV3(args);
+};
+
+const isMainModule = process.argv[1] &&
+    path.resolve(process.argv[1]) === fileURLToPath(import.meta.url);
+
+if (isMainModule) {
+    try {
+        process.exitCode = await run();
+    } catch (error) {
+        console.error(`MainSettlementBus Pear runner: ${error.message}`);
+        process.exitCode = 1;
+    }
+}

package/src/config/args.js

@@ -1,19 +1,69 @@
 import { createConfig, ENV } from './env.js';
 
-const getArguments = () => {
-    const pearApp = typeof Pear !== 'undefined' ? (Pear.app ?? Pear.config) : undefined;
-    const runtimeArgs = typeof process !== 'undefined' ? process.argv.slice(2) : [];
-    return pearApp?.args ?? runtimeArgs;
+export const getArguments = (runtime = globalThis) => {
+    const pearRuntime = runtime.Pear;
+    const pearApp = pearRuntime?.app ?? pearRuntime?.config;
+    const bareArgs = runtime.Bare?.argv?.slice(2);
+    const processArgs = runtime.process?.argv?.slice(2) ?? [];
+    return pearApp?.args ?? bareArgs ?? processArgs;
+};
+
+const getOptionValue = (args, flag) => {
+    const index = args.indexOf(flag);
+    if (index === -1) {
+        return undefined;
+    }
+
+    const value = args[index + 1];
+    if (value === undefined || String(value).startsWith('--')) {
+        throw new Error(`MainSettlementBus CLI: ${flag} requires a value.`);
+    }
+
+    return value;
+};
+
+const parseNonEmptyStringOption = (args, flag) => {
+    const value = getOptionValue(args, flag);
+    if (value === undefined) {
+        return undefined;
+    }
+
+    if (typeof value !== 'string' || value.trim().length === 0) {
+        throw new Error(`MainSettlementBus CLI: ${flag} must be a non-empty string.`);
+    }
+
+    return value;
+};
+
+const parsePortOption = (args) => {
+    const value = getOptionValue(args, '--port');
+    if (value === undefined) {
+        return undefined;
+    }
+
+    if (!/^\d+$/.test(value)) {
+        throw new Error('MainSettlementBus CLI: --port must be an integer in range 1-65535.');
+    }
+
+    const port = Number(value);
+    if (!Number.isInteger(port) || port < 1 || port > 65535) {
+        throw new Error('MainSettlementBus CLI: --port must be an integer in range 1-65535.');
+    }
+
+    return port;
 };
 
 export const resolveEnvironment = (args = []) => {
-    const networkIndex = args.indexOf('--network');
-    const network = (networkIndex !== -1 && args[networkIndex + 1]) ? args[networkIndex + 1] : undefined;
+    const network = getOptionValue(args, '--network');
+    if (network === undefined) {
+        return ENV.MAINNET;
+    }
 
     if (network === ENV.MAINNET) return ENV.MAINNET;
     if (network === ENV.DEVELOPMENT) return ENV.DEVELOPMENT;
     if (network === ENV.TESTNET1 || network === 'testnet') return ENV.TESTNET1;
-    return ENV.MAINNET;
+
+    throw new Error('MainSettlementBus CLI: --network must be one of: mainnet, development, testnet.');
 };
 
 export const isRpcEnabled = () => {
@@ -25,12 +75,9 @@ export const resolveConfig = () => {
     const args = getArguments();
     const runRpc = isRpcEnabled();
     const selectedEnv = resolveEnvironment(args);
-    const storesDirectoryIndex = args.indexOf('--stores-directory');
-    const storesDirectory = (storesDirectoryIndex !== -1 && args[storesDirectoryIndex + 1]) ? args[storesDirectoryIndex + 1] : undefined;
-    const hostIndex = args.indexOf('--host');
-    const host = (hostIndex !== -1 && args[hostIndex + 1]) ? args[hostIndex + 1] : undefined;
-    const portIndex = args.indexOf('--port');
-    const port = (portIndex !== -1 && args[portIndex + 1]) ? parseInt(args[portIndex + 1], 10) : undefined;
+    const storesDirectory = parseNonEmptyStringOption(args, '--stores-directory');
+    const host = runRpc ? parseNonEmptyStringOption(args, '--host') : undefined;
+    const port = runRpc ? parsePortOption(args) : undefined;
 
     const rpc = {
         storesDirectory,

package/src/config/config.js

@@ -12,9 +12,12 @@ export class Config {
         this.#validate(options, config)
         this.#options = options
         this.#config = config
-        this.#bootstrap = b4a.from(this.#options.bootstrap || this.#config.bootstrap, 'hex')
-        // Ensure a 32-byte channel buffer (repeat-fill from string/Buffer if provided)
-        this.#channel = b4a.alloc(32).fill(this.#options.channel || this.#config.channel)
+        this.#bootstrap = this.#normalizeBootstrap(
+            isDefined(options.bootstrap) ? options.bootstrap : config.bootstrap
+        )
+        this.#channel = this.#normalizeChannel(
+            isDefined(options.channel) ? options.channel : config.channel
+        )
     }
 
     get addressLength() {
@@ -46,10 +49,6 @@ export class Config {
         return this.#config.dhtBootstrap
     }
 
-    get derivationPath() {
-        return this.#config.derivationPath
-    }
-
     get disableRateLimit() {
         if (this.#isOverriden('disableRateLimit')) return !!this.#options.disableRateLimit
         return !!this.#config.disableRateLimit
@@ -89,8 +88,12 @@ export class Config {
         return _.endsWith(this.storesDirectory, '/admin')
     }
 
+    get keyPairDirectoryPath() {
+        return `${this.storesFullPath}/db`
+    }
+
     get keyPairPath()  {
-        return `${this.storesFullPath}/db/keypair.json`
+        return `${this.keyPairDirectoryPath}/keypair.json`
     }
 
     get maxRetries() {
@@ -219,17 +222,142 @@ export class Config {
         return this.#config.debug
     }
 
-    // Most of these properties are boolean
+    get derivationPath() {
+        return this.#config.derivationPath
+    }
+    
+    get pollInterval() {
+        if (this.#isOverriden('pollInterval')) return this.#options.pollInterval
+        return this.#config.pollInterval
+    }
+
+    get adminCacheTTL() {
+        if (this.#isOverriden('adminCacheTTL')) return this.#options.adminCacheTTL
+        return this.#config.adminCacheTTL
+    }
+    
+    get bootstrapTimeout() {
+        if (this.#isOverriden('bootstrapTimeout')) return this.#options.bootstrapTimeout
+        return this.#config.bootstrapTimeout
+    }
+
+    get writersShortCacheTTL() {
+        if (this.#isOverriden('writersShortCacheTTL')) return this.#options.writersShortCacheTTL
+        return this.#config.writersShortCacheTTL
+    }
+
+    get writersLongCacheTTL() {
+        if (this.#isOverriden('writersLongCacheTTL')) return this.#options.writersLongCacheTTL
+        return this.#config.writersLongCacheTTL
+    }
+    
+    get validatorConnectionAttemptDelay() {
+        if (this.#isOverriden('validatorConnectionAttemptDelay')) return this.#options.validatorConnectionAttemptDelay
+        return this.#config.validatorConnectionAttemptDelay
+    }
+
     #isOverriden(prop) {
         return this.#options.hasOwnProperty(prop) && isDefined(this.#options[prop])
     }
 
+    #normalizeBootstrap(bootstrap) {
+        if (b4a.isBuffer(bootstrap)) {
+            return b4a.from(bootstrap)
+        }
+
+        return b4a.from(bootstrap, 'hex')
+    }
+
+    #normalizeChannel(channel) {
+        return b4a.alloc(32).fill(channel)
+    }
+
+    #validateStringOverride(field, value) {
+        if (typeof value !== 'string' || value.trim().length === 0) {
+            throw new Error(`MainSettlementBus Config: ${field} must be a non-empty string.`);
+        }
+    }
+
+    #validatePortOverride(port) {
+        if (!Number.isInteger(port) || port < 1 || port > 65535) {
+            throw new Error('MainSettlementBus Config: port must be an integer in range 1-65535.');
+        }
+    }
+
+    #validateBootstrapOverride(bootstrap) {
+        if (b4a.isBuffer(bootstrap)) {
+            if (bootstrap.length !== 32) {
+                throw new Error('MainSettlementBus Config: bootstrap must be a 32-byte hex string or Buffer.');
+            }
+            return;
+        }
+
+        if (typeof bootstrap !== 'string' || !/^[0-9a-fA-F]{64}$/.test(bootstrap)) {
+            throw new Error('MainSettlementBus Config: bootstrap must be a 32-byte hex string or Buffer.');
+        }
+    }
+
+    #validateChannelOverride(channel) {
+        if (!(typeof channel === 'string' || b4a.isBuffer(channel))) {
+            throw new Error('MainSettlementBus Config: channel must be a string or Buffer.');
+        }
+
+        const length = b4a.isBuffer(channel) ? channel.length : b4a.from(channel).length
+
+        if (length === 0 || length > 32) {
+            throw new Error('MainSettlementBus Config: channel must be 1-32 bytes long.');
+        }
+    }
+
+    #validateDhtBootstrapOverride(dhtBootstrap) {
+        if (!Array.isArray(dhtBootstrap) || dhtBootstrap.length === 0) {
+            throw new Error('MainSettlementBus Config: dhtBootstrap must be a non-empty array of strings.');
+        }
+
+        for (const entry of dhtBootstrap) {
+            if (typeof entry !== 'string' || entry.trim().length === 0) {
+                throw new Error('MainSettlementBus Config: dhtBootstrap entries must be non-empty strings.');
+            }
+        }
+    }
+
     #validate(options, config) {
+        if (options === null || typeof options !== 'object') {
+            throw new Error('MainSettlementBus Config: options must be an object.');
+        }
+
+        if (config === null || typeof config !== 'object') {
+            throw new Error('MainSettlementBus Config: config must be an object.');
+        }
+
         if (!options.channel && !config.channel) {
             throw new Error(
                 "MainSettlementBus: Channel is required. Application cannot start without channel."
             );
         }
-    }
 
+        if (isDefined(options.bootstrap)) {
+            this.#validateBootstrapOverride(options.bootstrap);
+        }
+
+        if (isDefined(options.channel)) {
+            this.#validateChannelOverride(options.channel);
+        }
+
+        if (isDefined(options.storesDirectory)) {
+            this.#validateStringOverride('storesDirectory', options.storesDirectory);
+        }
+
+        if (isDefined(options.host)) {
+            this.#validateStringOverride('host', options.host);
+        }
+
+        if (isDefined(options.port)) {
+            this.#validatePortOverride(options.port);
+        }
+
+        if (isDefined(options.dhtBootstrap)) {
+            this.#validateDhtBootstrapOverride(options.dhtBootstrap);
+        }
+    }
 }