// Copyright 2018 The Fuchsia Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.

library fuchsia.net.http;

using fuchsia.mem;

/// An error occurred during the HTTP transaction.
struct Error {
    /// The numerical error code.
    ///
    /// These error codes correspond to
    /// <https://fuchsia.googlesource.com/fuchsia/+/master/garnet/bin/network/net_error_list.h>
    int32 code;

    /// A textual description of the error in en-US.
    string? description;
};

/// An HTTP header field.
struct Header {
    /// The name of the header field.
    bytes name;

    /// The value of the header field.
    bytes value;
};

/// The body of either an HTTP request or an HTTP response.
union Body {
    /// A buffer that will contain the complete request or response body.
    1: fuchsia.mem.Buffer buffer;

    /// A socket that will contain the streaming request or response body.
    2: handle<socket> stream;
};

/// Specify the cache behavior of the request.
enum CacheMode {
    /// Default behavior.
    DEFAULT = 0;

    /// 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.
    BYPASS_CACHE = 1;

    /// The HTTP request will fail if it cannot serve the requested resource
    /// from the cache (or some equivalent local store).
    ONLY_FROM_CACHE = 2;
};

/// Specify the mechanism used to return the response body.
///
/// Streaming the response can be more efficient if the response body is large
/// and can be processed incrementally (e.g., by an image decoder).
///
/// Buffering the response can be more efficient if the response body is in cache
/// and the cache entry can be directly mapped into the resulting buffer.
enum ResponseBodyMode {
    /// The complete response body should be returned in the `buffer` field of
    /// the response body.
    ///
    /// The loader MAY abort the transation if the buffer size exceeds an
    /// implementation-defined limit.
    BUFFER = 0;

    /// The response body should be streamed through the `stream` field of the
    /// response body.
    STREAM = 1;
};

/// An HTTP request.
struct Request {
    /// The HTTP method if applicable.
    string method = "GET";

    /// The URL to load.
    bytes url;

    /// Additional HTTP request headers.
    vector<Header>? headers;

    /// The payload for the request body. For HTTP requests, the method must be set
    /// to "POST" or "PUT". If a buffer is used for the body, a Content-Length
    /// header will automatically be added.
    Body? body;

    /// The loader will cancel the request if the peer for this event is closed.
    ///
    /// When this happens, the loader will send a Response with the appropriate
    /// error code.
    handle<eventpair>? event;

    /// The cache behavior for the request.
    CacheMode cache_mode = CacheMode.DEFAULT;

    /// The response body mode.
    ResponseBodyMode response_body_mode = ResponseBodyMode.BUFFER;
};

/// A description of the redirect the server requested.
///
/// The semantics of an HTTP redirect vary according to the status code use to
/// generate the redirect. This structure ensures that the loader and its client
/// agree on the interpretation of the redirect response from the server.
struct RedirectTarget {
    /// The HTTP method the server suggested for the redirect.
    string method;

    /// The URL the server suggested for the redirect.
    bytes url;

    /// The referrer the server suggested for the redirect.
    bytes referrer;
};

/// A response to an HTTP request.
struct Response {
    /// If the response resulted in a network level error, this field will be set.
    Error? error;

    /// The response body.
    Body? body;

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

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

    /// The HTTP status line.
    string? status_line;

    /// The HTTP response headers.
    vector<Header>? headers;

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

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

/// An HTTP loader.
///
/// The loader can service many HTTP requests concurrently. The loader tracks all
/// the outstanding requests and will cancel them all if the client closes the
/// loader interface.
[Discoverable]
protocol Loader {
    /// Initiate the given HTTP request, follow redirects, and return the final
    /// response.
    ///
    /// The loader will follow redirects (up to an implementation-defined limit)
    /// and return the final response as a reply to this message. To cancel the
    /// request, either close the loader interface or close the peer to the `event`
    /// included in the `request`.
    Fetch(Request request) -> (Response response);

    /// Initiate the given HTTP request and return all intermediate responses to
    /// the given client.
    ///
    /// Unlike `Fetch`, `Start` does not automatically follow all redirects.
    /// Instead, each individual response along the redirect chain is delivered to
    /// the `LoaderClient`.
    Start(Request request, LoaderClient client);
};

/// A client interface used with `Loader.Start`.
///
/// Closing the underlying channel will cancel the associated HTTP transaction.
protocol LoaderClient {
    /// Called by the loader when the loader receives an HTTP response.
    ///
    /// If the server has requested a redirect, then `redirect` will be non-null
    /// and describe the target the server requested. To follow the redirect, reply
    /// to this message. To not follow the redirect, close the underlying channel.
    OnResponse(Response response, RedirectTarget? redirect) -> ();
};