webkit/glue/resource_loader_bridge.h

// Copyright (c) 2011 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.
//
// The intent of this file is to provide a type-neutral abstraction between
// Chrome and WebKit for resource loading. This pure-virtual interface is
// implemented by the embedder, which also provides a factory method Create
// to instantiate this object.
//
// One of these objects will be created by WebKit for each request. WebKit
// will own the pointer to the bridge, and will delete it when the request is
// no longer needed.
//
// In turn, the bridge's owner on the WebKit end will implement the Peer
// interface, which we will use to communicate notifications back.

#ifndef WEBKIT_GLUE_RESOURCE_LOADER_BRIDGE_H_
#define WEBKIT_GLUE_RESOURCE_LOADER_BRIDGE_H_

#include <utility>
#include <vector>

#include "build/build_config.h"
#if defined(OS_POSIX)
#include "base/file_descriptor_posix.h"
#endif
#include "base/file_path.h"
#include "base/memory/ref_counted.h"
#include "base/memory/scoped_ptr.h"
#include "base/platform_file.h"
#include "base/time.h"
#include "base/values.h"
#include "googleurl/src/gurl.h"
#include "net/base/host_port_pair.h"
#include "net/url_request/url_request_status.h"
#include "webkit/glue/resource_type.h"

namespace net {
class HttpResponseHeaders;
}

namespace webkit_glue {

// Structure containing timing information for the request. It addresses
// http://groups.google.com/group/http-archive-specification/web/har-1-1-spec
// and http://dev.w3.org/2006/webapi/WebTiming/ needs.
//
// All the values for starts and ends are given in milliseconds and are
// offsets with respect to the given base time.
struct ResourceLoadTimingInfo {
  ResourceLoadTimingInfo();
  ~ResourceLoadTimingInfo();

  // All the values in this struct are given as offsets in milliseconds wrt
  // this base time.
  base::Time base_time;

  // The time that proxy processing started. For requests with no proxy phase,
  // this time is -1.
  int32 proxy_start;

  // The time that proxy processing ended. For reused sockets this time
  // is -1.
  int32 proxy_end;

  // The time that DNS lookup started. For reused sockets this time is -1.
  int32 dns_start;

  // The time that DNS lookup ended. For reused sockets this time is -1.
  int32 dns_end;

  // The time that establishing connection started. Connect time includes
  // DNS, blocking, TCP, TCP retries and SSL time.
  int32 connect_start;

  // The time that establishing connection ended. Connect time includes
  // DNS, blocking, TCP, TCP retries and SSL time.
  int32 connect_end;

  // The time at which SSL handshake started. For non-HTTPS requests this
  // is 0.
  int32 ssl_start;

  // The time at which SSL handshake ended. For non-HTTPS requests this is 0.
  int32 ssl_end;

  // The time that HTTP request started. For non-HTTP requests this is 0.
  int32 send_start;

  // The time that HTTP request ended. For non-HTTP requests this is 0.
  int32 send_end;

  // The time at which receiving HTTP headers started. For non-HTTP requests
  // this is 0.
  int32 receive_headers_start;

  // The time at which receiving HTTP headers ended. For non-HTTP requests
  // this is 0.
  int32 receive_headers_end;
};

struct ResourceDevToolsInfo : base::RefCounted<ResourceDevToolsInfo> {
  typedef std::vector<std::pair<std::string, std::string> >
      HeadersVector;

  ResourceDevToolsInfo();
  ~ResourceDevToolsInfo();

  int32 http_status_code;
  std::string http_status_text;
  HeadersVector request_headers;
  HeadersVector response_headers;
};

struct ResourceResponseInfo {
  ResourceResponseInfo();
  ~ResourceResponseInfo();

  // The time at which the request was made that resulted in this response.
  // For cached responses, this time could be "far" in the past.
  base::Time request_time;

  // The time at which the response headers were received.  For cached
  // responses, this time could be "far" in the past.
  base::Time response_time;

  // The response headers or NULL if the URL type does not support headers.
  scoped_refptr<net::HttpResponseHeaders> headers;

  // The mime type of the response.  This may be a derived value.
  std::string mime_type;

  // The character encoding of the response or none if not applicable to the
  // response's mime type.  This may be a derived value.
  std::string charset;

  // An opaque string carrying security information pertaining to this
  // response.  This may include information about the SSL connection used.
  std::string security_info;

  // Content length if available. -1 if not available
  int64 content_length;

  // Length of the encoded data transferred over the network. In case there is
  // no data, contains -1.
  int64 encoded_data_length;

