@zapo-js/fake-server 0.3.0 → 1.0.0

package/dist/esm/api/FakeWaServer.js

@@ -0,0 +1,680 @@
+import { Agent as HttpsAgent } from 'node:https';
+import { WaFakeConnectionPipeline } from '../infra/WaFakeConnectionPipeline.js';
+import { WaFakeMediaHttpsServer } from '../infra/WaFakeMediaHttpsServer.js';
+import { WaFakeWsServer } from '../infra/WaFakeWsServer.js';
+import { generateFakeNoiseRootCa } from '../protocol/auth/cert-chain.js';
+import { WaFakeIqRouter } from '../protocol/iq/router.js';
+import { FakeMediaStore } from '../state/fake-media-store.js';
+import { X25519 } from '../transport/crypto.js';
+import { AppStateSyncManager } from './AppStateSyncManager.js';
+import { FakePairingDriver } from './FakePairingDriver.js';
+import { FakePeer } from './FakePeer.js';
+import { registerDefaultIqHandlers } from './iq-handlers.js';
+import { PreKeyDispenser } from './PreKeyDispenser.js';
+import { Scenario } from './Scenario.js';
+import { ServerRegistries } from './ServerRegistries.js';
+export class FakeWaServer {
+    constructor(options = {}) {
+        this.registries = new ServerRegistries();
+        this.preKeyDispenser = new PreKeyDispenser();
+        this.appStateSync = new AppStateSyncManager();
+        this.pipelines = new Set();
+        this.iqRouter = new WaFakeIqRouter();
+        this.capturedStanzas = [];
+        this.pendingIqExpectations = new Set();
+        this.pendingStanzaExpectations = new Set();
+        this.authenticatedListeners = new Set();
+        this.inboundStanzaListeners = new Set();
+        this.capturedStanzaListeners = new Set();
+        this.rootCa = null;
+        this.serverStaticKeyPair = null;
+        this.listenInfo = null;
+        this.pipelineListener = null;
+        this.rejectMode = null;
+        this.mediaStore = new FakeMediaStore();
+        this.mediaHttpsServer = new WaFakeMediaHttpsServer();
+        this.capturedMediaUploads = [];
+        this.nextUploadCounter = 0;
+        this.cachedMediaProxyAgent = null;
+        this.wsServer = new WaFakeWsServer(options);
+        this.wsServer.onConnection((connection) => this.handleConnection(connection));
+        registerDefaultIqHandlers(this.iqRouter, this.buildIqHandlerDeps());
+    }
+    buildIqHandlerDeps() {
+        const reg = this.registries;
+        const preKey = this.preKeyDispenser;
+        const appState = this.appStateSync;
+        return {
+            get peerRegistry() {
+                return reg.peerRegistry;
+            },
+            get groupRegistry() {
+                return reg.groupRegistry;
+            },
+            get privacySettings() {
+                return reg.privacySettings;
+            },
+            get blocklistJids() {
+                return reg.blocklistJids;
+            },
+            get profilePicturesByJid() {
+                return reg.profilePicturesByJid;
+            },
+            get businessProfilesByJid() {
+                return reg.businessProfilesByJid;
+            },
+            get abPropsInput() {
+                return reg.abPropsInput;
+            },
+            get issuedPrivacyTokens() {
+                return reg.issuedPrivacyTokens;
+            },
+            get latestStatusText() {
+                return reg.latestStatusText;
+            },
+            setLatestStatusText: (text) => {
+                reg.latestStatusText = text;
+            },
+            lookupDeviceIdsForUser: (userJid) => reg.lookupDeviceIdsForUser(userJid),
+            notifyGroupOp: (op) => reg.notifyGroupOp(op),
+            mutatePrivacySettings: (category, value) => reg.mutatePrivacySettings(category, value),
+            mutateBlocklist: (action, jid) => reg.mutateBlocklist(action, jid),
+            notifyProfilePictureSet: (op) => reg.notifyProfilePictureSet(op),
+            handleProfilePictureSet: (targetJid, newId) => reg.handleProfilePictureSet(targetJid, newId),
+            notifyStatusSet: (text) => reg.notifyStatusSet(text),
+            notifyLogout: () => reg.notifyLogout(),
+            notifyPrivacyTokenIssue: (token) => reg.notifyPrivacyTokenIssue(token),
+            notifyDirtyBitsClear: (op) => reg.notifyDirtyBitsClear(op),
+            notifyPrivacySet: (change) => {
+                for (const listener of reg.privacySetListeners) {
+                    try {
+                        listener(change);
+                    }
+                    catch (error) {
+                        void error;
+                    }
+                }
+            },
+            notifyBlocklistChange: (change) => {
+                for (const listener of reg.blocklistChangeListeners) {
+                    try {
+                        listener(change);
+                    }
+                    catch (error) {
+                        void error;
+                    }
+                }
+            },
+            capturePreKeyBundle: (bundle) => preKey.captureBundle(bundle),
+            consumeOutboundAppStatePatches: (iq) => appState.consumeOutboundAppStatePatches(iq),
+            get appStateCollectionProviders() {
+                return appState.appStateCollectionProviders;
+            },
+            requireMediaHttpsInfo: () => this.requireMediaHttpsInfo()
+        };
+    }
+    registerIqHandler(matcher, respond, label) {
+        const handler = { matcher, respond, label };
+        return this.iqRouter.register(handler, { priority: 'high' });
+    }
+    async routeIqForTest(iq) {
+        return this.iqRouter.route(iq);
+    }
+    onOutboundGroupOp(listener) {
+        return this.registries.onOutboundGroupOp(listener);
+    }
+    onOutboundPrivacySet(listener) {
+        return this.registries.onOutboundPrivacySet(listener);
+    }
+    onOutboundBlocklistChange(listener) {
+        return this.registries.onOutboundBlocklistChange(listener);
+    }
+    onOutboundProfilePictureSet(listener) {
+        return this.registries.onOutboundProfilePictureSet(listener);
+    }
+    onOutboundStatusSet(listener) {
+        return this.registries.onOutboundStatusSet(listener);
+    }
+    onLogout(listener) {
+        return this.registries.onLogout(listener);
+    }
+    onOutboundPrivacyTokenIssue(listener) {
+        return this.registries.onOutboundPrivacyTokenIssue(listener);
+    }
+    onOutboundDirtyBitsClear(listener) {
+        return this.registries.onOutboundDirtyBitsClear(listener);
+    }
+    privacyTokensIssuedSnapshot() {
+        return this.registries.privacyTokensIssuedSnapshot();
+    }
+    privacySettingsSnapshot() {
+        return this.registries.privacySettingsSnapshot();
+    }
+    blocklistSnapshot() {
+        return this.registries.blocklistSnapshot();
+    }
+    latestStatusSnapshot() {
+        return this.registries.latestStatusSnapshot();
+    }
+    groupRegistrySnapshot() {
+        return this.registries.groupRegistrySnapshot();
+    }
+    setAbProps(input) {
+        this.registries.setAbProps(input);
+    }
+    setPrivacyDisallowedList(category, jids) {
+        this.registries.setPrivacyDisallowedList(category, jids);
+    }
+    setProfilePictureRecord(jid, picture) {
+        this.registries.setProfilePictureRecord(jid, picture);
+    }
+    setBusinessProfileRecord(jid, profile) {
+        this.registries.setBusinessProfileRecord(jid, profile);
+    }
+    createFakeGroup(input) {
+        return this.registries.createFakeGroup(input);
+    }
+    async triggerPreKeyUpload(pipeline, options = {}) {
+        return this.preKeyDispenser.triggerPreKeyUpload(pipeline, options);
+    }
+    awaitPreKeyBundle(timeoutMs = 15000) {
+        return this.preKeyDispenser.awaitPreKeyBundle(timeoutMs);
+    }
+    capturedPreKeyBundleSnapshot() {
+        return this.preKeyDispenser.capturedPreKeyBundleSnapshot();
+    }
+    dispenseOneTimePreKey() {
+        return this.preKeyDispenser.dispenseOneTimePreKey();
+    }
+    preKeyDispenserMissesSnapshot() {
+        return this.preKeyDispenser.preKeyDispenserMissesSnapshot();
+    }
+    preKeysAvailable() {
+        return this.preKeyDispenser.preKeysAvailable();
+    }
+    registerAppStateSyncKey(keyId, keyData) {
+        this.appStateSync.registerAppStateSyncKey(keyId, keyData);
+    }
+    onOutboundAppStateMutation(listener) {
+        return this.appStateSync.onOutboundAppStateMutation(listener);
+    }
+    expectAppStateMutation(predicate, timeoutMs = 15000) {
+        return this.appStateSync.expectAppStateMutation(predicate, timeoutMs);
+    }
+    provideAppStateCollection(name, provider) {
+        return this.appStateSync.provideAppStateCollection(name, provider);
+    }
+    async pushServerSyncNotification(pipeline, input) {
+        return this.appStateSync.pushServerSyncNotification(pipeline, input);
+    }
+    onAuthenticatedPipeline(listener) {
+        this.authenticatedListeners.add(listener);
+        return () => this.authenticatedListeners.delete(listener);
+    }
+    scenario(configure) {
+        configure(new Scenario(this));
+    }
+    expectIq(matcher, options = {}) {
+        const timeoutMs = options.timeoutMs ?? 2000;
+        for (const captured of this.capturedStanzas) {
+            if (matchesIq(captured, matcher)) {
+                return Promise.resolve(captured);
+            }
+        }
+        return new Promise((resolve, reject) => {
+            const expectation = {
+                matcher,
+                resolve: (iq) => {
+                    this.pendingIqExpectations.delete(expectation);
+                    clearTimeout(expectation.timer);
+                    resolve(iq);
+                },
+                reject: (error) => {
+                    this.pendingIqExpectations.delete(expectation);
+                    clearTimeout(expectation.timer);
+                    reject(error);
+                },
+                timer: setTimeout(() => {
+                    this.pendingIqExpectations.delete(expectation);
+                    reject(new Error(`expectIq timed out after ${timeoutMs}ms (${describeMatcher(matcher)})`));
+                }, timeoutMs)
+            };
+            this.pendingIqExpectations.add(expectation);
+        });
+    }
+    capturedStanzaSnapshot() {
+        return this.capturedStanzas.slice();
+    }
+    /**
+     * Subscribes to every stanza captured from the client side (the lib).
+     * The listener is called synchronously for each new stanza as it
+     * arrives, in addition to `capturedStanzas` being appended. Returns
+     * an unsubscribe function. Useful for benches that need to count or
+     * react to a stream of receipts/messages without paying the O(N²)
+     * cost of polling `capturedStanzaSnapshot()` or queuing one
+     * `expectStanza(...)` per iteration.
+     */
+    onCapturedStanza(listener) {
+        this.capturedStanzaListeners.add(listener);
+        return () => {
+            this.capturedStanzaListeners.delete(listener);
+        };
+    }
+    expectStanza(matcher, options = {}) {
+        const timeoutMs = options.timeoutMs ?? 2000;
+        for (const captured of this.capturedStanzas) {
+            if (matchesStanza(captured, matcher)) {
+                return Promise.resolve(captured);
+            }
+        }
+        return new Promise((resolve, reject) => {
+            const expectation = {
+                matcher,
+                resolve: (node) => {
+                    this.pendingStanzaExpectations.delete(expectation);
+                    clearTimeout(expectation.timer);
+                    resolve(node);
+                },
+                reject: (error) => {
+                    this.pendingStanzaExpectations.delete(expectation);
+                    clearTimeout(expectation.timer);
+                    reject(error);
+                },
+                timer: setTimeout(() => {
+                    this.pendingStanzaExpectations.delete(expectation);
+                    reject(new Error(`expectStanza timed out after ${timeoutMs}ms (${describeStanzaMatcher(matcher)})`));
+                }, timeoutMs)
+            };
+            this.pendingStanzaExpectations.add(expectation);
+        });
+    }
+    async broadcastStanza(node) {
+        const tasks = [];
+        for (const pipeline of this.pipelines) {
+            tasks.push(pipeline.sendStanza(node).catch(() => undefined));
+        }
+        await Promise.all(tasks);
+        return tasks.length;
+    }
+    waitForAuthenticatedPipeline(timeoutMs = 60000) {
+        for (const pipeline of this.pipelines) {
+            if (pipeline.isAuthenticated()) {
+                return Promise.resolve(pipeline);
+            }
+        }
+        return this.waitForNextAuthenticatedPipeline(timeoutMs);
+    }
+    waitForNextAuthenticatedPipeline(timeoutMs = 60000) {
+        return new Promise((resolve, reject) => {
+            const timer = setTimeout(() => reject(new Error(`waitForNextAuthenticatedPipeline timed out after ${timeoutMs}ms`)), timeoutMs);
+            const unregister = this.onAuthenticatedPipeline((pipeline) => {
+                clearTimeout(timer);
+                unregister();
+                resolve(pipeline);
+            });
+        });
+    }
+    async publishMediaBlob(input) {
+        return this.mediaStore.publish(input);
+    }
+    mediaUrl(path) {
+        const info = this.requireMediaHttpsInfo();
+        const normalized = path.startsWith('/') ? path : `/${path}`;
+        return `https://${info.host}:${info.port}${normalized}`;
+    }
+    requireMediaHttpsInfo() {
+        const info = this.mediaHttpsServer.info;
+        if (!info) {
+            throw new Error('fake media https server is not listening');
+        }
+        return info;
+    }
+    get mediaProxyAgent() {
+        if (!this.cachedMediaProxyAgent) {
+            // keepAlive is required for representative perf measurements
+            // and matches what real-world WhatsApp clients do – every
+            // media upload/download would otherwise pay a full TLS
+            // handshake. The `src/media/__tests__/media.test.ts` fixtures
+            // and a production-quality `proxy.mediaUpload` configuration
+            // all set this; mirroring it here keeps benches in line.
+            this.cachedMediaProxyAgent = new HttpsAgent({
+                rejectUnauthorized: false,
+                keepAlive: true
+            });
+        }
+        return this.cachedMediaProxyAgent;
+    }
+    capturedMediaUploadSnapshot() {
+        return this.capturedMediaUploads.slice();
+    }
+    async createFakePeer(options, pipeline) {
+        const peer = await FakePeer.create(options, this.buildFakePeerDeps(pipeline));
+        this.registries.registerPeer(peer);
+        return peer;
+    }
+    async createFakePeerWithDevices(input, pipeline) {
+        if (input.deviceIds.length === 0) {
+            throw new Error('createFakePeerWithDevices requires at least one deviceId');
+        }
+        const atIdx = input.userJid.indexOf('@');
+        if (atIdx < 0) {
+            throw new Error(`invalid userJid ${input.userJid}`);
+        }
+        const userPart = input.userJid.slice(0, atIdx);
+        const server = input.userJid.slice(atIdx + 1);
+        const peers = [];
+        for (const deviceId of input.deviceIds) {
+            const deviceJid = deviceId === 0 ? input.userJid : `${userPart}:${deviceId}@${server}`;
+            const peer = await FakePeer.create({
+                jid: deviceJid,
+                displayName: input.displayName,
+                skipOneTimePreKey: input.skipOneTimePreKey
+            }, this.buildFakePeerDeps(pipeline));
+            this.registries.registerPeer(peer);
+            peers.push(peer);
+        }
+        return peers;
+    }
+    buildFakePeerDeps(pipeline) {
+        return {
+            bundleResolver: () => this.preKeyDispenser.awaitPreKeyBundle(),
+            reserveOneTimePreKey: () => this.preKeyDispenser.dispenseOneTimePreKey(),
+            pushStanza: (stanza) => pipeline.sendStanza(stanza),
+            subscribeInboundMessages: (listener) => {
+                const wrapped = (node) => {
+                    if (node.tag !== 'message')
+                        return;
+                    listener(node);
+                };
+                this.inboundStanzaListeners.add(wrapped);
+                return () => {
+                    this.inboundStanzaListeners.delete(wrapped);
+                };
+            }
+        };
+    }
+    async runPairing(pipeline, options, companionMaterialResolver) {
+        const driver = new FakePairingDriver(options, {
+            pipeline,
+            companionMaterialResolver,
+            waitForPairDeviceAck: async (pairDeviceIqId) => {
+                await this.expectIq({
+                    id: pairDeviceIqId
+                }, {
+                    timeoutMs: 15000
+                });
+            }
+        });
+        await driver.run();
+    }
+    setRejectMode(info) {
+        if (info === null) {
+            this.rejectMode = null;
+            return;
+        }
+        this.rejectMode = {
+            code: info.code ?? 1011,
+            reason: info.reason ?? 'fake-server reject mode'
+        };
+    }
+    static async start(options = {}) {
+        const server = new FakeWaServer(options);
+        await server.listen();
+        return server;
+    }
+    get url() {
+        return this.requireListening().url;
+    }
+    get host() {
+        return this.requireListening().host;
+    }
+    get port() {
+        return this.requireListening().port;
+    }
+    get noiseRootCa() {
+        const root = this.requireRootCa();
+        return { publicKey: root.publicKey, serial: root.serial };
+    }
+    onPipeline(listener) {
+        this.pipelineListener = listener;
+    }
+    async listen() {
+        if (this.listenInfo) {
+            return;
+        }
+        ;
+        [this.rootCa, this.serverStaticKeyPair] = await Promise.all([
+            generateFakeNoiseRootCa(),
+            X25519.generateKeyPair()
+        ]);
+        const mediaHandler = this.buildMediaRequestHandler();
+        this.wsServer.setHttpRequestHandler(mediaHandler);
+        this.mediaHttpsServer.setRequestHandler(mediaHandler);
+        this.listenInfo = await this.wsServer.listen();
+        await this.mediaHttpsServer.listen('127.0.0.1');
+    }
+    async stop() {
+        this.pipelines.clear();
+        await this.wsServer.close();
+        await this.mediaHttpsServer.close();
+        if (this.cachedMediaProxyAgent) {
+            this.cachedMediaProxyAgent.destroy();
+            this.cachedMediaProxyAgent = null;
+        }
+        this.listenInfo = null;
+        this.rootCa = null;
+        this.serverStaticKeyPair = null;
+    }
+    handleConnection(connection) {
+        if (this.rejectMode) {
+            connection.close(this.rejectMode.code, this.rejectMode.reason);
+            return;
+        }
+        if (!this.rootCa || !this.serverStaticKeyPair) {
+            connection.close(1011, 'fake server not initialized');
+            return;
+        }
+        const pipeline = new WaFakeConnectionPipeline({
+            connection,
+            rootCa: this.rootCa,
+            serverStaticKeyPair: this.serverStaticKeyPair,
+            iqRouter: this.iqRouter
+        });
+        this.pipelines.add(pipeline);
+        pipeline.setEvents({
+            onAuthenticated: () => {
+                for (const listener of this.authenticatedListeners) {
+                    void listener(pipeline);
+                }
+            },
+            onStanza: (node) => this.handleCapturedStanza(node),
+            onClose: () => this.pipelines.delete(pipeline)
+        });
+        this.pipelineListener?.(pipeline);
+    }
+    handleCapturedStanza(node) {
+        this.capturedStanzas.push(node);
+        for (const listener of this.capturedStanzaListeners) {
+            try {
+                listener(node);
+            }
+            catch (error) {
+                void error;
+            }
+        }
+        for (const listener of this.inboundStanzaListeners) {
+            try {
+                listener(node);
+            }
+            catch (error) {
+                void error;
+            }
+        }
+        for (const expectation of this.pendingStanzaExpectations) {
+            if (matchesStanza(node, expectation.matcher)) {
+                expectation.resolve(node);
+                break;
+            }
+        }
+        if (node.tag !== 'iq') {
+            return;
+        }
+        for (const expectation of this.pendingIqExpectations) {
+            if (matchesIq(node, expectation.matcher)) {
+                expectation.resolve(node);
+                return;
+            }
+        }
+    }
+    buildMediaRequestHandler() {
+        return (req, res) => {
+            const rawUrl = req.url ?? '';
+            const [path, query] = rawUrl.split('?');
+            const method = (req.method ?? 'GET').toUpperCase();
+            if (method === 'POST') {
+                this.handleMediaUpload(req, res, path, query);
+                return;
+            }
+            const blob = this.mediaStore.get(path);
+            if (!blob) {
+                res.statusCode = 404;
+                res.end();
+                return;
+            }
+            res.statusCode = 200;
+            res.setHeader('content-type', 'application/octet-stream');
+            res.setHeader('content-length', String(blob.encryptedBytes.byteLength));
+            res.end(Buffer.from(blob.encryptedBytes));
+        };
+    }
+    handleMediaUpload(req, res, path, query) {
+        const chunks = [];
+        req.on('data', (chunk) => {
+            chunks.push(chunk);
+        });
+        req.on('end', () => {
+            const encryptedBytes = new Uint8Array(Buffer.concat(chunks));
+            const segments = path.split('/').filter(Boolean);
+            const mediaType = segments[1] ?? 'unknown';
+            const auth = parseQueryParam(query, 'auth');
+            const upload = {
+                path,
+                mediaType,
+                encryptedBytes,
+                contentType: req.headers['content-type'],
+                auth,
+                receivedAtMs: Date.now()
+            };
+            this.capturedMediaUploads.push(upload);
+            this.mediaStore.setRaw(path, encryptedBytes, mediaType);
+            this.nextUploadCounter += 1;
+            const downloadUrl = this.mediaUrl(path);
+            const responseBody = JSON.stringify({
+                url: downloadUrl,
+                direct_path: path
+            });
+            res.statusCode = 200;
+            res.setHeader('content-type', 'application/json');
+            res.setHeader('content-length', String(Buffer.byteLength(responseBody)));
+            res.end(responseBody);
+        });
+        req.on('error', (error) => {
+            if (!res.headersSent) {
+                res.statusCode = 500;
+            }
+            res.end(error.message);
+        });
+    }
+    requireListening() {
+        if (!this.listenInfo) {
+            throw new Error('fake server is not listening');
+        }
+        return this.listenInfo;
+    }
+    requireRootCa() {
+        if (!this.rootCa) {
+            throw new Error('fake server is not listening');
+        }
+        return this.rootCa;
+    }
+}
+function parseQueryParam(query, name) {
+    if (!query)
+        return undefined;
+    for (const pair of query.split('&')) {
+        const eq = pair.indexOf('=');
+        if (eq < 0)
+            continue;
+        const key = decodeURIComponent(pair.slice(0, eq));
+        if (key !== name)
+            continue;
+        return decodeURIComponent(pair.slice(eq + 1));
+    }
+    return undefined;
+}
+function matchesIq(iq, matcher) {
+    if (iq.tag !== 'iq')
+        return false;
+    if (matcher.id !== undefined && iq.attrs.id !== matcher.id)
+        return false;
+    if (matcher.type !== undefined && iq.attrs.type !== matcher.type)
+        return false;
+    if (matcher.xmlns !== undefined && iq.attrs.xmlns !== matcher.xmlns)
+        return false;
+    if (matcher.childTag !== undefined) {
+        const children = Array.isArray(iq.content) ? iq.content : null;
+        if (!children || children.length === 0)
+            return false;
+        if (children[0].tag !== matcher.childTag)
+            return false;
+    }
+    return true;
+}
+function describeMatcher(matcher) {
+    const parts = [];
+    if (matcher.id !== undefined)
+        parts.push(`id=${matcher.id}`);
+    if (matcher.type !== undefined)
+        parts.push(`type=${matcher.type}`);
+    if (matcher.xmlns !== undefined)
+        parts.push(`xmlns=${matcher.xmlns}`);
+    if (matcher.childTag !== undefined)
+        parts.push(`childTag=${matcher.childTag}`);
+    return parts.length > 0 ? parts.join(', ') : 'any iq';
+}
+function matchesStanza(node, matcher) {
+    if (matcher.tag !== undefined && node.tag !== matcher.tag)
+        return false;
+    if (matcher.type !== undefined && node.attrs.type !== matcher.type)
+        return false;
+    if (matcher.xmlns !== undefined && node.attrs.xmlns !== matcher.xmlns)
+        return false;
+    if (matcher.from !== undefined && node.attrs.from !== matcher.from)
+        return false;
+    if (matcher.to !== undefined && node.attrs.to !== matcher.to)
+        return false;
+    if (matcher.childTag !== undefined) {
+        const children = Array.isArray(node.content) ? node.content : null;
+        if (!children || children.length === 0)
+            return false;
+        if (children[0].tag !== matcher.childTag)
+            return false;
+    }
+    return true;
+}
+function describeStanzaMatcher(matcher) {
+    const parts = [];
+    if (matcher.tag !== undefined)
+        parts.push(`tag=${matcher.tag}`);
+    if (matcher.type !== undefined)
+        parts.push(`type=${matcher.type}`);
+    if (matcher.xmlns !== undefined)
+        parts.push(`xmlns=${matcher.xmlns}`);
+    if (matcher.from !== undefined)
+        parts.push(`from=${matcher.from}`);
+    if (matcher.to !== undefined)
+        parts.push(`to=${matcher.to}`);
+    if (matcher.childTag !== undefined)
+        parts.push(`childTag=${matcher.childTag}`);
+    return parts.length > 0 ? parts.join(', ') : 'any stanza';
+}