En esta página

Qt GRPC Guía para el cliente

La guía del cliente de « Qt GRPC ».

Métodos de servicio

En gRPC™, los métodos de servicio se pueden definir en un esquema Protobuf para especificar la comunicación entre clientes y servidores. El compilador de Protobuf, protoc, puede generar entonces las interfaces de servidor y cliente necesarias basándose en estas definiciones. gRPC admite cuatro tipos de métodos de servicio:

  • Llamadas unarias: el cliente envía una única solicitud y recibe una única respuesta.
    rpc UnaryCall (Request) returns (Response);

    El controlador de cliente correspondiente es QGrpcCallReply.

  • Transmisión del servidor: el cliente envía una única solicitud y recibe varias respuestas.
    rpc ServerStreaming (Request) returns (stream Response);

    El controlador de cliente correspondiente es QGrpcServerStream.

  • Transmisión del cliente: el cliente envía varias solicitudes y recibe una única respuesta.
    rpc ClientStreaming (stream Request) returns (Response);

    El controlador de cliente correspondiente es QGrpcClientStream.

  • Transmisión bidireccional: el cliente y el servidor intercambian varios mensajes.
    rpc BidirectionalStreaming (stream Request) returns (stream Response);

    El controlador de cliente correspondiente es QGrpcBidiStream.

gRPC La comunicación siempre la inicia el cliente, que inicia la llamada a procedimiento remoto (RPC) enviando el primer mensaje al servidor. A continuación, el servidor concluye cualquier tipo de comunicación devolviendo un ` StatusCode`.

Todos los controladores RPC de cliente derivan de la clase ` QGrpcOperation `, que proporciona funcionalidad compartida. Debido a la naturaleza asíncrona de las RPC, se gestionan de forma natural a través del mecanismo de señales y ranuras de Qt.

Una señal clave común a todos los controladores RPC es « finished », que indica la finalización de una RPC. El controlador emite esta señal exactamente una vez durante su ciclo de vida. Esta señal transmite el objeto « QGrpcStatus » correspondiente, que proporciona información adicional sobre el éxito o el fallo de la RPC.

También existen funcionalidades específicas de cada operación, como « messageReceived » para los mensajes entrantes, « writeMessage » para el envío de mensajes al servidor y « writesDone » para cerrar la comunicación del lado del cliente. La tabla siguiente resume las funcionalidades compatibles con los controladores de cliente RPC:

FuncionalidadQGrpcCallReplyQGrpcServerStreamQGrpcClientStreamQGrpcBidiStream
finished✓ (read: respuesta final)✓✓ (read respuesta final)✓
messageReceived✗✓✗✓
writeMessage✗✗✓✓
writesDone✗✗✓✓

Primeros pasos

Para utilizar la API de C++ de Qt GRPC, empieza por utilizar un esquema protobuf ya disponible o define uno propio. Utilizaremos el archivo clientguide.proto como ejemplo:

syntax = "proto3";
package client.guide; // enclosing namespace

message Request {
    int64 time = 1;
    sint32 num = 2;
}

message Response {
    int64 time = 1;
    sint32 num = 2;
}

service ClientGuideService {
    rpc UnaryCall (Request) returns (Response);
    rpc ServerStreaming (Request) returns (stream Response);
    rpc ClientStreaming (stream Request) returns (Response);
    rpc BidirectionalStreaming (stream Request) returns (stream Response);
}

Para utilizar este archivo .proto en nuestro cliente de Qt GRPC en C++, debemos ejecutar el compilador protoc con los complementos del generador de Qt. Afortunadamente, Qt proporciona las funciones de CMake qt_add_grpc y qt_add_protobuf para agilizar este proceso.

set(proto_files "${CMAKE_CURRENT_LIST_DIR}/../proto/clientguide.proto")

find_package(Qt6 COMPONENTS Protobuf Grpc)
qt_standard_project_setup(REQUIRES 6.9)

qt_add_executable(clientguide_client main.cpp interceptors.cpp)

# Using the executable as input target will append the generated files to it.
qt_add_protobuf(clientguide_client
    PROTO_FILES ${proto_files}
)
qt_add_grpc(clientguide_client CLIENT
    PROTO_FILES ${proto_files}
)

target_link_libraries(clientguide_client PRIVATE Qt6::Protobuf Qt6::Grpc)

Esto da lugar a la generación de dos archivos de cabecera en el directorio de compilación actual:

  • clientguide.qpb.h: Generado por qtprotobufgen. Declara los mensajes protobuf de Request y Response a partir del esquema.
  • clientguide_client.grpc.qpb.h: Generado por qtgrpcgen. Declara la interfaz de cliente para llamar a los métodos de un servidor gRPC que implementa el ClientGuideService a partir del esquema.

Se genera la siguiente interfaz de cliente:

namespace client::guide {
namespace ClientGuideService {

class Client : public QGrpcClientBase
{
    ...
    std::unique_ptr<QGrpcCallReply> UnaryCall(const client::guide::Request &arg);
    std::unique_ptr<QGrpcServerStream> ServerStreaming(const client::guide::Request &arg);
    std::unique_ptr<QGrpcClientStream> ClientStreaming(const client::guide::Request &arg);
    std::unique_ptr<QGrpcBidiStream> BidirectionalStreaming(const client::guide::Request &arg);
    ...
};

} // namespace ClientGuideService
} // namespace client::guide

