// Copyright 2014 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 mojo;

import "mojo/services/public/interfaces/network/network_error.mojom";

struct URLRequest {
  // The URL to load.
  string? url;

  // The HTTP method if applicable.
  string? method = "GET";

  // Additional HTTP request headers.
  array<string?>? headers;

  // The payload for the request body, represented as a concatenation of data
  // streams. For HTTP requests, the method must be set to "POST" or "PUT".
  array<handle<data_pipe_consumer>?>? body;

  // The number of bytes to be read from |body|. A Content-Length header of
  // this value will be sent. Set to -1 if length is unknown, which will cause
  // |body| to be uploaded using a chunked encoding.
  int64 body_length = 0;

  // The buffer size of the data pipe returned in URLResponse's |body| member.
  // A value of 0 indicates that the default buffer size should be used.  This
  // value is just a suggestion. The URLLoader may choose to ignore this value.
  uint32 response_body_buffer_size = 0;

  // If set to true, then redirects will be automatically followed. Otherwise,
  // when a redirect is encounterd, FollowRedirect must be called to proceed.
  bool auto_follow_redirects = false;

  // If set to true, then the HTTP request will bypass the local cache and will
  // have a 'Cache-Control: nocache' header added in that causes any proxy
  // servers to also not satisfy the request from their cache.  This has the
  // effect of forcing a full end-to-end fetch.
  bool bypass_cache = false;
};

struct URLResponse {
  // If the response resulted in a network level error, this field will be set.
  NetworkError? error;

  // The response body stream. Read from this data pipe to receive the bytes of
  // response body.
  handle<data_pipe_consumer>? body;

  // The final URL of the response, after redirects have been followed.
  string? url;

  // The HTTP status code. 0 if not applicable.
  uint32 status_code;

  // The HTTP status line.
  string? status_line;

  // The HTTP response headers.
  array<string?>? headers;

  // The MIME type of the response body.
  string? mime_type;

  // The character set of the response body.
  string? charset;

  // These fields are set to non-NULL if this response corresponds to a
  // redirect.  Call the |FollowRedirect| method on the URLLoader instance to
  // follow this redirect.
  string? redirect_method;
  string? redirect_url;
};

struct URLLoaderStatus {
  // If the loader has failed due to a network level error, this field will be
  // set.
  NetworkError? error;

  // Set to true if the URLLoader is still working. Set to false once an error
  // is encountered or the response body is completely copied to the response
  // body stream.
  bool is_loading;

  // TODO(darin): Add further details about the stages of loading (e.g.,
  // "resolving host") that happen prior to receiving bytes.
};

interface URLLoader {
  // Loads the given |request|, asynchronously producing |response|. Consult
  // |response| to determine if the request resulted in an error, was
  // redirected, or has a response body to be consumed.
  Start(URLRequest? request) => (URLResponse? response);

  // If the request passed to |Start| had |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.
  FollowRedirect() => (URLResponse? response);

  // Query status about the URLLoader.
  QueryStatus() => (URLLoaderStatus? status);
};