| // 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) -> (); |
| }; |