libbrillo/brillo/http/http_transport.h

// Copyright 2014 The Chromium OS Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.

#ifndef LIBBRILLO_BRILLO_HTTP_HTTP_TRANSPORT_H_
#define LIBBRILLO_BRILLO_HTTP_HTTP_TRANSPORT_H_

#include <memory>
#include <string>
#include <utility>
#include <vector>

#include <base/callback_forward.h>
#include <base/files/file_path.h>
#include <base/location.h>
#include <base/macros.h>
#include <base/time/time.h>
#include <brillo/brillo_export.h>
#include <brillo/errors/error.h>

namespace brillo {
namespace http {

BRILLO_EXPORT extern const char kErrorDomain[];
// Constant referring to 'direct' proxy which implies no proxy server.
BRILLO_EXPORT extern const char kDirectProxy[];  // direct://

class Request;
class Response;
class Connection;

using RequestID = int;

using HeaderList = std::vector<std::pair<std::string, std::string>>;
using SuccessCallback =
    base::Callback<void(RequestID, std::unique_ptr<Response>)>;
using ErrorCallback = base::Callback<void(RequestID, const brillo::Error*)>;

///////////////////////////////////////////////////////////////////////////////
// Transport is a base class for specific implementation of HTTP communication.
// This class (and its underlying implementation) is used by http::Request and
// http::Response classes to provide HTTP functionality to the clients. By
// default, this interface will use CA certificates that only allow secure
// (HTTPS) communication with Google services.
///////////////////////////////////////////////////////////////////////////////
class BRILLO_EXPORT Transport : public std::enable_shared_from_this<Transport> {
 public:
  enum class Certificate {
    // Default certificate; only allows communication with Google services.
    kDefault,
    // Certificates for communicating only with production SM-DP+ and SM-DS
    // servers.
    kHermesProd,
    // Certificates for communicating only with test SM-DP+ and SM-DS servers.
    kHermesTest,
    // The NSS certificate store, which the curl command-line tool and libcurl
    // library use by default. This set of certificates does not restrict
    // secure communication to only Google services.
    kNss,
  };

  Transport() = default;
  virtual ~Transport() = default;

  // Creates a connection object and initializes it with the specified data.
  // |transport| is a shared pointer to this transport object instance,
  // used to maintain the object alive as long as the connection exists.
  // The |url| here is the full URL specified in the request. It is passed
  // to the underlying transport (e.g. CURL) to establish the connection.
  virtual std::shared_ptr<Connection> CreateConnection(
      const std::string& url,
      const std::string& method,
      const HeaderList& headers,
      const std::string& user_agent,
      const std::string& referer,
      brillo::ErrorPtr* error) = 0;

  // Runs |callback| on the task runner (message loop) associated with the
  // transport. For transports that do not contain references to real message
  // loops (e.g. a fake transport), calls the callback immediately.
  virtual void RunCallbackAsync(const base::Location& from_here,
                                const base::Closure& callback) = 0;

  // Initiates an asynchronous transfer on the given |connection|.
  // The actual implementation of an async I/O is transport-specific.
  // Returns a request ID which can be used to cancel the request.
  virtual RequestID StartAsyncTransfer(Connection* connection,
                                       const SuccessCallback& success_callback,
                                       const ErrorCallback& error_callback) = 0;

  // Cancels a pending asynchronous request. This will cancel a pending request
  // scheduled by the transport while the I/O operations are still in progress.
  // As soon as all I/O completes for the request/response, or when an error
  // occurs, the success/error callbacks are invoked and the request is
  // considered complete and can no longer be canceled.
  // Returns false if pending request with |request_id| is not found (e.g. it
  // has already completed/its callbacks are dispatched).
  virtual bool CancelRequest(RequestID request_id) = 0;

  // Set the default timeout of requests made.
  virtual void SetDefaultTimeout(base::TimeDelta timeout) = 0;

  // Set the local IP address of requests
  virtual void SetLocalIpAddress(const std::string& ip_address) = 0;

  // Use the default CA certificate for certificate verification. This
  // means that clients are only allowed to communicate with Google services.
  virtual void UseDefaultCertificate() {}

  // Set the CA certificate to use for certificate verification.
  //
  // This call can allow a client to securly communicate with a different subset
  // of services than it can otherwise. However, setting a custom certificate
  // should be done only when necessary, and should be done with careful control
  // over the certificates that are contained in the relevant path. See
  // https://chromium.googlesource.com/chromiumos/docs/+/master/ca_certs.md for
  // more information on certificates in Chrome OS.
  virtual void UseCustomCertificate(Transport::Certificate cert) {}

  // Appends host entry to DNS cache. curl can only do HTTPS request to a custom
  // IP if it resolves an HTTPS hostname to that IP. This is useful in
  // forcing a particular mapping for an HTTPS host. See CURLOPT_RESOLVE for
  // more details.
  virtual void ResolveHostToIp(const std::string& host,
                               uint16_t port,
                               const std::string& ip_address) {}

  // Creates a default http::Transport (currently, using http::curl::Transport).
  static std::shared_ptr<Transport> CreateDefault();

  // Creates a default http::Transport that will utilize the passed in proxy
  // server (currently, using a http::curl::Transport). |proxy| should be of the
  // form scheme://[user:pass@]host:port or may be the empty string or the
  // string kDirectProxy (i.e. direct://) to indicate no proxy.
  static std::shared_ptr<Transport> CreateDefaultWithProxy(
      const std::string& proxy);

 protected:
  // Clears the forced DNS mappings created by ResolveHostToIp.
  virtual void ClearHost() {}

  static base::FilePath CertificateToPath(Certificate cert);

 private:
  DISALLOW_COPY_AND_ASSIGN(Transport);
};

}  // namespace http
}  // namespace brillo

#endif  // LIBBRILLO_BRILLO_HTTP_HTTP_TRANSPORT_H_