Nota: Los usuarios son responsables de gestionar los controladores RPC únicos devueltos por la interfaz Client, asegurándose de que permanezcan activos al menos hasta que se emita la señal finished. Tras recibir esta señal, el controlador puede reasignarse o eliminarse de forma segura.

Configuración del servidor

La implementación del servidor para la interfaz ` ClientGuideService ` sigue un enfoque sencillo. Valida el campo ` time ` del mensaje de solicitud y devuelve el código de estado ` INVALID_ARGUMENT ` si la hora es futura:

const auto time = now();
if (request->time() > time)
    return { grpc::StatusCode::INVALID_ARGUMENT, "Request time is in the future!" };

Además, el servidor establece la hora actual en cada mensaje de respuesta:

response->set_num(request->num());
response->set_time(time);
return grpc::Status::OK;

En el caso de las solicitudes time válidas, los métodos del servicio se comportan de la siguiente manera:

  • UnaryCall: Responde con el campo « num » de la solicitud.
  • ServerStreaming: Envía respuestas « num » que coincidan con el mensaje de la solicitud.
  • ClientStreaming: Cuenta el número de mensajes de solicitud y establece este recuento como num.
  • BidirectionalStreaming: Responde inmediatamente con el campo « num » de cada mensaje de solicitud entrante.
Configuración del cliente

Comenzamos incluyendo los archivos de encabezado generados:

#include "clientguide.qpb.h"
#include "clientguide_client.grpc.qpb.h"

Para este ejemplo, creamos la clase « ClientGuide » para gestionar todas las comunicaciones, lo que facilita su comprensión. Empezamos configurando la columna vertebral de todas las comunicaciones de « gRPC »: un canal.

channel = std::make_shared<QGrpcHttp2Channel>(
    QUrl("http://localhost:50056")
    /* without channel options. */
);
ClientGuide clientGuide(channel);

La biblioteca Qt GRPC ofrece QGrpcHttp2Channel, que puedes attach a la interfaz de cliente generada:

explicit ClientGuide(std::shared_ptr<QAbstractGrpcChannel> channel)
{
    m_client.attachChannel(std::move(channel));
}

Con esta configuración, el cliente se comunicará a través de HTTP/2 utilizando TCP como protocolo de transporte. La comunicación no estará cifrada (es decir, sin configuración SSL/TLS).

Creación de un mensaje de solicitud

A continuación se muestra una sencilla envoltura para crear mensajes de solicitud:

static guide::Request createRequest(int32_t num,
                                    ExpectedResult expected = ExpectedResult::Success)
{
    guide::Request request;
    request.setNum(num);
    // The server-side logic fails the RPC if the time is in the future.
    const auto time = expected == ExpectedResult::Failure ?
        std::numeric_limits<int64_t>::max() : now();
    request.setTime(time);
    return request;
}

Esta función toma un entero y un valor booleano opcional. Por defecto, sus mensajes utilizan la hora actual, por lo que la lógica del servidor debería aceptarlos. Sin embargo, cuando se invoca con ` fail ` establecido en ` true`, genera mensajes que el servidor rechazará.

RPC de un solo uso

Existen diferentes paradigmas para trabajar con los controladores de cliente RPC. En concreto, puedes optar por un diseño basado en clases, en el que el controlador RPC es un miembro de la clase que lo engloba, o bien puedes gestionar el ciclo de vida del controlador RPC mediante la señal « finished ».

Hay dos aspectos importantes que hay que tener en cuenta al aplicar el paradigma de «un solo disparo». El código que aparece a continuación muestra cómo funcionaría para llamadas unarias, pero es igual para cualquier otro tipo de RPC.

std::unique_ptr<QGrpcCallReply> reply = m_client.UnaryCall(requestMessage);
const auto *replyPtr = reply.get(); // 1
QObject::connect(
    replyPtr, &QGrpcCallReply::finished, replyPtr,
    [reply = std::move(reply)](const QGrpcStatus &status) {
        ...
    },
    Qt::SingleShotConnection        // 2
);
  • 1: Dado que gestionamos el ciclo de vida del único objeto RPC dentro de la lambda, trasladarlo al ámbito de captura de la lambda invalidaría ` get() ` y otras funciones miembro. Por lo tanto, debemos copiar la dirección de los punteros antes de trasladarlo.
  • 2: La señal « finished » solo se emite una vez, lo que convierte a esta conexión en una auténtica conexión de «single-shot». Es importante marcar esta conexión como « SingleShotConnection »! De lo contrario, la captura de « reply » no se destruirá, lo que provocará una fuga de memoria oculta difícil de detectar.

El argumento SingleShotConnection en la llamada a connect garantiza que el functor de la ranura (el lambda) se destruya tras ser emitido, liberando así los recursos asociados a la ranura, incluidas sus capturas.

Llamadas a procedimientos remotos

Llamadas unarias

Las llamadas unarias solo requieren gestionar la señal « finished ». Cuando se emite esta señal, podemos comprobar el « status » de la RPC para determinar si se ha realizado correctamente. Si es así, podemos « read » la única y última respuesta del servidor.

En este ejemplo, utilizamos el paradigma «single-shot». Asegúrate de leer atentamente la sección «RPC de un solo disparo ».

