components/cronet/native/cronet.idl

// Copyright 2017 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 IDL in this file is based on Mojo IDL, but is not currently targeted
// for direct use in Mojo projects.

module Cronet;

// General system support interfaces.

/**
 * Data buffer provided by the application to read and write data.
 */
interface Buffer {
  /**
   * Initialize Buffer with raw buffer |data| of |size| allocated by the app.
   * The |callback| is invoked when buffer is destroyed.
   */
  InitWithDataAndCallback(handle data, uint64 size, BufferCallback callback);

  /**
   * Initialize Buffer by allocating buffer of |size|. The content of allocated
   * data is not initialized.
   */
  InitWithAlloc(uint64 size);

  /**
   * Return size of data owned by this buffer.
   */
  [Sync]
  GetSize() => (uint64 size);

  /**
   * Return raw pointer to |data| owned by this buffer.
   */
  [Sync]
  GetData() => (handle data);
};

/**
 * App-provided callback passed to Buffer::InitWithDataAndCallback that gets invoked
 * when Buffer is destroyed.
 */
[Abstract]
interface BufferCallback {
  /**
   * Method invoked when |buffer| is destroyed so its app-allocated |data| can
   * be freed. If a UrlRequest has ownership of a Buffer and the UrlRequest is destroyed
   * (e.g. Cronet_UrlRequest_Destroy() is called), then Cronet will call OnDestroy().
   */
  OnDestroy(Buffer buffer);
};

// Base exception passed to UrlRequestCallback.onFailed().
struct Exception {
  enum ERROR_CODE {
    /**
     * Error code indicating the error returned by app callback.
     */
    ERROR_CALLBACK = 0,

    /**
     * Error code indicating the host being sent the request could not be resolved to an IP address.
     */
    ERROR_HOSTNAME_NOT_RESOLVED = 1,

    /**
     * Error code indicating the device was not connected to any network.
     */
    ERROR_INTERNET_DISCONNECTED = 2,

    /**
     * Error code indicating that as the request was processed the network configuration changed.
     */
    ERROR_NETWORK_CHANGED = 3,

    /**
     * Error code indicating a timeout expired. Timeouts expiring while attempting to connect will
     * be reported as the more specific {@link #ERROR_CONNECTION_TIMED_OUT}.
     */
    ERROR_TIMED_OUT = 4,

    /**
     * Error code indicating the connection was closed unexpectedly.
     */
    ERROR_CONNECTION_CLOSED = 5,

    /**
     * Error code indicating the connection attempt timed out.
     */
    ERROR_CONNECTION_TIMED_OUT = 6,

    /**
     * Error code indicating the connection attempt was refused.
     */
    ERROR_CONNECTION_REFUSED = 7,

    /**
     * Error code indicating the connection was unexpectedly reset.
     */
    ERROR_CONNECTION_RESET = 8,

    /**
     * Error code indicating the IP address being contacted is unreachable, meaning there is no
     * route to the specified host or network.
     */
    ERROR_ADDRESS_UNREACHABLE = 9,

    /**
     * Error code indicating an error related to the <a href="https://www.chromium.org/quic">
     * QUIC</a> protocol. When {@link #getErrorCode} returns this code, this exception can be cast
     * to {@link QuicException} for more information.
     */
    ERROR_QUIC_PROTOCOL_FAILED = 10,

    /**
     * Error code indicating another type of error was encountered.
     * |internal_error_code| can be consulted to get a more specific cause.
     */
    ERROR_OTHER = 11
  };

  /**
   * Error code, one of ERROR_* values.
   */
  ERROR_CODE error_code = ERROR_CALLBACK;
  /**
   * Cronet internal error code. This may provide more specific error
   * diagnosis than |error_code|, but the constant values  may change over time.
   * See
   * <a href=https://chromium.googlesource.com/chromium/src/+/master/net/base/net_error_list.h>
   * here</a> for the lastest list of values.
   */
  int32 internal_error_code = 0;

  /**
   * |true| if retrying this request right away might succeed, |false|
   * otherwise. For example, is |true| when |error_code| is |ERROR_NETWORK_CHANGED|
   * because trying the request might succeed using the new
   * network configuration, but |false| when |error_code| is
   * ERROR_INTERNET_DISCONNECTED because retrying the request right away will
   * encounter the same failure (instead retrying should be delayed until device regains
   * network connectivity).
   */
  bool immediately_retryable = false;