  // The appcache this response was loaded from, or kNoCacheId.
  int64 appcache_id;

  // The manifest url of the appcache this response was loaded from.
  // Note: this value is only populated for main resource requests.
  GURL appcache_manifest_url;

  // Connection identifier from the underlying network stack. In case there
  // is no associated connection, contains 0.
  uint32 connection_id;

  // Determines whether physical connection reused.
  bool connection_reused;

  // Detailed timing information used by the WebTiming, HAR and Developer
  // Tools.
  ResourceLoadTimingInfo load_timing;

  // Actual request and response headers, as obtained from the network stack.
  // Only present if request had LOAD_REPORT_RAW_HEADERS in load_flags, and
  // requesting renderer had CanReadRowCookies permission.
  scoped_refptr<ResourceDevToolsInfo> devtools_info;

  // The path to a file that will contain the response body.  It may only
  // contain a portion of the response body at the time that the ResponseInfo
  // becomes available.
  FilePath download_file_path;

  // True if the response was delivered using SPDY.
  bool was_fetched_via_spdy;

  // True if the response was delivered after NPN is negotiated.
  bool was_npn_negotiated;

  // True if response could use alternate protocol. However, browser will
  // ignore the alternate protocol when spdy is not enabled on browser side.
  bool was_alternate_protocol_available;

  // True if the response was fetched via an explicit proxy (as opposed to a
  // transparent proxy). The proxy could be any type of proxy, HTTP or SOCKS.
  // Note: we cannot tell if a transparent proxy may have been involved.
  bool was_fetched_via_proxy;

  // Remote address of the socket which fetched this resource.
  net::HostPortPair socket_address;
};

class ResourceLoaderBridge {
 public:
  // Structure used when calling ResourceLoaderBridge::Create().
  struct RequestInfo {
    RequestInfo();
    ~RequestInfo();

    // HTTP-style method name (e.g., "GET" or "POST").
    std::string method;

    // Absolute URL encoded in ASCII per the rules of RFC-2396.
    GURL url;

    // URL of the document in the top-level window, which may be checked by the
    // third-party cookie blocking policy.
    GURL first_party_for_cookies;

    // Optional parameter, a URL with similar constraints in how it must be
    // encoded as the url member.
    GURL referrer;

    std::string frame_origin;
    std::string main_frame_origin;

    // For HTTP(S) requests, the headers parameter can be a \r\n-delimited and
    // \r\n-terminated list of MIME headers.  They should be ASCII-encoded using
    // the standard MIME header encoding rules.  The headers parameter can also
    // be null if no extra request headers need to be set.
    std::string headers;

    // Composed of the values defined in url_request_load_flags.h.
    int load_flags;

    // Process id of the process making the request.
    int requestor_pid;

    // Indicates if the current request is the main frame load, a sub-frame
    // load, or a sub objects load.
    ResourceType::Type request_type;

    // Used for plugin to browser requests.
    uint32 request_context;

    // Identifies what appcache host this request is associated with.
    int appcache_host_id;

    // Used to associated the bridge with a frame's network context.
    int routing_id;

    // If true, then the response body will be downloaded to a file and the
    // path to that file will be provided in ResponseInfo::download_file_path.
    bool download_to_file;

    // True if the request was user initiated.
    bool has_user_gesture;
  };

  // See the SyncLoad method declared below.  (The name of this struct is not
  // suffixed with "Info" because it also contains the response data.)
  struct SyncLoadResponse : ResourceResponseInfo {
    SyncLoadResponse();
    ~SyncLoadResponse();

    // The response status.
    net::URLRequestStatus status;

    // The final URL of the response.  This may differ from the request URL in
    // the case of a server redirect.
    GURL url;

    // The response data.
    std::string data;
  };

  // Generated by the bridge. This is implemented by our custom resource loader
  // within webkit. The Peer and it's bridge should have identical lifetimes
  // as they represent each end of a communication channel.
  //
  // These callbacks mirror net::URLRequest::Delegate and the order and
  // conditions in which they will be called are identical. See url_request.h
  // for more information.
  class Peer {
   public:
    virtual ~Peer() {}

    // Called as upload progress is made.
    // note: only for requests with LOAD_ENABLE_UPLOAD_PROGRESS set
    virtual void OnUploadProgress(uint64 position, uint64 size) = 0;

