trac-msb 0.2.26 → 0.3.0-beta.1

package/src/core/network/protocols/consensus/IndexerMessages.js

@@ -0,0 +1,72 @@
+import Protomux from 'protomux';
+import _ from 'lodash';
+import ConsensusV1MessageRouter from "./v1/ConsensusV1MessageRouter.js";
+import ConsensusV1Protocol from "./v1/ConsensusV1Protocol.js";
+import ConsensusV1ConnectionPolicy from './v1/ConsensusV1ConnectionPolicy.js';
+import { Logger } from '../../../../utils/logger.js';
+
+const PROTOCOL = 'consensus/v1';
+
+class IndexerMessages {
+    #consensusRouter;
+    #pendingRequestService;
+    #onSessionClosed;
+    #connectionPolicy;
+
+    constructor(state, wallet, config, pendingRequestService, onSessionClosed, appenderSelector = null) {
+        this.#pendingRequestService = pendingRequestService;
+        this.#onSessionClosed = onSessionClosed;
+        const logger = new Logger(config);
+        this.#connectionPolicy = new ConsensusV1ConnectionPolicy(state, logger, config);
+        this.#consensusRouter = new ConsensusV1MessageRouter(
+            state, wallet, config, pendingRequestService, this.#connectionPolicy, appenderSelector
+        );
+    }
+
+    createProtocolSession(connection) {
+        return new ConsensusV1Protocol(
+            this.#consensusRouter,
+            connection,
+            this.#pendingRequestService,
+            session => {
+                if (connection.protocolSessions?.indexer !== session) return;
+                delete connection.protocolSessions.indexer;
+                this.#onSessionClosed(connection);
+            },
+            this.#connectionPolicy
+        );
+    }
+
+    /**
+     * Opens the consensus/v1 channel only for a peer recognized as an indexer.
+     * The close callback removes the session reference so a new channel can open.
+     */
+    async attachChannel(connection) {
+        if (connection.destroyed) return;
+        if (_.isNil(connection.protocolSessions)) {
+            connection.protocolSessions = {};
+        }
+        if (connection.protocolSessions.indexer) return;
+        try {
+            if (!await this.#connectionPolicy.shouldAcceptConsensusChannel(connection)) return;
+            // The connection may close or another attempt may create the session while awaiting state.
+            if (connection.destroyed || connection.protocolSessions.indexer) return;
+            const session = this.createProtocolSession(connection);
+            if (!session.closed) connection.protocolSessions.indexer = session;
+        } catch (error) {
+            // A rejected Protomux pairing callback would destroy the shared transport.
+            this.#connectionPolicy.handleLocalError(`IndexerMessages: failed to open Consensus V1 channel: ${error.message}`);
+        }
+    }
+
+    /**
+     * Applies the same admission check to remote opens. Returning without creating
+     * a session rejects only this channel attempt. Replication and later retries remain possible.
+     */
+    prepareConnection(connection) {
+        const mux = Protomux.from(connection);
+        mux.pair({ protocol: PROTOCOL }, () => this.attachChannel(connection));
+    }
+}
+
+export default IndexerMessages;

package/src/core/network/protocols/consensus/v1/ConsensusV1ConnectionPolicy.js

