sdk/fidl/fuchsia.web/navigation.fidl

// 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.net.http;

/// Interface supplied by the embedder for receiving notifications about navigation events in a
/// [`Frame`].
protocol NavigationEventListener {
    /// Called when user-visible navigation state has changed since [`Frame`] creation or the last
    /// acknowledgement callback, whichever occurred last. `change` will contain all the
    /// differences in navigation state since the last acknowledgement. Any unchanged properties
    /// will be left unset in `change`.
    ///
    /// Implementer must call the acknowledgement callback to receive new navigation events.
    OnNavigationStateChanged(NavigationState change) -> ();
};

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(RequestedNavigation requested_navigation)
        -> (NavigationDecision decision);
};

/// Represents the return status of a [`NavigationController`] method.
enum NavigationControllerError : 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 occured, 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(Url url, LoadUrlParams params)
        -> () 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(ReloadType type);

    /// Returns information for the currently visible content regardless of loading state, or an
    /// empty entry if no content is being displayed.
    GetVisibleEntry() -> (NavigationState entry);
};

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

    /// The URL that linked to the resource being requested.
    2: Url referrer_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: bool was_user_activated;

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

/// Contains information about the [`Frame`]'s navigation state.
resource table NavigationState {
    /// 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: string:MAX title;

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

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

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

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

/// Characterizes the type of reload.
enum ReloadType : 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.
enum LoadUrlReason : 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`].
enum PageType {
    /// 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.
bits NavigationPhase : 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`].
table NavigationPolicyProviderParams {
    /// Specifies the set of navigation phases in the main frame that should be evaluated.
    1: NavigationPhase main_frame_phases;

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

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

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

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

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

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

    /// 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: bool has_gesture;

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

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

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

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