[headless] Initial skeleton of headless/public/

Create outline of future Headless API.

BUG=546953

Review URL: https://codereview.chromium.org/1461693003

Cr-Commit-Position: refs/heads/master@{#362712}

headless/BUILD.gn

@@ -0,0 +1,24 @@
+# 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.
+
+group("headless") {
+  deps = [
+    "//headless:headless_lib",
+  ]
+}
+
+static_library("headless_lib") {
+  sources = [
+    "public/headless_browser.cc",
+    "public/headless_browser.h",
+    "public/headless_export.h",
+    "public/network.h",
+    "public/web_contents.h",
+    "public/web_frame.h",
+  ]
+
+  deps = [
+    "//base",
+  ]
+}

headless/public/headless_browser.cc

@@ -0,0 +1,41 @@
+// 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.
+
+#include "headless/public/headless_browser.h"
+
+using Options = headless::HeadlessBrowser::Options;
+using Builder = headless::HeadlessBrowser::Options::Builder;
+
+namespace headless {
+
+Options::Options(int argc, const char** argv)
+    : argc(argc), argv(argv), devtools_http_port(kInvalidPort) {}
+
+Options::~Options() {}
+
+Builder::Builder(int argc, const char** argv) : options_(argc, argv) {}
+
+Builder::~Builder() {}
+
+Builder& Builder::SetUserAgent(const std::string& user_agent) {
+  options_.user_agent = user_agent;
+  return *this;
+}
+
+Builder& Builder::EnableDevToolsServer(int port) {
+  options_.devtools_http_port = port;
+  return *this;
+}
+
+Builder& Builder::SetURLRequestContextGetter(
+    scoped_refptr<net::URLRequestContextGetter> url_request_context_getter) {
+  options_.url_request_context_getter = url_request_context_getter;
+  return *this;
+}
+
+Options Builder::Build() {
+  return options_;
+}
+
+}  // namespace headless

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/macros.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;
+
+  // Main routine for running browser.
+  // Takes command line args and callback to run as soon as browser starts.
+  static int Run(
+      const Options& options,
+      const base::Callback<void(HeadlessBrowser*)>& on_browser_start_callback);
+
+  // Create a new browser tab.
+  virtual scoped_ptr<WebContents> CreateWebContents(const gfx::Size& size) = 0;
+
+  virtual scoped_refptr<base::SingleThreadTaskRunner> BrowserMainThread() = 0;
+  virtual scoped_refptr<base::SingleThreadTaskRunner> RendererMainThread() = 0;
+
+  // Requests browser to stop as soon as possible.
+  // |Run| will return as soon as browser stops.
+  virtual void Stop() = 0;
+
+  virtual void StartTracing(const base::trace_event::TraceConfig& trace_config,
+                            const base::Closure& on_tracing_started) = 0;
+  virtual void StopTracing(const std::string& log_file_name,
+                           const base::Closure& on_tracing_stopped) = 0;
+
+ protected:
+  virtual ~HeadlessBrowser() {}
+
+ private:
+  DISALLOW_COPY_AND_ASSIGN(HeadlessBrowser);
+};
+
+struct HeadlessBrowser::Options {
+  ~Options();
+
+  class Builder;
+
+  // Command line options to be passed to browser.
+  int argc;
+  const char** argv;
+
+  std::string user_agent;
+
+  static const int kInvalidPort = -1;
+  // If not null, create start devtools for remote debugging
+  // on specified port.
+  int devtools_http_port;
+
+  // Optional URLRequestContextGetter for customizing network stack.
+  scoped_refptr<net::URLRequestContextGetter> url_request_context_getter;
+
+ private:
+  Options(int argc, const char** argv);
+};
+
+class HeadlessBrowser::Options::Builder {
+ public:
+  Builder(int argc, const char** argv);
+  ~Builder();
+
+  Builder& SetUserAgent(const std::string& user_agent);
+  Builder& EnableDevToolsServer(int port);
+  Builder& SetURLRequestContextGetter(
+      scoped_refptr<net::URLRequestContextGetter> url_request_context_getter);
+
+  Options Build();
+
+ private:
+  Options options_;
+
+  DISALLOW_COPY_AND_ASSIGN(Builder);
+};
+
+}  // namespace headless
+
+#endif  // HEADLESS_PUBLIC_HEADLESS_BROWSER_H_

headless/public/headless_export.h

@@ -0,0 +1,29 @@
+// 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_EXPORT_H_
+#define HEADLESS_PUBLIC_HEADLESS_EXPORT_H_
+
+#if defined(COMPONENT_BUILD)
+#if defined(WIN32)
+
+#if defined(HEADLESS_IMPLEMENTATION)
+#define HEADLESS_EXPORT __declspec(dllexport)
+#else
+#define HEADLESS_EXPORT __declspec(dllimport)
+#endif  // defined(HEADLESS_IMPLEMENTATION)
+
+#else  // defined(WIN32)
+#if defined(HEADLESS_IMPLEMENTATION)
+#define HEADLESS_EXPORT __attribute__((visibility("default")))
+#else
+#define HEADLESS_EXPORT
+#endif
+#endif
+
+#else  // defined(COMPONENT_BUILD)
+#define HEADLESS_EXPORT
+#endif
+
+#endif  // HEADLESS_PUBLIC_HEADLESS_EXPORT_H_