@@ -0,0 +1,57 @@
+import { ConsensusResultCode, CustomEventType } from '../../../../../utils/constants.js';
+import { publicKeyToAddress } from '../../../../../utils/helpers.js';
+import { V1ConsensusProtocolError } from './V1ConsensusProtocolError.js';
+
+class ConsensusV1ConnectionPolicy {
+    #state;
+    #logger;
+    #config;
+
+    constructor(state, logger, config) {
+        this.#state = state;
+        this.#logger = logger;
+        this.#config = config;
+    }
+
+    async shouldAcceptConsensusChannel(connection) {
+        try {
+            const address = publicKeyToAddress(connection.remotePublicKey, this.#config);
+            // Waiting for replication inside Protomux pairing can block the shared stream.
+            return await this.#state.isIndexerAddress(address, { wait: false, update: false });
+        } catch (error) {
+            this.handleLocalError(`ConsensusV1ConnectionPolicy: failed to check indexer membership: ${error.message}`);
+            return false;
+        }
+    }
+
+    // Remote rejections are returned as results, not local validation errors.
+    // Returns true when a ban was requested, so the handler skips the response.
+    requestPeerBan(connection, error) {
+        if (!(error instanceof V1ConsensusProtocolError)) return false;
+        if (error.resultCode !== ConsensusResultCode.PUBLIC_KEY_MISMATCH) return false;
+
+        this.#state.emit(CustomEventType.CONSENSUS_PEER_BAN_REQUESTED, { connection, error });
+        return true;
+    }
+
+    // Expired requests and responses from an older session do not penalize the peer.
+    shouldIgnoreApproval(pendingEntry, protocolSession) {
+        if (!pendingEntry) return true;
+        if (!pendingEntry.session) return false;
+        return pendingEntry.session !== protocolSession;
+    }
+
+    // Invalid frames, message types, session IDs and unexpected senders close only consensus.
+    // Proposal payload rejections use signed responses rather than this routing policy.
+    handleInvalidMessage(protocolSession, reason) {
+        this.#logger.error(reason);
+        protocolSession.close();
+    }
+
+    // Local failures provide no grounds to close a peer's channel or transport.
+    handleLocalError(reason) {
+        this.#logger.error(reason);
+    }
+}
+
+export default ConsensusV1ConnectionPolicy;

package/src/core/network/protocols/consensus/v1/ConsensusV1MessageRouter.js

@@ -0,0 +1,147 @@
+import { decodeConsensusMessage } from '../../../../../codecs/consensus/v1/consensusV1OperationCodec.js'
+import b4a from 'b4a'
+import { ConsensusOperationType, ConsensusResultCode, CONSENSUS_MESSAGE_MAX_BYTE_SIZE } from '../../../../../utils/constants.js'
+import { publicKeyToAddress } from '../../../../../utils/helpers.js'
+import V1EpochProofProposalOperationHandler from './handlers/V1EpochProofProposalOperationHandler.js'
+import V1EpochAppendOperationHandler from './handlers/V1EpochAppendOperationHandler.js';
+import { V1ConsensusProtocolError } from './V1ConsensusProtocolError.js';
+
+class ConsensusV1MessageRouter {
+    #config
+    #connectionPolicy
+    #epochProofProposalHandler
+    #pendingRequestService
+    #appendHandler;
+    constructor(
+        state,
+        wallet,
+        config,
+        pendingRequestService,
+        connectionPolicy,
+        appenderSelector = null
+    ) {
+        this.#config = config
+        this.#connectionPolicy = connectionPolicy;
+        this.#epochProofProposalHandler = new V1EpochProofProposalOperationHandler(
+            state,
+            wallet,
+            config,
+            connectionPolicy
+        );
+        this.#pendingRequestService = pendingRequestService;
+        this.#appendHandler = new V1EpochAppendOperationHandler(state, wallet, config, appenderSelector);
+    }
+
+    async route(incomingMessage, connection, protocolSession) {
+        if (protocolSession.closed) return;
+
+        if (!this.#preValidate(incomingMessage)) {
+            this.#handleInvalidMessage(connection, protocolSession, 'Pre-validation failed for incoming Consensus V1 message')
+            return;
+        }
+        let decodedMessage;
+
+        try {
+            decodedMessage = decodeConsensusMessage(incomingMessage)
+        } catch (error) {
+            this.#handleInvalidMessage(connection, protocolSession, `Failed to decode incoming Consensus V1 message: ${error.message}`)
+            return;
+        }
+
+        // again in the next switch statement
+        if (!decodedMessage || !Number.isInteger(decodedMessage.type) || decodedMessage.type <= 0) {
+            this.#handleInvalidMessage(connection, protocolSession, `Invalid Consensus V1 message type: ${decodedMessage?.type}`)
+            return;
+        }
+
+        let pendingRequest;
+        try {
+            switch (decodedMessage.type) {
+                case ConsensusOperationType.REQUEST:
+                    await this.#appendHandler.handleRequest(decodedMessage, connection, protocolSession);
+                    break;
+                case ConsensusOperationType.REPLY: {
+                    const entry = this.#pendingRequestService.getPendingRequest(decodedMessage.session_id);
+                    if (
+                        !entry || entry.requestType !== ConsensusOperationType.REQUEST ||
+                        entry.session !== protocolSession ||
+                        entry.requestedTo !== b4a.toString(connection.remotePublicKey, 'hex')
+                    ) {
+                        break;
+                    }
+                    pendingRequest = entry;
+                    const response = await this.#appendHandler.handleReply(
+                        decodedMessage,
+                        connection,
+                        protocolSession,
+                        entry.appendRequest
+                    );
+                    if (
+                        response && !protocolSession.closed &&
+                        this.#pendingRequestService.getPendingRequest(decodedMessage.session_id) === entry
+                    ) {
+                        this.#pendingRequestService.resolvePendingRequest(decodedMessage.session_id, response);
+                    }
+                    break;
+                }
+                case ConsensusOperationType.PROOF_PROPOSAL:
+                    await this.#epochProofProposalHandler.handleRequest(decodedMessage, connection, protocolSession);
+                    break;
+                case ConsensusOperationType.PROOF_PROPOSAL_APPROVAL: {
+                    const pendingEntry = this.#pendingRequestService.getPendingRequest(decodedMessage.session_id)
+                    if (pendingEntry && pendingEntry.requestType !== ConsensusOperationType.PROOF_PROPOSAL) break;
+                    const expectedPeer = pendingEntry?.requestedTo ? b4a.from(pendingEntry.requestedTo, 'hex') : null;
+                    if (expectedPeer && !b4a.equals(expectedPeer, connection.remotePublicKey)) {
+                        this.#handleInvalidMessage(connection, protocolSession, 'Consensus V1 message: approval received from unexpected peer')
+                        break;
+                    }
+                    if (this.#connectionPolicy.shouldIgnoreApproval(pendingEntry, protocolSession)) break;
+
+                    pendingRequest = pendingEntry;
+                    const response = await this.#epochProofProposalHandler.handleApproval(
+                        decodedMessage,
+                        connection,
+                        protocolSession,
+                        pendingEntry.proofProposal
+                    );
+                    // Validation may finish after this request was cancelled or replaced.
+                    if (this.#pendingRequestService.getPendingRequest(decodedMessage.session_id) === pendingEntry) {
+                        this.#pendingRequestService.resolvePendingRequest(decodedMessage.session_id, response);
+                    }
+                    break;
+                }
+                default:
+                    this.#handleInvalidMessage(connection, protocolSession, `Unsupported Consensus V1 message type: ${decodedMessage.type}`)
+            }
+        } catch (error) {
+            if (pendingRequest && this.#pendingRequestService.getPendingRequest(decodedMessage.session_id) === pendingRequest) {
+                this.#pendingRequestService.rejectPendingRequest(decodedMessage.session_id, error);
+            }
+            const isArbitrationMessage = decodedMessage.type === ConsensusOperationType.REQUEST ||
+                decodedMessage.type === ConsensusOperationType.REPLY;
+            if (isArbitrationMessage && this.#connectionPolicy.requestPeerBan(connection, error)) {
+                return;
+            }
+            if (isArbitrationMessage && error instanceof V1ConsensusProtocolError && error.resultCode === ConsensusResultCode.EPOCH_INVALID) {
+                return;
+            }
+            this.#logError(connection, `Unhandled error while routing Consensus V1 message: ${error.message}`)
+        }
+    }
+
+    #preValidate(incomingMessage) {
+        return !(!incomingMessage || !b4a.isBuffer(incomingMessage) || incomingMessage.length === 0 || incomingMessage.length > CONSENSUS_MESSAGE_MAX_BYTE_SIZE);
+    }
+
+    #handleInvalidMessage(connection, protocolSession, reason) {
+        const sender = publicKeyToAddress(connection.remotePublicKey, this.#config);
+        this.#connectionPolicy.handleInvalidMessage(protocolSession, `ConsensusV1MessageRouter: ${reason}, sender: ${sender}`);
+    }
+
+    #logError(connection, reason) {
+        const sender = publicKeyToAddress(connection.remotePublicKey, this.#config)
+        this.#connectionPolicy.handleLocalError(`ConsensusV1MessageRouter: ${reason}, sender: ${sender}`);
+    }
+}
+
+export default ConsensusV1MessageRouter