  /**
   * Contains detailed <a href="https://www.chromium.org/quic">QUIC</a> error code from
   * <a href=https://cs.chromium.org/chromium/src/net/quic/quic_protocol.h?type=cs&q=%22enum+QuicErrorCode+%7B%22+file:src/net/quic/quic_protocol.h>
   * QuicErrorCode</a> when the |error_code| code is |ERROR_QUIC_PROTOCOL_FAILED|.
   */
  int32 quic_detailed_error_code = 0;
};

/**
 * An interface to run commands on the |Executor|.
 */
[Abstract]
interface Runnable {
  Run();
};

/**
 * An interface provided by the app to run |command| asynchronously.
 */
[Abstract]
interface Executor {
  /**
   * Takes ownership of |command| and runs it synchronously or asynchronously.
   * Destroys the |command| after execution.
   */
  Execute(Runnable command);
};

/**
 * An engine to process UrlRequests, which uses the best HTTP stack
 * available on the current platform. An instance of this class can be started
 * using StartWithParams.
 */
interface Engine {
  /**
   * Starts Engine using given |params|. The engine must be started once
   * and only once before other methods can be used.
   */
  StartWithParams(EngineParams params);

  /**
   * Starts NetLog logging to a file. The NetLog will contain events emitted
   * by all live Engines. The NetLog is useful for debugging.
   * The file can be viewed using a Chrome browser navigated to
   * chrome://net-internals/#import
   * @param fileName the complete file path. It must not be empty. If the file
   *            exists, it is truncated before starting. If actively logging,
   *            this method is ignored.
   * @param logAll {@code true} to include basic events, user cookies,
   *    credentials and all transferred bytes in the log. This option presents
   *    a privacy risk, since it exposes the user's credentials, and should
   *    only be used with the user's consent and in situations where the log
   *    won't be public.  {@code false} to just include basic events.
   */
  StartNetLogToFile(string fileName, bool logAll);

  /**
   * Stops NetLog logging and flushes file to disk. If a logging session is
   * not in progress, this call is ignored.
   */
  StopNetLog();

  /**
   * Returns a human-readable version string of the engine.
   */
  [Sync]
  GetVersionString() => (string version_string);

  /**
   * Returns default human-readable version string of the engine. Can be used
   * before StartWithParams() is called.
   */
  [Sync]
  GetDefaultUserAgent() => (string default_user_agent);
};

/**
 * Hint that |host| supports QUIC.
 */
struct QuicHint {
  /**
   * Name of the host that supports QUIC.
   */
  string host;

  /**
   * Port of the server that supports QUIC.
   */
  int32 port = 0;

  /**
   * Alternate port to use for QUIC.
   */
  int32 alternatePort = 0;
};

/**
 * Pins a set of public keys for a given |host|. By pinning a set of public keys,
 * |pinsSha256|, communication with |host| is required to
 * authenticate with a certificate with a public key from the set of pinned ones.
 * An app can pin the public key of the root certificate, any of the intermediate
 * certificates or the end-entry certificate. Authentication will fail and secure
 * communication will not be established if none of the public keys is present in the
 * host's certificate chain, even if the host attempts to authenticate with a
 * certificate allowed by the device's trusted store of certificates.
 *
 * More information about the public key pinning can be found in
 * <a href="https://tools.ietf.org/html/rfc7469">RFC 7469</a>.
 */
struct PublicKeyPins {
  /**
   * Name of the host to which the public keys should be pinned. A host that
   * consists only of digits and the dot character is treated as invalid.
   */
  string host;

  /**
   * An array of pins. Each pin is the SHA-256 cryptographic
   * hash of the DER-encoded ASN.1 representation of the Subject Public
   * Key Info (SPKI) of the host's X.509 certificate.
   * Although, the method does not mandate the presence of the backup pin
   * that can be used if the control of the primary private key has been
   * lost, it is highly recommended to supply one.
   */
  array<handle> pinsSha256;

  /**
   * Indicates whether the pinning policy should be applied to subdomains of |host|.
   */
  bool includeSubdomains = false;
};

