contrib/llvm-project/llvm/include/llvm/Debuginfod/HTTPClient.h

   1 //===-- llvm/Support/HTTPClient.h - HTTP client library ---------*- C++ -*-===//
   2 //
   3 // Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
   4 // See https://llvm.org/LICENSE.txt for license information.
   5 // SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
   6 //
   7 //===----------------------------------------------------------------------===//
   8 ///
   9 /// \file
  10 /// This file contains the declarations of the HTTPClient, HTTPMethod,
  11 /// HTTPResponseHandler, and BufferedHTTPResponseHandler classes, as well as
  12 /// the HTTPResponseBuffer and HTTPRequest structs.
  13 ///
  14 //===----------------------------------------------------------------------===//
  15
  16 #ifndef LLVM_DEBUGINFOD_HTTPCLIENT_H
  17 #define LLVM_DEBUGINFOD_HTTPCLIENT_H
  18
  19 #include "llvm/Support/Error.h"
  20 #include "llvm/Support/MemoryBuffer.h"
  21
  22 #include <chrono>
  23
  24 namespace llvm {
  25
  26 enum class HTTPMethod { GET };
  27
  28 /// A stateless description of an outbound HTTP request.
  29 struct HTTPRequest {
  30   SmallString<128> Url;
  31   HTTPMethod Method = HTTPMethod::GET;
  32   bool FollowRedirects = true;
  33   HTTPRequest(StringRef Url);
  34 };
  35
  36 bool operator==(const HTTPRequest &A, const HTTPRequest &B);
  37
  38 /// A handler for state updates occurring while an HTTPRequest is performed.
  39 /// Can trigger the client to abort the request by returning an Error from any
  40 /// of its methods.
  41 class HTTPResponseHandler {
  42 public:
  43   /// Processes one line of HTTP response headers.
  44   virtual Error handleHeaderLine(StringRef HeaderLine) = 0;
  45
  46   /// Processes an additional chunk of bytes of the HTTP response body.
  47   virtual Error handleBodyChunk(StringRef BodyChunk) = 0;
  48
  49   /// Processes the HTTP response status code.
  50   virtual Error handleStatusCode(unsigned Code) = 0;
  51
  52 protected:
  53   ~HTTPResponseHandler();
  54 };
  55
  56 /// An HTTP response status code bundled with a buffer to store the body.
  57 struct HTTPResponseBuffer {
  58   unsigned Code = 0;
  59   std::unique_ptr<WritableMemoryBuffer> Body;
  60 };
  61
  62 /// A simple handler which writes returned data to an HTTPResponseBuffer.
  63 /// Ignores all headers except the Content-Length, which it uses to
  64 /// allocate an appropriately-sized Body buffer.
  65 class BufferedHTTPResponseHandler final : public HTTPResponseHandler {
  66   size_t Offset = 0;
  67
  68 public:
  69   /// Stores the data received from the HTTP server.
  70   HTTPResponseBuffer ResponseBuffer;
  71
  72   /// These callbacks store the body and status code in an HTTPResponseBuffer
  73   /// allocated based on Content-Length. The Content-Length header must be
  74   /// handled by handleHeaderLine before any calls to handleBodyChunk.
  75   Error handleHeaderLine(StringRef HeaderLine) override;
  76   Error handleBodyChunk(StringRef BodyChunk) override;
  77   Error handleStatusCode(unsigned Code) override;
  78 };
  79
  80 /// A reusable client that can perform HTTPRequests through a network socket.
  81 class HTTPClient {
  82 #ifdef LLVM_ENABLE_CURL
  83   void *Curl = nullptr;
  84 #endif
  85
  86 public:
  87   HTTPClient();
  88   ~HTTPClient();
  89
  90   static bool IsInitialized;
  91
  92   /// Returns true only if LLVM has been compiled with a working HTTPClient.
  93   static bool isAvailable();
  94
  95   /// Must be called at the beginning of a program, while it is a single thread.
  96   static void initialize();
  97
  98   /// Must be called at the end of a program, while it is a single thread.
  99   static void cleanup();
 100
 101   /// Sets the timeout for the entire request, in milliseconds. A zero or
 102   /// negative value means the request never times out.
 103   void setTimeout(std::chrono::milliseconds Timeout);
 104
 105   /// Performs the Request, passing response data to the Handler. Returns all
 106   /// errors which occur during the request. Aborts if an error is returned by a
 107   /// Handler method.
 108   Error perform(const HTTPRequest &Request, HTTPResponseHandler &Handler);
 109
 110   /// Performs the Request with the default BufferedHTTPResponseHandler, and
 111   /// returns its HTTPResponseBuffer or an Error.
 112   Expected<HTTPResponseBuffer> perform(const HTTPRequest &Request);
 113
 114   /// Performs an HTTPRequest with the default configuration to make a GET
 115   /// request to the given Url. Returns an HTTPResponseBuffer or an Error.
 116   Expected<HTTPResponseBuffer> get(StringRef Url);
 117 };
 118
 119 } // end namespace llvm
 120
 121 #endif // LLVM_DEBUGINFOD_HTTPCLIENT_H