// 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;

using fuchsia.mem;
using fuchsia.net.http;

/// Interface supplied by the embedder for receiving notifications about navigation events in a
/// [`Frame`].
protocol NavigationEventListener {
    /// Called immediately after [`Frame.SetNavigationEventListener`] and every time user-visible
    /// navigation state has changed. In the first call, `change` contains the current navigation
    /// state (empty before the first navigation request). In every following call, `change` will
    /// have values set for all fields that have changed at any time since the previous
    /// notification. This means that some fields may have the same value as was previously
    /// reported, for example, if they changed to some other value and back again. If a field is
    /// unset, then its value has not changed at any time since the previous notification.
    ///
    /// Implementer must call the acknowledgement callback to receive new navigation events.
    OnNavigationStateChanged(resource struct {
        change NavigationState;
    }) -> ();
};

protocol NavigationPolicyProvider {
    /// Called when the [`Frame`] is processing a navigation request in one of the phase(s)
    /// specified in [`NavigationPolicyProviderParams`]. Navigation is paused until the result is
    /// received. The returned [`NavigationDecision`] defines how the navigation should proceed.
    EvaluateRequestedNavigation(struct {
        requested_navigation RequestedNavigation;
    }) -> (resource struct {
        decision NavigationDecision;
    });
};

/// Represents the return status of a [`NavigationController`] method.
type NavigationControllerError = strict enum : int32 {
    /// The provided URL is invalid.
    INVALID_URL = 1;

    /// At least one of the provided headers was invalid.
    INVALID_HEADER = 2;
};

/// Provides methods for controlling and querying the navigation state of a [`Frame`].
protocol NavigationController {
    /// Tells the [`Frame`] to navigate to a `url`.
    ///
    /// - `url`: The address to navigate to.
    /// - `params`: Additional parameters that affect how the resource will be  loaded (e.g.
    ///   cookies, HTTP headers, etc.)
    ///
    /// If an error occurred, the [`NavigationControllerError`] will be set to one of these values:
    /// - `INVALID_URL`: The `url` parameter is invalid.
    /// - `INVALID_HEADER`: At least one of the headers in [`LoadUrlParams.headers`] is invalid.
    LoadUrl(resource struct {
        url Url;
        params LoadUrlParams;
    }) -> (struct {}) error NavigationControllerError;

    /// Tells the [`Frame`] to navigate to the previous page in its history, if any.
    GoBack();

    /// Tells the [`Frame`] to navigate to the next page in its history, if any.
    GoForward();

    /// Tells the [`Frame`] to stop the current navigation if a navigation is ongoing.
    Stop();

    /// Tells the [`Frame`] to reload the current page.
    Reload(struct {
        type ReloadType;
    });

    /// Returns information for the currently visible content regardless of loading state, or an
    /// empty entry if no content is being displayed.
    @deprecated("Use a NavigationEventListener to receive state changes, instead.")
    @transitional
    GetVisibleEntry() -> (resource struct {
        entry NavigationState;
    });
};

/// Additional parameters for modifying the behavior of [`NavigationController.LoadUrl`].
type LoadUrlParams = resource table {
    /// Provides a hint to the browser UI about how [`NavigationController.LoadUrl`] was triggered.
    1: type LoadUrlReason;

    /// The URL that linked to the resource being requested.
    2: referrer_url Url;

    /// Should be set to true to propagate user activation to the frame. User activation implies
    /// that the user is interacting with the web frame. It enables some web features that are not
    /// available otherwise. For example, autoplay will work only when this flag is set to true.
    3: was_user_activated bool;

    /// Custom HTTP headers. RFC7540 does not specify a limit on the number nor
    /// size of headers.
    4: headers vector<fuchsia.net.http.Header>:MAX;
};

