// 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.
@available(added=7)
library fuchsia.net.http;

using fuchsia.mem;
using fuchsia.url;
using zx;

alias Method = string:1024;

/// An error occurred during the HTTP transaction.
type Error = strict enum {
    /// Some other problem occurred that cannot be classified using one of the
    /// more specific statuses. Retry is optional.
    INTERNAL = 1;

    /// An HTTP parse error.
    UNABLE_TO_PARSE = 2;

    /// Indicates a channel (client or body sender) is closed.
    CHANNEL_CLOSED = 3;

    /// Error occurred while connecting.
    CONNECT = 4;

    /// The deadline specified in Request has passed
    DEADLINE_EXCEEDED = 5;
};

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

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

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

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

/// An HTTP request.
type Request = resource table {
    /// The HTTP method if applicable.
    ///
    /// Defaults to "GET".
    1: method Method;

    /// The URL to load.
    ///
    /// Required.
    2: url fuchsia.url.Url;

    /// Additional HTTP request headers.
    3: headers vector<Header>:MAX;

    /// 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.
    4: body Body;

    /// Determines when to give up on waiting for a response from the server. If no deadline is
    /// provided, the implementation will provide a reasonable default.
    5: deadline zx.time;
};

/// 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.
type RedirectTarget = table {
    /// The HTTP method the server suggested for the redirect.
    1: method Method;

    /// The URL the server suggested for the redirect.
    2: url fuchsia.url.Url;

    /// The referrer the server suggested for the redirect.
    3: referrer fuchsia.url.Url;
};

/// A response to an HTTP request.
type Response = resource table {
    /// If the response resulted in a network level error, this field will be
    /// set.
    1: error Error;

    /// The response body.
    2: body zx.handle:SOCKET;

    /// The final URL of the response, after redirects have been followed.
    3: final_url fuchsia.url.Url;

    /// The HTTP status code.
    4: status_code uint32;

    /// The HTTP status line.
    5: status_line bytes;

    /// The HTTP response headers.
    6: headers vector<Header>:MAX;

    /// A description of the redirect the server requested, if any.
    7: redirect RedirectTarget;
};

/// 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(resource struct {
        request Request;
    }) -> (resource struct {
        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(resource struct {
        request Request;
        client client_end:LoaderClient;
    });
};

/// 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` in `response`
    /// table will describe the target the server requested. To follow the
    /// redirect, reply to this message. To not follow the redirect, close the
    /// underlying channel.
    OnResponse(resource struct {
        response Response;
    }) -> ();
};