[headless] Initial skeleton of headless/public/

headless/public/headless_browser.h

Index: headless/public/headless_browser.h
diff --git a/headless/public/headless_browser.h b/headless/public/headless_browser.h
new file mode 100644
index 0000000000000000000000000000000000000000..adadee87606aaa55a251c77fd7cc48e07c87a914
--- /dev/null
+++ b/headless/public/headless_browser.h
@@ -0,0 +1,110 @@
+// Copyright 2015 The Chromium 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 HEADLESS_PUBLIC_HEADLESS_BROWSER_H_
+#define HEADLESS_PUBLIC_HEADLESS_BROWSER_H_
+
+#include "base/callback.h"
+#include "base/memory/ref_counted.h"
+#include "base/memory/scoped_ptr.h"
+#include "headless/public/headless_export.h"
+
+namespace base {
+class SingleThreadTaskRunner;
+
+namespace trace_event {
+class TraceConfig;
+}
+}
+
+namespace gfx {
+class Size;
+}
+
+namespace net {
+class URLRequestContextGetter;
+}
+
+namespace headless {
+class WebContents;
+
+class HEADLESS_EXPORT HeadlessBrowser {
+ public:
+  static HeadlessBrowser* Get();
+
+  struct Options;
+
+  // Create a new browser tab.
+  virtual scoped_ptr<WebContents> CreateWebContents(const gfx::Size& size) = 0;

[Sami, 2015/12/01 14:03:57]

Which of these methods are safe to call before entering run? I wonder if we
should make our lives simpler by making Run be the static entrypoint and passing
the HeadlessBrowser pointer to the on_browser_start closure?

[altimin, 2015/12/01 15:17:29]

Great idea.
Done.

+
+  virtual scoped_refptr<base::SingleThreadTaskRunner> browser_main_thread() = 0;
+  virtual scoped_refptr<base::SingleThreadTaskRunner>
+  renderer_main_thread() = 0;
+
+  // Main routine for running browser.
+  // Takes command line args and callback to run as soon as browser starts.
+  // Should be called from main in the following manner:
+  // int main(int argc, const char** argv) {
+  //   return headless::HeadlessBrowser::Get()->Run(
+  //     argc, argv, base::Bind(function_to_be_run_on_browser_start));

[Sami, 2015/12/01 14:03:57]

This comment looks out of date. We could move the example code to the toplevel
README.md file.

[altimin, 2015/12/01 15:17:28]

Done.

+  // }
+  virtual int Run(const Options& options,
+                  const base::Closure& on_browser_start_callback) = 0;
+
+  // Requests browser to stop as soon as possible.

[Sami, 2015/12/01 14:03:57]

Might want to mention that this causes |Run| to return.

[altimin, 2015/12/01 15:17:29]

Done.

+  virtual void Stop() = 0;
+
+  virtual void StartTracing(const base::trace_event::TraceConfig& trace_config,
+                            const base::Closure& tracing_started) = 0;

[Sami, 2015/12/01 14:03:57]

Let's name callbacks consistently: either everything with an "on_" prefix or
without one.

[altimin, 2015/12/01 15:17:28]

Done.

+  virtual void StopTracing(const std::string& log_file_name,
+                           const base::Closure& tracing_stopped) = 0;
+
+ protected:
+  virtual ~HeadlessBrowser() {}

[Sami, 2015/12/01 14:03:57]

DISALLOW_COPY_AND_ASSIGN

[altimin, 2015/12/01 15:17:28]

Done.

+};
+
+struct HeadlessBrowser::Options {
+  Options(Options&&);

[Sami, 2015/12/01 14:03:57]

Missing a move assignment operator.

[altimin, 2015/12/01 15:17:29]

Done.

+  ~Options();
+
+  class Builder;
+
+  // Command line options to be passed to browser.
+  int argc;
+  const char** argv;
+
+  scoped_ptr<std::string> user_agent;

[Sami, 2015/12/01 14:03:57]

Can we make this a regular string that's initialized to the default user agent?

[altimin, 2015/12/01 15:17:28]

Done.

+
+  // If not null, create start devtools for remote debugging

[Sami, 2015/12/01 14:03:57]

A heap allocation seems overkill here. Could we make this kInvalidPort (-1) by
default and then only act on it if its non-negative?

[altimin, 2015/12/01 15:17:28]

Done.

+  // on specified port.
+  scoped_ptr<int> devtools_http_port;
+
+  // Using URLRequestContextGetter we can provide our own implementation of

[Sami, 2015/12/01 14:03:57]

nit: instead of talking about 'we' (who?) how about something like

Optional URLRequestContextGetter for customizing the network stack.

[altimin, 2015/12/01 15:17:29]

Done.

+  // entire network stack.
+  // If null, default Chromium network settings will be used.
+  scoped_refptr<net::URLRequestContextGetter> url_request_context_getter;
+
+ private:
+  Options(int argc, const char** argv);

[Sami, 2015/12/01 14:03:57]

DISALLOW_COPY_AND_ASSIGN? Not sure how that interacts with the move constructor.

[altimin, 2015/12/01 15:17:29]

Done.

+};
+
+class HeadlessBrowser::Options::Builder {
+ public:
+  Builder(int argc, const char** argv);
+  ~Builder();
+
+  Builder& SetUserAgent(const std::string& user_agent);
+  Builder& EnableDevtoolsServer(int port);

[Sami, 2015/12/01 14:03:57]

s/Devtools/DevTools/

[altimin, 2015/12/01 15:17:29]

Done.

+  Builder& SetURLRequestContextGetter(
+      scoped_refptr<net::URLRequestContextGetter> url_request_context_getter);
+
+  Options Build();
+
+ private:
+  Options options_;
+};

[Sami, 2015/12/01 14:03:57]

DISALLOW_COPY_AND_ASSIGN

[altimin, 2015/12/01 15:17:29]

Done.

+
+}  // namespace headless
+
+#endif  // HEADLESS_PUBLIC_HEADLESS_BROWSER_H_