@aztec-labs/p2p 6.0.0-nightly.20260829

package/dest/services/reqresp/reqresp.js

@@ -0,0 +1,887 @@
+// @attribution: lodestar impl for inspiration
+function applyDecs2203RFactory() {
+    function createAddInitializerMethod(initializers, decoratorFinishedRef) {
+        return function addInitializer(initializer) {
+            assertNotFinished(decoratorFinishedRef, "addInitializer");
+            assertCallable(initializer, "An initializer");
+            initializers.push(initializer);
+        };
+    }
+    function memberDec(dec, name, desc, initializers, kind, isStatic, isPrivate, metadata, value) {
+        var kindStr;
+        switch(kind){
+            case 1:
+                kindStr = "accessor";
+                break;
+            case 2:
+                kindStr = "method";
+                break;
+            case 3:
+                kindStr = "getter";
+                break;
+            case 4:
+                kindStr = "setter";
+                break;
+            default:
+                kindStr = "field";
+        }
+        var ctx = {
+            kind: kindStr,
+            name: isPrivate ? "#" + name : name,
+            static: isStatic,
+            private: isPrivate,
+            metadata: metadata
+        };
+        var decoratorFinishedRef = {
+            v: false
+        };
+        ctx.addInitializer = createAddInitializerMethod(initializers, decoratorFinishedRef);
+        var get, set;
+        if (kind === 0) {
+            if (isPrivate) {
+                get = desc.get;
+                set = desc.set;
+            } else {
+                get = function() {
+                    return this[name];
+                };
+                set = function(v) {
+                    this[name] = v;
+                };
+            }
+        } else if (kind === 2) {
+            get = function() {
+                return desc.value;
+            };
+        } else {
+            if (kind === 1 || kind === 3) {
+                get = function() {
+                    return desc.get.call(this);
+                };
+            }
+            if (kind === 1 || kind === 4) {
+                set = function(v) {
+                    desc.set.call(this, v);
+                };
+            }
+        }
+        ctx.access = get && set ? {
+            get: get,
+            set: set
+        } : get ? {
+            get: get
+        } : {
+            set: set
+        };
+        try {
+            return dec(value, ctx);
+        } finally{
+            decoratorFinishedRef.v = true;
+        }
+    }
+    function assertNotFinished(decoratorFinishedRef, fnName) {
+        if (decoratorFinishedRef.v) {
+            throw new Error("attempted to call " + fnName + " after decoration was finished");
+        }
+    }
+    function assertCallable(fn, hint) {
+        if (typeof fn !== "function") {
+            throw new TypeError(hint + " must be a function");
+        }
+    }
+    function assertValidReturnValue(kind, value) {
+        var type = typeof value;
+        if (kind === 1) {
+            if (type !== "object" || value === null) {
+                throw new TypeError("accessor decorators must return an object with get, set, or init properties or void 0");
+            }
+            if (value.get !== undefined) {
+                assertCallable(value.get, "accessor.get");
+            }
+            if (value.set !== undefined) {
+                assertCallable(value.set, "accessor.set");
+            }
+            if (value.init !== undefined) {
+                assertCallable(value.init, "accessor.init");
+            }
+        } else if (type !== "function") {
+            var hint;
+            if (kind === 0) {
+                hint = "field";
+            } else if (kind === 10) {
+                hint = "class";
+            } else {
+                hint = "method";
+            }
+            throw new TypeError(hint + " decorators must return a function or void 0");
+        }
+    }
+    function applyMemberDec(ret, base, decInfo, name, kind, isStatic, isPrivate, initializers, metadata) {
+        var decs = decInfo[0];
+        var desc, init, value;
+        if (isPrivate) {
+            if (kind === 0 || kind === 1) {
+                desc = {
+                    get: decInfo[3],
+                    set: decInfo[4]
+                };
+            } else if (kind === 3) {
+                desc = {
+                    get: decInfo[3]
+                };
+            } else if (kind === 4) {
+                desc = {
+                    set: decInfo[3]
+                };
+            } else {
+                desc = {
+                    value: decInfo[3]
+                };
+            }
+        } else if (kind !== 0) {
+            desc = Object.getOwnPropertyDescriptor(base, name);
+        }
+        if (kind === 1) {
+            value = {
+                get: desc.get,
+                set: desc.set
+            };
+        } else if (kind === 2) {
+            value = desc.value;
+        } else if (kind === 3) {
+            value = desc.get;
+        } else if (kind === 4) {
+            value = desc.set;
+        }
+        var newValue, get, set;
+        if (typeof decs === "function") {
+            newValue = memberDec(decs, name, desc, initializers, kind, isStatic, isPrivate, metadata, value);
+            if (newValue !== void 0) {
+                assertValidReturnValue(kind, newValue);
+                if (kind === 0) {
+                    init = newValue;
+                } else if (kind === 1) {
+                    init = newValue.init;
+                    get = newValue.get || value.get;
+                    set = newValue.set || value.set;
+                    value = {
+                        get: get,
+                        set: set
+                    };
+                } else {
+                    value = newValue;
+                }
+            }
+        } else {
+            for(var i = decs.length - 1; i >= 0; i--){
+                var dec = decs[i];
+                newValue = memberDec(dec, name, desc, initializers, kind, isStatic, isPrivate, metadata, value);
+                if (newValue !== void 0) {
+                    assertValidReturnValue(kind, newValue);
+                    var newInit;
+                    if (kind === 0) {
+                        newInit = newValue;
+                    } else if (kind === 1) {
+                        newInit = newValue.init;
+                        get = newValue.get || value.get;
+                        set = newValue.set || value.set;
+                        value = {
+                            get: get,
+                            set: set
+                        };
+                    } else {
+                        value = newValue;
+                    }
+                    if (newInit !== void 0) {
+                        if (init === void 0) {
+                            init = newInit;
+                        } else if (typeof init === "function") {
+                            init = [
+                                init,
+                                newInit
+                            ];
+                        } else {
+                            init.push(newInit);
+                        }
+                    }
+                }
+            }
+        }
+        if (kind === 0 || kind === 1) {
+            if (init === void 0) {
+                init = function(instance, init) {
+                    return init;
+                };
+            } else if (typeof init !== "function") {
+                var ownInitializers = init;
+                init = function(instance, init) {
+                    var value = init;
+                    for(var i = 0; i < ownInitializers.length; i++){
+                        value = ownInitializers[i].call(instance, value);
+                    }
+                    return value;
+                };
+            } else {
+                var originalInitializer = init;
+                init = function(instance, init) {
+                    return originalInitializer.call(instance, init);
+                };
+            }
+            ret.push(init);
+        }
+        if (kind !== 0) {
+            if (kind === 1) {
+                desc.get = value.get;
+                desc.set = value.set;
+            } else if (kind === 2) {
+                desc.value = value;
+            } else if (kind === 3) {
+                desc.get = value;
+            } else if (kind === 4) {
+                desc.set = value;
+            }
+            if (isPrivate) {
+                if (kind === 1) {
+                    ret.push(function(instance, args) {
+                        return value.get.call(instance, args);
+                    });
+                    ret.push(function(instance, args) {
+                        return value.set.call(instance, args);
+                    });
+                } else if (kind === 2) {
+                    ret.push(value);
+                } else {
+                    ret.push(function(instance, args) {
+                        return value.call(instance, args);
+                    });
+                }
+            } else {
+                Object.defineProperty(base, name, desc);
+            }
+        }
+    }
+    function applyMemberDecs(Class, decInfos, metadata) {
+        var ret = [];
+        var protoInitializers;
+        var staticInitializers;
+        var existingProtoNonFields = new Map();
+        var existingStaticNonFields = new Map();
+        for(var i = 0; i < decInfos.length; i++){
+            var decInfo = decInfos[i];
+            if (!Array.isArray(decInfo)) continue;
+            var kind = decInfo[1];
+            var name = decInfo[2];
+            var isPrivate = decInfo.length > 3;
+            var isStatic = kind >= 5;
+            var base;
+            var initializers;
+            if (isStatic) {
+                base = Class;
+                kind = kind - 5;
+                staticInitializers = staticInitializers || [];
+                initializers = staticInitializers;
+            } else {
+                base = Class.prototype;
+                protoInitializers = protoInitializers || [];
+                initializers = protoInitializers;
+            }
+            if (kind !== 0 && !isPrivate) {
+                var existingNonFields = isStatic ? existingStaticNonFields : existingProtoNonFields;
+                var existingKind = existingNonFields.get(name) || 0;
+                if (existingKind === true || existingKind === 3 && kind !== 4 || existingKind === 4 && kind !== 3) {
+                    throw new Error("Attempted to decorate a public method/accessor that has the same name as a previously decorated public method/accessor. This is not currently supported by the decorators plugin. Property name was: " + name);
+                } else if (!existingKind && kind > 2) {
+                    existingNonFields.set(name, kind);
+                } else {
+                    existingNonFields.set(name, true);
+                }
+            }
+            applyMemberDec(ret, base, decInfo, name, kind, isStatic, isPrivate, initializers, metadata);
+        }
+        pushInitializers(ret, protoInitializers);
+        pushInitializers(ret, staticInitializers);
+        return ret;
+    }
+    function pushInitializers(ret, initializers) {
+        if (initializers) {
+            ret.push(function(instance) {
+                for(var i = 0; i < initializers.length; i++){
+                    initializers[i].call(instance);
+                }
+                return instance;
+            });
+        }
+    }
+    function applyClassDecs(targetClass, classDecs, metadata) {
+        if (classDecs.length > 0) {
+            var initializers = [];
+            var newClass = targetClass;
+            var name = targetClass.name;
+            for(var i = classDecs.length - 1; i >= 0; i--){
+                var decoratorFinishedRef = {
+                    v: false
+                };
+                try {
+                    var nextNewClass = classDecs[i](newClass, {
+                        kind: "class",
+                        name: name,
+                        addInitializer: createAddInitializerMethod(initializers, decoratorFinishedRef),
+                        metadata
+                    });
+                } finally{
+                    decoratorFinishedRef.v = true;
+                }
+                if (nextNewClass !== undefined) {
+                    assertValidReturnValue(10, nextNewClass);
+                    newClass = nextNewClass;
+                }
+            }
+            return [
+                defineMetadata(newClass, metadata),
+                function() {
+                    for(var i = 0; i < initializers.length; i++){
+                        initializers[i].call(newClass);
+                    }
+                }
+            ];
+        }
+    }
+    function defineMetadata(Class, metadata) {
+        return Object.defineProperty(Class, Symbol.metadata || Symbol.for("Symbol.metadata"), {
+            configurable: true,
+            enumerable: true,
+            value: metadata
+        });
+    }
+    return function applyDecs2203R(targetClass, memberDecs, classDecs, parentClass) {
+        if (parentClass !== void 0) {
+            var parentMetadata = parentClass[Symbol.metadata || Symbol.for("Symbol.metadata")];
+        }
+        var metadata = Object.create(parentMetadata === void 0 ? null : parentMetadata);
+        var e = applyMemberDecs(targetClass, memberDecs, metadata);
+        if (!classDecs.length) defineMetadata(targetClass, metadata);
+        return {
+            e: e,
+            get c () {
+                return applyClassDecs(targetClass, classDecs, metadata);
+            }
+        };
+    };
+}
+function _apply_decs_2203_r(targetClass, memberDecs, classDecs, parentClass) {
+    return (_apply_decs_2203_r = applyDecs2203RFactory())(targetClass, memberDecs, classDecs, parentClass);
+}
+var _dec, _dec1, _initProto;
+import { AbortError, TimeoutError } from '@aztec-labs/foundation/error';
+import { createLogger } from '@aztec-labs/foundation/log';
+import { executeTimeout } from '@aztec-labs/foundation/timer';
+import { PeerErrorSeverity } from '@aztec-labs/stdlib/p2p';
+import { Attributes, getTelemetryClient, trackSpan } from '@aztec-labs/telemetry-client';
+import { pipeline } from 'node:stream/promises';
+import { IndividualReqRespTimeoutError, OversizedReqRespRequestError } from '../../errors/reqresp.error.js';
+import { DEFAULT_MAX_RESPONSE_SIZE_KB, OversizedSnappyResponseError, ResponseSizeLimitExceededError, SnappyTransform } from '../encoding.js';
+import { DEFAULT_INDIVIDUAL_REQUEST_TIMEOUT_MS, DEFAULT_REQRESP_DIAL_TIMEOUT_MS, MAX_REQRESP_REQUEST_SIZE_BYTES } from './config.js';
+import { ConnectionSampler, RandomSampler } from './connection-sampler/connection_sampler.js';
+import { ReqRespSubProtocol, UNAUTHENTICATED_ALLOWED_PROTOCOLS, subProtocolSizeCalculators } from './interface.js';
+import { ReqRespMetrics } from './metrics.js';
+import { RateLimitStatus, RequestResponseRateLimiter, prettyPrintRateLimitStatus } from './rate-limiter/rate_limiter.js';
+import { ReqRespStatus, ReqRespStatusError, parseStatusChunk } from './status.js';
+_dec = trackSpan('ReqResp.sendRequestToPeer', (peerId, subProtocol, _)=>({
+        [Attributes.P2P_ID]: peerId.toString(),
+        [Attributes.P2P_REQ_RESP_PROTOCOL]: subProtocol
+    })), _dec1 = trackSpan('ReqResp.streamHandler', (protocol, { connection })=>({
+        [Attributes.P2P_REQ_RESP_PROTOCOL]: protocol,
+        [Attributes.P2P_ID]: connection.remotePeer.toString()
+    }));
+/**
+ * The Request Response Service
+ *
+ * It allows nodes to request specific information from their peers, its use case covers recovering
+ * information that was missed during a synchronisation or a gossip event.
+ *
+ * This service implements the request response sub protocol, it is heavily inspired from
+ * ethereum implementations of the same name.
+ *
+ * Note, responses get compressed in streamHandler
+ *       so they get decompressed in readMessage
+ *
+ * see: https://github.com/ethereum/consensus-specs/blob/dev/specs/phase0/p2p-interface.md#the-reqresp-domain
+ */ export class ReqResp {
+    libp2p;
+    peerScoring;
+    logger;
+    static{
+        ({ e: [_initProto] } = _apply_decs_2203_r(this, [
+            [
+                _dec,
+                2,
+                "sendRequestToPeer"
+            ],
+            [
+                _dec1,
+                2,
+                "streamHandler"
+            ]
+        ], []));
+    }
+    individualRequestTimeoutMs;
+    dialTimeoutMs;
+    subProtocolHandlers;
+    connectionSampler;
+    rateLimiter;
+    snappyTransform;
+    shouldRejectPeer;
+    metrics;
+    constructor(config, libp2p, peerScoring, logger = createLogger('p2p:reqresp'), rateLimits = {}, telemetryClient = getTelemetryClient()){
+        this.libp2p = libp2p;
+        this.peerScoring = peerScoring;
+        this.logger = logger;
+        this.individualRequestTimeoutMs = (_initProto(this), DEFAULT_INDIVIDUAL_REQUEST_TIMEOUT_MS);
+        this.dialTimeoutMs = DEFAULT_REQRESP_DIAL_TIMEOUT_MS;
+        this.subProtocolHandlers = {};
+        this.updateConfig(config);
+        this.rateLimiter = new RequestResponseRateLimiter(peerScoring, rateLimits);
+        // Connection sampler is used to sample our connected peers
+        this.connectionSampler = new ConnectionSampler(libp2p, new RandomSampler(), createLogger(`${logger.module}:connection-sampler`), config);
+        this.snappyTransform = new SnappyTransform();
+        this.metrics = new ReqRespMetrics(telemetryClient);
+    }
+    updateConfig(config) {
+        if (typeof config.individualRequestTimeoutMs === 'number') {
+            this.individualRequestTimeoutMs = config.individualRequestTimeoutMs;
+        }
+        if (typeof config.dialTimeoutMs === 'number') {
+            this.dialTimeoutMs = config.dialTimeoutMs;
+        }
+    }
+    setShouldRejectPeer(checker) {
+        this.shouldRejectPeer = checker;
+    }
+    get tracer() {
+        return this.metrics.tracer;
+    }
+    /**
+   * Get the connection sampler instance
+   */ getConnectionSampler() {
+        return this.connectionSampler;
+    }
+    /**
+   * Start the reqresp service
+   */ async start(subProtocolHandlers) {
+        Object.assign(this.subProtocolHandlers, subProtocolHandlers);
+        // Register streamHandler with libp2p.
+        // The streamHandler is responsible for reading the incoming stream, determining the protocol, then triggering the appropriate handler.
+        for (const subProtocol of Object.keys(subProtocolHandlers)){
+            this.logger.debug(`Registering handler for sub protocol ${subProtocol}`);
+            await this.libp2p.handle(subProtocol, (data)=>void this.streamHandler(subProtocol, data).catch((err)=>this.logger.error(`Error on libp2p subprotocol ${subProtocol} handler`, err)));
+        }
+        this.rateLimiter.start();
+    }
+    async addSubProtocol(subProtocol, handler) {
+        this.subProtocolHandlers[subProtocol] = handler;
+        this.logger.debug(`Registering handler for sub protocol ${subProtocol}`);
+        await this.libp2p.handle(subProtocol, (data)=>void this.streamHandler(subProtocol, data).catch((err)=>this.logger.error(`Error on libp2p subprotocol ${subProtocol} handler`, err)));
+    }
+    /**
+   * Stop the reqresp service
+   */ async stop() {
+        // Unregister handlers in parallel
+        const unregisterPromises = Object.keys(this.subProtocolHandlers).map((protocol)=>this.libp2p.unhandle(protocol));
+        await Promise.all(unregisterPromises);
+        // Close connection sampler
+        await this.connectionSampler.stop();
+        this.logger.debug('ReqResp: Connection sampler stopped');
+        // Close streams in parallel
+        const closeStreamPromises = this.libp2p.getConnections().map((connection)=>connection.close());
+        await Promise.all(closeStreamPromises);
+        this.logger.debug('ReqResp: All active streams closed');
+        this.rateLimiter.stop();
+        this.logger.debug('ReqResp: Rate limiter stopped');
+    // NOTE: We assume libp2p instance is managed by the caller
+    }
+    /**
+   * Sends a request to a specific peer
+   *
+   * We first dial a particular protocol for the peer, this ensures that the peer knows
+   * what to respond with
+   *
+   *
+   * @param peerId - The peer to send the request to
+   * @param subProtocol - The protocol to use to request
+   * @param payload - The payload to send
+   * @param dialTimeout - If establishing a stream takes longer than this an error will be thrown
+   * @returns If the request is successful, the response is returned, otherwise undefined
+   *
+   * @description
+   * This method attempts to open a stream with the specified peer, send the payload,
+   * and await a response.
+   * If an error occurs, it penalizes the peer and returns undefined.
+   *
+   * The method performs the following steps:
+   * - Opens a stream with the peer using the specified sub-protocol.
+   * - Sends the payload and awaits a response with a timeout.
+   *
+   * If the stream is not closed by the dialled peer, and a timeout occurs, then
+   * the stream is closed on the requester's end and sender (us) updates its peer score
+   */ async sendRequestToPeer(peerId, subProtocol, payload, dialTimeout = this.dialTimeoutMs) {
+        // Thrown before the try block so the generic error handling below does not penalize the peer for our own bug.
+        if (payload.length > MAX_REQRESP_REQUEST_SIZE_BYTES) {
+            throw new OversizedReqRespRequestError(subProtocol, payload.length, MAX_REQRESP_REQUEST_SIZE_BYTES);
+        }
+        let stream;
+        try {
+            this.metrics.recordRequestSent(subProtocol);
+            // Calculate expected response size based on the request payload
+            const expectedSizeKb = subProtocolSizeCalculators[subProtocol](payload);
+            this.logger.trace(`Sending request to peer ${peerId.toString()} on sub protocol ${subProtocol}`);
+            stream = await this.connectionSampler.dialProtocol(peerId, subProtocol, dialTimeout);
+            this.logger.trace(`Opened stream ${stream.id} for sending request to peer ${peerId.toString()} on sub protocol ${subProtocol}`);
+            const timeoutErr = new IndividualReqRespTimeoutError();
+            // Create a wrapper to pass the expected size to readMessage
+            const readMessageWithSizeLimit = (source)=>this.readMessage(source, expectedSizeKb);
+            const [_, resp] = await executeTimeout((signal)=>Promise.all([
+                    pipeline([
+                        payload
+                    ], stream.sink, {
+                        signal
+                    }),
+                    pipeline(stream.source, readMessageWithSizeLimit, {
+                        signal
+                    })
+                ]), this.individualRequestTimeoutMs, ()=>timeoutErr);
+            return resp;
+        } catch (e) {
+            this.logger.debug(`SUBPROTOCOL: ${subProtocol}\n`, e);
+            // On error we immediately abort the stream, this is preferred way,
+            // because it signals to the sender that error happened, whereas
+            // closing the stream only closes our side and is much slower
+            if (stream) {
+                stream.abort(e);
+            }
+            this.metrics.recordRequestError(subProtocol);
+            this.handleResponseError(e, peerId, subProtocol);
+            // If there is an exception, we return an unknown response
+            this.logger.debug(`Error sending request to peer ${peerId.toString()} on sub protocol ${subProtocol}: ${e}`);
+            return {
+                status: ReqRespStatus.FAILURE
+            };
+        } finally{
+            // Only close the stream if we created it
+            // Note even if we aborted the stream, calling close on it is ok, it's just a no-op
+            if (stream) {
+                try {
+                    this.logger.trace(`Closing stream ${stream.id} for request to peer ${peerId.toString()} on sub protocol ${subProtocol}`);
+                    await this.connectionSampler.close(stream);
+                } catch (closeError) {
+                    this.logger.error(`Error closing stream: ${closeError instanceof Error ? closeError.message : 'Unknown error'}`);
+                }
+            }
+        }
+    }
+    /**
+   * Handle a response error
+   *
+   * ReqResp errors are punished differently depending on the severity of the offense
+   *
+   * @param e - The error
+   * @param peerId - The peer id
+   * @param subProtocol - The sub protocol
+   * @returns If the error is non pubishable, then undefined is returned, otherwise the peer is penalized
+   */ handleResponseError(e, peerId, subProtocol) {
+        const severity = this.categorizeResponseError(e, peerId, subProtocol);
+        if (severity) {
+            this.peerScoring.penalizePeer(peerId, severity);
+        }
+    }
+    /**
+   * Read a message returned from a stream into a single buffer
+   *
+   * The message is split into two components
+   * - The first chunk should contain a control byte, indicating the status of the response see `ReqRespStatus`
+   * - The second chunk should contain the response data
+   *
+   * To bound memory usage we abort reception as soon as the accumulated compressed bytes exceed a
+   * bound derived from `maxSizeKb`, before the full stream has been buffered. Without this a peer we
+   * dialed could stream data up to the request timeout, forcing us to buffer arbitrarily much (the
+   * `maxSizeKb` guard in `inboundTransformData` only runs after the whole compressed payload is
+   * concatenated, so it does nothing to cap reception memory). Snappy can expand incompressible input
+   * to ~1.17x its size, so we allow 2x `maxSizeKb`: comfortably above the worst-case expansion of a
+   * legitimate max-size response, while still capping buffered memory at twice the permitted size.
+   *
+   * @param source - The async iterable source of data chunks
+   * @param maxSizeKb - Optional maximum expected size in KB for the decompressed response
+   */ async readMessage(source, maxSizeKb) {
+        let status;
+        const chunks = [];
+        const maxAccumulatedBytes = (maxSizeKb ?? DEFAULT_MAX_RESPONSE_SIZE_KB) * 1024 * 2;
+        let accumulatedBytes = 0;
+        try {
+            for await (const chunk of source){
+                const statusParsed = status !== undefined;
+                if (statusParsed) {
+                    // Use `byteLength` (the logical length) rather than `chunk.subarray().length`: calling
+                    // `subarray()` on a `Uint8ArrayList` consolidates its backing buffers into a single copy,
+                    // which would materialize the very chunk we are trying to reject.
+                    accumulatedBytes += chunk.byteLength;
+                    if (accumulatedBytes > maxAccumulatedBytes) {
+                        throw new ResponseSizeLimitExceededError(accumulatedBytes, maxAccumulatedBytes);
+                    }
+                    chunks.push(chunk.subarray());
+                    continue;
+                }
+                const firstChunkBuffer = chunk.subarray();
+                status = parseStatusChunk(firstChunkBuffer);
+                // In case status is not SUCCESS, we do not expect any data in the response
+                // we can return early
+                if (status !== ReqRespStatus.SUCCESS) {
+                    return {
+                        status
+                    };
+                }
+            }
+            const messageData = Buffer.concat(chunks);
+            const message = this.snappyTransform.inboundTransformData(messageData, undefined, maxSizeKb);
+            return {
+                status: status ?? ReqRespStatus.UNKNOWN,
+                data: message
+            };
+        } catch (e) {
+            // All errors (invalid status bytes, oversized snappy responses, corrupt data, etc.)
+            // are re-thrown so the caller can penalize the peer via handleResponseError.
+            this.logger.debug(`Reading message failed: ${e.message}`);
+            throw e;
+        }
+    }
+    /**
+   * Stream Handler
+   * Reads the incoming stream, determines the protocol, then triggers the appropriate handler
+   *
+   * @param protocol - The sub protocol to handle
+   * @param incomingStream - The incoming stream data containing the stream and connection
+   *
+   * @description
+   * An individual stream handler will be bound to each sub protocol, and handles returning data back
+   * to the requesting peer.
+   *
+   * The sub protocol handler interface is defined within `interface.ts` and will be assigned to the
+   * req resp service on start up.
+   *
+   * We check rate limits for each peer, note the peer will be penalised within the rate limiter implementation
+   * if they exceed their peer specific limits.
+   */ async streamHandler(protocol, incomingStream) {
+        const { stream, connection } = incomingStream;
+        try {
+            this.metrics.recordRequestReceived(protocol);
+            const rateLimitStatus = this.rateLimiter.allow(protocol, connection.remotePeer);
+            if (rateLimitStatus !== RateLimitStatus.Allowed) {
+                this.logger.verbose(`Rate limit exceeded ${prettyPrintRateLimitStatus(rateLimitStatus)} for ${protocol} from ${connection.remotePeer}`);
+                throw new ReqRespStatusError(ReqRespStatus.RATE_LIMIT_EXCEEDED);
+            }
+            // When p2pAllowOnlyValidators is enabled, reject unauthenticated peers on data protocols
+            if (!UNAUTHENTICATED_ALLOWED_PROTOCOLS.has(protocol) && (this.shouldRejectPeer?.(connection.remotePeer.toString()) ?? false)) {
+                this.logger.debug(`Rejecting unauthenticated peer ${connection.remotePeer} on gated protocol ${protocol}`);
+                throw new ReqRespStatusError(ReqRespStatus.FAILURE);
+            }
+            await this.processStream(protocol, incomingStream);
+        } catch (err) {
+            this.metrics.recordResponseError(protocol);
+            this.handleRequestError(err, connection.remotePeer, protocol);
+            if (err instanceof ReqRespStatusError) {
+                const errorSent = await this.trySendError(stream, connection.remotePeer, protocol, err.status);
+                const logMessage = errorSent ? 'Protocol error sent successfully.' : 'Stream already closed or poisoned, not sending error response.';
+                const isRateLimit = err.status === ReqRespStatus.RATE_LIMIT_EXCEEDED;
+                const level = isRateLimit ? 'debug' : 'warn';
+                this.logger[level](logMessage + ` Status: ${ReqRespStatus[err.status]}`, {
+                    protocol,
+                    err,
+                    errorStatus: err.status,
+                    cause: err.cause ?? 'Cause unknown'
+                });
+            } else {
+                // In erroneous case we abort the stream, this will signal the peer that something went wrong
+                // and that this stream should be dropped
+                const isMessageToNotWarn = err instanceof Error && [
+                    'stream reset',
+                    'Cannot push value onto an ended pushable',
+                    'read ECONNRESET'
+                ].some((msg)=>err.message.includes(msg));
+                const level = isMessageToNotWarn ? 'debug' : 'warn';
+                this.logger[level]('Unknown stream error while handling the stream, aborting', {
+                    protocol,
+                    err
+                });
+                stream.abort(err);
+            }
+        } finally{
+            //NOTE: This is idempotent action, so it's ok to call it even if stream was aborted
+            await stream.close();
+        }
+    }
+    /**
+   * Reads incoming data from the stream, processes it according to the sub protocol,
+   * and puts response back into the stream.
+   *
+   * @param protocol - The sub protocol to use for processing the stream
+   * @param incomingStream - The incoming stream data containing the stream and connection
+   *
+   * */ async processStream(protocol, { stream, connection }) {
+        const handler = this.subProtocolHandlers[protocol];
+        if (!handler) {
+            throw new Error(`No handler defined for reqresp subprotocol ${protocol}`);
+        }
+        const snappy = this.snappyTransform;
+        const SUCCESS = Uint8Array.of(ReqRespStatus.SUCCESS);
+        await pipeline(stream.source, async function*(source) {
+            // Req/resp is one-request-one-response: an honest sender writes a single payload and half-closes.
+            // Process only the first chunk and return, so extra frames a peer queues on the same stream cannot
+            // drive further handler invocations that bypass the per-stream rate-limit check in streamHandler.
+            for await (const chunk of source){
+                const response = await handler(connection.remotePeer, chunk.subarray());
+                if (protocol === ReqRespSubProtocol.GOODBYE) {
+                    // NOTE: The stream was already closed by Goodbye handler
+                    // peerManager.goodbyeReceived(peerId, reason); will call libp2p.hangUp closing all active streams and connections
+                    // Don't try to respond
+                    return;
+                }
+                stream.metadata.written = true; // Mark the stream as written to;
+                yield SUCCESS;
+                yield snappy.outboundTransformData(response);
+                return;
+            }
+        }, stream.sink);
+    }
+    /**
+   * Try to send error status to the peer. We say try, because the stream,
+   * might already be closed
+   * @param stream - The stream opened between us and the peer
+   * @param status - The error status to send back to the peer
+   * @returns true if error was sent successfully, otherwise false
+   *
+   */ async trySendError(stream, peerId, protocol, status) {
+        const canWriteToStream = // 'writing' is a bit weird naming, but it actually means that the stream is ready to write
+        // 'ready' means that stream ready to be opened for writing
+        stream.status === 'open' && (stream.writeStatus === 'writing' || stream.writeStatus === 'ready');
+        // Stream was already written to, we consider it poisoned, in a sense,
+        // that even if we write an error response, it will not be interpreted correctly by the peer
+        const streamPoisoned = stream.metadata.written === true;
+        const shouldWriteToStream = canWriteToStream && !streamPoisoned;
+        if (!shouldWriteToStream) {
+            return false;
+        }
+        try {
+            await pipeline(function*() {
+                yield Uint8Array.of(status);
+            }, stream.sink);
+            return true;
+        } catch (e) {
+            this.logger.warn('Error while sending error response', e);
+            stream.abort(e);
+            this.handleRequestError(e, peerId, protocol);
+            return false;
+        }
+    }
+    handleRequestError(e, peerId, subProtocol) {
+        const severity = this.categorizeRequestError(e, peerId, subProtocol);
+        if (severity) {
+            this.peerScoring.penalizePeer(peerId, severity);
+        }
+    }
+    /**
+   * Categorize the request error and log it.
+   *
+   * @returns Severity of the error, or undefined if the error is not punishable.
+   */ categorizeRequestError(e, peerId, subProtocol) {
+        const logTags = {
+            peerId: peerId.toString(),
+            subProtocol
+        };
+        // Punishable error - peer should never send badly formed request
+        if (e instanceof ReqRespStatusError && e.status === ReqRespStatus.BADLY_FORMED_REQUEST) {
+            this.logger.debug(`Punishable error in ${subProtocol}: ${e.cause}`, logTags);
+            return PeerErrorSeverity.LowToleranceError;
+        }
+        // TODO: (mralj): think if we should penalize peer here based on connection errors
+        return undefined;
+    }
+    /**
+   * Categorize the response error and log it.
+   *
+   * @returns Severity of the error, or undefined if the error is not punishable.
+   */ categorizeResponseError(e, peerId, subProtocol) {
+        const logTags = {
+            peerId: peerId.toString(),
+            subProtocol
+        };
+        // Non punishable errors - we do not expect a response for goodbye messages
+        if (subProtocol === ReqRespSubProtocol.GOODBYE) {
+            this.logger.debug('Error encountered on goodbye sub protocol, no penalty', logTags);
+            return undefined;
+        }
+        // Invalid status byte: the peer sent a status byte that doesn't match any known status code.
+        // This is a protocol violation, penalize harshly.
+        if (e instanceof ReqRespStatusError) {
+            this.logger.warn(`Invalid status byte from peer ${peerId.toString()} in ${subProtocol}: ${e.message}`, logTags);
+            return PeerErrorSeverity.LowToleranceError;
+        }
+        // Oversized snappy response: the peer is sending data that exceeds the allowed size.
+        // This is a protocol violation that wastes bandwidth, so penalize harshly.
+        if (e instanceof OversizedSnappyResponseError) {
+            this.logger.warn(`Oversized response from peer ${peerId.toString()} in ${subProtocol}: ${e.message}`, logTags);
+            return PeerErrorSeverity.LowToleranceError;
+        }
+        // Response exceeded the reception buffer bound: the peer streamed more compressed data than the
+        // per-request size limit allows. Same protocol violation as above, penalize harshly.
+        if (e instanceof ResponseSizeLimitExceededError) {
+            this.logger.warn(`Oversized response from peer ${peerId.toString()} in ${subProtocol}: ${e.message}`, logTags);
+            return PeerErrorSeverity.LowToleranceError;
+        }
+        return this.categorizeConnectionErrors(e, peerId, subProtocol);
+    }
+    /*
+   * Errors specific to connection  handling
+   * These can happen  both when sending request and response.
+   */ categorizeConnectionErrors(e, peerId, subProtocol) {
+        const logTags = {
+            peerId: peerId.toString(),
+            subProtocol
+        };
+        // Do not punish if we are stopping the service
+        if (e instanceof AbortError || e?.code == 'ABORT_ERR') {
+            this.logger.debug(`Request aborted: ${e.message}`, logTags);
+            return undefined;
+        }
+        // Do not punish if we are the ones closing the connection
+        if (e?.code === 'ERR_CONNECTION_BEING_CLOSED' || e?.code === 'ERR_CONNECTION_CLOSED' || e?.code === 'ERR_TRANSIENT_CONNECTION' || e?.message?.includes('Muxer already closed') || e?.message?.includes('muxer closed') || e?.message?.includes('ended pushable')) {
+            this.logger.debug(`Connection closed to peer from our side: ${peerId.toString()} (${e?.message ?? 'missing error message'})`, logTags);
+            return undefined;
+        }
+        // Pubishable errors
+        // Connection reset errors in the networking stack are punished with high severity
+        // it just signals an unreliable peer
+        // We assume that the requesting node has a functioning networking stack.
+        if (e?.code === 'ECONNRESET' || e?.code === 'EPIPE') {
+            this.logger.debug(`Connection reset: ${peerId.toString()}`, logTags);
+            return PeerErrorSeverity.HighToleranceError;
+        }
+        if (e?.code === 'ECONNREFUSED') {
+            this.logger.debug(`Connection refused: ${peerId.toString()}`, logTags);
+            return PeerErrorSeverity.HighToleranceError;
+        }
+        if (e?.code === 'ERR_UNEXPECTED_EOF') {
+            this.logger.debug(`Connection unexpected EOF: ${peerId.toString()}`, logTags);
+            return PeerErrorSeverity.HighToleranceError;
+        }
+        if (e?.code === 'ERR_UNSUPPORTED_PROTOCOL') {
+            this.logger.debug(`Sub protocol not supported by peer: ${peerId.toString()}`, logTags);
+            return PeerErrorSeverity.HighToleranceError;
+        }
+        // Timeout errors are punished with high tolerance, they can be due to a geographically far away or overloaded peer
+        if (e instanceof IndividualReqRespTimeoutError || e instanceof TimeoutError) {
+            this.logger.debug(`Timeout error in ${subProtocol}: ${e.message}`, logTags);
+            return PeerErrorSeverity.HighToleranceError;
+        }
+        // Catch all error
+        this.logger.error(`Unexpected error in ReqResp protocol`, e, logTags);
+        return PeerErrorSeverity.HighToleranceError;
+    }
+}