/**
 * Parameters for Engine, which allows its configuration before start.
 * Configuration options are set on the EngineParms and
 * then Engine.StartWithParams is called to start the Engine.
 */
struct EngineParams {
  /**
   * Override of the User-Agent header for all requests. An explicitly
   * set User-Agent header will override a value set using this param.
   */
  string userAgent;

  /**
   * Directory for HTTP Cache and Prefs Storage. The directory must exist.
   */
  string storagePath;

  /**
   * Whether <a href="https://www.chromium.org/quic">QUIC</a> protocol
   * is enabled. If QUIC is enabled, then QUIC User Agent Id
   * containing application name and Cronet version is sent to the server.
   */
  bool enableQuic = false;

  /**
   * Whether <a href="https://tools.ietf.org/html/rfc7540">HTTP/2</a>
   * protocol is enabled.
   */
  bool enableHttp2 = true;

  /**
   * Whether <a href="https://tools.ietf.org/html/rfc7932">Brotli</a> compression is
   * enabled. If enabled, Brotli will be advertised in Accept-Encoding request headers.
   */
  bool enableBrotli = true;

  /**
   * Enables or disables caching of HTTP data and other information like QUIC
   * server information.
   */
  enum HTTP_CACHE_MODE {
    /**
     * Disable HTTP cache. Some data may still be temporarily stored in memory.
     */
    DISABLED = 0,

    /**
     * Enable in-memory HTTP cache, including HTTP data.
     */
    IN_MEMORY = 1,

    /**
     * Enable on-disk cache, excluding HTTP data.
     * |storagePath| must be set to existing directory.
     */
    DISK_NO_HTTP = 2,

    /**
     * Enable on-disk cache, including HTTP data.
     * |storagePath| must be set to existing directory.
     */
    DISK = 3
  };
  HTTP_CACHE_MODE httpCacheMode = DISABLED;

  /**
   * Maximum size in bytes used to cache data (advisory and maybe exceeded at
   * times).
   */
  int64 httpCacheMaxSize = 0;

  /**
   * Hints that hosts support QUIC.
   */
  array<QuicHint> quicHints;

  /**
   * Pins a set of public keys for given hosts. See |PublicKeyPins| for explanation.
   */
  array<PublicKeyPins> publicKeyPins;

  /**
   * Enables or disables public key pinning bypass for local trust anchors. Disabling the
   * bypass for local trust anchors is highly discouraged since it may prohibit the app
   * from communicating with the pinned hosts. E.g., a user may want to send all traffic
   * through an SSL enabled proxy by changing the device proxy settings and adding the
   * proxy certificate to the list of local trust anchor. Disabling the bypass will most
   * likly prevent the app from sending any traffic to the pinned hosts. For more
   * information see 'How does key pinning interact with local proxies and filters?' at
   * https://www.chromium.org/Home/chromium-security/security-faq
   */
  bool enablePublicKeyPinningBypassForLocalTrustAnchors = true;
};

/**
  * Single HTTP request or response header.
  */
struct HttpHeader {
  /**
   * Header name.
   */
  string name;

  /**
   * Header value.
   */
  string value;
};

struct UrlResponseInfo {
  /**
   * The URL the response is for. This is the URL after following
   * redirects, so it may not be the originally requested URL.
   */
  string url;

  /**
   * The URL chain. The first entry is the originally requested URL;
   * the following entries are redirects followed.
   */
  array<string> urlChain;

  /**
   * The HTTP status code. When a resource is retrieved from the cache,
   * whether it was revalidated or not, the original status code is returned.
   */
  int32 httpStatusCode;

  /**
   * The HTTP status text of the status line. For example, if the
   * request received a "HTTP/1.1 200 OK" response, this method returns "OK".
   */
  string httpStatusText;

  /**
   * Returns an unmodifiable list of response header field and value pairs.
   * The headers are in the same order they are received over the wire.
   */
  array<HttpHeader> allHeadersList;

  /**
   * True if the response came from the cache, including
   * requests that were revalidated over the network before being retrieved
   * from the cache, failed otherwise.
   */
  bool wasCached;

