blob: bf6b6800426986260cde7b1be6cb22816fdd8e90 [file] [log] [blame]
// 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;
type ContextError = strict enum : int32 {
/// The remote debugging service was not opened.
// TODO( Remove ContextProvider in favor of launching Context instances directly.
/// The top-level service interface which allows for the creation of Context resources.
protocol ContextProvider {
/// Creates a new browser [`Context`] whose state is wholly independent and isolated from other
/// [`Context`](`Contexts`).
/// - `params`: The configuration used to create the [`Context`].
/// - `context`: An interface request which will receive a bound [`Context`]
/// service.
Create(resource struct {
params CreateContextParams;
context server_end:Context;
/// Defines a provider which hosts resources from a [``]. Content can `GET`
/// resource files via the provider, but not enumerate directories. Resources can be accessed by
/// their URLs: `fuchsia-dir://<provider-name>/<path/to/resource>`
/// By default the MIME types of files are determined automatically by "sniffing" the contents of
/// the files. No content encoding will be declared, which browsers will interpret as meaning
/// `"text/plain"`.
/// Content type and encoding metadata may optionally be specified explicitly by metadata files,
/// which reside alongside the file. Metadata is expressed in JSON files, named after the files
/// they describe with a `"._metadata"` suffix.
/// For example, the file `"index.html"` would have the a metadata file called
/// `"index.html._metadata"`, with the following contents:
/// ```
/// {
/// "charset": "utf-8",
/// "mime": "text/html"
/// }
/// ```
type ContentDirectoryProvider = resource table {
/// Name of the provider. Must be non-empty and composed solely of alphanumerics, dots, and
/// dashes.
1: name string:255;
/// Directory containing the files served by this provider.
2: directory;
/// Feature flags that allow augmenting Context behavior. Some features require additional services
/// in the service directory provided during context initialization. See
/// [`CreateContextParams.service_directory`].
type ContextFeatureFlags = strict bits : uint64 {
/// Enables network access. Requires the following services:
/// - [``]
/// - [``]
/// - [`fuchsia.posix.socket/Provider`]
NETWORK = 0x1;
/// Enables audio input and output. Requires the following services:
/// - [``]
/// - [``]
/// - [``]
AUDIO = 0x2;
/// Enables GPU-accelerated rendering of the web content. Requires the following services:
/// - [`fuchsia.vulkan.loader/Loader`]
VULKAN = 0x4;
/// Enables hardware video decoding. `VULKAN` must be enabled as well. Requires the following
/// service:
/// - [`fuchsia.mediacodec/CodecFactory`]
/// Disables video codecs that cannot be decoded in hardware.
/// Software decoders will only be used as fallbacks for hardware decoders, such as when
/// insufficient resources are available.
/// Requires the `HARDWARE_VIDEO_DECODER` flag.
/// Enables Widevine CDM modules for EME API. `VULKAN` feature must be enabled as well.
/// Requires [``] service. Requires that a `cdm_data_directory` be
/// specified in [`CreateContextParams`].
/// Allows embedders to render web content without graphical output or Scenic.
/// Not compatible with the `VULKAN` flag.
HEADLESS = 0x40;
/// Report telemetry data to the [`fuchsia.legacymetrics/MetricsRecorder`].
/// Enables input events for keyboard keypresses.
/// Requires [`fuchsia.ui.input3/Keyboard`], from which the events are obtained.
KEYBOARD = 0x100;
/// Enables the use of onscreen virtual keyboards. The implementation will manage the state of
/// the keyboard in response to input/focus events in web content.
/// Requires the [`fuchsia.input.virtualkeyboard/ControllerCreator`] service and the
/// `KEYBOARD` ContextFeatureFlag.
/// Parameters specifying the configuration for a new [`Context`].
type CreateContextParams = resource table {
/// Service directory to be used by the context. The following services must be present in the
/// directory:
/// - [`fuchsia.buildinfo/Provider`]
/// - [`fuchsia.device/NameProvider`]
/// - [`fuchsia.fonts/Provider`]
/// - [`fuchsia.intl/PropertyProvider`]
/// - [`fuchsia.logger/LogSink`]
/// - [`fuchsia.memorypressure/Provider`]
/// - [`fuchsia.process/Launcher`]
/// - [`fuchsia.sysmem/Allocator`]
/// The following services must be present in order to render web content in a Scenic view
/// using [`Frame.CreateView`], [`Frame.CreateViewWithViewRef`] or [`Frame.CreateView2`]]:
/// - [`fuchsia.accessibility.semantics/SemanticsManager`]
/// - [`fuchsia.ui.composition/Allocator`]
/// - [`fuchsia.ui.composition/Flatland`]
/// - [`fuchsia.ui.scenic/Scenic`]
// TODO( Remove gfx references after Flatland migration is completed.
1: service_directory;
/// Handle to the directory that will contain the [`Context`]'s persistent data. If it is left
/// unset, then the created [`Context`] will be stateless, with all of its data discarded upon
/// [`Context`] destruction.
/// If set, `data_directory` must not be shared with any other [`Context`].
// TODO( Provide an API to inform the caller when the `data_directory` can be safely
// removed.
2: data_directory;
/// Optional string describing the embedding product to append to the User-Agent string.
/// See the specification for the
/// [HTTP User-Agent header](
/// Requires that `user_agent_version` is also specified.
3: user_agent_product string:128;
/// Optional version for the embedding product to append to the User-Agent string.
/// Requires that `user_agent_product` is also specified.
4: user_agent_version string:128;
/// Enables Frames to be created with remote debugging enabled using the DevTools protocol. If
/// `port` is 0, then an ephemeral port will be used, which can be queried via the
/// [`Context.GetRemoteDebuggingPort`] API.
5: remote_debugging_port uint16;
/// List of providers whose contents will be served by `fuchsia-dir://` URLs.
6: content_directories vector<ContentDirectoryProvider>:100;
/// Optional features that should be enabled for this context. Some features may also require
/// additional services in `service_directory`.
7: features ContextFeatureFlags;
/// Enables PlayReady CDM for the Context using the specified string as a key system
/// string. The string should be a reverse domain name, as required by
/// [EME API](
/// - Requires [``] service.
/// - Requires that a `cdm_data_directory` be specified in [`CreateContextParams`].
8: playready_key_system string:128;
/// Treat given insecure origins as secure origins. For the definition of secure contexts, see
/// [Secure Contexts]( and
/// [origin trustworthiness](
/// Example value: `{"", ""}`.
9: unsafely_treat_insecure_origins_as_secure vector<UrlSchemeAndHostName>:100;
/// Specifies a set of header names for which [Cross-Origin Resource Sharing
/// (CORS)]( checks should not be enforced.
10: cors_exempt_headers vector<bytes:MAX>:MAX;
/// Specifies the storage to use to persistent content licensing related data (e.g.
/// provisioning data, persistent session data). By default these data will be placed under the
/// `data_directory`, if specified.
/// If neither `data_directory` nor `cdm_data_directory` are specified, then content licensing
/// features requiring persistent storage (e.g. persistent licensing sessions) will not be
/// available to the [`Context`].
/// Note that not all content licensing systems support persistent sessions, regardless of
/// whether persistent storage is provided.
11: cdm_data_directory;
/// Specifies a target maximum size for `cdm_data_directory` contents, in bytes. If the amount
/// of persisted CDM data exceeds this threshold, then the [`Context`] will attempt to purge
/// some data to meet the specified quota.
12: cdm_data_quota_bytes uint64;
/// Specifies a target maximum size for `data_directory` contents, in bytes.
/// The [`Context`] will attempt to limit browsing state (e.g. cookies, LocalStorage) to
/// not exceed the specified size.
13: data_quota_bytes uint64;
/// Manages browsing state (e.g. LocalStorage, cookies, etc) associated with a set of [`Frame`].
protocol Context {
/// Creates a new [`Frame`] under this [`Context`]. Destruction of a [`Context`] triggers the
/// destruction of all of its associated [`Frame`]. [`Frame`] can be transferred to another
/// component but cannot be shared across multiple components.
/// - `frame`: An interface request that will be bound to the created [`Frame`].
CreateFrame(resource struct {
frame server_end:Frame;
/// Similar to [`Context.CreateFrame`], with extra parameters.
/// - `params`: The configuration used to create the [`Frame`].
/// This method will fail with `ZX_ERR_INVALID_ARGS` if the table is not clonable.
/// - `frame`: An interface request that will be bound to the created [`Frame`].
// TODO( Consider removing the clonable params restriction if clients
// become responsible for providing parameters for [each] popup.
CreateFrameWithParams(resource struct {
params CreateFrameParams;
frame server_end:Frame;
/// Used to observe cookies for sites hosted under this Context.
GetCookieManager(resource struct {
manager server_end:CookieManager;
/// Waits until debugging is available on one or more Frames, and returns the DevTools port
/// number. Multiple calls may be queued to received the port number.
/// If an error occurred, the [`ContextError`] will be set to this value:
/// - `REMOTE_DEBUGGING_PORT_NOT_OPENED`: `remote_debugging_port` was not set in
/// [`CreateContextParams`] or the remote debugging service failed to start.
GetRemoteDebuggingPort() -> (struct {
port uint16;
}) error ContextError;
/// Parameters specifying the configuration for a new [`Frame`].
type CreateFrameParams = resource table {
/// Set to true to enable remote debugging. The [`Frame`] will be closed with
/// `ERR_INVALID_ARGS` if `remote_debugging_port` was not set in
/// [`CreateContextParams`].
1: enable_remote_debugging bool;
/// Set to give the Frame a name to help distinguish it in debug contexts , such as system log
/// output. For example, the name may be added to messages from web content when they are logged
/// to the system logger. The name does not affect user- or web-visible behavior.
/// Popup Frames created by the Frame will have a name derived from the parent Frame's name.
2: debug_name string:MAX;
/// Sets the autoplay policy for the Frame. If omitted, the default policy is
/// [`CreateFrame`] will fail with `ZX_ERR_NOT_SUPPORTED` if the value specified is not
/// supported by the [`Context`].
@deprecated("use fuchsia.web.SetContentAreaSettings instead")
3: autoplay_policy AutoplayPolicy;
/// Enables automatic blocking of navigations to explicit sites, and specifies the error page
/// content, in HTML, to be loaded in the Frame when a navigation is canceled by the filter.
/// Applies to navigations in all frames within the Frame.
/// When navigation of the main document is canceled, the Frame's [`NavigationState.PageType`]
/// is `ERROR`.
/// If set to an empty buffer, a default error message will be displayed.
/// If set and such filtering is not supported, the [`Frame`] will disconnect with
4: explicit_sites_filter_error_page fuchsia.mem.Data;
/// Used by [`Context`] clients to delegate [`Frame`] hosting capabilities to selected peers.
protocol FrameHost {
/// Behaves identically to [`Context.CreateFrameWithParams`].
CreateFrameWithParams(resource struct {
params CreateFrameParams;
frame server_end:Frame;
/// Specifies the policy for automatic (non user-initiated) playback of video and audio content.
type AutoplayPolicy = strict enum : int32 {
/// All media is permitted to autoplay.
ALLOW = 1;
/// Allow autoplay when the document has received a user activation. This can be the result of
/// user action or [`LoadUrlParams.was_user_activated`] being set.