package/src/core/network/protocols/consensus/v1/ConsensusV1Protocol.js

@@ -0,0 +1,72 @@
+import Protomux from 'protomux';
+import c from 'compact-encoding';
+import { encodeConsensusMessage } from '../../../../../codecs/consensus/v1/consensusV1OperationCodec.js';
+
+class ConsensusV1Protocol {
+    #channel;
+    #session;
+    #router;
+    #pendingRequestService;
+    #publicKeyHex;
+    #connectionPolicy;
+
+    constructor(router, connection, pendingRequestService, onClose, connectionPolicy) {
+        this.#router = router;
+        this.#pendingRequestService = pendingRequestService;
+        this.#publicKeyHex =connection.remotePublicKey.toString('hex');
+        this.#connectionPolicy = connectionPolicy;
+        this.#init(connection, onClose);
+    }
+
+    get closed() {
+        return !this.#channel || this.#channel.closed;
+    }
+
+    #init(connection, onClose) {
+        const mux = Protomux.from(connection);
+
+        this.#channel = mux.createChannel({
+            protocol: 'consensus/v1',
+            onopen() {},
+            onclose: () => {
+                this.#pendingRequestService.rejectPendingRequestsForSession(this, new Error('Consensus session closed before response'));
+                onClose(this);
+            }
+        });
+
+        if (!this.#channel) return; // connection already destroyed before protocol setup completed
+
+        this.#session = this.#channel.addMessage({
+            encoding: c.raw,
+            onmessage: (incomingMessage) => {
+                this.#router.route(incomingMessage, connection, this).catch((err) => {
+                    this.#connectionPolicy.handleLocalError(`ConsensusV1Protocol: unhandled router error for Consensus V1 message, peer: ${this.#publicKeyHex}: ${err.message}`);
+                });
+            }
+        });
+        this.#channel.open();
+    }
+
+    async send(message) {
+        if (this.closed) throw new Error('Consensus session is closed');
+        const encodedMessage = encodeConsensusMessage(message);
+        const msgReplyPromise = this.#pendingRequestService.registerPendingRequest(this.#publicKeyHex, message, this);
+        try {
+            this.#session.send(encodedMessage);
+        } catch (error) {
+            this.#pendingRequestService.rejectPendingRequest(message.session_id, error);
+        }
+        return msgReplyPromise;
+    }
+
+    sendAndForget(message) {
+        if (this.closed) return;
+        this.#session?.send(encodeConsensusMessage(message));
+    }
+
+    close() {
+        this.#channel?.close();
+    }
+}
+
+export default ConsensusV1Protocol;