  /**
   * The protocol (for example 'quic/1+spdy/3') negotiated with the server.
   * An empty string if no protocol was negotiated, the protocol is
   * not known, or when using plain HTTP or HTTPS.
   */
  string negotiatedProtocol;

  /**
   * The proxy server that was used for the request.
   */
  string proxyServer;

  /**
   * A minimum count of bytes received from the network to process this
   * request. This count may ignore certain overheads (for example IP and
   * TCP/UDP framing, SSL handshake and framing, proxy handling). This count is
   * taken prior to decompression (for example GZIP and Brotli) and includes
   * headers and data from all redirects.
   */
  int64 receivedByteCount;
};

/**
 * Listener class used with UrlRequest.GetStatus() to receive the status of a
 * UrlRequest.
 */
[Abstract]
interface UrlRequestStatusListener {
  enum Status {
    /**
     * This state indicates that the request is completed, canceled, or is not
     * started.
     */
    INVALID = -1,

    /**
     * This state corresponds to a resource load that has either not yet begun
     * or is idle waiting for the consumer to do something to move things along
     * (e.g. when the consumer of a UrlRequest has not called
     * UrlRequest.read() yet).
     */
    IDLE = 0,

    /**
     * When a socket pool group is below the maximum number of sockets allowed
     * per group, but a new socket cannot be created due to the per-pool socket
     * limit, this state is returned by all requests for the group waiting on an
     * idle connection, except those that may be serviced by a pending new
     * connection.
     */
    WAITING_FOR_STALLED_SOCKET_POOL = 1,

    /**
     * When a socket pool group has reached the maximum number of sockets
     * allowed per group, this state is returned for all requests that don't
     * have a socket, except those that correspond to a pending new connection.
     */
    WAITING_FOR_AVAILABLE_SOCKET = 2,

    /**
     * This state indicates that the URLRequest delegate has chosen to block
     * this request before it was sent over the network.
     */
    WAITING_FOR_DELEGATE = 3,

    /**
     * This state corresponds to a resource load that is blocked waiting for
     * access to a resource in the cache. If multiple requests are made for the
     * same resource, the first request will be responsible for writing (or
     * updating) the cache entry and the second request will be deferred until
     * the first completes. This may be done to optimize for cache reuse.
     */
    WAITING_FOR_CACHE = 4,

    /**
     * This state corresponds to a resource being blocked waiting for the
     * PAC script to be downloaded.
     */
    DOWNLOADING_PROXY_SCRIPT = 5,

    /**
     * This state corresponds to a resource load that is blocked waiting for a
     * proxy autoconfig script to return a proxy server to use.
     */
    RESOLVING_PROXY_FOR_URL = 6,

    /**
     * This state corresponds to a resource load that is blocked waiting for a
     * proxy autoconfig script to return a proxy server to use, but that proxy
     * script is busy resolving the IP address of a host.
     */
    RESOLVING_HOST_IN_PROXY_SCRIPT = 7,

    /**
     * This state indicates that we're in the process of establishing a tunnel
     * through the proxy server.
     */
    ESTABLISHING_PROXY_TUNNEL = 8,

    /**
     * This state corresponds to a resource load that is blocked waiting for a
     * host name to be resolved. This could either indicate resolution of the
     * origin server corresponding to the resource or to the host name of a
     * proxy server used to fetch the resource.
     */
    RESOLVING_HOST = 9,

    /**
     * This state corresponds to a resource load that is blocked waiting for a
     * TCP connection (or other network connection) to be established. HTTP
     * requests that reuse a keep-alive connection skip this state.
     */
    CONNECTING = 10,

    /**
     * This state corresponds to a resource load that is blocked waiting for the
     * SSL handshake to complete.
     */
    SSL_HANDSHAKE = 11,

    /**
     * This state corresponds to a resource load that is blocked waiting to
     * completely upload a request to a server. In the case of a HTTP POST
     * request, this state includes the period of time during which the message
     * body is being uploaded.
     */
    SENDING_REQUEST = 12,

    /**
     * This state corresponds to a resource load that is blocked waiting for the
     * response to a network request. In the case of a HTTP transaction, this
     * corresponds to the period after the request is sent and before all of the
     * response headers have been received.
     */
    WAITING_FOR_RESPONSE = 13,

