Network

This guide shows how to work with the network-related functionality such as proxy, network events, authentication, TLS, client certificate authentication, etc.

The network-related functionality can be accessed through the Network instance:

auto network = app->profile()->network();

Online/offline detection

The Network API allows you to track the status of the Internet connection. By default, when the Internet connection is dropped and then restored, Molybden detects the change and reloads the currently loaded web page.

To get notifications about the Internet access status changes, subscribe to the onNetworkChanged event. The following code snippet shows how to detect the online/offline status changes:

network->onNetworkChanged += [](const NetworkChanged& event) {
  if (event.connection_type == ConnectionType::kTypeNone) {
    // The network connection has been dropped. We are offline.
  } else {
    // The network connection has been established. We are online.
  }
};

Server whitelist

HTTP server authorization whitelist

You can configure HTTP server authorization whitelist that represents a string with a list of comma/semicolon separated URLs. For example:

network->httpAuthPrefs()->setServerWhitelist("*google.com,*example.com,*baz");

HTTP network delegate whitelist

To configure HTTP network delegate whitelist you can use the approach described below:

network->httpAuthPrefs()->setDelegateWhitelist("*google.com,*example.com,*baz");

TLS

Certificate Verification

By default, Chromium verifies all SSL certificates obtained from a web server during the web page loading. In Molybden, you can override this behavior and take control over the verification process.

To handle certificate verification use the onVerifyCert delegate of the Browser. Chromium verifies the certificate before this delegate is called, and you can access verification results in the arguments.

browser->onVerifyCert = [](const VerifyCertArgs& args, 
                           VerifyCertAction action) {
  auto certificate = args.certificate;
  auto errors = args.verification_errors;
  for (auto error : errors) {
    std::cout << "Error: " << error.short_description << std::endl;
  }
  action.valid();
};

Intercepting URL requests

Molybden provides an API to intercept a URL request and send a URL response as it was sent from a web server. This API is used to serve custom schemes:

network->onInterceptUrlRequest = [](const InterceptUrlRequestArgs& args, 
                                    InterceptUrlRequestAction action) {
  action.proceed();
};

Network events & delegates

The Network API defines a set of events and delegates that follow the lifecycle of a web request. You can use these events to observe and analyze traffic. The delegates allow you to intercept, block, and modify requests.

The event lifecycle of successful requests looks as follows:

Before URL Request

The onBeforeUrlRequest delegate is invoked when an HTTP request is about to occur. You can use this delegate to redirect the request to another location. For example:

network->onBeforeUrlRequest = [](const BeforeUrlRequestArgs& args, 
                                 BeforeUrlRequestAction action) {
  action.redirect("<new-url>");
};

Before Send Upload Data

The onBeforeSendUploadData delegated is invoked before the upload data is sent to a web server. Here you can override the upload data. For example:

network->onBeforeSendUploadData = [](const BeforeSendUploadDataArgs& args, 
                                     BeforeSendUploadDataAction action) {
  action.override(TextData::create("Hello world!"));
};

This delegate will not be called if the request does not have the upload data.

The following types of upload data are supported:

• BytesData represents a sequence of bytes.
• TextData the data of the text/plain content type.
• FormData the data of the application/x-www-form-urlencoded content type.
• MultipartFormData the data of the multipart/form-data content type.

Before Start Transaction

The onBeforeStartTransaction delegate is invoked before the network transaction starts. In this delegate, you can add or override the HTTP headers before they are sent out. For example:

network->onBeforeStartTransaction = [](const BeforeStartTransactionArgs& args, 
                                       BeforeStartTransactionAction action) {
  action.proceed();
};

This delegate doesn’t capture the following headers. The list is a subject to change and may not be complete:

- Authorization
- Cache-Control
- Connection
- Content-Length
- Host
- If-Modified-Since
- If-None-Match
- If-Range
- Partial-Data
- Pragma
- Proxy-Authorization
- Proxy-Connection
- Transfer-Encoding

Receive Headers

The onReceiveHeaders delegate is invoked for HTTP requests when the headers have been received. Here you can add, modify, or remove the HTTP headers received over the network. For example:

network->onReceiveHeaders = [](const ReceiveHeadersArgs& args, ReceiveHeadersAction action) {
  // TBD: CODE
};

Redirect Response Code Received

The RedirectResponseCodeReceived event is fired when a redirect response code 3xx has been received for the request. In this event, you can get the details about the redirect such as new URL and response code. For example:

network->onRedirectResponseCodeReceived += [](const RedirectResponseCodeReceived& event) {
  uint32_t code = event.response_code;
  std::string new_url = event.new_url;
};

Response Started

The ResponseStarted event is fired when the first byte of the URL response body has been received. For HTTP requests, this means that the status line and the response headers are available. In this eventm you can access the corresponding request and the response code. For example:

network->onResponseStarted += [](const ResponseStarted& event) {
  auto request = event.url_request;
  uint32_t code = event.response_code;
};

Request Completed

The RequestCompleted event is fired when the URL request has been successfully completed or failed. In this event, you can check whether the request has been started at all, get the details of the request status, access the response code. For example:

network->onRequestCompleted += [](const RequestCompleted& event) {
  auto request = event.url_request;
  auto status = event.status;
};

Request Destroyed

The RequestDestroyed event is fired when the request has been destroyed, so it cannot be used anymore. To access the details of the destroyed request use the following code:

network->onRequestDestroyed += [](const RequestDestroyed& event) {
  auto request = event.url_request;
};

Response Bytes Received

The ResponseBytesReceived event is fired when a part of HTTP response body has been received over the network. It allows accessing the bytes of the HTTP response body:

network->onResponseBytesReceived += [](const ResponseBytesReceived& event) {};

The parts of the response body may come in a random order. Keep this in mind when restoring the full response using this event.