package/src/core/network/protocols/consensus/v1/IndexerPendingRequestService.js

@@ -0,0 +1,108 @@
+import {ConsensusOperationType, PEER_PUBLIC_KEY_HEX_LENGTH, ConsensusResultCode} from '../../../../../utils/constants.js';
+import {isHexString, publicKeyToAddress} from '../../../../../utils/helpers.js';
+import {V1ConsensusProtocolError} from "./V1ConsensusProtocolError.js";
+import BasePendingRequestService from '../../../shared/BasePendingRequestService.js';
+
+export class IndexerPendingRequestServiceTimeoutError extends Error {
+    constructor(requestId, peerAddress, timeoutMs) {
+        super(`Pending request ${requestId} to peer ${peerAddress} timed out after ${timeoutMs} ms.`);
+        this.name = this.constructor.name;
+    }
+}
+
+export default class IndexerPendingRequestService extends BasePendingRequestService {
+    #config;
+
+    constructor(config) {
+        super();
+        this.#config = config;
+    }
+
+    #validateRegisterInput(peerPubKeyHex, message) {
+        if (!isHexString(peerPubKeyHex) || peerPubKeyHex.length !== PEER_PUBLIC_KEY_HEX_LENGTH) {
+            throw new Error('Invalid peer public key. Expected 32-byte hex string.');
+        }
+
+        if (typeof message?.session_id !== 'string' || message?.session_id.length === 0) {
+            throw new Error('Pending request ID must be a non-empty string.');
+        }
+
+        if (message.type !== ConsensusOperationType.PROOF_PROPOSAL && message.type !== ConsensusOperationType.REQUEST) {
+            throw new Error('Unsupported pending request type');
+        }
+    }
+
+    /*
+    @returns {Promise}
+    */
+    registerPendingRequest(peerPubKeyHex, message, session = null) {
+        this.#validateRegisterInput(peerPubKeyHex, message);
+        const id = message.session_id;
+        const peerAddress = publicKeyToAddress(peerPubKeyHex, this.#config);
+        if (this._pendingRequests.size >= this.#config.maxPendingRequestsInPendingRequestsService) {
+            throw new Error('Maximum number of pending requests reached.');
+        }
+
+        if (this._pendingRequests.has(id)) {
+            throw new Error(`Pending request with ID ${id} from peer ${peerPubKeyHex} already exists.`);
+        }
+
+        const entry = {
+            id: id,
+            requestType: message.type,
+            requestedTo: peerPubKeyHex,
+            session,
+            proofProposal: message.proof_proposal,
+            timeoutId: null,
+            resolve: null,
+            reject: null,
+        };
+
+        if (message.type === ConsensusOperationType.REQUEST) {
+            entry.appendRequest = message;
+        }
+
+        const promise = new Promise((resolve, reject) => {
+            entry.resolve = resolve;
+            entry.reject = reject;
+        });
+
+        entry.timeoutId = setTimeout(() => {
+            this.rejectPendingRequest(
+                id,
+                new IndexerPendingRequestServiceTimeoutError(
+                    id,
+                    peerAddress,
+                    this.#config.indexerPendingRequestTimeout
+                )
+            );
+
+        }, this.#config.indexerPendingRequestTimeout);
+
+        this._pendingRequests.set(id, entry);
+        return promise;
+    }
+
+    /** Complete a proof approval or a validated arbitration reply. */
+    resolvePendingRequest(id, result = ConsensusResultCode.OK) {
+        const entry = this.getAndDeletePendingRequest(id);
+        if (!entry) return false;
+        entry.resolve(result);
+        return true;
+    }
+
+    _createShutdownError(id) {
+        return new V1ConsensusProtocolError(
+            ConsensusResultCode.UNEXPECTED_ERROR,
+            `Pending request ${id} cancelled (shutdown).`
+        );
+    }
+
+    rejectPendingRequestsForSession(session, error) {
+        for (const [id, entry] of this._pendingRequests) {
+            if (entry.session === session) {
+                this.rejectPendingRequest(id, error);
+            }
+        }
+    }
+}

package/src/core/network/protocols/consensus/v1/V1ConsensusProtocolError.js

@@ -0,0 +1,29 @@
+import {ConsensusResultCode} from '../../../../../utils/constants.js';
+
+/**
+ * V1 consensus protocol error type.
+ *
+ * `V1ConsensusProtocolError` is the v1 base class used by handlers/validators to attach:
+ * - `resultCode`: a stable `ConsensusResultCode` enum value for programmatic handling
+ */
+export class V1ConsensusProtocolError extends Error {
+    /**
+     * @param {number} resultCode Stable rejection reason (a `ConsensusResultCode` enum value).
+     * @param {string} message Human-readable error message.
+     */
+    constructor(resultCode, message) {
+        super(message);
+        this.name = this.constructor.name;
+        this.resultCode = resultCode;
+    }
+}
+
+/**
+ * Returns the consensus result code attached to a protocol error.
+ *
+ * @param {unknown} err Error-like value to inspect.
+ * @returns {number} Attached `ConsensusResultCode`, or `ConsensusResultCode.UNEXPECTED_ERROR`.
+ */
+export function getResultCode(err) {
+    return err instanceof V1ConsensusProtocolError ? err.resultCode : ConsensusResultCode.UNEXPECTED_ERROR;
+}

package/src/core/network/protocols/consensus/v1/handlers/V1EpochAppendOperationHandler.js

@@ -0,0 +1,68 @@
+import V1EpochAppendRequest from '../validators/V1EpochAppendRequest.js';
+import V1EpochAppendReply from '../validators/V1EpochAppendReply.js';
+import { consensusMessageFactory } from '../../../../../../messages/consensus/v1/consensusMessageFactory.js';
+import { sameSelectionContext } from '../../../../../consensus/epochAppenderSelection/epochAppenderSelectionState.js';
+
+export default class V1EpochAppendOperationHandler {
+    #state;
+    #wallet;
+    #config;
+    #selector;
+    #requestValidator;
+    #replyValidator;
+
+    constructor(state, wallet, config, selector) {
+        this.#state = state;
+        this.#wallet = wallet;
+        this.#config = config;
+        this.#selector = selector;
+        this.#requestValidator = new V1EpochAppendRequest(config, state);
+        this.#replyValidator = new V1EpochAppendReply(config, state);
+    }
+
+    /** Validate REQUEST before arbitration; the selector may defer its reply. */
+    async handleRequest(message, connection, session) {
+        if (!this.#selector || session.closed) {
+            return;
+        }
+        const request = await this.#requestValidator.validate(message, connection);
+        if (session.closed) {
+            return;
+        }
+        await this.#selector.refreshAppendOutcome();
+        if (!await this.#canReply(request, session)) {
+            return;
+        }
+        await this.#selector.handleSelectionRequest(request, response => {
+            return this.#sendReply(message.session_id, response, session);
+        });
+    }
+
+    async #canReply(request, session) {
+        if (session.closed) {
+            return false;
+        }
+        const context = await this.#state.getEpochAppenderSelectionContext();
+        return !session.closed && sameSelectionContext(request, context);
+    }
+
+    async #sendReply(sessionId, request, session) {
+        if (session.closed) {
+            return;
+        }
+        const reply = await consensusMessageFactory(this.#wallet, this.#config).buildReply(sessionId, request);
+        // Deferred replies can outlive both their epoch and their Protomux session.
+        if (await this.#canReply(request, session)) {
+            session.sendAndForget(reply);
+        }
+    }
+
+    /** @returns {Promise<object|null>} Validated request identity, or null after context/session expiry. */
+    async handleReply(message, connection, session, pendingRequest) {
+        const request = await this.#replyValidator.validate(message, connection, pendingRequest);
+        if (!await this.#canReply(request, session)) {
+            return null;
+        }
+        return request;
+    }
+}