    /**
     * This state corresponds to a resource load that is blocked waiting for a
     * read to complete. In the case of a HTTP transaction, this corresponds to
     * the period after the response headers have been received and before all
     * of the response body has been downloaded. (NOTE: This state only applies
     * for an {@link UrlRequest} while there is an outstanding
     * {@link UrlRequest#read read()} operation.)
     */
    READING_RESPONSE = 14
  };

  /**
   * Invoked on UrlRequest's Executor when request status is obtained.
   * |status| is representing the status of the request.
   */
  OnStatus(Status status);
};

/**
 * Users of Cronet implement this interface to receive callbacks indicating the
 * progress of a UrlRequest being processed. An instance of this interface
 * is passed in to UrlRequest's method InitWithParams().
 * <p>
 * Note:  All methods will be invoked on the Executor passed to UrlRequest.InitWithParams();
 */
[Abstract]
interface UrlRequestCallback {

  /**
   * Invoked whenever a redirect is encountered. This will only be invoked
   * between the call to UrlRequest.start() and
   * UrlRequestCallback.onResponseStarted().
   * The body of the redirect response, if it has one, will be ignored.
   *
   * The redirect will not be followed until the URLRequest.followRedirect()
   * ethod is called, either synchronously or asynchronously.
   *
   * @param request Request being redirected.
   * @param info Response information.
   * @param newLocationUrl Location where request is redirected.
   */
  OnRedirectReceived(UrlRequest request, UrlResponseInfo info, string newLocationUrl);

  /**
   * Invoked when the final set of headers, after all redirects, is received.
   * Will only be invoked once for each request.
   *
   * With the exception of UrlRequestCallback.onCanceled(),
   * no other UrlRequestCallback method will be invoked for the request,
   * including UrlRequestCallback.onSucceeded() and
   * UrlRequestCallback.onFailed(), until UrlRequest.read()} is called to attempt
   * to start reading the response body.
   *
   * @param request Request that started to get response.
   * @param info Response information.
   */
  OnResponseStarted(UrlRequest request, UrlResponseInfo info);

  /**
   * Invoked whenever part of the response body has been read. Only part of
   * the buffer may be populated, even if the entire response body has not yet
   * been consumed. This callback transfers ownership of |buffer| back to the app,
   * and Cronet guarantees not to access it.
   *
   * With the exception of UrlRequestCallback.onCanceled(),
   * no other UrlRequestCallback method will be invoked for the request,
   * including UrlRequestCallback.onSucceeded() and
   * UrlRequestCallback.onFailed(), until UrlRequest.read()} is called to attempt
   * to continue reading the response body.
   *
   * @param request Request that received data.
   * @param info Response information.
   * @param buffer The buffer that was passed in to UrlRequest.read(), now
   *         containing the received data. The buffer's position is updated to the end of
   *         the received data. The buffer's limit is not changed.
   */
  OnReadCompleted(UrlRequest request, UrlResponseInfo info, Buffer buffer);

  /**
   * Invoked when request is completed successfully. Once invoked, no other
   * UrlRequestCallback methods will be invoked.
   *
   * @param request Request that succeeded.
   * @param info Response information.
   */
  OnSucceeded(UrlRequest request, UrlResponseInfo info);

  /**
   * Invoked if request failed for any reason after UrlRequest.start().
   * Once invoked, no other UrlRequestCallback methods will be invoked.
   * |error| provides information about the failure.
   *
   * @param request Request that failed.
   * @param info Response information. May be null if no response was
   *         received.
   * @param error information about error.
   */
  OnFailed(UrlRequest request, UrlResponseInfo info, Exception error);

  /**
   * Invoked if request was canceled via UrlRequest.cancel(). Once
   * invoked, no other UrlRequestCallback methods will be invoked.
   *
   * @param request Request that was canceled.
   * @param info Response information. May be null if no response was
   *         received.
   */
  OnCanceled(UrlRequest request, UrlResponseInfo info);
};

/**
 * Defines callbacks methods for UploadDataProvider. All methods
 * may be called synchronously or asynchronously, on any thread.
 */
interface UploadDataSink {
  /**
   * Called by UploadDataProvider when a read succeeds.
   *
   * @param finalChunk For chunked uploads, |true| if this is the final
   *     read. It must be |false| for non-chunked uploads.
   */
  OnReadSucceeded(bool finalChunk);

