Revision control
++ // Copyright (C) 2023 The Qt Company Ltd.
++ // SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GPL-3.0-only
++
++ #include <QtGrpc/private/qgrpccommonoptions_p.h>
++ #include <QtGrpc/private/qgrpcoperation_p.h>
++ #include <QtGrpc/private/qgrpcoperationcontext_p.h>
++ #include <QtGrpc/qgrpcoperation.h>
++ #include <QtGrpc/qgrpcoperationcontext.h>
++ #include <QtGrpc/qgrpcstatus.h>
++
++ #include <QtProtobuf/qprotobufserializer.h>
++
++ #include <QtCore/private/qobject_p.h>
++ #include <QtCore/qbytearray.h>
++ #include <QtCore/qbytearrayview.h>
++ #include <QtCore/qlatin1stringview.h>
++
++ #include <atomic>
++ #include <utility>
++
++ QT_BEGIN_NAMESPACE
++
++ namespace {
++
++ quint64 nextOperationId()
++ {
++ static std::atomic<quint64> counter{ 0 };
++ return counter.fetch_add(1, std::memory_order_relaxed);
++ }
++
++ }
++
++ /*!
++ \class QGrpcOperationContext
++ \inmodule QtGrpc
++ \since 6.7
++ \brief The QGrpcOperationContext class provides context for communication
++ between an individual \gRPC operation and a channel.
++
++ QGrpcOperationContext is constructed internally when a remote procedure call
++ (RPC) is requested, mediating interaction between the client's operation
++ request and the channel's operation outcome.
++
++ RPCs requested on the client interface return specializations of
++ QGrpcOperation, such as QGrpcCallReply, QGrpcServerStream,
++ QGrpcClientStream, or QGrpcBidiStream. These classes are implicitly
++ integrated with the underlying QGrpcOperationContext counterpart.
++
++ \note Don't use this class directly unless implementing a custom channel.
++
++ The signals contained within this class are used to build the communication
++ between the client-facing QGrpcOperation and the QAbstractGrpcChannel
++ implementation. These operations are asynchronous in nature, and multiple
++ RPCs can operate on the same channel concurrently. Channels typically treat
++ all operations the same, and it is the channel's responsibility to
++ correctly support and restrict the subset of features its RPC type
++ supports.
++
++ Signals which should only be emitted by the channel's implementation are:
++ \list
++ \li finished()
++ \li messageReceived()
++ \li messageWritten()
++ \endlist
++
++ Signals which will be emitted by QGrpcOperation and its specializations are:
++ \list
++ \li cancelRequested()
++ \li writeMessageRequested()
++ \li writesDoneRequested()
++ \endlist
++
++ Custom implementations of QAbstractGrpcChannel must handle the client's
++ signals, as no default signal handling is provided, and emit their own
++ signals accordingly.
++ */
++
++ /*!
++ \fn void QGrpcOperationContext::finished(const QGrpcStatus &status)
++
++ This signal should be emitted by the channel when an RPC finishes.
++
++ It usually means that the server sent a \a status for the requested RPC and
++ closed the connection. Implementations of QAbstractGrpcChannel should
++ detect this situation and emit the signal.
++
++ After receiving this signal, no further communication should occur through
++ this operation context. The client side may then safely delete the
++ corresponding RPC object.
++
++ \note This signal is implicitly connected to the QGrpcOperation counterpart.
++
++ \sa QGrpcOperation::finished
++ */
++
++ /*!
++ \fn void QGrpcOperationContext::messageReceived(const QByteArray &data)
++
++ This signal should be emitted by the channel when a new chunk of \a data is
++ received from the server.
++
++ For client streams and unary calls, this means that the single and final
++ response has arrived and communication is about to finish.
++
++ For server and bidirectional streams, this signal should be continuously
++ emitted by the channel upon receiving each new messages.
++
++ \note This signal is implicitly connected to the QGrpcOperation
++ counterpart.
++
++ \sa QGrpcServerStream::messageReceived
++ \sa QGrpcBidiStream::messageReceived
++ */
++
++ /*!
++ \since 6.13
++ \fn void QGrpcOperationContext::messageWritten()
++
++ This signal should be emitted by the channel when it has passed an
++ outgoing message on to the transport: once for the initial request
++ message and once per writeMessageRequested(), in write order.
++
++ Clients rely on this signal to pace their writes and bound their
++ outgoing queue. Channels that buffer messages should therefore delay
++ the emission while the transport applies backpressure, and channels
++ that never emit it leave client-streaming and bidirectional-streaming
++ RPCs without write pacing. The signal must not be emitted once finished()
++ has been emitted. Channels should additionally report their queue state
++ through setBytesToWrite().
++
++ \note This signal is implicitly connected to the QGrpcClientStream and
++ QGrpcBidiStream counterparts.
++
++ \sa QGrpcClientStream::messageWritten
++ \sa QGrpcBidiStream::messageWritten
++ \sa setBytesToWrite()
++ */
++
++ /*!
++ \fn void QGrpcOperationContext::cancelRequested()
++
++ This signal is emitted by QGrpcOperation when requesting cancellation of the
++ communication.
++
++ The channel is expected to connect its cancellation logic to this signal
++ and attempt to cancel the RPC and finish it with a
++ \l{QtGrpc::StatusCode::}{Cancelled} status code. Successful cancellation
++ cannot be guaranteed. Further processing of the data received from a
++ channel is not required and should be avoided.
++
++ \sa QGrpcOperation::cancel
++ */
++
++ /*!
++ \fn void QGrpcOperationContext::writeMessageRequested(const QByteArray &data)
++
++ This signal is emitted by QGrpcClientStream or QGrpcBidiStream when it has
++ serialized \a data ready for a channel to deliver.
++
++ The channel is expected to connect its writing logic to this signal and wrap
++ the serialized data in channel-related headers before writing it to the
++ wire.
++
++ \sa QGrpcClientStream::writeMessage
++ \sa QGrpcBidiStream::writeMessage
++ */
++
++ /*!
++ \fn void QGrpcOperationContext::writesDoneRequested()
++
++ This signal is emitted by QGrpcClientStream or QGrpcBidiStream to indicate
++ that it's done writing messages. The channel should respond to this by
++ half-closing the stream.
++
++ \note After receiving this signal no more write operations are permitted
++ for the streaming RPCs. The server can still send messages, which should be
++ forwarded with messageReceived().
++
++ \sa QGrpcClientStream::writesDone
++ \sa QGrpcBidiStream::writesDone
++ */
++
++ /*!
++ \fn void QGrpcOperationContext::serverInitialMetadataReceived(const QMultiHash<QByteArray, QByteArray> &metadata)
++ \since 6.11
++
++ \include qgrpcoperation.cpp serverInitialMetadataReceived
++
++ \sa QGrpcOperation::serverInitialMetadataReceived
++ \sa QGrpcBidiStream::writesDone
++ */
++
++ /*!
++ \internal
++
++ Constructs an operation context with the given \a descriptor, \a options,
++ and \a serializer. The \a parent is the QGrpcOperation that owns this
++ context.
++
++ \note This class can only be constructed by its parent QGrpcOperation.
++ */
++ QGrpcOperationContext::QGrpcOperationContext(QtGrpc::RpcDescriptor descriptor,
++ const QGrpcCallOptions &options,
++ std::shared_ptr<QAbstractProtobufSerializer>
++ serializer,
++ QGrpcOperation *parent, PrivateConstructor /*unused*/)
++ : QObject(*new QGrpcOperationContextPrivate(std::move(descriptor), options,
++ std::move(serializer), nextOperationId()),
++ parent)
++ {
++ using namespace QtGrpc;
++ Q_D(const QGrpcOperationContext);
++ const auto type = d->descriptor.type;
++ if (type == RpcType::UnaryCall || type == RpcType::ServerStreaming) {
++ connect(this, &QGrpcOperationContext::writeMessageRequested, this, []() {
++ Q_ASSERT_X(false, "QGrpcOperationContext::writeMessageRequested",
++ "This signal is disallowed for unary and server-streaming operations");
++ });
++ connect(this, &QGrpcOperationContext::writesDoneRequested, this, []() {
++ Q_ASSERT_X(false, "QGrpcOperationContext::writesDoneRequested",
++ "This signal is disallowed for unary and server-streaming operations");
++ });
++ }
++ }
++
++ /*!
++ Destroys the operation-context.
++ */
++ QGrpcOperationContext::~QGrpcOperationContext() = default;
++
++ /*!
++ Returns the method name of the service associated with this
++ operation-context.
++ */
++ QLatin1StringView QGrpcOperationContext::method() const noexcept
++ {
++ Q_D(const QGrpcOperationContext);
++ return d->descriptor.method;
++ }
++
++ /*!
++ Returns the service name associated with this operation-context.
++ */
++ QLatin1StringView QGrpcOperationContext::service() const noexcept
++ {
++ Q_D(const QGrpcOperationContext);
++ return d->descriptor.service;
++ }
++
++ /*!
++ \since 6.11
++ Returns the QtGrpc::RpcDescriptor for this operation-context.
++ */
++ QtGrpc::RpcDescriptor QGrpcOperationContext::descriptor() const noexcept
++ {
++ Q_D(const QGrpcOperationContext);
++ return d->descriptor;
++ }
++
++ /*!
++ Returns the call options that is utilized by this operation-context.
++
++ For channel-wide options, see QGrpcChannelOptions.
++ */
++ const QGrpcCallOptions &QGrpcOperationContext::callOptions() const & noexcept
++ {
++ Q_D(const QGrpcOperationContext);
++ return d->options;
++ }
++
++ /*!
++ Returns the serializer of this operation-context
++ */
++ std::shared_ptr<const QAbstractProtobufSerializer>
++ QGrpcOperationContext::serializer() const
++ {
++ Q_D(const QGrpcOperationContext);
++ return d->serializer;
++ }
++
++ #if QT_DEPRECATED_SINCE(6, 13)
++
++ /*!
++ \deprecated [6.13] Use serverInitialMetadata() and serverTrailingMetadata() instead.
++
++ \include qgrpcoperation.cpp serverInitialMetadata-shared
++ \note This method is used implicitly by QGrpcOperation.
++
++ \sa serverInitialMetadata() QGrpcOperation::serverInitialMetadata()
++ */
++ const QHash<QByteArray, QByteArray> &QGrpcOperationContext::serverMetadata() const & noexcept
++ {
++ Q_D(const QGrpcOperationContext);
++ return d->deprServerInitialMetadata;
++ }
++
++ /*!
++ \fn void QGrpcOperationContext::setServerMetadata(const QHash<QByteArray, QByteArray> &metadata)
++ \fn void QGrpcOperationContext::setServerMetadata(QHash<QByteArray, QByteArray> &&metadata)
++ \deprecated [6.13] Use setServerInitialMetadata() instead.
++
++ Sets the metadata received from the server at the start of the RPC.
++
++ \sa setServerInitialMetadata()
++ */
++ void QGrpcOperationContext::setServerMetadata(const QHash<QByteArray, QByteArray> &metadata)
++ {
++ Q_D(QGrpcOperationContext);
++ if (d->deprServerInitialMetadata == metadata)
++ return;
++ d->deprServerInitialMetadata = metadata;
++ d->serverInitialMetadata = QMultiHash<QByteArray, QByteArray>(metadata);
++ }
++ void QGrpcOperationContext::setServerMetadata(QHash<QByteArray, QByteArray> &&metadata)
++ {
++ Q_D(QGrpcOperationContext);
++ if (d->deprServerInitialMetadata == metadata)
++ return;
++ d->deprServerInitialMetadata = std::move(metadata);
++ d->serverInitialMetadata = QMultiHash<QByteArray, QByteArray>(d->deprServerInitialMetadata);
++ }
++
++ #endif // QT_DEPRECATED_SINCE(6, 13)
++
++ /*!
++ \since 6.10
++
++ \include qgrpcoperation.cpp serverInitialMetadata-shared
++ \note This method is used implicitly by QGrpcOperation.
++
++ \sa QGrpcOperation::serverInitialMetadata() serverTrailingMetadata()
++ */
++ const QMultiHash<QByteArray, QByteArray> &
++ QGrpcOperationContext::serverInitialMetadata() const & noexcept
++ {
++ Q_D(const QGrpcOperationContext);
++ return d->serverInitialMetadata;
++ }
++
++ /*!
++ \since 6.10
++
++ Sets the \a metadata received from the server at the start of the RPC.
++
++ \sa serverInitialMetadata()
++ */
++ void QGrpcOperationContext::setServerInitialMetadata(QMultiHash<QByteArray, QByteArray> &&metadata)
++ {
++ Q_D(QGrpcOperationContext);
++ if (auto channel = operation().d_func()->channel.lock()) {
++ auto &engine = QAbstractGrpcChannelPrivate::get(channel.get())->interceptorEngine;
++ if (engine.hasHandlerFor(QtGrpc::InterceptorCapability::InitialMetadata))
++ engine.onInitialMetadata(*this, metadata);
++ }
++ d->serverInitialMetadata = std::move(metadata);
++ #if QT_DEPRECATED_SINCE(6, 13)
++ d->deprServerInitialMetadata = QtGrpcPrivate::toHash(d->serverInitialMetadata);
++ #endif
++ emit serverInitialMetadataReceived(d->serverInitialMetadata, QPrivateSignal{});
++ }
++
++ /*!
++ \since 6.10
++
++ \include qgrpcoperation.cpp serverTrailingMetadata
++ \note This method is used implicitly by QGrpcOperation.
++
++ \sa QGrpcOperation::serverTrailingMetadata() setServerTrailingMetadata()
++ */
++ const QMultiHash<QByteArray, QByteArray> &
++ QGrpcOperationContext::serverTrailingMetadata() const & noexcept
++ {
++ Q_D(const QGrpcOperationContext);
++ return d->serverTrailingMetadata;
++ }
++
++ /*!
++ \since 6.10
++
++ Sets the trailing \a metadata received from the server after all response
++ messages.
++
++ \sa serverTrailingMetadata()
++ */
++ void QGrpcOperationContext::setServerTrailingMetadata(QMultiHash<QByteArray, QByteArray> &&metadata)
++ {
++ Q_D(QGrpcOperationContext);
++ if (auto channel = operation().d_func()->channel.lock()) {
++ auto &engine = QAbstractGrpcChannelPrivate::get(channel.get())->interceptorEngine;
++ if (engine.hasHandlerFor(QtGrpc::InterceptorCapability::TrailingMetadata))
++ engine.onTrailingMetadata(*this, metadata);
++ }
++ if (d->serverTrailingMetadata == metadata)
++ return;
++ d->serverTrailingMetadata = std::move(metadata);
++ }
++
++ /*!
++ Returns the meta type of the RPC result message.
++ */
++ QMetaType QGrpcOperationContext::responseMetaType() const
++ {
++ Q_D(const QGrpcOperationContext);
++ return d->responseMetaType;
++ }
++
++ /*!
++ Stores the \a metaType of the RPC result message.
++ */
++ void QGrpcOperationContext::setResponseMetaType(QMetaType metaType)
++ {
++ Q_D(QGrpcOperationContext);
++ d->responseMetaType = metaType;
++ }
++
++ /*!
++ \since 6.11
++
++ Returns the unique identifier for this operation context.
++
++ Each ID is unique across all channels for the application lifetime.
++ */
++ quint64 QGrpcOperationContext::operationId() const noexcept
++ {
++ Q_D(const QGrpcOperationContext);
++ return d->operationId;
++ }
++
++ /*!
++ \since 6.13
++
++ Returns the number of bytes the channel has accepted for this operation
++ but not yet written to the transport.
++
++ \sa setBytesToWrite()
++ */
++ quint64 QGrpcOperationContext::bytesToWrite() const noexcept
++ {
++ Q_D(const QGrpcOperationContext);
++ return d->bytesToWrite;
++ }
++
++ /*!
++ \since 6.13
++
++ Stores the number of \a bytes the channel has accepted for this operation
++ but not yet written to the transport.
++
++ This function should be called by the channel whenever its outgoing queue
++ for this operation changes, so that clients can pace their writes against
++ the reported value.
++
++ \sa bytesToWrite()
++ */
++ void QGrpcOperationContext::setBytesToWrite(quint64 bytes)
++ {
++ Q_D(QGrpcOperationContext);
++ d->bytesToWrite = bytes;
++ }
++
++ const QGrpcOperation &QGrpcOperationContext::operation() const &
++ {
++ // Guaranteed by construction & parent<>child relationship
++ const auto *p = parent();
++ Q_ASSERT(p);
++ return static_cast<const QGrpcOperation &>(*p);
++ }
++
++ // For future extensions
++ bool QGrpcOperationContext::event(QEvent *event)
++ {
++ return QObject::event(event);
++ }
++
++ QT_END_NAMESPACE
++
++ #include "moc_qgrpcoperationcontext.cpp"