void unaryCall(const guide::Request &request, const QGrpcCallOptions&opts = { })
{
    std::unique_ptr<QGrpcCallReply> reply = m_client.UnaryCall(request, opts);
    const auto *replyPtr = reply.get();
    connect(
        replyPtr, &QGrpcCallReply::finished, replyPtr,
        [reply = std::move(reply)](const QGrpcStatus&status) {
            if (status.isOk()) {
                if (const auto response = reply->read<guide::Response>())
                    qDebug() << "Client (UnaryCall) finished, received:" << *response;
               sino
                    qDebug("Client (UnaryCall) deserialization failed");
            } else {
                qDebug() << "Client (UnaryCall) failed:" << status;
            }
        },
        Qt::SingleShotConnection);
}

La función inicia el RPC invocando la función miembro ` UnaryCall ` de la interfaz de cliente generada ` m_client`. El ciclo de vida se gestiona exclusivamente mediante la señal ` finished `.

Ejecución del código

En ` main`, simplemente invocamos esta función tres veces, dejando que la segunda invocación falle:

clientGuide.unaryCall(ClientGuide::createRequest(1));
clientGuide.unaryCall(ClientGuide::createRequest(2, ExpectedResult::Failure));
clientGuide.unaryCall(ClientGuide::createRequest(3));

Un posible resultado de la ejecución podría ser el siguiente:

Welcome to the clientguide!
Starting the server process ...
    Server listening on: localhost:50056
    Server (UnaryCall): Request( time: 1733498584776, num: 1 )
    Server (UnaryCall): Request( time: 9223372036854775807, num: 2 )
    Server (UnaryCall): Request( time: 1733498584776, num: 3 )
Client (UnaryCall) finished, received: Response( time:  1733498584778257 , num:  1  )
Client (UnaryCall) failed: QGrpcStatus( code: QtGrpc::StatusCode::InvalidArgument, message: "Request time is in the future!" )
Client (UnaryCall) finished, received: Response( time:  1733498584778409 , num:  3  )

Vemos que el servidor recibe los tres mensajes, y que el segundo contiene un valor elevado en el campo «time». En el lado del cliente, la primera y la última llamada devolvieron un código de estado « Ok », pero el segundo mensaje falló con el código de estado « InvalidArgument » debido a que la hora del mensaje se situaba en el futuro.

Transmisión por servidor

En una transmisión del servidor, el cliente envía una solicitud inicial y el servidor responde con uno o más mensajes. Además de la señal « finished », también hay que gestionar la señal « messageReceived ».

En este ejemplo, utilizamos el paradigma «single-shot» para gestionar el ciclo de vida del RPC de streaming. Asegúrate de leer atentamente la sección «RPC de un solo disparo ».

Al igual que con cualquier RPC, primero nos conectamos a la señal « finished »:

void serverStreaming(const guide::Request &initialRequest)
{
    std::unique_ptr<QGrpcServerStream> stream = m_client.ServerStreaming(initialRequest);
    const auto *streamPtr = stream.get();

    connect(
        streamPtr, &QGrpcServerStream::finished, streamPtr,
        [stream = std::move(stream)](const QGrpcStatus&status) {
            if (status.isOk())
                qDebug("Client (ServerStreaming) finished");
           sino
                qDebug() << "Client (ServerStreaming) failed:" << status;
        },
        Qt::SingleShotConnection);

Para gestionar los mensajes del servidor, nos conectamos a la señal « messageReceived » y, cuando se emite la señal, « read » la respuesta.

    connect(streamPtr, &QGrpcServerStream::messageReceived, streamPtr, [streamPtr] {
        if (const auto response = streamPtr->read<guide::Response>())
            qDebug() << "Client (ServerStream) received:" << *response;
       sino
            qDebug("Client (ServerStream) deserialization failed");
    });
}
Ejecución del código

La lógica del servidor devuelve al cliente la cantidad recibida en la solicitud inicial. Creamos dicha solicitud e invocamos la función.

clientGuide.serverStreaming(ClientGuide::createRequest(3));

Un posible resultado de la ejecución del servidor podría ser el siguiente:

Welcome to the clientguide!
Starting the server process ...
    Server listening on: localhost:50056
    Server (ServerStreaming): Request( time: 1733504435800, num: 3 )
Client (ServerStream) received: Response( time:  1733504435801724 , num:  0  )
Client (ServerStream) received: Response( time:  1733504435801871 , num:  1  )
Client (ServerStream) received: Response( time:  1733504435801913 , num:  2  )
Client (ServerStreaming) finished

Una vez que el servidor se inicia, recibe una solicitud con un valor de «num» igual a 3 y responde con tres mensajes « Response » antes de finalizar la comunicación.

Transmisión del cliente

En una transmisión de cliente, el cliente envía una o más solicitudes y el servidor responde con una única respuesta final. Se debe gestionar la señal « finished », y los mensajes se pueden enviar utilizando la función « writeMessage ». A continuación, se puede utilizar la función « writesDone » para indicar que el cliente ha terminado de escribir y que no se enviarán más mensajes.

Utilizamos un enfoque basado en clases para interactuar con el RPC de flujo continuo, incorporando el controlador como miembro de la clase. Al igual que con cualquier RPC, nos conectamos a la señal « finished »:

