interface headers {
    // A resource for accessing HTTP headers.
    resource headers {
        /// Get all of the values corresponding to a name. If the name is not present
        /// in this `fields`, an empty list is returned. However, if the name is
        /// present but empty, this is represented by a list with one or more
        /// empty values present.
        get: func(name: string) -> list<list<u8>>;

        /// Returns `true` when the name is present in this `fields`. If the name is
        /// syntactically invalid, `false` is returned.
        has: func(name: string) -> bool;

        /// Set all of the values for a name. Clears any existing values for that
        /// name, if they have been set.
        ///
        /// Fails with `header-error.immutable` if the `fields` are immutable.
        set: func(name: string, value: list<list<u8>>) -> result<_, header-error>;

        /// Delete all values for a name. Does nothing if no values for the name
        /// exist.
        ///
        /// Fails with `header-error.immutable` if the `fields` are immutable.
        delete: func(name: string) -> result<_, header-error>;

        /// Delete all values for a name. Does nothing if no values for the name
        /// exist.
        ///
        /// Returns all values previously corresponding to the name, if any.
        ///
        /// Fails with `header-error.immutable` if the `fields` are immutable.
        get-and-delete: func(name: string) -> result<list<list<u8>>, header-error>;

        /// Append a value for a name. Does not change or delete any existing
        /// values for that name.
        ///
        /// Fails with `header-error.immutable` if the `fields` are immutable.
        append: func(name: string, value: list<u8>) -> result<_, header-error>;

        /// Retrieve the full set of names and values in the Fields. Like the
        /// constructor, the list represents each name-value pair.
        ///
        /// The outer list represents each name-value pair in the Fields. Names
        /// which have multiple values are represented by multiple entries in this
        /// list with the same name.
        ///
        /// The names and values are always returned in the original casing and in
        /// the order in which they will be serialized for transport.
        entries: func() -> list<tuple<string,list<u8>>>;

        /// Create new headers
        new: static func() -> headers;
    }

    /// setting or appending to a `fields` resource.
    variant header-error {
        /// This error indicates that a `field-name` or `field-value` was
        /// syntactically invalid when used with an operation that sets headers in a
        /// `fields`.
        invalid-syntax,

        /// This error indicates that a forbidden `field-name` was used when trying
        /// to set a header in a `fields`.
        forbidden,

        /// This error indicates that the operation on the `fields` was not
        /// permitted because the fields are immutable.
        immutable,
    }
}
