0
Files
src/headless
Devlin Cronin df260f5e98 [Extensions] Allow service worker requests to continue without a cert
Certain requests may request, but not require, a client cert. Today,
this will result in one of three things happening if there isn't a
client cert available (either from a previous request or from
enterprise policy):
1) The request will fail
2) The user will be shown a cert picker dialog
3) The request will continue without a certificate

On desktop platforms for WebContents-based requesting contexts:
* If there are no certs to choose from, the request will continue
  without a cert.
* If there are client certs and the WebContents supports showing
  dialogs, the cert picker will be shown.
* If there are certs and the WebContents does not support showing
  dialogs, the request will fail.

On Android for WebContents-based requesting contexts:
* We will always call out to the native cert-picker, which may or
  may not show a dialog (depending on other device configurations
  which Chrome doesn't know about).

On desktop and Android platforms for service worker requesting
contexts:
* The request will always fail.

This CL changes this behavior to allow requests from extension
background service workers to proceed without a client cert if there
are no certs to choose from; this then matches the behavior for
extension background and offscreen WebContents (which do not support
showing dialogs).

Bug: 333954429
Change-Id: Ia6111f3bd499998d6244945daa13ac67774804bf
Reviewed-on: https://chromium-review.googlesource.com/c/chromium/src/+/5455480
Reviewed-by: Emily Stark <estark@chromium.org>
Reviewed-by: David Benjamin <davidben@chromium.org>
Reviewed-by: Richard (Torne) Coles <torne@chromium.org>
Reviewed-by: Alex Moshchuk <alexmos@chromium.org>
Reviewed-by: Luke Halliwell <halliwell@chromium.org>
Reviewed-by: Andrey Kosyakov <caseq@chromium.org>
Commit-Queue: Devlin Cronin <rdevlin.cronin@chromium.org>
Reviewed-by: Wez <wez@chromium.org>
Cr-Commit-Position: refs/heads/main@{#1322530}
2024-07-03 02:13:39 +00:00
..

Headless Chromium

Headless Chromium allows running Chromium in a headless/server environment. Expected use cases include loading web pages, extracting metadata (e.g., the DOM) and generating bitmaps from page contents -- using all the modern web platform features provided by Chromium and Blink.

There are two ways to use Headless Chromium:

Usage via the DevTools remote debugging protocol

  1. Start a normal Chrome binary with the --headless command line flag:
$ chrome --headless --remote-debugging-port=9222 https://chromium.org/
  1. Navigate to http://localhost:9222/ in another browser to open the DevTools interface or use a tool such as Selenium to drive the headless browser.

Usage from Node.js

For example, the chrome-remote-interface Node.js package can be used to extract a page's DOM like this:

const CDP = require('chrome-remote-interface');

CDP((client) => {
  // Extract used DevTools domains.
  const {Page, Runtime} = client;

  // Enable events on domains we are interested in.
  Promise.all([
    Page.enable()
  ]).then(() => {
    return Page.navigate({url: 'https://example.com'});
  });

  // Evaluate outerHTML after page has loaded.
  Page.loadEventFired(() => {
    Runtime.evaluate({expression: 'document.body.outerHTML'}).then((result) => {
      console.log(result.result.value);
      client.close();
    });
  });
}).on('error', (err) => {
  console.error('Cannot connect to browser:', err);
});

Usage as a C++ library

Headless Chromium can be built as a library for embedding into a C++ application. This approach is otherwise similar to controlling the browser over a DevTools connection, but it provides more customization points, e.g., for networking and mojo services.

Headless Example is a small sample application which demonstrates the use of the headless C++ API. It loads a web page and outputs the resulting DOM. To run it, first initialize a headless build configuration:

$ mkdir -p out/Debug
$ echo 'import("//build/args/headless.gn")' > out/Debug/args.gn
$ gn gen out/Debug

Then build the example:

$ ninja -C out/Debug headless_example

After the build completes, the example can be run with the following command:

$ out/Debug/headless_example https://www.google.com/

Headless Shell is a more capable headless application. For instance, it supports remote debugging with the DevTools protocol. To do this, start the application with an argument specifying the debugging port:

$ ninja -C out/Debug headless_shell
$ out/Debug/headless_shell --remote-debugging-port=9222 https://youtube.com/

Then navigate to http://localhost:9222/ with your browser.

As of M118, precompiled headless_shell binaries are available for download under the name chrome-headless-shell via Chrome for Testing infrastructure.

Embedder API

The embedder API allows developers to integrate the headless library into their application. The API provides default implementations for low level adaptation points such as networking and the run loop.

The main embedder API classes are:

  • HeadlessBrowser::Options::Builder - Defines the embedding options, e.g.:
    • SetMessagePump - Replaces the default base message pump. See base::MessagePump.
    • SetProxyServer - Configures an HTTP/HTTPS proxy server to be used for accessing the network.

Client/DevTools API

The headless client API is used to drive the browser and interact with loaded web pages. Its main classes are:

  • HeadlessBrowser - Represents the global headless browser instance.
  • HeadlessWebContents - Represents a single "tab" within the browser.
  • HeadlessDevToolsClient - Provides a C++ interface for inspecting and controlling a tab. The API functions corresponds to DevTools commands. See the client API documentation for more information.

Resources and Documentation

Mailing list: headless-dev@chromium.org

Bug tracker: Internals>Headless

File a new bug (bit.ly/2pP6SBb)