void clientStreaming(const guide::Request &initialRequest)
{
    m_clientStream = m_client.ClientStreaming(initialRequest);
   for (int32_t i = 1; i < 3;++i)
        m_clientStream->writeMessage(createRequest(initialRequest.num() + i));
    m_clientStream->writesDone();

    connect(m_clientStream.get(), &QGrpcClientStream::finished, m_clientStream.get(),
        [this](const QGrpcStatus&status) {
            if (status.isOk()) {
                if (const auto response = m_clientStream->read<guide::Response>()) {
                    qDebug() << "Client (ClientStreaming) finished, received:"
                            << *respuesta;
                }
                m_clientStream.reset();
            } else {
                qDebug() << "Client (ClientStreaming) failed:" << status;
                qDebug("Restarting the client stream");
                clientStreaming(createRequest(0));
            }
        });
}

La función inicia la transmisión del cliente con un mensaje inicial. A continuación, sigue escribiendo dos mensajes adicionales antes de señalar el fin de la comunicación llamando a ` writesDone`. Si la RPC de transmisión se realiza correctamente, ` read ` la respuesta final del servidor y ` reset ` el objeto RPC. Si el RPC falla, lo reintentamos invocando la misma función, que sobrescribe el miembro ` m_clientStream ` y vuelve a conectar la señal ` finished `. No podemos limitarnos a reasignar el miembro ` m_clientStream ` dentro de la lambda, ya que así se perdería la conexión necesaria.

Ejecución del código

En main, invocamos la función clientStreaming con un mensaje erróneo, lo que provoca un fallo de RPC y ejecuta la lógica de reintento.

clientGuide.clientStreaming(ClientGuide::createRequest(0, ExpectedResult::Failure));

Un posible resultado de ejecutar la transmisión del cliente podría ser el siguiente:

Welcome to the clientguide!
Starting the server process ...
    Server listening on: localhost:50056
    Server (ClientStreaming): Request( time: 9223372036854775807, num: 0 )
Client (ClientStreaming) failed: QGrpcStatus( code: QtGrpc::StatusCode::InvalidArgument, message: "Request time is in the future!" )
Restarting the client stream
    Server (ClientStreaming): Request( time: 1733912946696, num: 0 )
    Server (ClientStreaming): Request( time: 1733912946697, num: 1 )
    Server (ClientStreaming): Request( time: 1733912946697, num: 2 )
Client (ClientStreaming) finished, received: Response( time:  1733912946696922 , num:  3  )

El servidor recibe un mensaje inicial que provoca un fallo en la RPC, lo que activa la lógica de reintento. El reintento inicia la RPC con un mensaje válido, tras lo cual se envían tres mensajes al servidor antes de completarse correctamente.

Transmisión bidireccional

La transmisión bidireccional ofrece la mayor flexibilidad, ya que permite tanto al cliente como al servidor enviar y recibir mensajes simultáneamente. Requiere que se gestionen las señales « finished » y « messageReceived », y proporciona la funcionalidad de escritura a través de « writeMessage ».

Utilizamos un enfoque basado en clases con conexiones de ranura de funciones miembro para demostrar la funcionalidad, incorporando el controlador como miembro de la clase. Además, utilizamos la función « read » basada en punteros. Los dos miembros utilizados son:

std::unique_ptr<QGrpcBidiStream> m_bidiStream;
guide::Response m_bidiResponse;

Creamos una función para iniciar la transmisión bidireccional a partir de un mensaje inicial y conectamos las funciones de ranura a las señales respectivas finished y messageReceived.

void bidirectionalStreaming(const guide::Request &initialRequest)
{
    m_bidiStream = m_client.BidirectionalStreaming(initialRequest);
    connect(m_bidiStream.get(), &QGrpcBidiStream::finished, this, &ClientGuide::bidiFinished);
    connect(m_bidiStream.get(), &QGrpcBidiStream::messageReceived, this,
            &ClientGuide::bidiMessageReceived);
}

El funcionamiento de las ranuras es sencillo. La ranura finished simplemente muestra y restablece el objeto RPC:

void bidiFinished(const QGrpcStatus&status)
{
    if (status.isOk())
        qDebug("Client (BidirectionalStreaming) finished");
   sino
        qDebug() << "Client (BidirectionalStreaming) failed:" << status;
    m_bidiStream.reset();
}

La ranura messageReceived read en el miembro m_bidiResponse, y continúa escribiendo mensajes hasta que el número de respuestas recibidas llega a cero. En ese momento, cerramos parcialmente la comunicación del lado del cliente utilizando writesDone.

void bidiMessageReceived()
{
    if (m_bidiStream->read(&m_bidiResponse)) {
        qDebug() << "Client (BidirectionalStreaming) received:" << m_bidiResponse;
       if (m_bidiResponse.num() > 0) {
            m_bidiStream->writeMessage(createRequest(m_bidiResponse.num() - 1));
            return;
        }
    } else {
        qDebug("Client (BidirectionalStreaming) deserialization failed");
    }
    m_bidiStream->writesDone();
}
Ejecución del código

La lógica del servidor simplemente devuelve un mensaje en cuanto lee algo, creando una respuesta con el número de la solicitud. En main creamos dicha solicitud, que en última instancia sirve como contador.

clientGuide.bidirectionalStreaming(ClientGuide::createRequest(3));