  /**
   * Called by UploadDataProvider when a read fails.
   * @param error to pass on to UrlRequestCallback.onFailed().
   */
  OnReadError(Exception error);

  /**
   * Called by UploadDataProvider when a rewind succeeds.
   */
  OnRewindSucceded();

  /**
   * Called by UploadDataProvider when a rewind fails, or if rewinding
   * uploads is not supported.
   * @param error to pass on to UrlRequestCallback.onFailed().
   */
  OnRewindError(Exception error);
};

/**
 * The interface allowing the embedder to provide an upload body to
 * UrlRequest. It supports both non-chunked (size known in advanced) and
 * chunked (size not known in advance) uploads. Be aware that not all servers
 * support chunked uploads.
 *
 * An upload is either always chunked, across multiple uploads if the data
 * ends up being sent more than once, or never chunked.
 */
[Abstract]
interface UploadDataProvider {
  /**
   * If this is a non-chunked upload, returns the length of the upload. Must
   * always return -1 if this is a chunked upload.
   */
  [Sync]
  GetLength() => (int64 length);

  /**
   * Reads upload data into |buffer|. Upon completion, the buffer's
   * position is updated to the end of the bytes that were read. The buffer's
   * limit is not changed. Each call of this method must be followed be a
   * single call, either synchronous or asynchronous, to
   * UploadDataSink.onReadSucceeded() on success
   * or UploadDataSink.onReadError() on failure. Neither read nor rewind
   * will be called until one of those methods or the other is called. Even if
   * the associated UrlRequest is canceled, one or the other must
   * still be called before resources can be safely freed.
   *
   * @param uploadDataSink The object to notify when the read has completed,
   *            successfully or otherwise.
   * @param buffer The buffer to copy the read bytes into. Do not change
   *            byteBuffer's limit.
   */
  Read(UploadDataSink uploadDataSink, Buffer buffer);

  /**
   * Rewinds upload data. Each call must be followed be a single
   * call, either synchronous or asynchronous, to
   * UploadDataSink.onRewindSucceeded() on success or
   * UploadDataSink.onRewindError() on failure. Neither read nor rewind
   * will be called until one of those methods or the other is called.
   * Even if the associated UrlRequest is canceled, one or the other
   * must still be called before resources can be safely freed. Throwing an
   * exception will also result in resources being freed and the request being
   * errored out.
   *
   * If rewinding is not supported, this should call
   * UploadDataSink.onRewindError(). Note that rewinding is required to
   * follow redirects that preserve the upload body, and for retrying when the
   * server times out stale sockets.
   *
   * @param uploadDataSink The object to notify when the rewind operation has
   *         completed, successfully or otherwise.
   */
  Rewind(UploadDataSink uploadDataSink);

  /**
   * Called when this UploadDataProvider is no longer needed by a request, so that resources
   * (like a file) can be explicitly released.
   */
  Close();
};

/**
 * Controls an HTTP request (GET, PUT, POST etc).
 * Initialized by InitWithParams().
 * Note: All methods must be called on the Executor passed to InitWithParams().
 */
interface UrlRequest {

  /**
   * Initialized UrlRequest to |url| with |params|. All methods of |callback| for
   * request will be invoked on |executor|. The |executor| must not run tasks on
   * the thread calling Executor.execute() to prevent blocking networking
   * operations and causing exceptions during shutdown.
   *
   * @param engine Engine to process the request.
   * @param url URL for the request.
   * @param params additional parameters for the request, like headers and priority.
   * @param callback Callback that gets invoked on different events.
   * @param executor Executor on which all callbacks will be invoked.
   */
  InitWithParams(Engine engine,
                 string url,
                 UrlRequestParams params,
                 UrlRequestCallback callback,
                 Executor executor);

  /**
   * Starts the request, all callbacks go to UrlRequestCallback. May only be called
   * once. May not be called if Cancel() has been called.
   */
  Start();

  /**
   * Follows a pending redirect. Must only be called at most once for each
   * invocation of UrlRequestCallback.OnRedirectReceived().
   */
  FollowRedirect();

