headless/public/headless_browser.h

   1 // Copyright 2015 The Chromium Authors
   2 // Use of this source code is governed by a BSD-style license that can be
   3 // found in the LICENSE file.
   4
   5 #ifndef HEADLESS_PUBLIC_HEADLESS_BROWSER_H_
   6 #define HEADLESS_PUBLIC_HEADLESS_BROWSER_H_
   7
   8 #include <memory>
   9 #include <string>
  10 #include <vector>
  11
  12 #include "base/files/file_path.h"
  13 #include "base/memory/raw_ptr.h"
  14 #include "build/build_config.h"
  15 #include "headless/public/headless_browser_context.h"
  16 #include "headless/public/headless_export.h"
  17 #include "net/base/host_port_pair.h"
  18 #include "ui/gfx/font_render_params.h"
  19 #include "ui/gfx/geometry/size.h"
  20
  21 namespace base {
  22 class SingleThreadTaskRunner;
  23 }
  24
  25 namespace blink {
  26 struct UserAgentMetadata;
  27 }
  28
  29 namespace headless {
  30
  31 class HeadlessWebContents;
  32
  33 // This class represents the global headless browser instance. To get a pointer
  34 // to one, call |HeadlessBrowserMain| to initiate the browser main loop. An
  35 // instance of |HeadlessBrowser| will be passed to the callback given to that
  36 // function.
  37 class HEADLESS_EXPORT HeadlessBrowser {
  38  public:
  39   struct Options;
  40
  41   HeadlessBrowser(const HeadlessBrowser&) = delete;
  42   HeadlessBrowser& operator=(const HeadlessBrowser&) = delete;
  43
  44   // Create a new browser context which can be used to create tabs and isolate
  45   // them from one another.
  46   // Pointer to HeadlessBrowserContext becomes invalid after:
  47   // a) Calling HeadlessBrowserContext::Close or
  48   // b) Calling HeadlessBrowser::Shutdown
  49   virtual HeadlessBrowserContext::Builder CreateBrowserContextBuilder() = 0;
  50
  51   virtual std::vector<HeadlessBrowserContext*> GetAllBrowserContexts() = 0;
  52
  53   // Returns the HeadlessWebContents associated with the
  54   // |devtools_agent_host_id| if any.  Otherwise returns null.
  55   virtual HeadlessWebContents* GetWebContentsForDevToolsAgentHostId(
  56       const std::string& devtools_agent_host_id) = 0;
  57
  58   // Returns HeadlessBrowserContext associated with the given id if any.
  59   // Otherwise returns null.
  60   virtual HeadlessBrowserContext* GetBrowserContextForId(
  61       const std::string& id) = 0;
  62
  63   // Allows setting and getting the browser context that DevTools will create
  64   // new targets in by default.
  65   virtual void SetDefaultBrowserContext(
  66       HeadlessBrowserContext* browser_context) = 0;
  67   virtual HeadlessBrowserContext* GetDefaultBrowserContext() = 0;
  68
  69   // Returns a task runner for submitting work to the browser main thread.
  70   virtual scoped_refptr<base::SingleThreadTaskRunner> BrowserMainThread()
  71       const = 0;
  72
  73   // Requests browser to stop as soon as possible. |Run| will return as soon as
  74   // browser stops.
  75   // IMPORTANT: All pointers to HeadlessBrowserContexts and HeadlessWebContents
  76   // become invalid after calling this function.
  77   virtual void Shutdown() = 0;
  78
  79   static std::string GetProductNameAndVersion();
  80   static blink::UserAgentMetadata GetUserAgentMetadata();
  81
  82  protected:
  83   HeadlessBrowser() {}
  84   virtual ~HeadlessBrowser() {}
  85 };
  86
  87 // Embedding API overrides for the headless browser.
  88 struct HEADLESS_EXPORT HeadlessBrowser::Options {
  89   class Builder;
  90
  91   Options(Options&& options);
  92
  93   Options(const Options&) = delete;
  94   Options& operator=(const Options&) = delete;
  95
  96   ~Options();
  97
  98   Options& operator=(Options&& options);
  99
 100   // Address at which DevTools should listen for connections. Disabled by
 101   // default.
 102   net::HostPortPair devtools_endpoint;
 103
 104   // Enables remote debug over stdio pipes [in=3, out=4].
 105   bool devtools_pipe_enabled = false;
 106
 107   // A single way to test whether the devtools server has been requested.
 108   bool DevtoolsServerEnabled();
 109
 110   // Default per-context options, can be specialized on per-context basis.
 111   std::string accept_language;
 112   std::string user_agent;
 113
 114   // The ProxyConfig to use. The system proxy settings are used by default.
 115   std::unique_ptr<net::ProxyConfig> proxy_config;
 116
 117   // Default window size. This is also used to create the window tree host and
 118   // as initial screen size. Defaults to 800x600.
 119   gfx::Size window_size;
 120
 121   // Path to user data directory, where browser will look for its state.
 122   // If empty, default directory (where the binary is located) will be used.
 123   base::FilePath user_data_dir;
 124
 125   // Path to disk cache directory. If emppty, 'Cache' subdirectory of the
 126   // user data directory will be used.
 127   base::FilePath disk_cache_dir;
 128
 129   // Run a browser context in an incognito mode. Enabled by default.
 130   bool incognito_mode = true;
 131
 132   // If true, then all pop-ups and calls to window.open will fail.
 133   bool block_new_web_contents = false;
 134
 135   // Whether or not BeginFrames will be issued over DevTools protocol
 136   // (experimental).
 137   bool enable_begin_frame_control = false;
 138
 139   // Font render hinting value to override any default settings
 140   gfx::FontRenderParams::Hinting font_render_hinting;
 141
 142   // Whether lazy loading of images and frames is enabled.
 143   bool lazy_load_enabled = true;
 144
 145   // Reminder: when adding a new field here, do not forget to add it to
 146   // HeadlessBrowserContextOptions (where appropriate).
 147  private:
 148   Options();
 149 };
 150
 151 class HEADLESS_EXPORT HeadlessBrowser::Options::Builder {
 152  public:
 153   Builder();
 154
 155   Builder(const Builder&) = delete;
 156   Builder& operator=(const Builder&) = delete;
 157
 158   ~Builder();
 159
 160   // Browser-wide settings.
 161
 162   Builder& EnableDevToolsServer(const net::HostPortPair& endpoint);
 163   Builder& EnableDevToolsPipe();
 164
 165   // Settings that are currently browser-wide, but could be per-context if
 166   // needed.
 167   Builder& SetEnableLazyLoading(bool enable);
 168
 169   // Per-context settings.
 170
 171   Builder& SetAcceptLanguage(const std::string& language);
 172   Builder& SetEnableBeginFrameControl(bool enable);
 173   Builder& SetUserAgent(const std::string& agent);
 174   Builder& SetProxyConfig(std::unique_ptr<net::ProxyConfig> config);
 175   Builder& SetWindowSize(const gfx::Size& size);
 176   Builder& SetUserDataDir(const base::FilePath& dir);
 177   Builder& SetDiskCacheDir(const base::FilePath& dir);
 178   Builder& SetIncognitoMode(bool incognito);
 179   Builder& SetBlockNewWebContents(bool block);
 180   Builder& SetCrashReporterEnabled(bool enabled);
 181   Builder& SetCrashDumpsDir(const base::FilePath& dir);
 182   Builder& SetFontRenderHinting(gfx::FontRenderParams::Hinting hinting);
 183   Options Build();
 184
 185  private:
 186   Options options_;
 187 };
 188
 189 }  // namespace headless
 190
 191 #endif  // HEADLESS_PUBLIC_HEADLESS_BROWSER_H_