Un posible resultado de la ejecución de la transmisión bidireccional podría ser el siguiente:

Welcome to the clientguide!
Starting the server process ...
    Server listening on: localhost:50056
    Server (BidirectionalStreaming): Request( time: 1733503832107, num: 3 )
Client (BidirectionalStreaming) received: Response( time:  1733503832108708 , num:  3  )
    Server (BidirectionalStreaming): Request( time: 1733503832109, num: 2 )
Client (BidirectionalStreaming) received: Response( time:  1733503832109024 , num:  2  )
    Server (BidirectionalStreaming): Request( time: 1733503832109, num: 1 )
Client (BidirectionalStreaming) received: Response( time:  1733503832109305 , num:  1  )
    Server (BidirectionalStreaming): Request( time: 1733503832109, num: 0 )
Client (BidirectionalStreaming) received: Response( time:  1733503832109529 , num:  0  )
Client (BidirectionalStreaming) finished

Interceptores de ClientGuide

Para obtener una introducción al mecanismo de interceptación y a cómo las interfaces de interceptor participan en el ciclo de vida de una RPC, consulta la Descripción general de los interceptores deQt GRPC .

El ejemplo de la guía del cliente muestra tres interceptores combinados en una única cadena:

  • Un interceptor de métricas que registra estadísticas de RPC e inyecta un identificador de seguimiento.
  • Un interceptor de autenticación que adjunta un token de portador.
  • Un interceptor de saneamiento que valida y normaliza los mensajes.

En conjunto, demuestran cómo los interceptores pueden observar, modificar y validar el tráfico RPC en diferentes etapas del ciclo de vida de la llamada.

Interceptor de métricas

El interceptor de métricas se sitúa en primer lugar en la cadena para poder observar todo el ciclo de vida del RPC. Registra estadísticas básicas, como el tamaño de las cargas útiles recibidas, la duración de las llamadas RPC y el recuento de éxitos o fallos para cada método RPC.

class MetricsInterceptor final : public QGrpcStartInterceptor,
                                 public QGrpcMessageReceivedInterceptor,
                                 public QGrpcFinishedInterceptor
{
public:
    ~MetricsInterceptor() override;

    Continuation onStart(QGrpcInterceptionContext &context,
                         QProtobufMessage &message,
                         QGrpcCallOptions &callOptions) override;

    void onMessageReceived(QGrpcInterceptionContext &context,
                           QByteArray &messageData) override;

    void onFinished(QGrpcInterceptionContext &context,
                    QGrpcStatus &status) override;

private:
    using Clock = std::chrono::steady_clock;
    using Ms = std::chrono::duration<double, std::milli>;

    struct RpcMetrics {
        quint64 bytesReceived = 0;
        quint64 completed = 0;
        quint64 failed = 0;
        QList<double> durations;
    };

    QHash<quint64, Clock::time_point> m_activeRPCs;
    QMap<QtGrpc::RpcDescriptor, RpcMetrics> m_metrics;
};
Implementación del interceptor de métricas

Cuando se inicia una RPC, el interceptor registra la marca de tiempo actual y la almacena utilizando el identificador de seguimiento único ( operationId ) como clave. También se añade un identificador de seguimiento a los metadatos salientes para que la llamada pueda correlacionarse entre servicios.

QGrpcStartInterceptor::Continuation
MetricsInterceptor::onStart(QGrpcInterceptionContext &context,
                            QProtobufMessage & /*message*/,
                            QGrpcCallOptions &callOptions)
{
    m_activeRPCs.insert(context.operationId(), std::chrono::steady_clock::now());
    callOptions.addMetadata("x-trace-id"_L1, QUuid::createUuid().toByteArray());

    return Continuation::Proceed;
}

void MetricsInterceptor::onMessageReceived(QGrpcInterceptionContext &context,
                                           QByteArray &messageData)
{
    m_metrics[context.descriptor()].bytesReceived += messageData.size();
}

void MetricsInterceptor::onFinished(QGrpcInterceptionContext &context,
                                    QGrpcStatus &status)
{
    const auto it = m_activeRPCs.find(context.operationId());
    Q_ASSERT(it != m_activeRPCs.cend());

    const auto duration = Ms(Clock::now() - it.value()).count();
    m_activeRPCs.erase(it);

    auto &metrics = m_metrics[context.descriptor()];
    if (!status.isOk()) {
        ++metrics.failed;
        return;
    }
    ++metrics.completed;
    metrics.durations.append(duration);
}

Mientras la RPC está activa, los mensajes entrantes contribuyen a las métricas recopiladas al acumular el número de bytes de carga útil recibidos.

Cuando finaliza el RPC, el interceptor calcula la duración total y actualiza las estadísticas agregadas por descriptor de RPC.

A efectos de demostración, las métricas recopiladas se muestran cuando se destruye la instancia del interceptor.

MetricsInterceptor::~MetricsInterceptor()
{
    Q_ASSERT(m_activeRPCs.isEmpty());
    const auto keys = m_metrics.keys();
    for (const auto &k: keys) {
        qInfo() << "Metrics for:" << k;
       const auto &m = m_metrics[k];
        qInfo() << "  Bytes received    :" << m.bytesReceived;
        qInfo() << "  Failed RPCs       :" << m.failed;
        qInfo() << "  Completed RPCs    :" << m.completed;
        qInfo() << "  Completed Durations (ms):" << m.durations;
    }
}
Interceptor de autenticación