  /**
   * Attempts to read part of the response body into the provided buffer.
   * Must only be called at most once in response to each invocation of the
   * UrlRequestCallback.OnResponseStarted() and
   * UrlRequestCallback.OnReadCompleted()} methods of the UrlRequestCallback.
   * Each call will result in an asynchronous call to
   * either the UrlRequestCallback.OnReadCompleted() method if data
   * is read, its UrlRequestCallback.OnSucceeded() method if
   * there's no more data to read, or its UrlRequestCallback.OnFailed()
   * method if there's an error.
   * This callback transfers ownership of |buffer| Cronet, and app guarantees
   * not to access it until one of these callbacks is invoked.
   *
   * @param buffer to write response body to. The app must not read or
   *        modify buffer's position, limit, or data between its position and
   *        limit until the request calls back into the UrlRequestCallback.
   */
  Read(Buffer buffer);

  /**
   * Cancels the request. Can be called at any time.
   * UrlRequestCallback.OnCanceled() will be invoked when cancellation
   * is complete and no further callback methods will be invoked. If the
   * request has completed or has not started, calling Cancel() has no
   * effect and OnCanceled() will not be invoked. If the
   * Executor passed in to UrlRequest.InitWithParams() runs
   * tasks on a single thread, and Cancel() is called on that thread,
   * no callback methods (besides OnCanceled() will be invoked after
   * Cancel() is called. Otherwise, at most one callback method may be
   * invoked after Cancel() has completed.
   */
  Cancel();

  /**
   * Returns true if the request was successfully started and is now
   * finished (completed, canceled, or failed).
   */
  [Sync]
  IsDone() => (bool done);

  /**
   * Queries the status of the request.
   * @param listener a UrlRequestStatusListener that will be invoked with
   *         the request's current status. Listener will be invoked
   *         back on the Executor passed in when the request was
   *         created.
   */
  GetStatus(UrlRequestStatusListener listener);
};

/**
 * Parameters for UrlRequest. Allows configuring requests before initializing them
 * with UrlRequest.InitWithParams().
 */
struct UrlRequestParams {
  enum REQUEST_PRIORITY {
    /**
     * Lowest request priority.
     */
    REQUEST_PRIORITY_IDLE = 0,
    /**
     * Very low request priority.
     */
    REQUEST_PRIORITY_LOWEST = 1,
    /**
     * Low request priority.
     */
    REQUEST_PRIORITY_LOW = 2,
    /**
     * Medium request priority. This is the default priority given to the request.
     */
    REQUEST_PRIORITY_MEDIUM = 3,
    /**
     * Highest request priority.
     */
    REQUEST_PRIORITY_HIGHEST = 4,
  };

  /**
   * The HTTP method verb to use for this request.
   *
   * The default when this value is not set is "GET" if the request has
   * no body or "POST" if it does.
   *
   * Allowed methods are "GET", "HEAD", "DELETE", "POST" or "PUT".
   */
  string httpMethod;

  /**
   * Array of HTTP headers for this request..
   */
  array<HttpHeader> requestHeaders;

  /**
   * Disables cache for the request. If context is not set up to use cache,
   * this call has no effect.
   */
  bool disableCache = false;

  /**
   * Priority of the request which should be one of the REQUEST_PRIORITY values.
   */
  REQUEST_PRIORITY priority = REQUEST_PRIORITY_MEDIUM;

  /**
   * Upload data provider. Setting this value switches method to "POST" if not
   * explicitly set. Starting the request will fail if a Content-Type header is not set.
   */
  UploadDataProvider uploadDataProvider;

  /**
   * Upload data provider executor that will be used to invoke uploadDataProvider.
   */
  Executor uploadDataProviderExecutor;

  /**
   * Marks that the executors this request will use to notify callbacks (for
   * UploadDataProvider andUrlRequestCallback) is intentionally performing
   * inline execution without switching to another thread.
   *
   * <p><b>Warning:</b> This option makes it easy to accidentally block the network thread.
   * It should not be used if your callbacks perform disk I/O, acquire locks, or call into
   * other code you don't carefully control and audit.
   */
  bool allowDirectExecutor = false;

  /**
   * Associates the annotation object with this request. May add more than one.
   * Passed through to a RequestFinishedInfo.Listener.
   */
  array<handle> annotations;
};