// Copyright 2019 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.web;

// RFC6265 specifies that implementations must support at least 4096 of data
// per-cookie (including name, value & attributes) but does not specify an
// upper-bound on their size.
alias CookieName = string:MAX;

/// Provides methods for monitoring and accessing browser cookie state.
protocol CookieManager {
    /// Observe changes to all cookies named `name` that would be sent in a request to `url`.
    ///
    /// If neither `url` nor `name` are set then all cookies are observed. If only `url` is set
    /// then all cookies for that URL are observed. If both are set then only cookies matching both
    /// fields are observed.
    ///
    /// `changes` iterates over a stream of cookie changes. Additions or updates are expressed as
    /// complete cookies, while deletions are expressed as cookies with no `value` set.
    ObserveCookieChanges(
        Url? url,
        CookieName? name,
        request<CookiesIterator> changes);

    /// Returns a list of Cookies, optionally limited to those matching `url`, and optionally
    /// `name`. `cookies` iterates over the matching cookies, including their `value`s.
    GetCookieList(Url? url,
                  CookieName? name,
                  request<CookiesIterator> cookies);
};

/// Used to iterator over a set of cookies, or a stream of changes to cookies.
protocol CookiesIterator {
    /// Fetches the next batch of cookies, or of changes to cookies.
    /// RFC6265 does not specify an upper-bound on the number of cookies which
    /// may be stored.
    GetNext() -> (vector<Cookie>:MAX changed_cookies);
};

table CookieId {
    /// An RFC2616 "token" chosen by the site to identify the cookie.
    1: CookieName name;

    /// The RFC1034 "subdomain" to which this cookie is scoped.
    /// e.g. "example.com" allows access from all *.example.com sub-domains.
    2: string:MAX_HOST_LENGTH domain;

    /// The URL "path" prefix to which this cookie is scoped.
    /// e.g. "/" allows access from all paths.
    3: string:MAX_URL_LENGTH path;
};

resource table Cookie {
    /// A table with fields to identify a cookie.
    1: CookieId id;

    /// The cookie value.
    /// RFC6265 does not specify an upper limit on cookie size, but recommends
    /// that at least 4096 bytes are supported.
    2: string:MAX value;
};