El interceptor de autenticación adjunta un token de portador a las llamadas RPC salientes. Si la aplicación ya proporciona un encabezado « authorization », el interceptor lo deja sin cambios.

Si el servidor notifica un error de autenticación, el interceptor actualiza el token para que las llamadas RPC posteriores utilicen las credenciales actualizadas.

class TokenProvider
{
public:
    TokenProvider();
    QByteArray token();
    void refresh();

private:
    QByteArray m_token;
};

class AuthInterceptor final : public QGrpcStartInterceptor,
                              public QGrpcTrailingMetadataInterceptor,
                              public QGrpcFinishedInterceptor
{
public:
    Continuation onStart(QGrpcInterceptionContext &context,
                         QProtobufMessage &message,
                         QGrpcCallOptions &callOptions) override;

    void onTrailingMetadata(QGrpcInterceptionContext &context,
                            QMultiHash<QByteArray, QByteArray> &metadata) override;

    void onFinished(QGrpcInterceptionContext &context,
                    QGrpcStatus &status) override;

private:
    TokenProvider m_tokenProvider;
    QByteArray m_serverAuthHint;
};
Implementación del interceptor de autenticación

El TokenProvider encapsula la gestión de tokens. En este ejemplo, genera una cadena de token simplificada con fines meramente demostrativos. No representa un token de autenticación real. En aplicaciones reales, los tokens se obtendrían y actualizarían normalmente a través de un sistema de identidad externo encargado de emitir y gestionar los tokens de autenticación.

TokenProvider::TokenProvider() { refresh(); }
QByteArray TokenProvider::token() { return m_token; }
void TokenProvider::refresh()
{
    // NOTE: This is NOT a real JWT or secure token.
    // It only mimics the structure: header.payload.signature
    // The payload is just a timestamp used for expiry checks.
    auto header = R"({"alg":"none","typ":"JWT"})"_ba; // fake header
    auto payload = QByteArray::number(now()); // fake "iat"
    auto signature = "no_signature"_ba; // fake signing

    m_token = header + '.' + payload + '.' + signature;
}

En el lado del servidor, las llamadas entrantes validan los metadatos del « authorization ». Si la validación falla, el servidor devuelve un estado « Unauthenticated » y proporciona información adicional en los metadatos finales.

if (auto authStatus = validateAuth(context); !authStatus.ok())
    return authStatus;

Cuando se inicia una RPC, el interceptor comprueba si la llamada ya contiene un encabezado authorization. Si no es así, adjunta un token de portador a los metadatos salientes.

Se revisan los metadatos finales en busca de indicaciones de autenticación devueltas por el servidor. Si están presentes, la indicación se almacena para que pueda notificarse en caso de que la llamada falle finalmente con un error de autenticación.

Cuando el RPC finaliza con un estado « Unauthenticated », el interceptor actualiza el token. En este ejemplo, la actualización simplemente regenera un token con la nueva hora actual. En situaciones reales, esto implicaría solicitar un nuevo token a un sistema de identidad externo.

QGrpcStartInterceptor::Continuación
AuthInterceptor::onStart(QGrpcInterceptionContext& /*context*/,
                         QProtobufMessage& /*mensaje*/,
                         QGrpcCallOptions&callOptions)
{
    constexpr QByteArrayView AuthKey("authorization");

    if (!callOptions.metadata(QtGrpc::MultiValue).contains(AuthKey))
        callOptions.addMetadata(AuthKey, "Bearer " + m_tokenProvider.token());

    return Continuation::Proceed;
}

void AuthInterceptor::onTrailingMetadata(QGrpcInterceptionContext& /*contexto*/,
                                         QMultiHash<QByteArray, QByteArray> &metadata)
{
    constexpr QByteArrayView AuthErrorKey("www-authenticate");
    const auto it = metadata.constFind(AuthErrorKey);
   if (it== metadata.cend())
        return;
    m_serverAuthHint = it.value();
}

void AuthInterceptor::onFinished(QGrpcInterceptionContext& /*context*/, QGrpcStatus&status)
{
    // Solo gestionar los códigos de estado de «No autenticado».
    if (status.code() != QtGrpc::StatusCode::Unauthenticated)
        return;

    qDebug("[AuthInterceptor] Refreshing token for next call");
   // NOTA: Se ha simplificado a modo de ejemplo. Los tokens reales se obtienen mediante el flujo de autenticación adecuado.
    m_tokenProvider.refresh();
    if (!m_serverAuthHint.isEmpty()) {
        status = QGrpcStatus{ status.code(), status.message() + u", Sugerencia: "_s + m_serverAuthHint };
        m_serverAuthHint.clear();
    }
}
Interceptor de saneamiento

El interceptor de saneamiento valida y normaliza los datos de las solicitudes y las respuestas. Muestra cómo los interceptores pueden aplicar restricciones básicas del lado del cliente antes de que se envíen los mensajes y después de que se reciban las respuestas.

En este ejemplo, el interceptor limita los valores de la solicitud a rangos aceptables, normaliza las marcas de tiempo y rechaza las llamadas cuyos metadatos superen un límite de tamaño predefinido.

