There are a few critical parameters that must be set within the transport layer in order to set it up for use. There are a number of additional parameters that can be used to configure various aspects of it. This document describes how to configure the Transport Layer and its key components.

Contents

1. Typical use case examples
   1. Injecting an HTTP protocol implementation
   2. Verifying SSL certificates
   3. Setting the HTTP User Agent
   4. Controlling concurrency
   5. Handling transient HTTP errors
2. HttpTransportLayerConfig vs HttpTransportOptions

Typical use case examples

These examples show how to configure aspects of the Transport Layer that come into play when making HTTP requests either explicitly with the transport layer components or indirectly such as making calls to cloud services.

Injecting an HTTP protocol implementation

Components that perform HTTP messaging use dependency injection to bind to an HTTP protocol implementation. This is achieved either by giving them the HttpTransport instance to use, a HttpTransportFactory for instantiating instances as they are needed, or HttpTransportLayerConfig with a default HttpTransportFactory bound to it.

Verifying SSL certificates

The HttpTransportOptions can specify a path to a data file for validating SSL certificates. The SDK comes with a data file suitable for validating all the certificates used by services hosted in the Google Platform and other common Internet web servers. You must tell the runtime where this path is if it is not in the default location. The default location is a file called roots.pem in the directory that the program executable is located in. The CMake build files in the SDK will copy this into the bin and export/bin directories of your build. It is up to you to include these when you install your applications, or explicitly set some other path.

The location is an attribute in the HttpTransportOptions. This means that you can have some paths with different data files if you so desire. You may also disable this feature, at the risk of your users, by setting the path to HttpTransportOptions::kDisableSslVerification.

Setting the HTTP User Agent

HTTP users a special header called User-Agent for applications and transport implementations to identify themselves. This is typically used for monitoring, diagnostics, and various types of server-side analysis. We would prefer that you leave the default value or change it with SetApplicationName when talking to Google servers. You may also change this to a literal value with the set_nonstandard_user_agent attribute on HttpTransportOptions.

Controlling concurrency

Individual HttpRequest instances execute synchronously, however you can execute multiple requests concurrently. There are two ways to do this:

• Yourself by calling HttpRequest::Execute from separate threads.
• Implicitly by calling HttpRequest::ExecuteAsync and setting a multi-threaded Executor.

If you do not want to execute requests concurrently, such as if you are using a custom HTTP protocol implementation that is not thread-safe, you also have two ways to restrict concurrency:

• Use synchronization, such as a Mutex within your transport implementation.
  • You must do this if concurrent requests from different HttpTransport instances is a concern.
  • Use a single-threaded Executor such as NewInlineExecutor.
    • This should be sufficient if you only use one transport instance or only concurrent requests from the same instance are of concern.

Handling transient HTTP errors

The HttpTransportOptions contains an error_handler attribute with a reference to an HttpTransportErrorHandler. The options does not own the error handler instance, so the instance can be shared across multiple option instances used by multiple transport instance.

The error handler is called as needed by the base HttpRequest class while executing requests. This includes receiving HTTP redirect responses and HTTP error responses. The intention is that the error handler is used to decide when and how to retry the request as part of the processing flow. It is not intended to be used for handling the final response status. That would be left to the caller or, in the case of asynchronous execution, the callback.

HttpTransportLayerConfig vs HttpTransportOptions

The HttpTransportLayerConfig contains a default HttpTransportOptions attribute. The intent is that when using a config, you use the transport options from that config (or copy construct a new one from it) rather than the default constructor for HttpTransportOptions.

Some of the attributes of HttpTransportOptions are object pointers. The options instance does not own these pointers, rather the caller is responsible for them. The HttpTransportLayerConfig provides memory management for these options so that the objects referenced by its default_transport_options are managed by the config instance making it encapsulated.