/// Contains information about the [`Frame`]'s navigation state.
type NavigationState = resource table {
    /// The page's URL.
    1: url Url;

    /// The user-visible page title. While W3C style recommendation is that HTML
    /// TITLE tags not exceed 64 characters in length, there is no actual limit.
    2: title string:MAX;

    /// Indicates whether this was a navigation to an error page.
    3: page_type PageType;

    /// Indicates if there is a following navigation.
    4: can_go_forward bool;

    /// Indicates if there is a previous navigation.
    5: can_go_back bool;

    /// Indicates that the main document's statically declared resources have been loaded.
    6: is_main_document_loaded bool;

    /// Current favicon for the page. The field is set only when the `FAVICON` flag is set for the
    /// `NavigationEventListener` and the favicon has changed.
    7: favicon Favicon;
};

/// Characterizes the type of reload.
type ReloadType = strict enum : uint32 {
    /// Reloads the current entry, bypassing the cache for the main resource.
    PARTIAL_CACHE = 0;

    /// Reloads the current entry, bypassing the cache entirely.
    NO_CACHE = 1;
};

/// Characterizes the origin of a [`NavigationController.LoadUrl`] request.
type LoadUrlReason = strict enum : uint32 {
    /// Navigation was initiated by the user following a link.
    LINK = 0;

    /// Navigation was initiated by a user-provided URL.
    TYPED = 1;
};

/// Characterizes the page type in a [`NavigationState`].
type PageType = strict enum {
    /// Regular web page.
    NORMAL = 0;

    /// Error page.
    ERROR = 1;
};

/// Unique identifier of a navigation. Can be used to correlate different phases for the
/// same navigation. Guaranteed to be unique for all navigations in the same [`Context`].
alias NavigationId = uint64;

/// Identifies a navigation phase.
type NavigationPhase = strict bits : uint32 {
    /// Navigation is being started.
    START = 0x1;

    /// Navigation was redirected.
    REDIRECT = 0x2;

    /// Navigation response is being processed. At this point navigation hasn't been committed
    /// yet, so it is not too late to cancel it.
    PROCESS_RESPONSE = 0x4;

    /// Navigation has failed.
    FAIL = 0x8;
};

/// Used to specify which navigation events should be delegated to [`NavigationPolicyProvider`].
type NavigationPolicyProviderParams = table {
    /// Specifies the set of navigation phases in the main frame that should be evaluated.
    1: main_frame_phases NavigationPhase;

    /// Specifies the set of navigation phases in subframes that should be evaluated.
    2: subframe_phases NavigationPhase;
};

type RequestedNavigation = table {
    /// Unique ID of the navigation.
    1: id NavigationId;

    /// Current navigation phase. Exactly one bit will be set.
    2: phase NavigationPhase;

    /// Whether the navigation is taking place in the main frame versus in a subframe.
    3: is_main_frame bool;

    /// Whether the navigation happened without changing the document.
    4: is_same_document bool;

    /// Whether the navigation is a POST request.
    5: is_http_post bool;

    /// The current target URL of the navigation. This may change for the same navigation after
    /// encountering a server redirect.
    6: url Url;

    /// Whether the navigation was initiated by a user gesture.
    7: has_gesture bool;

    /// Whether the navigation has encountered a server redirect or not.
    8: was_server_redirect bool;
};

/// Empty struct used in NavigationDecision for actions that don't hav any arguments.
// TODO: fxbug.dev/7913
type NoArgumentsAction = struct {};

/// Navigation action that should be taken in response to a navigation request. Returned from
/// [`NavigationPolicyProvider.EvaluateRequestedNavigation`].
type NavigationDecision = strict resource union {
    /// Navigation should proceed normally.
    1: proceed NoArgumentsAction;

    /// Navigation should be aborted. The frame should stay on the current page.
    2: abort NoArgumentsAction;
};

/// Used to represent a favicon for a page. An empty table (all fields are unset) is used to indicate
/// that the page doesn't have a favicon.
type Favicon = resource table {
    /// The image content encoded as an RGBA bitmap with premultiplied alpha channel. The data is
    /// densely packed, so the stride is always `4 * width` and the total size is
    /// `4 * width * height`.
    1: data fuchsia.mem.Buffer;

    /// The width of the image.
    2: width uint32;

    /// The height of the image.
    3: height uint32;
};