class SanitizingInterceptor final : public QGrpcStartInterceptor,
                                    public QGrpcWriteMessageInterceptor,
                                    public QGrpcMessageReceivedInterceptor
{
public:
    Continuation onStart(QGrpcInterceptionContext &context,
                         QProtobufMessage &message,
                         QGrpcCallOptions &callOptions) override;

    void onWriteMessage(QGrpcInterceptionContext &context,
                        QProtobufMessage &message) override;

    void onMessageReceived(QGrpcInterceptionContext &context,
                           QByteArray &messageData) override;
};
Implementación del interceptor de saneamiento

Se utilizan funciones auxiliares para calcular el tamaño total de los metadatos y para aplicar reglas básicas de normalización a los mensajes de solicitud y respuesta.

qsizetype getTotalBytes(const QMultiHash<QByteArray, QByteArray> &md)
{
    qsizetype total = 0;
    for (const auto &[k, v] : md.asKeyValueRange())
        total += k.size() + v.size();
    return total;
}

template <typename T>
void sanitizeMessage(T &request)
{
    const auto num = request.num();
    if (num < 0 || num > 5)
        request.setNum(qBound(0, num, 5));

    const auto time = request.time();
    const auto currentTime = now();
    if (time < 0 || time > currentTime)
        request.setTime(qMax(0, currentTime));
}

Cuando se inicia una RPC, el interceptor comprueba en primer lugar que los metadatos salientes no superen el tamaño permitido. Si se supera el límite, la llamada se interrumpe devolviendo Continuation::Drop

Si el mensaje de solicitud coincide con el tipo esperado, sus campos se depuran antes de enviar la RPC.

En el caso de las llamadas de streaming, los mensajes salientes también se depuran en el gancho « onWriteMessage ».

Por último, se interceptan las respuestas entrantes. La carga útil serializada se deserializa, se normaliza y se vuelve a serializar antes de entregarse a la aplicación.

QGrpcStartInterceptor::Continuación
SanitizingInterceptor::onStart(QGrpcInterceptionContext&context, QProtobufMessage&message,
                               QGrpcCallOptions&callOptions)
{
    constexpr quint16 MaxMetadata = 1024 * 8; // 8 KiB
    auto totalMdBytes = getTotalBytes(callOptions.metadata(QtGrpc::MultiValue));
    if (totalMdBytes > MaxMetadata) {
        qDebug() << "[Sanitizing] Aborting call with metadata size of" << totalMdBytes << "bytes";
       return Continuation::Drop;
    }

    onWriteMessage(context, message);

    return Continuation::Proceed;
}

void SanitizingInterceptor::onWriteMessage(QGrpcInterceptionContext& /*context*/,
                                           QProtobufMessage&message)
{
    // Para gestionar situaciones más complejas con distintos tipos de mensajes de solicitud,
    // lo más adecuado sería realizar una ramificación en función de context.descriptor() según corresponda.
   if (auto *request = qprotobufmessage_cast<client::guide::Request *>(&message))
        sanitizeMessage(*request);
}

void SanitizingInterceptor::onMessageReceived(QGrpcInterceptionContext&context,
                                              QByteArray&messageData)
{
    // messageData solo puede ser de tipo client::guide::Response. Para  un
    // manejo  más  complejo, añade el tratamiento adecuado mediante context.descriptor().
    // Ten en cuenta que la deserialización y la serialización introducen una sobrecarga.
    client::guide::Response response;
   auto serializer = context.channel().serializer();
    if (serializer->deserialize(&response, messageData))
        return;
    sanitizeMessage(response);
    messageData = serializer->serialize(&response);
}
Uso del interceptor

Construye la cadena de interceptores en una función auxiliar y devuélvela al llamante.

inline QGrpcInterceptorChain createInterceptors()
{
    QGrpcInterceptorChain chain;
    chain.set(
        std::make_unique<MetricsInterceptor>(),
        std::make_unique<AuthInterceptor>(),
        std::make_unique<SanitizingInterceptor>()
    );
    return chain;
}

Antes de asociar la cadena al canal, comprueba que se haya rellenado correctamente (por ejemplo, comprobando isEmpty()) y aplica una estrategia adecuada de gestión de errores si la creación ha fallado.

auto interceptors = createInterceptors();
if (interceptors.isEmpty()) {
    qWarning("Failed to create the interceptor chain");
   return EXIT_FAILURE; // o cualquier otra alternativa adecuada
}
channel = std::make_shared<QGrpcHttp2Channel>(
    QUrl("http://localhost:50056"),
    std::move(interceptors)
);

En el caso de las llamadas unarias, el ejemplo programa una secuencia de peticiones con un breve retraso entre ellas. Esto facilita la observación de cómo los interceptores afectan a las llamadas sucesivas: se añaden metadatos de rastreo, los fallos de autenticación actualizan el token para peticiones posteriores y los metadatos no válidos pueden provocar que una llamada se descarte antes de ser enviada.

