Revision control

// Copyright (C) 2025 The Qt Company Ltd.
// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GPL-3.0-only
// Qt-Security score:significant reason:default
#include <QtGrpc/qgrpcinterceptor.h>
#include <QtGrpc/qgrpcoperationcontext.h>
using namespace QtGrpc;
using QtGrpcPrivate::InterceptorTypes;
static_assert(InterceptorTypes::size <= std::numeric_limits<
std::underlying_type_t<QtGrpc::InterceptorCapability>>::digits,
"Interceptors exceed the capability limit!");
QT_BEGIN_NAMESPACE
+ /*!
+ \since 6.11
+ \inmodule QtGrpc
+ \headerfile <QGrpcInterceptor>
+ \title Interceptor types
+ \brief The <QGrpcInterceptor> header file provides the basic interceptor
+ types.
+
+ Qt GRPC provides various types that are commonly grouped in the
+ \c{<QtGrpcInterceptor>} header file.
+
+ \section1 Interceptor mechanism
+
+ The following classes and pages form the Qt GRPC interceptor mechanism:
+
+ \generatelist qtgrpc-interceptors
+ */
+
+ /*!
+ \group qtgrpc-interceptors
+ \title Qt GRPC Interceptors
+
+ The following classes and pages form the Qt GRPC interceptor mechanism:
+ */
+
+ /*!
+ \since 6.11
+ \inmodule QtGrpc
+ \ingroup qtgrpc-interceptors
+ \inheaderfile QGrpcInterceptor
+ \class QGrpcInterceptionContext
+ \brief Provides contextual information to interceptor callbacks.
+
+ QGrpcInterceptionContext is passed to interceptor callbacks and provides
+ access to information about the intercepted RPC, such as the channel, the
+ RPC descriptor, or call options.
+
+ A QGrpcInterceptionContext instance is created by Qt GRPC for each callback
+ invocation. The context object is only valid for the duration of the
+ callback and must not be stored.
+
+ \note QGrpcInterceptionContext is not copyable or movable.
+
+ \sa QGrpcStartInterceptor, QGrpcInitialMetadataInterceptor,
+ QGrpcMessageReceivedInterceptor, QGrpcWriteMessageInterceptor,
+ QGrpcWritesDoneInterceptor, QGrpcTrailingMetadataInterceptor,
+ QGrpcFinishedInterceptor, QGrpcCancelInterceptor
+ */
+
+ /*!
+ \fn quint32 QGrpcInterceptionContext::version() const noexcept
+
+ Returns the version of the interception context.
+
+ Future versions of Qt may extend QGrpcInterceptionContext. This function
+ can be used to identify the supported revision of the context.
+ */
+
+ /*!
+ \fn const QAbstractGrpcChannel &QGrpcInterceptionContext::channel() const & noexcept
+
+ Returns the channel used for the intercepted RPC.
+ */
+
+ /*!
+ Returns the call options that are in effect for the intercepted RPC.
+ */
const QGrpcCallOptions &QGrpcInterceptionContext::callOptions() const & noexcept
{
return m_operationContext->callOptions();
}
+ /*!
+ Returns the descriptor identifying the intercepted RPC.
+ */
RpcDescriptor QGrpcInterceptionContext::descriptor() const noexcept
{
return m_operationContext->descriptor();
}
+ /*!
+ Returns the unique identifier of the intercepted call.
+
+ Each ID is unique across all channels for the application lifetime.
+
+ This identifier can be used to correlate interception callbacks that belong
+ to the same RPC operation across multiple hook points.
+ */
quint64 QGrpcInterceptionContext::operationId() const noexcept
{
return m_operationContext->operationId();
}
+ /*!
+ \since 6.11
+ \ingroup qtgrpc-interceptors
+ \relates <QGrpcInterceptor>
+ \enum QtGrpc::InterceptorCapability
+ \brief Specifies interception hook points supported by an interceptor.
+
+ Qt GRPC uses InterceptorCapability values to describe which interception
+ hook points an interceptor provides.
+
+ A single interceptor class can implement multiple interceptor interfaces
+ (for example, QGrpcStartInterceptor and QGrpcFinishedInterceptor) and
+ therefore support multiple capabilities.
+
+ \value Start The interceptor implements QGrpcStartInterceptor.
+ \value InitialMetadata The interceptor implements QGrpcInitialMetadataInterceptor.
+ \value MessageReceived The interceptor implements QGrpcMessageReceivedInterceptor.
+ \value WriteMessage The interceptor implements QGrpcWriteMessageInterceptor.
+ \value WritesDone The interceptor implements QGrpcWritesDoneInterceptor.
+ \value TrailingMetadata The interceptor implements QGrpcTrailingMetadataInterceptor.
+ \value Finished The interceptor implements QGrpcFinishedInterceptor.
+ \value Cancel The interceptor implements QGrpcCancelInterceptor.
+ */
+
+ /*!
+ \since 6.11
+ \ingroup qtgrpc-interceptors
+ \relates <QGrpcInterceptor>
+ \typedef QtGrpc::InterceptorCapabilities
+ \brief A QFlags type that stores a combination of InterceptorCapability values.
+
+ \sa QtGrpc::InterceptorCapability
+ */
+
+ /*!
+ \since 6.11
+ \inmodule QtGrpc
+ \ingroup qtgrpc-interceptors
+ \inheaderfile QGrpcInterceptor
+ \class QGrpcStartInterceptor
+ \brief Intercepts the start of an RPC.
+ \reentrant
+
+ Implement QGrpcStartInterceptor to observe or adjust parameters that are
+ used when an RPC is started.
+
+ The interceptor is invoked once per RPC, before the call proceeds.
+
+ \sa QtGrpc::InterceptorCapability::Start, QGrpcInterceptionContext,
+ QGrpcInterceptionContext
+ */
+
+ /*!
+ \since 6.11
+ \inmodule QtGrpc
+ \ingroup qtgrpc-interceptors
+ \relates QGrpcStartInterceptor
+ \enum QGrpcStartInterceptor::Continuation
+ \brief Controls whether an intercepted RPC should proceed.
+
+ \value Proceed Continue the call.
+ \value Drop Abort the call.
+ */
+
+ /*!
+ \fn QGrpcStartInterceptor::Continuation QGrpcStartInterceptor::onStart(QGrpcInterceptionContext &context, QProtobufMessage &message, QGrpcCallOptions &callOptions)
+
+ Called when an RPC is about to start.
+
+ The \a context provides information about the intercepted RPC.
+
+ The \a message contains the initial request message and can be modified in place.
+
+ The \a callOptions can be modified to adjust per-call settings.
+
+ Return Continuation::Proceed to continue the RPC, or
+ Continuation::Drop to prevent it from proceeding.
+
+ If Continuation::Drop is returned, the RPC is aborted and the operation
+ transitions to \l{QGrpcOperation::}{finished()}. The resulting status code
+ is \l{QtGrpc::StatusCode::}{Aborted}. Interceptors implementing
+ QGrpcFinishedInterceptor are still invoked.
+
+ \note The mutable \a callOptions refers to the same call options
+ instance returned by \c{context.callOptions()}.
+ */
+
+ /*!
+ Destroys the interceptor.
+ */
QGrpcStartInterceptor::~QGrpcStartInterceptor() = default;
+
+ /*!
+ \since 6.11
+ \inmodule QtGrpc
+ \ingroup qtgrpc-interceptors
+ \inheaderfile QGrpcInterceptor
+ \class QGrpcInitialMetadataInterceptor
+ \brief Intercepts initial metadata for an RPC.
+ \reentrant
+
+ Implement QGrpcInitialMetadataInterceptor to observe or modify initial
+ metadata associated with an RPC.
+
+ Initial metadata is sent by the server immediately after the call is
+ established and before any response messages are delivered.
+
+ \sa QtGrpc::InterceptorCapability::InitialMetadata,
+ QGrpcOperation::serverInitialMetadata(),
+ QGrpcOperation::serverInitialMetadataReceived(),
+ QGrpcInterceptionContext
+ */
+
+ /*!
+ \fn void QGrpcInitialMetadataInterceptor::onInitialMetadata(QGrpcInterceptionContext &context, QMultiHash<QByteArray, QByteArray> &metadata)
+
+ Called when the initial \a metadata becomes available for the RPC.
+
+ The \a context provides information about the intercepted RPC.
+ The \a metadata can be modified in place before it is forwarded to the RPC.
+
+ \sa QGrpcOperation::serverInitialMetadata(),
+ QGrpcOperation::serverInitialMetadataReceived()
+ */
+
+ /*!
+ Destroys the interceptor.
+ */
QGrpcInitialMetadataInterceptor::~QGrpcInitialMetadataInterceptor() = default;
+
+ /*!
+ \since 6.11
+ \inmodule QtGrpc
+ \ingroup qtgrpc-interceptors
+ \inheaderfile QGrpcInterceptor
+ \class QGrpcMessageReceivedInterceptor
+ \brief Intercepts incoming message payloads for an RPC.
+ \reentrant
+
+ Implement QGrpcMessageReceivedInterceptor to observe or modify the
+ serialized message payload of messages received from an RPC.
+
+ \sa QtGrpc::InterceptorCapability::MessageReceived, QGrpcInterceptionContext
+ */
+
+ /*!
+ \fn void QGrpcMessageReceivedInterceptor::onMessageReceived(QGrpcInterceptionContext &context, QByteArray &messageData)
+
+ Called when an incoming message payload \a messageData becomes available.
+
+ The \a context provides information about the intercepted RPC.
+ The \a messageData contains serialized message bytes and can be modified in place.
+
+ \sa QGrpcServerStream::messageReceived(), QGrpcBidiStream::messageReceived()
+ */
+
+ /*!
+ Destroys the interceptor.
+ */
QGrpcMessageReceivedInterceptor::~QGrpcMessageReceivedInterceptor() = default;
+
+ /*!
+ \since 6.11
+ \inmodule QtGrpc
+ \ingroup qtgrpc-interceptors
+ \inheaderfile QGrpcInterceptor
+ \class QGrpcWriteMessageInterceptor
+ \brief Intercepts outgoing messages written for an RPC.
+ \reentrant
+
+ Implement QGrpcWriteMessageInterceptor to observe or modify messages that are
+ written as part of an RPC after it has been started.
+
+ \sa QtGrpc::InterceptorCapability::WriteMessage, QGrpcInterceptionContext
+ */
+
+ /*!
+ \fn void QGrpcWriteMessageInterceptor::onWriteMessage(QGrpcInterceptionContext &context, QProtobufMessage &message)
+
+ Called when an outgoing \a message is about to be written for the RPC.
+
+ The \a context provides information about the intercepted RPC.
+ The \a message can be modified in place.
+
+ \sa QGrpcClientStream::writeMessage(), QGrpcBidiStream::writeMessage()
+ */
+
+ /*!
+ Destroys the interceptor.
+ */
QGrpcWriteMessageInterceptor::~QGrpcWriteMessageInterceptor() = default;
+
+ /*!
+ \since 6.11
+ \inmodule QtGrpc
+ \ingroup qtgrpc-interceptors
+ \inheaderfile QGrpcInterceptor
+ \class QGrpcWritesDoneInterceptor
+ \brief Intercepts the completion of message writes for an RPC.
+ \reentrant
+
+ Implement QGrpcWritesDoneInterceptor to observe when no further outgoing
+ messages will be written for an RPC.
+
+ \sa QtGrpc::InterceptorCapability::WritesDone, QGrpcInterceptionContext
+ */
+
+ /*!
+ \fn void QGrpcWritesDoneInterceptor::onWritesDone(QGrpcInterceptionContext &context)
+
+ Called when the local side indicates that no further outgoing messages will
+ be written.
+
+ The \a context provides information about the intercepted RPC.
+
+ \sa QGrpcClientStream::writesDone(), QGrpcBidiStream::writesDone()
+ */
+
+ /*!
+ Destroys the interceptor.
+ */
QGrpcWritesDoneInterceptor::~QGrpcWritesDoneInterceptor() = default;
+
+ /*!
+ \since 6.11
+ \inmodule QtGrpc
+ \ingroup qtgrpc-interceptors
+ \inheaderfile QGrpcInterceptor
+ \class QGrpcTrailingMetadataInterceptor
+ \brief Intercepts trailing metadata for an RPC.
+ \reentrant
+
+ Implement QGrpcTrailingMetadataInterceptor to observe or modify trailing
+ metadata associated with an RPC.
+
+ Trailing metadata is sent by the server when the RPC is completing,
+ after all response messages have been delivered.
+
+
+ \sa QtGrpc::InterceptorCapability::TrailingMetadata,
+ QGrpcOperation::serverTrailingMetadata(), QGrpcInterceptionContext
+ */
+
+ /*!
+ \fn void QGrpcTrailingMetadataInterceptor::onTrailingMetadata(QGrpcInterceptionContext &context, QMultiHash<QByteArray, QByteArray> &metadata)
+
+ Called when trailing \a metadata becomes available for the RPC.
+
+ The \a context provides information about the intercepted RPC.
+ The \a metadata can be modified in place before it is forwarded to the RPC.
+
+ \sa QGrpcOperation::serverTrailingMetadata()
+ */
+
+ /*!
+ Destroys the interceptor.
+ */
QGrpcTrailingMetadataInterceptor::~QGrpcTrailingMetadataInterceptor() = default;
+
+ /*!
+ \since 6.11
+ \inmodule QtGrpc
+ \ingroup qtgrpc-interceptors
+ \inheaderfile QGrpcInterceptor
+ \class QGrpcFinishedInterceptor
+ \brief Intercepts the completion status of an RPC.
+ \reentrant
+
+ Implement QGrpcFinishedInterceptor to observe or modify the final status of
+ an RPC.
+
+ \sa QtGrpc::InterceptorCapability::Finished, QGrpcOperation::finished(),
+ QGrpcInterceptionContext
+ */
+
+ /*!
+ \fn void QGrpcFinishedInterceptor::onFinished(QGrpcInterceptionContext &context, QGrpcStatus &status)
+
+ Called when an RPC is completing.
+
+ The \a context provides information about the intercepted RPC.
+ The \a status contains the final status and can be modified in place.
+
+ \sa QGrpcOperation::finished()
+ */
+
+ /*!
+ Destroys the interceptor.
+ */
QGrpcFinishedInterceptor::~QGrpcFinishedInterceptor() = default;
+
+ /*!
+ \since 6.11
+ \inmodule QtGrpc
+ \ingroup qtgrpc-interceptors
+ \inheaderfile QGrpcInterceptor
+ \class QGrpcCancelInterceptor
+ \brief Intercepts cancellation requests for an RPC.
+ \reentrant
+
+ Implement QGrpcCancelInterceptor to observe when cancellation is requested
+ for an RPC.
+
+ \sa QtGrpc::InterceptorCapability::Cancel, QGrpcInterceptionContext
+ */
+
+ /*!
+ \fn void QGrpcCancelInterceptor::onCancel(QGrpcInterceptionContext &context)
+
+ Called when cancellation is requested for the RPC.
+
+ The \a context provides information about the intercepted RPC.
+
+ \sa QGrpcOperation::cancel()
+ */
+
+ /*!
+ Destroys the interceptor.
+ */
QGrpcCancelInterceptor::~QGrpcCancelInterceptor() = default;
QT_END_NAMESPACE