    // Called when a redirect occurs.  The implementation may return false to
    // suppress the redirect.  The given ResponseInfo provides complete
    // information about the redirect, and new_url is the URL that will be
    // loaded if this method returns true.  If this method returns true, the
    // output parameter *has_new_first_party_for_cookies indicates whether the
    // output parameter *new_first_party_for_cookies contains the new URL that
    // should be consulted for the third-party cookie blocking policy.
    virtual bool OnReceivedRedirect(const GURL& new_url,
                                    const ResourceResponseInfo& info,
                                    bool* has_new_first_party_for_cookies,
                                    GURL* new_first_party_for_cookies) = 0;

    // Called when response headers are available (after all redirects have
    // been followed).
    virtual void OnReceivedResponse(const ResourceResponseInfo& info) = 0;

    // Called when a chunk of response data is downloaded.  This method may be
    // called multiple times or not at all if an error occurs.  This method is
    // only called if RequestInfo::download_to_file was set to true, and in
    // that case, OnReceivedData will not be called.
    virtual void OnDownloadedData(int len) = 0;

    // Called when a chunk of response data is available. This method may
    // be called multiple times or not at all if an error occurs.
    // The encoded_data_length is the length of the encoded data transferred
    // over the network, which could be different from data length (e.g. for
    // gzipped content), or -1 if if unknown.
    virtual void OnReceivedData(const char* data,
                                int data_length,
                                int encoded_data_length) = 0;

    // Called when metadata generated by the renderer is retrieved from the
    // cache. This method may be called zero or one times.
    virtual void OnReceivedCachedMetadata(const char* data, int len) { }

    // Called when the response is complete.  This method signals completion of
    // the resource load.ff
    virtual void OnCompletedRequest(const net::URLRequestStatus& status,
                                    const std::string& security_info,
                                    const base::Time& completion_time) = 0;
  };

  // use Create() for construction, but anybody can delete at any time,
  // INCLUDING during processing of callbacks.
  virtual ~ResourceLoaderBridge();

  // Call this method to make a new instance.
  //
  // For HTTP(S) POST requests, the AppendDataToUpload and AppendFileToUpload
  // methods may be called to construct the body of the request.
  static ResourceLoaderBridge* Create(const RequestInfo& request_info);

  // Call this method before calling Start() to append a chunk of binary data
  // to the request body.  May only be used with HTTP(S) POST requests.
  virtual void AppendDataToUpload(const char* data, int data_len) = 0;

  // Call this method before calling Start() to append the contents of a file
  // to the request body.  May only be used with HTTP(S) POST requests.
  void AppendFileToUpload(const FilePath& file_path) {
    AppendFileRangeToUpload(file_path, 0, kuint64max, base::Time());
  }

  // Call this method before calling Start() to append the contents of a file
  // to the request body.  May only be used with HTTP(S) POST requests.
  virtual void AppendFileRangeToUpload(
      const FilePath& file_path,
      uint64 offset,
      uint64 length,
      const base::Time& expected_modification_time) = 0;

  // Call this method before calling Start() to append the contents of a blob
  // to the request body.  May only be used with HTTP(S) POST requests.
  virtual void AppendBlobToUpload(const GURL& blob_url) = 0;

  // Call this method before calling Start() to assign an upload identifier to
  // this request.  This is used to enable caching of POST responses.  A value
  // of 0 implies the unspecified identifier.
  virtual void SetUploadIdentifier(int64 identifier) = 0;

  // Call this method to initiate the request.  If this method succeeds, then
  // the peer's methods will be called asynchronously to report various events.
  virtual bool Start(Peer* peer) = 0;

  // Call this method to cancel a request that is in progress.  This method
  // causes the request to immediately transition into the 'done' state. The
  // OnCompletedRequest method will be called asynchronously; this assumes
  // the peer is still valid.
  virtual void Cancel() = 0;

  // Call this method to suspend or resume a load that is in progress.  This
  // method may only be called after a successful call to the Start method.
  virtual void SetDefersLoading(bool value) = 0;

  // Call this method to load the resource synchronously (i.e., in one shot).
  // This is an alternative to the Start method.  Be warned that this method
  // will block the calling thread until the resource is fully downloaded or an
  // error occurs.  It could block the calling thread for a long time, so only
  // use this if you really need it!  There is also no way for the caller to
  // interrupt this method.  Errors are reported via the status field of the
  // response parameter.
  virtual void SyncLoad(SyncLoadResponse* response) = 0;

 protected:
  // construction must go through Create()
  ResourceLoaderBridge();

 private:
  DISALLOW_COPY_AND_ASSIGN(ResourceLoaderBridge);
};

}  // namespace webkit_glue

#endif  // WEBKIT_GLUE_RESOURCE_LOADER_BRIDGE_H_