int delayMs = 150;
for (int i = 1; i < 6; ++i) {
    QTimer::singleShot(delayMs, [&, i] {
        auto expected = i % 2 == 0 ? ExpectedResult::Failure : ExpectedResult::Success;
        clientGuide.unaryCall(ClientGuide::createRequest(i, expected));
    });
    delayMs += 150;
}
QTimer::singleShot(delayMs, [&] {
    QGrpcCallOptions invalidOpts;
    invalidOpts.addMetadata("huge_key"_ba, "huge_value"_ba.repeated(8'000));
    clientGuide.unaryCall(guide::Request{ }, invalidOpts); // this call will fail.
});
delayMs += 150;

El ejemplo también realiza una RPC de streaming bidireccional. La implementación de bidirectionalStreaming() normalmente intercambiaría mensajes « 666 », pero el interceptor de saneamiento limita los valores de las solicitudes para que el flujo termine tras cinco intercambios.

QTimer::singleShot(delayMs, [&] {
    clientGuide.bidirectionalStreaming(ClientGuide::createRequest(666));
});
Ejecución del código

Ejecuta clientguide_client con la opción -I para habilitar la compatibilidad con los interceptores. A continuación se muestra un posible resultado:

Welcome to the clientguide!
Running with Interceptor support
Starting the server process ...
    Server listening on: localhost:50056
    Server (UnaryCall): Request( time: 1774360832277, num: 1 ), Metadata: { x-trace-id: {360bb041-9ab5-4940-95c1-0d4c89491570} }
Client (UnaryCall) finished, received: Response( time: 1774360832278, num: 1 )
    Server (UnaryCall): Request( time: 1774360832427, num: 2 ), Metadata: { x-trace-id: {01817a8f-9f0e-404e-a21c-767f81e74a2d} }
Client (UnaryCall) finished, received: Response( time: 1774360832429, num: 2 )
    Server (UnaryCall): Request( time: 1774360832577, num: 3 ), Metadata: { x-trace-id: {78cb336f-0396-4bbc-b1ee-59914651feef} }
Client (UnaryCall) finished, received: Response( time: 1774360832578, num: 3 )
[AuthInterceptor] Refreshing token for next call
Client (UnaryCall) failed: QGrpcStatus( code: QtGrpc::StatusCode::Unauthenticated, message: "Token expired with age: 603 ms, Hint: Bearer realm=\"clientguide\", error=\"invalid_token\"" )
    Server (UnaryCall): Request( time: 1774360832876, num: 5 ), Metadata: { x-trace-id: {63a40327-2f46-43c4-9e2c-44b67f297bd2} }
Client (UnaryCall) finished, received: Response( time: 1774360832877, num: 5 )
[Sanitizing] Aborting call with metadata size of 80129 bytes
Client (UnaryCall) failed: QGrpcStatus( code: QtGrpc::StatusCode::Aborted, message: "Interceptors dropped the call" )
    Server (BidirectionalStreaming) accepted call, Metadata: { x-trace-id: {fc945bdb-5c8a-4c65-8bfb-8655800d5774} }
    Server (BidirectionalStreaming): Request( time: 1774360833177, num: 5 )
Client (BidirectionalStreaming) received: Response( time: 1774360833178, num: 5 )
    Server (BidirectionalStreaming): Request( time: 1774360833178, num: 4 )
Client (BidirectionalStreaming) received: Response( time: 1774360833179, num: 4 )
    Server (BidirectionalStreaming): Request( time: 1774360833179, num: 3 )
Client (BidirectionalStreaming) received: Response( time: 1774360833179, num: 3 )
    Server (BidirectionalStreaming): Request( time: 1774360833179, num: 2 )
Client (BidirectionalStreaming) received: Response( time: 1774360833180, num: 2 )
    Server (BidirectionalStreaming): Request( time: 1774360833180, num: 1 )
Client (BidirectionalStreaming) received: Response( time: 1774360833180, num: 1 )
    Server (BidirectionalStreaming): Request( time: 1774360833180, num: 0 )
Client (BidirectionalStreaming) received: Response( time: 1774360833180, num: 0 )
Client (BidirectionalStreaming) finished
All operations completed! Automatically shutting down...
Metrics for: QtGrpc::RpcDescriptor( service: "client.guide.ClientGuideService", method: "BidirectionalStreaming", type: QtGrpc::RpcType::BidiStreaming )
Bytes received    : 52
Failed RPCs       : 0
Completed RPCs    : 1
Completed Durations (ms): QList(3.97233)
Metrics for: QtGrpc::RpcDescriptor( service: "client.guide.ClientGuideService", method: "UnaryCall", type: QtGrpc::RpcType::UnaryCall )
Bytes received    : 36
Failed RPCs       : 2
Completed RPCs    : 4
Completed Durations (ms): QList(1.937, 1.90971, 1.624, 1.50429)

La salida muestra la cadena de interceptores en acción. Las llamadas unarias salientes llegan al servidor con metadatos de seguimiento añadidos por el interceptor de métricas. Cuando el servidor notifica un fallo de autenticación, el interceptor de autenticación actualiza el token para las llamadas posteriores y amplía el mensaje de error con la indicación proporcionada por el servidor. Una llamada posterior es rechazada localmente por el interceptor de saneamiento porque sus metadatos superan el límite configurado. La llamada de streaming bidireccional muestra que los interceptores también se aplican a las RPC de streaming: el interceptor de saneamiento limita el valor de la solicitud, por lo que el streaming finaliza tras cinco intercambios de mensajes en lugar de continuar desde 666. Por último, cuando el cliente se apaga, el interceptor de métricas muestra las estadísticas recopiladas para cada método RPC.

Proyecto de ejemplo en code.qt.io

© 2026 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.