headless/public/network.h

@@ -0,0 +1,36 @@
+// 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_NETWORK_H_
+#define HEADLESS_PUBLIC_NETWORK_H_
+
+#include <base/macros.h>
+#include <base/memory/ref_counted.h>
+#include <base/memory/scoped_ptr.h>
+
+namespace net {
+class URLRequestContextGetter;
+class ClientSocketFactory;
+class HttpTransactionFactory;
+}
+
+namespace headless {
+
+class Network {
+ public:
+  static scoped_refptr<net::URLRequestContextGetter>
+  CreateURLRequestContextGetterUsingSocketFactory(
+      scoped_ptr<net::ClientSocketFactory> socket_factory);
+
+  static scoped_refptr<net::URLRequestContextGetter>
+  CreateURLRequestContextGetterUsingHttpTransactionFactory(
+      scoped_ptr<net::HttpTransactionFactory> http_transaction_factory);
+
+ private:
+  Network() = delete;
+};
+
+}  // namespace headless
+
+#endif  // HEADLESS_PUBLIC_NETWORK_H_

headless/public/web_contents.h

@@ -0,0 +1,69 @@
+// 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_WEB_CONTENTS_H_
+#define HEADLESS_PUBLIC_WEB_CONTENTS_H_
+
+#include "base/callback.h"
+#include "base/macros.h"
+#include "base/memory/scoped_ptr.h"
+#include "headless/public/headless_export.h"
+#include "url/gurl.h"
+
+class SkBitmap;
+
+namespace content {
+class WebContents;
+}
+
+namespace headless {
+class WebFrame;
+
+// Class representing contents of a browser tab.
+// Should be accessed from browser main thread.
+class HEADLESS_EXPORT WebContents {
+ public:
+  virtual ~WebContents() {}
+
+  class Observer {
+   public:
+    // Will be called on browser thread.
+    virtual void DocumentOnLoadCompletedInMainFrame() = 0;
+
+    // TODO(altimin): More OnSomething() methods will go here.
+
+   protected:
+    explicit Observer(WebContents* web_contents);
+    virtual ~Observer();
+
+   private:
+    class ObserverImpl;
+    scoped_ptr<ObserverImpl> observer_;
+
+    DISALLOW_COPY_AND_ASSIGN(Observer);
+  };
+
+  // Returns main frame for web page.
+  // Should be called on renderer main thread.
+  virtual WebFrame* MainFrame() = 0;
+
+  // Requests browser tab to nagivate to given url.
+  // Should be called on browser main thread.
+  virtual void OpenURL(const GURL& url) = 0;
+
+  using ScreenshotCallback = base::Callback<void(scoped_ptr<SkBitmap>)>;
+  // Requests an image of web contents.
+  // Should be called on browser main thread.
+  virtual void GetScreenshot(const ScreenshotCallback& callback) = 0;
+
+ protected:
+  virtual content::WebContents* web_contents() = 0;
+
+ private:
+  DISALLOW_COPY_AND_ASSIGN(WebContents);
+};
+
+}  // namespace headless
+
+#endif  // HEADLESS_PUBLIC_WEB_CONTENTS_H_

headless/public/web_frame.h

@@ -0,0 +1,53 @@
+// 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_WEB_FRAME_H_
+#define HEADLESS_PUBLIC_WEB_FRAME_H_
+
+#include "base/callback.h"
+#include "base/macros.h"
+#include "base/values.h"
+#include "headless/public/headless_export.h"
+
+namespace headless {
+
+class WebDocument;
+
+// Class representing a frame in a web page (e.g. main frame or an iframe).
+// Should be accessed from renderer main thread.
+class HEADLESS_EXPORT WebFrame {
+ public:
+  virtual ~WebFrame() {}
+
+  using ScriptExecutionCallback =
+      base::Callback<void(const std::vector<scoped_ptr<base::Value>>&)>;
+
+  // Schedule given script for execution.
+  virtual void ExecuteScript(const std::string& source_code) = 0;
+
+  // Execute given script and return its result.
+  // Returned value will be converted to json (base::Value).
+  // Special effects to bear in mind:
+  // - Boolean will be converted to base::FundamentalValue (no surprises here).
+  // - Number will be converted to base::FundamentalValue.
+  // - Array will be converted to base::ListValue.
+  //   Note: All non-numerical properties will be omitted
+  //   (e.g. "array = [1, 2, 3]; array['property'] = 'value'; return array"
+  //    will return [1, 2, 3]).
+  // - Object will be converted to base::DictionaryValue
+  //   Note: Only string can be key in base::DictionaryValue, so all non-string
+  //   properties will be omitted
+  //   (e.g. "obj = Object(); obj['key'] = 'value'; obj[0] = 42;" will return
+  //    {"key":"value"}).
+  virtual void ExecuteScriptAndReturnValue(
+      const std::string& source_code,
+      const ScriptExecutionCallback& callback) = 0;
+
+ private:
+  DISALLOW_COPY_AND_ASSIGN(WebFrame);
+};
+
+}  // namespace headless
+
+#endif  // HEADLESS_PUBLIC_WEB_FRAME_H_