// 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(resource struct {
        url Url:optional;
        name CookieName:optional;
        changes server_end:CookiesIterator;
    });

    /// 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(resource struct {
        url Url:optional;
        name CookieName:optional;
        cookies server_end:CookiesIterator;
    });
};

/// 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() -> (resource struct {
        changed_cookies vector<Cookie>:MAX;
    });
};

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

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

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

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

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