// Copyright 2016 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.

module network.mojom;

import "services/network/public/mojom/http_request_headers.mojom";
import "services/network/public/mojom/network_param.mojom";

[Native]
struct URLRequest;

[Native]
struct URLResponseHead;

[Native]
struct URLRequestRedirectInfo;

[Native]
struct CORSErrorStatus;

[Native]
struct URLLoaderCompletionStatus;

// This enum corresponds to net::RequestPriority. See its comments for details.
enum RequestPriority {
  kThrottled = 0,
  kIdle,
  kLowest,
  kLow,
  kMedium,
  kHighest
};

// Destroying a URLLoader will cancel the associated request.
interface URLLoader {
  // If a disconnection is initiated by the client side, it may send the
  // following disconnection reason, along with an application-defined string
  // description, to notify the service side.
  const uint32 kClientDisconnectReason = 1;

  // If the associated request has |auto_follow_redirects| set to false,
  // then upon receiving an URLResponse with a non-NULL |redirect_url| field,
  // |FollowRedirect| may be called to load the URL indicated by the redirect.
  // |modified_request_headers| can be used to add or override existing headers
  // for the redirect.
  FollowRedirect(network.mojom.HttpRequestHeaders? modified_request_headers);

  // Resumes loading the response body if the URLLoader paused the request upon
  // receiving the final response headers.
  // The URLLoader pauses the request when kURLLoadOptionPauseOnResponseStarted
  // is used.
  // TODO(arthursonzogni): This is a temporary feature. Remove this as soon as
  // the InterceptingResourceHandler is removed. See https://crbug.com/791049.
  ProceedWithResponse();

  // Sets the request priority.
  // |intra_priority_value| is a lesser priority which is used to prioritize
  // requests within a given priority level. If -1 is passed, the existing
  // intra priority value is maintained.
  SetPriority(RequestPriority priority, int32 intra_priority_value);

  // If the resource is being fetched from the network,
  // PauseReadingBodyFromNet() pauses fetching the response body. It is okay to
  // call this method before fetching the body starts, too.
  // ResumeReadingBodyFromNet() resumes fetching the body if it has been paused.
  //
  // Note that PauseReadingBodyFromNet() is asynchronous and only gurantees to
  // pause if the response body is fetched from the network. This means:
  // - any data in flight before PauseReadingBodyFromNet() is processed will
  //   still be passed to the client data pipe.
  // - a response body not from the network, e.g. from blob, may not be paused
  //   at all.
  //
  // Redundant calls to these methods are ingored. It is not required to match
  // pause and resume calls. It is not an error to resume a non-paused request,
  // or pause a request multiple times.
  PauseReadingBodyFromNet();
  ResumeReadingBodyFromNet();
};

// Opaque handle passed from the browser process to a child process to manage
// the lifetime of temporary files used for download_to_file resource loading.
// When the message pipe for this interface is closed, the browser process will
// clean up the corresponding temporary file.
interface DownloadedTempFile {
};

interface URLLoaderClient {
  // Called when the response head is received.
  // |downloaded_file| is non-null in the 'download_to_file' case.
  OnReceiveResponse(URLResponseHead head,
                    DownloadedTempFile? downloaded_file);

  // Called when the request has been redirected. The receiver is expected to
  // call FollowRedirect or cancel the request.
  OnReceiveRedirect(URLRequestRedirectInfo redirect_info, URLResponseHead head);

  // Called when some data from a resource request has been downloaded to the
  // file. This is only called in the 'download_to_file' case and replaces
  // OnStartLoadingResponseBody in the call sequence in that case.
  // TODO(yhirano): Remove |encoded_length| and use OnTransferSizeUpdated
  // instead.
  OnDataDownloaded(int64 data_length, int64 encoded_length);

  // Called when the service made some progress on the file upload. This is
  // called only when the request has an upload data.
  // The implementation should call the response closure when the client is
  // ready to receive the next upload progress.
  OnUploadProgress(int64 current_position, int64 total_size) => ();

  // Called when cached metadata from a resource request is ready.
  OnReceiveCachedMetadata(array<uint8> data);

  // Called when the transfer size is updated. This is only called if
  // |report_raw_headers| is set and |download_to_file| is unset in the request.
  // The transfer size is the length of the response (including both headers
  // and the body) over the network. |transfer_size_diff| is the difference from
  // the value previously reported one (including the one in OnReceiveResponse
  // and OnReceiveRedirect). It must be positive.
  // TODO(yhirano): Dispatch this notification even when |download_to_file| is
  // set.
  // TODO(yhirano): Consider using an unsigned type.
  OnTransferSizeUpdated(int32 transfer_size_diff);

  // Called when the loader starts loading response body. This is called after
  // OnReceiveResponse is called.
  OnStartLoadingResponseBody(handle<data_pipe_consumer> body);

  // Called when the loading completes. No notification will be dispatched for
  // this client after this message arrives. |status| has its |ssl_info| field
  // set only when |kURLLoadOptionsSendSSLInfoForCertificateError| was set.
  OnComplete(URLLoaderCompletionStatus status);
};

// Convenient struct that groups the two communication endpoints most
// implementations of URLLoaderClient use to communicate with their URLLoader.
struct URLLoaderClientEndpoints {
  URLLoader url_loader;
  URLLoaderClient& url_loader_client;
};