Quality: Silver Tier.

🐙 userver provides sqs::JsonClient, an Amazon SQS-compatible client for the AWS JSON protocol.

The client uses AWS SDK SQS request/result types (Aws::SQS::Model::*) and sends HTTP through clients::http::Client. It does not inherit Aws::SQS::SQSClient and does not use the AWS HTTP client or AWS thread-pool async API.

#include <userver/sqs/json_client.hpp>
 
#include <aws/sqs/model/SendMessageRequest.h>

Build

Enable the library when building userver (USERVER_FEATURE_SQS, off by default). See Build options.

In a service:

find_package(userver COMPONENTS core sqs REQUIRED)

target_link_libraries(${PROJECT_NAME} userver::sqs)

The library depends on AWS SDK core/sqs and userver::core.

Lifetime

Aws::InitAPI is not required: the client uses AWS request/result types as DTOs and signs requests with userver crypto. JsonClient does not own the HTTP client; clients::http::Client must outlive it.

Call SQS methods from a userver coroutine: they perform HTTP via clients::http::Request::perform().

    sqs::ClientSettings settings;
    settings.endpoint = "https://sqs.example.com";
    settings.region = "us-east-1";
    settings.timeout = std::chrono::seconds{30};
 
    const sqs::Credentials credentials{
        .access_key_id = "access-key",
        .secret_key = "secret-key",
    };
 
    sqs::JsonClient client{http_client, credentials, settings};

Configuration

JsonClient takes clients::http::Client&, sqs::Credentials and sqs::ClientSettings.

endpoint : SQS-compatible JSON API URL. Required.

region : Signing region for SigV4. Required.

timeout : Whole HTTP request timeout, including long polling on ReceiveMessage.

verify_ssl : TLS certificate verification for the userver HTTP client.

If credentials are non-empty, requests are signed with AWS SigV4 using userver crypto. If they are empty, the request is sent unsigned.

Example

    namespace model = Aws::SQS::Model;
 
    model::CreateQueueRequest create_request;
    create_request.SetQueueName("orders");
 
    const auto create_outcome = client.CreateQueue(create_request);
    if (!create_outcome.IsSuccess()) {
        throw std::runtime_error{create_outcome.GetError().GetMessage()};
    }
 
    const auto queue_url = create_outcome.GetResult().GetQueueUrl();
 
    model::SendMessageRequest send_request;
    send_request.SetQueueUrl(queue_url);
    send_request.SetMessageBody(R"({"order_id":"42"})");
 
    const auto send_outcome = client.SendMessage(send_request);
    if (!send_outcome.IsSuccess()) {
        throw std::runtime_error{send_outcome.GetError().GetMessage()};
    }
 
    model::ReceiveMessageRequest receive_request;
    receive_request.SetQueueUrl(queue_url);
    receive_request.SetMaxNumberOfMessages(1);
    receive_request.SetWaitTimeSeconds(5);
 
    const auto receive_outcome = client.ReceiveMessage(receive_request);
    if (!receive_outcome.IsSuccess()) {
        throw std::runtime_error{receive_outcome.GetError().GetMessage()};
    }

Supported Operations

The client currently implements the JSON protocol for:

AddPermission, ChangeMessageVisibility, ChangeMessageVisibilityBatch, CreateQueue, DeleteMessage, DeleteMessageBatch, DeleteQueue, GetQueueAttributes, GetQueueUrl, ListDeadLetterSourceQueues, ListQueueTags, ListQueues, PurgeQueue, ReceiveMessage, RemovePermission, SendMessage, SendMessageBatch, SetQueueAttributes, TagQueue, UntagQueue.