embedder_traits/
lib.rs

1/* This Source Code Form is subject to the terms of the Mozilla Public
2 * License, v. 2.0. If a copy of the MPL was not distributed with this
3 * file, You can obtain one at https://mozilla.org/MPL/2.0/. */
4
5//! Types used by the embedding layer and/or exposed to the API. This crate is responsible for
6//! defining types that cross the process boundary from the embedding/rendering layer all the way
7//! to script, thus it should have very minimal dependencies on other parts of Servo. If a type
8//! is not exposed in the API or doesn't involve messages sent to the embedding/libservo layer, it
9//! is probably a better fit for the `constellation_traits` crate.
10
11pub mod input_events;
12pub mod resources;
13pub mod user_content_manager;
14pub mod webdriver;
15
16use std::collections::HashMap;
17use std::ffi::c_void;
18use std::fmt::{Debug, Display, Error, Formatter};
19use std::hash::Hash;
20use std::ops::Range;
21use std::path::PathBuf;
22use std::sync::Arc;
23use std::time::SystemTime;
24
25use base::Epoch;
26use base::generic_channel::{GenericCallback, GenericSender, SendResult};
27use base::id::{PipelineId, WebViewId};
28use crossbeam_channel::Sender;
29use euclid::{Box2D, Point2D, Scale, Size2D, Vector2D};
30use http::{HeaderMap, Method, StatusCode};
31use ipc_channel::ipc::{IpcSender, IpcSharedMemory};
32use log::warn;
33use malloc_size_of::malloc_size_of_is_0;
34use malloc_size_of_derive::MallocSizeOf;
35use pixels::RasterImage;
36use serde::{Deserialize, Deserializer, Serialize, Serializer};
37use servo_geometry::{DeviceIndependentIntRect, DeviceIndependentIntSize};
38use servo_url::ServoUrl;
39use strum_macros::{EnumMessage, IntoStaticStr};
40use style::queries::values::PrefersColorScheme;
41use style_traits::CSSPixel;
42use url::Url;
43use uuid::Uuid;
44use webrender_api::ExternalScrollId;
45use webrender_api::units::{
46    DeviceIntPoint, DeviceIntRect, DeviceIntSize, DevicePixel, DevicePoint, DeviceRect,
47    DeviceVector2D, LayoutPoint, LayoutRect, LayoutSize, LayoutVector2D,
48};
49
50pub use crate::input_events::*;
51pub use crate::webdriver::*;
52
53/// A point in a `WebView`, either expressed in device pixels or page pixels.
54/// Page pixels are CSS pixels, which take into account device pixel scale,
55/// page zoom, and pinch zoom.
56#[derive(Clone, Copy, Debug, Deserialize, MallocSizeOf, PartialEq, Serialize)]
57pub enum WebViewPoint {
58    Device(DevicePoint),
59    Page(Point2D<f32, CSSPixel>),
60}
61
62impl WebViewPoint {
63    pub fn as_device_point(&self, scale: Scale<f32, CSSPixel, DevicePixel>) -> DevicePoint {
64        match self {
65            Self::Device(point) => *point,
66            Self::Page(point) => *point * scale,
67        }
68    }
69}
70
71impl From<DevicePoint> for WebViewPoint {
72    fn from(point: DevicePoint) -> Self {
73        Self::Device(point)
74    }
75}
76
77impl From<LayoutPoint> for WebViewPoint {
78    fn from(point: LayoutPoint) -> Self {
79        Self::Page(Point2D::new(point.x, point.y))
80    }
81}
82
83impl From<Point2D<f32, CSSPixel>> for WebViewPoint {
84    fn from(point: Point2D<f32, CSSPixel>) -> Self {
85        Self::Page(point)
86    }
87}
88
89/// A rectangle in a `WebView`, either expressed in device pixels or page pixels.
90/// Page pixels are CSS pixels, which take into account device pixel scale,
91/// page zoom, and pinch zoom.
92#[derive(Clone, Copy, Debug, Deserialize, MallocSizeOf, PartialEq, Serialize)]
93pub enum WebViewRect {
94    Device(DeviceRect),
95    Page(Box2D<f32, CSSPixel>),
96}
97
98impl WebViewRect {
99    pub fn as_device_rect(&self, scale: Scale<f32, CSSPixel, DevicePixel>) -> DeviceRect {
100        match self {
101            Self::Device(rect) => *rect,
102            Self::Page(rect) => *rect * scale,
103        }
104    }
105}
106
107impl From<DeviceRect> for WebViewRect {
108    fn from(rect: DeviceRect) -> Self {
109        Self::Device(rect)
110    }
111}
112
113impl From<LayoutRect> for WebViewRect {
114    fn from(rect: LayoutRect) -> Self {
115        Self::Page(Box2D::new(
116            Point2D::new(rect.min.x, rect.min.y),
117            Point2D::new(rect.max.x, rect.max.y),
118        ))
119    }
120}
121
122impl From<Box2D<f32, CSSPixel>> for WebViewRect {
123    fn from(rect: Box2D<f32, CSSPixel>) -> Self {
124        Self::Page(rect)
125    }
126}
127
128#[derive(Clone, Copy, Debug, Deserialize, MallocSizeOf, PartialEq, Serialize)]
129pub enum WebViewVector {
130    Device(DeviceVector2D),
131    Page(Vector2D<f32, CSSPixel>),
132}
133
134impl WebViewVector {
135    pub fn as_device_vector(&self, scale: Scale<f32, CSSPixel, DevicePixel>) -> DeviceVector2D {
136        match self {
137            Self::Device(vector) => *vector,
138            Self::Page(vector) => *vector * scale,
139        }
140    }
141}
142
143impl From<DeviceVector2D> for WebViewVector {
144    fn from(vector: DeviceVector2D) -> Self {
145        Self::Device(vector)
146    }
147}
148
149impl From<LayoutVector2D> for WebViewVector {
150    fn from(vector: LayoutVector2D) -> Self {
151        Self::Page(Vector2D::new(vector.x, vector.y))
152    }
153}
154
155impl From<Vector2D<f32, CSSPixel>> for WebViewVector {
156    fn from(vector: Vector2D<f32, CSSPixel>) -> Self {
157        Self::Page(vector)
158    }
159}
160
161#[derive(Clone, Copy, Debug, Deserialize, MallocSizeOf, PartialEq, Serialize)]
162pub enum Scroll {
163    Delta(WebViewVector),
164    Start,
165    End,
166}
167
168/// Tracks whether Servo isn't shutting down, is in the process of shutting down,
169/// or has finished shutting down.
170#[derive(Clone, Copy, Debug, PartialEq)]
171pub enum ShutdownState {
172    NotShuttingDown,
173    ShuttingDown,
174    FinishedShuttingDown,
175}
176
177/// A cursor for the window. This is different from a CSS cursor (see
178/// `CursorKind`) in that it has no `Auto` value.
179#[repr(u8)]
180#[derive(Clone, Copy, Debug, Default, Deserialize, Eq, MallocSizeOf, PartialEq, Serialize)]
181pub enum Cursor {
182    None,
183    #[default]
184    Default,
185    Pointer,
186    ContextMenu,
187    Help,
188    Progress,
189    Wait,
190    Cell,
191    Crosshair,
192    Text,
193    VerticalText,
194    Alias,
195    Copy,
196    Move,
197    NoDrop,
198    NotAllowed,
199    Grab,
200    Grabbing,
201    EResize,
202    NResize,
203    NeResize,
204    NwResize,
205    SResize,
206    SeResize,
207    SwResize,
208    WResize,
209    EwResize,
210    NsResize,
211    NeswResize,
212    NwseResize,
213    ColResize,
214    RowResize,
215    AllScroll,
216    ZoomIn,
217    ZoomOut,
218}
219
220pub trait EventLoopWaker: 'static + Send {
221    fn clone_box(&self) -> Box<dyn EventLoopWaker>;
222    fn wake(&self) {}
223}
224
225impl Clone for Box<dyn EventLoopWaker> {
226    fn clone(&self) -> Self {
227        self.clone_box()
228    }
229}
230/// Sends messages to the embedder.
231pub struct EmbedderProxy {
232    pub sender: Sender<EmbedderMsg>,
233    pub event_loop_waker: Box<dyn EventLoopWaker>,
234}
235
236impl EmbedderProxy {
237    pub fn send(&self, message: EmbedderMsg) {
238        // Send a message and kick the OS event loop awake.
239        if let Err(err) = self.sender.send(message) {
240            warn!("Failed to send response ({:?}).", err);
241        }
242        self.event_loop_waker.wake();
243    }
244}
245
246impl Clone for EmbedderProxy {
247    fn clone(&self) -> EmbedderProxy {
248        EmbedderProxy {
249            sender: self.sender.clone(),
250            event_loop_waker: self.event_loop_waker.clone(),
251        }
252    }
253}
254
255/// A [`RefreshDriver`] is a trait that can be implemented by Servo embedders in
256/// order to drive let Servo know when to start preparing the next frame. For example,
257/// on systems that support Vsync notifications, an embedder may want to implement
258/// this trait to drive Servo animations via those notifications.
259pub trait RefreshDriver {
260    /// Servo will call this method when it wants to be informed of the next frame start
261    /// time. Implementors should call the callback when it is time to start preparing
262    /// the new frame.
263    fn observe_next_frame(&self, start_frame_callback: Box<dyn Fn() + Send + 'static>);
264}
265
266#[derive(Deserialize, Serialize)]
267pub enum ContextMenuResult {
268    Dismissed,
269    Ignored,
270    Selected(usize),
271}
272
273/// [Simple dialogs](https://html.spec.whatwg.org/multipage/#simple-dialogs) are synchronous dialogs
274/// that can be opened by web content. Since their messages are controlled by web content, they
275/// should be presented to the user in a way that makes them impossible to mistake for browser UI.
276#[derive(Deserialize, Serialize)]
277pub enum SimpleDialog {
278    /// [`alert()`](https://html.spec.whatwg.org/multipage/#dom-alert).
279    /// TODO: Include details about the document origin.
280    Alert {
281        id: EmbedderControlId,
282        message: String,
283        response_sender: GenericSender<AlertResponse>,
284    },
285    /// [`confirm()`](https://html.spec.whatwg.org/multipage/#dom-confirm).
286    /// TODO: Include details about the document origin.
287    Confirm {
288        id: EmbedderControlId,
289        message: String,
290        response_sender: GenericSender<ConfirmResponse>,
291    },
292    /// [`prompt()`](https://html.spec.whatwg.org/multipage/#dom-prompt).
293    /// TODO: Include details about the document origin.
294    Prompt {
295        id: EmbedderControlId,
296        message: String,
297        default: String,
298        response_sender: GenericSender<PromptResponse>,
299    },
300}
301
302impl SimpleDialog {
303    /// Returns the message of the dialog.
304    pub fn message(&self) -> &str {
305        match self {
306            SimpleDialog::Alert { message, .. } => message,
307            SimpleDialog::Confirm { message, .. } => message,
308            SimpleDialog::Prompt { message, .. } => message,
309        }
310    }
311
312    pub fn set_message(&mut self, text: String) {
313        match self {
314            SimpleDialog::Alert { message, .. } => *message = text,
315            SimpleDialog::Confirm { message, .. } => *message = text,
316            SimpleDialog::Prompt { message, .. } => *message = text,
317        }
318    }
319
320    pub fn dismiss(&self) {
321        match self {
322            SimpleDialog::Alert {
323                response_sender, ..
324            } => {
325                let _ = response_sender.send(AlertResponse::Ok);
326            },
327            SimpleDialog::Confirm {
328                response_sender, ..
329            } => {
330                let _ = response_sender.send(ConfirmResponse::Cancel);
331            },
332            SimpleDialog::Prompt {
333                response_sender, ..
334            } => {
335                let _ = response_sender.send(PromptResponse::Cancel);
336            },
337        }
338    }
339
340    pub fn accept(&self) {
341        match self {
342            SimpleDialog::Alert {
343                response_sender, ..
344            } => {
345                let _ = response_sender.send(AlertResponse::Ok);
346            },
347            SimpleDialog::Confirm {
348                response_sender, ..
349            } => {
350                let _ = response_sender.send(ConfirmResponse::Ok);
351            },
352            SimpleDialog::Prompt {
353                default,
354                response_sender,
355                ..
356            } => {
357                let _ = response_sender.send(PromptResponse::Ok(default.clone()));
358            },
359        }
360    }
361
362    pub fn id(&self) -> EmbedderControlId {
363        match self {
364            SimpleDialog::Alert { id, .. } |
365            SimpleDialog::Confirm { id, .. } |
366            SimpleDialog::Prompt { id, .. } => *id,
367        }
368    }
369}
370
371#[derive(Debug, Default, Deserialize, PartialEq, Serialize)]
372pub struct AuthenticationResponse {
373    /// Username for http request authentication
374    pub username: String,
375    /// Password for http request authentication
376    pub password: String,
377}
378
379#[derive(Default, Deserialize, PartialEq, Serialize)]
380pub enum AlertResponse {
381    // Per <https://html.spec.whatwg.org/multipage/#dom-alert>,
382    // if we **cannot show simple dialogs**, including cases where the user or user agent decides to ignore
383    // all modal dialogs, we need to return (which represents Ok).
384    #[default]
385    /// The user chose Ok, or the dialog was otherwise dismissed or ignored.
386    Ok,
387}
388
389#[derive(Default, Deserialize, PartialEq, Serialize)]
390pub enum ConfirmResponse {
391    /// The user chose Ok.
392    Ok,
393    // Per <https://html.spec.whatwg.org/multipage/#dom-confirm>,
394    // if we **cannot show simple dialogs**, including cases where the user or user agent decides to ignore
395    // all modal dialogs, we need to return false (which represents Cancel), not true (Ok).
396    #[default]
397    /// The user chose Cancel, or the dialog was otherwise dismissed or ignored.
398    Cancel,
399}
400
401#[derive(Default, Deserialize, PartialEq, Serialize)]
402pub enum PromptResponse {
403    /// The user chose Ok, with the given input.
404    Ok(String),
405    // Per <https://html.spec.whatwg.org/multipage/#dom-prompt>,
406    // if we **cannot show simple dialogs**, including cases where the user or user agent decides to ignore
407    // all modal dialogs, we need to return null (which represents Cancel), not the default input.
408    #[default]
409    /// The user chose Cancel, or the dialog was otherwise dismissed or ignored.
410    Cancel,
411}
412
413/// A response to a request to allow or deny an action.
414#[derive(Clone, Copy, Debug, Deserialize, PartialEq, Serialize)]
415pub enum AllowOrDeny {
416    Allow,
417    Deny,
418}
419
420#[derive(Clone, Debug, Deserialize, Serialize)]
421pub struct SelectElementOption {
422    /// A unique identifier for the option that can be used to select it.
423    pub id: usize,
424    /// The label that should be used to display the option to the user.
425    pub label: String,
426    /// Whether or not the option is selectable
427    pub is_disabled: bool,
428}
429
430/// Represents the contents of either an `<option>` or an `<optgroup>` element
431#[derive(Clone, Debug, Deserialize, Serialize)]
432pub enum SelectElementOptionOrOptgroup {
433    Option(SelectElementOption),
434    Optgroup {
435        label: String,
436        options: Vec<SelectElementOption>,
437    },
438}
439
440/// Data about a `WebView` or `<iframe>` viewport: its size and also the
441/// HiDPI scale factor to use when rendering the contents.
442#[derive(Clone, Copy, Debug, Default, Deserialize, MallocSizeOf, PartialEq, Serialize)]
443pub struct ViewportDetails {
444    /// The size of the layout viewport.
445    pub size: Size2D<f32, CSSPixel>,
446
447    /// The scale factor to use to account for HiDPI scaling. This does not take into account
448    /// any page or pinch zoom applied by the compositor to the contents.
449    pub hidpi_scale_factor: Scale<f32, CSSPixel, DevicePixel>,
450}
451
452impl ViewportDetails {
453    /// Convert this [`ViewportDetails`] size to a [`LayoutSize`]. This is the same numerical
454    /// value as [`Self::size`], because a `LayoutPixel` is the same as a `CSSPixel`.
455    pub fn layout_size(&self) -> LayoutSize {
456        Size2D::from_untyped(self.size.to_untyped())
457    }
458}
459
460/// Unlike [`ScreenGeometry`], the data is in device-independent pixels
461/// to be used by DOM APIs
462#[derive(Default, Deserialize, Serialize)]
463pub struct ScreenMetrics {
464    pub screen_size: DeviceIndependentIntSize,
465    pub available_size: DeviceIndependentIntSize,
466}
467
468/// An opaque identifier for a single history traversal operation.
469#[derive(Clone, Deserialize, Eq, Hash, PartialEq, Serialize)]
470pub struct TraversalId(String);
471
472impl TraversalId {
473    #[allow(clippy::new_without_default)]
474    pub fn new() -> Self {
475        Self(Uuid::new_v4().to_string())
476    }
477}
478
479#[derive(Clone, Copy, Deserialize, Eq, Hash, PartialEq, Serialize)]
480pub enum PixelFormat {
481    /// Luminance channel only
482    K8,
483    /// Luminance + alpha
484    KA8,
485    /// RGB, 8 bits per channel
486    RGB8,
487    /// RGB + alpha, 8 bits per channel
488    RGBA8,
489    /// BGR + alpha, 8 bits per channel
490    BGRA8,
491}
492
493/// A raster image buffer.
494#[derive(Clone, Deserialize, Serialize)]
495pub struct Image {
496    pub width: u32,
497    pub height: u32,
498    pub format: PixelFormat,
499    /// A shared memory block containing the data of one or more image frames.
500    data: Arc<IpcSharedMemory>,
501    range: Range<usize>,
502}
503
504impl Image {
505    pub fn new(
506        width: u32,
507        height: u32,
508        data: Arc<IpcSharedMemory>,
509        range: Range<usize>,
510        format: PixelFormat,
511    ) -> Self {
512        Self {
513            width,
514            height,
515            format,
516            data,
517            range,
518        }
519    }
520
521    /// Return the bytes belonging to the first image frame.
522    pub fn data(&self) -> &[u8] {
523        &self.data[self.range.clone()]
524    }
525}
526
527#[derive(Deserialize, IntoStaticStr, Serialize)]
528pub enum EmbedderMsg {
529    /// A status message to be displayed by the browser chrome.
530    Status(WebViewId, Option<String>),
531    /// Alerts the embedder that the current page has changed its title.
532    ChangePageTitle(WebViewId, Option<String>),
533    /// Move the window to a point
534    MoveTo(WebViewId, DeviceIntPoint),
535    /// Resize the window to size
536    ResizeTo(WebViewId, DeviceIntSize),
537    /// Show the user a [simple dialog](https://html.spec.whatwg.org/multipage/#simple-dialogs) (`alert()`, `confirm()`,
538    /// or `prompt()`). Since their messages are controlled by web content, they should be presented to the user in a
539    /// way that makes them impossible to mistake for browser UI.
540    ShowSimpleDialog(WebViewId, SimpleDialog),
541    /// Request authentication for a load or navigation from the embedder.
542    RequestAuthentication(
543        WebViewId,
544        ServoUrl,
545        bool, /* for proxy */
546        GenericSender<Option<AuthenticationResponse>>,
547    ),
548    /// Show a context menu to the user
549    ShowContextMenu(
550        WebViewId,
551        GenericSender<ContextMenuResult>,
552        Option<String>,
553        Vec<String>,
554    ),
555    /// Whether or not to allow a pipeline to load a url.
556    AllowNavigationRequest(WebViewId, PipelineId, ServoUrl),
557    /// Whether or not to allow script to open a new tab/browser
558    AllowOpeningWebView(
559        WebViewId,
560        GenericSender<Option<(WebViewId, ViewportDetails)>>,
561    ),
562    /// A webview was destroyed.
563    WebViewClosed(WebViewId),
564    /// A webview potentially gained focus for keyboard events.
565    /// If the boolean value is false, the webiew could not be focused.
566    WebViewFocused(WebViewId, bool),
567    /// All webviews lost focus for keyboard events.
568    WebViewBlurred,
569    /// Wether or not to unload a document
570    AllowUnload(WebViewId, GenericSender<AllowOrDeny>),
571    /// Inform embedder to clear the clipboard
572    ClearClipboard(WebViewId),
573    /// Gets system clipboard contents
574    GetClipboardText(WebViewId, IpcSender<Result<String, String>>),
575    /// Sets system clipboard contents
576    SetClipboardText(WebViewId, String),
577    /// Changes the cursor.
578    SetCursor(WebViewId, Cursor),
579    /// A favicon was detected
580    NewFavicon(WebViewId, Image),
581    /// The history state has changed.
582    HistoryChanged(WebViewId, Vec<ServoUrl>, usize),
583    /// A history traversal operation completed.
584    HistoryTraversalComplete(WebViewId, TraversalId),
585    /// Get the device independent window rectangle.
586    GetWindowRect(WebViewId, GenericSender<DeviceIndependentIntRect>),
587    /// Get the device independent screen size and available size.
588    GetScreenMetrics(WebViewId, GenericSender<ScreenMetrics>),
589    /// Entered or exited fullscreen.
590    NotifyFullscreenStateChanged(WebViewId, bool),
591    /// The [`LoadStatus`] of the Given `WebView` has changed.
592    NotifyLoadStatusChanged(WebViewId, LoadStatus),
593    WebResourceRequested(
594        Option<WebViewId>,
595        WebResourceRequest,
596        GenericSender<WebResourceResponseMsg>,
597    ),
598    /// A pipeline panicked. First string is the reason, second one is the backtrace.
599    Panic(WebViewId, String, Option<String>),
600    /// Open dialog to select bluetooth device.
601    GetSelectedBluetoothDevice(WebViewId, Vec<String>, GenericSender<Option<String>>),
602    /// Open file dialog to select files. Set boolean flag to true allows to select multiple files.
603    SelectFiles(
604        EmbedderControlId,
605        FilePickerRequest,
606        GenericSender<Option<Vec<PathBuf>>>,
607    ),
608    /// Open interface to request permission specified by prompt.
609    PromptPermission(WebViewId, PermissionFeature, GenericSender<AllowOrDeny>),
610    /// Report a complete sampled profile
611    ReportProfile(Vec<u8>),
612    /// Notifies the embedder about media session events
613    /// (i.e. when there is metadata for the active media session, playback state changes...).
614    MediaSessionEvent(WebViewId, MediaSessionEvent),
615    /// Report the status of Devtools Server with a token that can be used to bypass the permission prompt.
616    OnDevtoolsStarted(Result<u16, ()>, String),
617    /// Ask the user to allow a devtools client to connect.
618    RequestDevtoolsConnection(GenericSender<AllowOrDeny>),
619    /// Request to play a haptic effect on a connected gamepad.
620    PlayGamepadHapticEffect(WebViewId, usize, GamepadHapticEffectType, IpcSender<bool>),
621    /// Request to stop a haptic effect on a connected gamepad.
622    StopGamepadHapticEffect(WebViewId, usize, IpcSender<bool>),
623    /// Informs the embedder that the constellation has completed shutdown.
624    /// Required because the constellation can have pending calls to make
625    /// (e.g. SetFrameTree) at the time that we send it an ExitMsg.
626    ShutdownComplete,
627    /// Request to display a notification.
628    ShowNotification(Option<WebViewId>, Notification),
629    /// Request to display a form control to the embedder.
630    ShowEmbedderControl(EmbedderControlId, DeviceIntRect, EmbedderControlRequest),
631    /// Request to display a form control to the embedder.
632    HideEmbedderControl(EmbedderControlId),
633    /// Inform the embedding layer that a JavaScript evaluation has
634    /// finished with the given result.
635    FinishJavaScriptEvaluation(
636        JavaScriptEvaluationId,
637        Result<JSValue, JavaScriptEvaluationError>,
638    ),
639    /// Inform the embedding layer that a particular `InputEvent` was handled by Servo
640    /// and the embedder can continue processing it, if necessary.
641    InputEventHandled(WebViewId, InputEventId, InputEventResult),
642}
643
644impl Debug for EmbedderMsg {
645    fn fmt(&self, formatter: &mut Formatter) -> Result<(), Error> {
646        let string: &'static str = self.into();
647        write!(formatter, "{string}")
648    }
649}
650
651#[derive(Clone, Copy, Debug, Deserialize, PartialEq, Serialize)]
652pub struct EmbedderControlId {
653    pub webview_id: WebViewId,
654    pub pipeline_id: PipelineId,
655    pub index: Epoch,
656}
657
658#[derive(Debug, Deserialize, Serialize)]
659pub enum EmbedderControlRequest {
660    /// Indicates that the user has activated a `<select>` element.
661    SelectElement(Vec<SelectElementOptionOrOptgroup>, Option<usize>),
662    /// Indicates that the user has activated a `<input type=color>` element.
663    ColorPicker(RgbColor),
664    /// Indicates that the user has activated a `<input type=file>` element.
665    FilePicker(FilePickerRequest),
666    /// Indicates that the the user has activated a text or input control that should show
667    /// an IME.
668    InputMethod(InputMethodRequest),
669}
670
671/// Request to present an IME to the user when an editable element is focused. If `type` is
672/// [`InputMethodType::Text`], then the `text` parameter specifies the pre-existing text content and
673/// `insertion_point` the zero-based index into the string of the insertion point.
674#[derive(Debug, Deserialize, Serialize)]
675pub struct InputMethodRequest {
676    pub input_method_type: InputMethodType,
677    pub text: String,
678    pub insertion_point: Option<u32>,
679    pub multiline: bool,
680}
681
682#[derive(Debug, Deserialize, Serialize)]
683pub struct FilePickerRequest {
684    pub origin: String,
685    pub current_paths: Vec<PathBuf>,
686    pub filter_patterns: Vec<FilterPattern>,
687    pub allow_select_multiple: bool,
688    pub accept_current_paths_for_testing: bool,
689}
690
691#[derive(Debug, Deserialize, Serialize)]
692pub enum EmbedderControlResponse {
693    SelectElement(Option<usize>),
694    ColorPicker(Option<RgbColor>),
695    FilePicker(Option<Vec<SelectedFile>>),
696}
697
698/// Response to file selection request
699#[derive(Debug, Deserialize, Serialize)]
700pub struct SelectedFile {
701    pub id: Uuid,
702    pub filename: PathBuf,
703    pub modified: SystemTime,
704    pub size: u64,
705    // https://w3c.github.io/FileAPI/#dfn-type
706    pub type_string: String,
707}
708
709/// Filter for file selection;
710/// the `String` content is expected to be extension (e.g, "doc", without the prefixing ".")
711#[derive(Clone, Debug, Deserialize, Serialize)]
712pub struct FilterPattern(pub String);
713
714/// <https://w3c.github.io/mediasession/#mediametadata>
715#[derive(Clone, Debug, Deserialize, Serialize)]
716pub struct MediaMetadata {
717    /// Title
718    pub title: String,
719    /// Artist
720    pub artist: String,
721    /// Album
722    pub album: String,
723}
724
725impl MediaMetadata {
726    pub fn new(title: String) -> Self {
727        Self {
728            title,
729            artist: "".to_owned(),
730            album: "".to_owned(),
731        }
732    }
733}
734
735/// <https://w3c.github.io/mediasession/#enumdef-mediasessionplaybackstate>
736#[repr(i32)]
737#[derive(Clone, Debug, Deserialize, Serialize)]
738pub enum MediaSessionPlaybackState {
739    /// The browsing context does not specify whether it’s playing or paused.
740    None_ = 1,
741    /// The browsing context is currently playing media and it can be paused.
742    Playing,
743    /// The browsing context has paused media and it can be resumed.
744    Paused,
745}
746
747/// <https://w3c.github.io/mediasession/#dictdef-mediapositionstate>
748#[derive(Clone, Debug, Deserialize, Serialize)]
749pub struct MediaPositionState {
750    pub duration: f64,
751    pub playback_rate: f64,
752    pub position: f64,
753}
754
755impl MediaPositionState {
756    pub fn new(duration: f64, playback_rate: f64, position: f64) -> Self {
757        Self {
758            duration,
759            playback_rate,
760            position,
761        }
762    }
763}
764
765/// Type of events sent from script to the embedder about the media session.
766#[derive(Clone, Debug, Deserialize, Serialize)]
767pub enum MediaSessionEvent {
768    /// Indicates that the media metadata is available.
769    SetMetadata(MediaMetadata),
770    /// Indicates that the playback state has changed.
771    PlaybackStateChange(MediaSessionPlaybackState),
772    /// Indicates that the position state is set.
773    SetPositionState(MediaPositionState),
774}
775
776/// Enum with variants that match the DOM PermissionName enum
777#[derive(Clone, Copy, Debug, Deserialize, Serialize)]
778pub enum PermissionFeature {
779    Geolocation,
780    Notifications,
781    Push,
782    Midi,
783    Camera,
784    Microphone,
785    Speaker,
786    DeviceInfo,
787    BackgroundSync,
788    Bluetooth,
789    PersistentStorage,
790}
791
792/// Used to specify the kind of input method editor appropriate to edit a field.
793/// This is a subset of htmlinputelement::InputType because some variants of InputType
794/// don't make sense in this context.
795#[derive(Clone, Copy, Debug, Deserialize, PartialEq, Serialize)]
796pub enum InputMethodType {
797    Color,
798    Date,
799    DatetimeLocal,
800    Email,
801    Month,
802    Number,
803    Password,
804    Search,
805    Tel,
806    Text,
807    Time,
808    Url,
809    Week,
810}
811
812#[derive(Clone, Debug, Deserialize, Serialize)]
813/// <https://w3.org/TR/gamepad/#dom-gamepadhapticeffecttype-dual-rumble>
814pub struct DualRumbleEffectParams {
815    pub duration: f64,
816    pub start_delay: f64,
817    pub strong_magnitude: f64,
818    pub weak_magnitude: f64,
819}
820
821#[derive(Clone, Debug, Deserialize, Serialize)]
822/// <https://w3.org/TR/gamepad/#dom-gamepadhapticeffecttype>
823pub enum GamepadHapticEffectType {
824    DualRumble(DualRumbleEffectParams),
825}
826
827#[derive(Clone, Debug, Deserialize, MallocSizeOf, Serialize)]
828pub struct WebResourceRequest {
829    #[serde(
830        deserialize_with = "::hyper_serde::deserialize",
831        serialize_with = "::hyper_serde::serialize"
832    )]
833    #[ignore_malloc_size_of = "Defined in hyper"]
834    pub method: Method,
835    #[serde(
836        deserialize_with = "::hyper_serde::deserialize",
837        serialize_with = "::hyper_serde::serialize"
838    )]
839    #[ignore_malloc_size_of = "Defined in hyper"]
840    pub headers: HeaderMap,
841    pub url: Url,
842    pub is_for_main_frame: bool,
843    pub is_redirect: bool,
844}
845
846#[derive(Clone, Deserialize, Serialize)]
847pub enum WebResourceResponseMsg {
848    /// Start an interception of this web resource load. It's expected that the client subsequently
849    /// send either a `CancelLoad` or `FinishLoad` message after optionally sending chunks of body
850    /// data via `SendBodyData`.
851    Start(WebResourceResponse),
852    /// Send a chunk of body data.
853    SendBodyData(Vec<u8>),
854    /// Signal that this load has been finished by the interceptor.
855    FinishLoad,
856    /// Signal that this load has been cancelled by the interceptor.
857    CancelLoad,
858    /// Signal that this load will not be intercepted.
859    DoNotIntercept,
860}
861
862#[derive(Clone, Debug, Deserialize, MallocSizeOf, Serialize)]
863pub struct WebResourceResponse {
864    pub url: Url,
865    #[serde(
866        deserialize_with = "::hyper_serde::deserialize",
867        serialize_with = "::hyper_serde::serialize"
868    )]
869    #[ignore_malloc_size_of = "Defined in hyper"]
870    pub headers: HeaderMap,
871    #[serde(
872        deserialize_with = "::hyper_serde::deserialize",
873        serialize_with = "::hyper_serde::serialize"
874    )]
875    #[ignore_malloc_size_of = "Defined in hyper"]
876    pub status_code: StatusCode,
877    pub status_message: Vec<u8>,
878}
879
880impl WebResourceResponse {
881    pub fn new(url: Url) -> WebResourceResponse {
882        WebResourceResponse {
883            url,
884            headers: HeaderMap::new(),
885            status_code: StatusCode::OK,
886            status_message: b"OK".to_vec(),
887        }
888    }
889
890    pub fn headers(mut self, headers: HeaderMap) -> WebResourceResponse {
891        self.headers = headers;
892        self
893    }
894
895    pub fn status_code(mut self, status_code: StatusCode) -> WebResourceResponse {
896        self.status_code = status_code;
897        self
898    }
899
900    pub fn status_message(mut self, status_message: Vec<u8>) -> WebResourceResponse {
901        self.status_message = status_message;
902        self
903    }
904}
905
906/// The type of platform theme.
907#[derive(Clone, Copy, Debug, Deserialize, Eq, MallocSizeOf, PartialEq, Serialize)]
908pub enum Theme {
909    /// Light theme.
910    Light,
911    /// Dark theme.
912    Dark,
913}
914
915impl From<Theme> for PrefersColorScheme {
916    fn from(value: Theme) -> Self {
917        match value {
918            Theme::Light => PrefersColorScheme::Light,
919            Theme::Dark => PrefersColorScheme::Dark,
920        }
921    }
922}
923
924// The type of MediaSession action.
925/// <https://w3c.github.io/mediasession/#enumdef-mediasessionaction>
926#[derive(Clone, Debug, Deserialize, Eq, Hash, MallocSizeOf, PartialEq, Serialize)]
927pub enum MediaSessionActionType {
928    /// The action intent is to resume playback.
929    Play,
930    /// The action intent is to pause the currently active playback.
931    Pause,
932    /// The action intent is to move the playback time backward by a short period (i.e. a few
933    /// seconds).
934    SeekBackward,
935    /// The action intent is to move the playback time forward by a short period (i.e. a few
936    /// seconds).
937    SeekForward,
938    /// The action intent is to either start the current playback from the beginning if the
939    /// playback has a notion, of beginning, or move to the previous item in the playlist if the
940    /// playback has a notion of playlist.
941    PreviousTrack,
942    /// The action is to move to the playback to the next item in the playlist if the playback has
943    /// a notion of playlist.
944    NextTrack,
945    /// The action intent is to skip the advertisement that is currently playing.
946    SkipAd,
947    /// The action intent is to stop the playback and clear the state if appropriate.
948    Stop,
949    /// The action intent is to move the playback time to a specific time.
950    SeekTo,
951}
952
953/// The status of the load in this `WebView`.
954#[derive(Clone, Copy, Debug, Deserialize, Eq, PartialEq, Serialize)]
955pub enum LoadStatus {
956    /// The load has started, but the headers have not yet been parsed.
957    Started,
958    /// The `<head>` tag has been parsed in the currently loading page. At this point the page's
959    /// `HTMLBodyElement` is now available in the DOM.
960    HeadParsed,
961    /// The `Document` and all subresources have loaded. This is equivalent to
962    /// `document.readyState` == `complete`.
963    /// See <https://developer.mozilla.org/en-US/docs/Web/API/Document/readyState>
964    Complete,
965}
966
967/// Data that could be used to display a desktop notification to the end user
968/// when the [Notification API](<https://notifications.spec.whatwg.org/#notifications>) is called.
969#[derive(Clone, Debug, Deserialize, Serialize)]
970pub struct Notification {
971    /// Title of the notification.
972    pub title: String,
973    /// Body string of the notification.
974    pub body: String,
975    /// An identifier tag for the notification. Notification with the same tag
976    /// can be replaced by another to avoid users' screen being filled up with similar notifications.
977    pub tag: String,
978    /// The tag for the language used in the notification's title, body, and the title of each its actions. [RFC 5646](https://datatracker.ietf.org/doc/html/rfc5646)
979    pub language: String,
980    /// A boolean value indicates the notification should remain readily available
981    /// until the end user activates or dismisses the notification.
982    pub require_interaction: bool,
983    /// When `true`, indicates no sounds or vibrations should be made. When `None`,
984    /// the device's default settings should be respected.
985    pub silent: Option<bool>,
986    /// The URL of an icon. The icon will be displayed as part of the notification.
987    pub icon_url: Option<ServoUrl>,
988    /// Icon's raw image data and metadata.
989    pub icon_resource: Option<Arc<RasterImage>>,
990    /// The URL of a badge. The badge is used when there is no enough space to display the notification,
991    /// such as on a mobile device's notification bar.
992    pub badge_url: Option<ServoUrl>,
993    /// Badge's raw image data and metadata.
994    pub badge_resource: Option<Arc<RasterImage>>,
995    /// The URL of an image. The image will be displayed as part of the notification.
996    pub image_url: Option<ServoUrl>,
997    /// Image's raw image data and metadata.
998    pub image_resource: Option<Arc<RasterImage>>,
999    /// Actions available for users to choose from for interacting with the notification.
1000    pub actions: Vec<NotificationAction>,
1001}
1002
1003/// Actions available for users to choose from for interacting with the notification.
1004#[derive(Clone, Debug, Deserialize, Serialize)]
1005pub struct NotificationAction {
1006    /// A string that identifies the action.
1007    pub name: String,
1008    /// The title string of the action to be shown to the user.
1009    pub title: String,
1010    /// The URL of an icon. The icon will be displayed with the action.
1011    pub icon_url: Option<ServoUrl>,
1012    /// Icon's raw image data and metadata.
1013    pub icon_resource: Option<Arc<RasterImage>>,
1014}
1015
1016/// Information about a `WebView`'s screen geometry and offset. This is used
1017/// for the [Screen](https://drafts.csswg.org/cssom-view/#the-screen-interface) CSSOM APIs
1018/// and `window.screenLeft` / `window.screenX` / `window.screenTop` / `window.screenY` /
1019/// `window.moveBy`/ `window.resizeBy` / `window.outerWidth` / `window.outerHeight` /
1020/// `window.screen.availHeight` / `window.screen.availWidth`.
1021#[derive(Clone, Copy, Debug, Default)]
1022pub struct ScreenGeometry {
1023    /// The size of the screen in device pixels. This will be converted to
1024    /// CSS pixels based on the pixel scaling of the `WebView`.
1025    pub size: DeviceIntSize,
1026    /// The available size of the screen in device pixels for the purposes of
1027    /// the `window.screen.availHeight` / `window.screen.availWidth`. This is the size
1028    /// available for web content on the screen, and should be `size` minus any system
1029    /// toolbars, docks, and interface elements. This will be converted to
1030    /// CSS pixels based on the pixel scaling of the `WebView`.
1031    pub available_size: DeviceIntSize,
1032    /// The rectangle the `WebView`'s containing window (including OS decorations)
1033    /// in device pixels for the purposes of the
1034    /// `window.screenLeft`, `window.outerHeight` and similar APIs.
1035    /// This will be converted to CSS pixels based on the pixel scaling of the `WebView`.
1036    pub window_rect: DeviceIntRect,
1037}
1038
1039impl From<SelectElementOption> for SelectElementOptionOrOptgroup {
1040    fn from(value: SelectElementOption) -> Self {
1041        Self::Option(value)
1042    }
1043}
1044
1045/// The address of a node. Layout sends these back. They must be validated via
1046/// `from_untrusted_node_address` before they can be used, because we do not trust layout.
1047#[derive(Clone, Copy, Debug, Eq, Hash, PartialEq)]
1048pub struct UntrustedNodeAddress(pub *const c_void);
1049
1050malloc_size_of_is_0!(UntrustedNodeAddress);
1051
1052#[allow(unsafe_code)]
1053unsafe impl Send for UntrustedNodeAddress {}
1054
1055impl From<style_traits::dom::OpaqueNode> for UntrustedNodeAddress {
1056    fn from(o: style_traits::dom::OpaqueNode) -> Self {
1057        UntrustedNodeAddress(o.0 as *const c_void)
1058    }
1059}
1060
1061impl Serialize for UntrustedNodeAddress {
1062    fn serialize<S: Serializer>(&self, s: S) -> Result<S::Ok, S::Error> {
1063        (self.0 as usize).serialize(s)
1064    }
1065}
1066
1067impl<'de> Deserialize<'de> for UntrustedNodeAddress {
1068    fn deserialize<D: Deserializer<'de>>(d: D) -> Result<UntrustedNodeAddress, D::Error> {
1069        let value: usize = Deserialize::deserialize(d)?;
1070        Ok(UntrustedNodeAddress::from_id(value))
1071    }
1072}
1073
1074impl UntrustedNodeAddress {
1075    /// Creates an `UntrustedNodeAddress` from the given pointer address value.
1076    #[inline]
1077    pub fn from_id(id: usize) -> UntrustedNodeAddress {
1078        UntrustedNodeAddress(id as *const c_void)
1079    }
1080}
1081
1082/// The result of a hit test in the compositor.
1083#[derive(Clone, Debug, Deserialize, Serialize)]
1084pub struct CompositorHitTestResult {
1085    /// The pipeline id of the resulting item.
1086    pub pipeline_id: PipelineId,
1087
1088    /// The hit test point in the item's viewport.
1089    pub point_in_viewport: Point2D<f32, CSSPixel>,
1090
1091    /// The [`ExternalScrollId`] of the scroll tree node associated with this hit test item.
1092    pub external_scroll_id: ExternalScrollId,
1093}
1094
1095/// For a given pipeline, whether any animations are currently running
1096/// and any animation callbacks are queued
1097#[derive(Clone, Copy, Debug, Deserialize, Eq, PartialEq, Serialize)]
1098pub enum AnimationState {
1099    /// Animations are active but no callbacks are queued
1100    AnimationsPresent,
1101    /// Animations are active and callbacks are queued
1102    AnimationCallbacksPresent,
1103    /// No animations are active and no callbacks are queued
1104    NoAnimationsPresent,
1105    /// No animations are active but callbacks are queued
1106    NoAnimationCallbacksPresent,
1107}
1108
1109/// A sequence number generated by a script thread for its pipelines. The
1110/// constellation attaches the target pipeline's last seen `FocusSequenceNumber`
1111/// to every focus-related message it sends.
1112///
1113/// This is used to resolve the inconsistency that occurs due to bidirectional
1114/// focus state synchronization and provide eventual consistency. Example:
1115///
1116/// ```text
1117/// script                            constellation
1118/// -----------------------------------------------------------------------
1119/// send ActivateDocument ----------> receive ActivateDocument
1120///                             ,---- send FocusDocument
1121///                             |
1122/// focus an iframe             |
1123/// send Focus -----------------|---> receive Focus
1124///                             |     focus the iframe's content document
1125/// receive FocusDocument <-----'     send FocusDocument to the content pipeline --> ...
1126/// unfocus the iframe
1127/// focus the document
1128///
1129/// Final state:                      Final state:
1130///  the iframe is not focused         the iframe is focused
1131/// ```
1132///
1133/// When the above sequence completes, from the script thread's point of view,
1134/// the iframe is unfocused, but from the constellation's point of view, the
1135/// iframe is still focused.
1136///
1137/// This inconsistency can be resolved by associating a sequence number to each
1138/// message. Whenever a script thread initiates a focus operation, it generates
1139/// and sends a brand new sequence number. The constellation attaches the
1140/// last-received sequence number to each message it sends. This way, the script
1141/// thread can discard out-dated incoming focus messages, and eventually, all
1142/// actors converge to the consistent state which is determined based on the
1143/// last focus message received by the constellation.
1144///
1145/// ```text
1146/// script                            constellation
1147/// -----------------------------------------------------------------------
1148/// send ActivateDocument ----------> receive ActivateDocument
1149///                             ,---- send FocusDocument (0)
1150///                             |
1151/// seq_number += 1             |
1152/// focus an iframe             |
1153/// send Focus (1) -------------|---> receive Focus (1)
1154///                             |     focus the iframe's content document
1155/// receive FocusDocument (0) <-'     send FocusDocument to the content pipeline --> ...
1156/// ignore it because 0 < 1
1157///
1158/// Final state:                      Final state:
1159///  the iframe is focused             the iframe is focused
1160/// ```
1161#[derive(
1162    Clone,
1163    Copy,
1164    Debug,
1165    Default,
1166    Deserialize,
1167    Eq,
1168    Hash,
1169    MallocSizeOf,
1170    PartialEq,
1171    Serialize,
1172    PartialOrd,
1173)]
1174pub struct FocusSequenceNumber(pub u64);
1175
1176impl Display for FocusSequenceNumber {
1177    fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error> {
1178        Display::fmt(&self.0, f)
1179    }
1180}
1181
1182/// An identifier for a particular JavaScript evaluation that is used to track the
1183/// evaluation from the embedding layer to the script layer and then back.
1184#[derive(Clone, Copy, Deserialize, Eq, Hash, PartialEq, Serialize)]
1185pub struct JavaScriptEvaluationId(pub usize);
1186
1187#[derive(Clone, Debug, Deserialize, PartialEq, Serialize)]
1188pub enum JSValue {
1189    Undefined,
1190    Null,
1191    Boolean(bool),
1192    Number(f64),
1193    String(String),
1194    Element(String),
1195    ShadowRoot(String),
1196    Frame(String),
1197    Window(String),
1198    Array(Vec<JSValue>),
1199    Object(HashMap<String, JSValue>),
1200}
1201
1202#[derive(Clone, Debug, Deserialize, PartialEq, Serialize)]
1203pub struct JavaScriptErrorInfo {
1204    pub message: String,
1205    pub filename: String,
1206    pub stack: Option<String>,
1207    pub line_number: u64,
1208    pub column: u64,
1209}
1210
1211/// Indicates the reason that JavaScript evaluation failed due serializing issues the
1212/// result of the evaluation.
1213#[derive(Clone, Debug, Deserialize, EnumMessage, PartialEq, Serialize)]
1214pub enum JavaScriptEvaluationResultSerializationError {
1215    /// Serialization could not complete because a JavaScript value contained a detached
1216    /// shadow root according to <https://w3c.github.io/webdriver/#dfn-internal-json-clone>.
1217    DetachedShadowRoot,
1218    /// Serialization could not complete because a JavaScript value contained a "stale"
1219    /// element reference according to <https://w3c.github.io/webdriver/#dfn-get-a-known-element>.
1220    StaleElementReference,
1221    /// Serialization could not complete because a JavaScript value of an unknown type
1222    /// was encountered.
1223    UnknownType,
1224    /// This is a catch all for other kinds of errors that can happen during JavaScript value
1225    /// serialization. For instances where this can happen, see:
1226    /// <https://w3c.github.io/webdriver/#dfn-clone-an-object>.
1227    OtherJavaScriptError,
1228}
1229
1230/// An error that happens when trying to evaluate JavaScript on a `WebView`.
1231#[derive(Clone, Debug, Deserialize, EnumMessage, PartialEq, Serialize)]
1232pub enum JavaScriptEvaluationError {
1233    /// The `Document` of frame that the script was going to execute in no longer exists.
1234    DocumentNotFound,
1235    /// The script could not be compiled.
1236    CompilationFailure,
1237    /// The script could not be evaluated.
1238    EvaluationFailure(Option<JavaScriptErrorInfo>),
1239    /// An internal Servo error prevented the JavaSript evaluation from completing properly.
1240    /// This indicates a bug in Servo.
1241    InternalError,
1242    /// The `WebView` on which this evaluation request was triggered is not ready. This might
1243    /// happen if the `WebView`'s `Document` is changing due to ongoing load events, for instance.
1244    WebViewNotReady,
1245    /// The script executed successfully, but Servo could not serialize the JavaScript return
1246    /// value into a [`JSValue`].
1247    SerializationError(JavaScriptEvaluationResultSerializationError),
1248}
1249
1250#[derive(Clone, Debug, Deserialize, PartialEq, Serialize)]
1251pub enum ScreenshotCaptureError {
1252    /// The screenshot request failed to read the screenshot image from the `WebView`'s
1253    /// `RenderingContext`.
1254    CouldNotReadImage,
1255    /// The WebView that this screenshot request was made for no longer exists.
1256    WebViewDoesNotExist,
1257}
1258
1259#[derive(Clone, Copy, Debug, Deserialize, Serialize)]
1260pub struct RgbColor {
1261    pub red: u8,
1262    pub green: u8,
1263    pub blue: u8,
1264}
1265
1266/// A Script to Embedder Channel
1267#[derive(Clone, Debug, Deserialize, MallocSizeOf, Serialize)]
1268pub struct ScriptToEmbedderChan(GenericCallback<EmbedderMsg>);
1269
1270impl ScriptToEmbedderChan {
1271    /// Create a new Channel allowing script to send messages to the Embedder
1272    pub fn new(
1273        embedder_chan: Sender<EmbedderMsg>,
1274        waker: Box<dyn EventLoopWaker>,
1275    ) -> ScriptToEmbedderChan {
1276        let embedder_callback = GenericCallback::new(move |embedder_msg| {
1277            let msg = match embedder_msg {
1278                Ok(embedder_msg) => embedder_msg,
1279                Err(err) => {
1280                    log::warn!("Script to Embedder message error: {err}");
1281                    return;
1282                },
1283            };
1284            let _ = embedder_chan.send(msg);
1285            waker.wake();
1286        })
1287        .expect("Failed to create channel");
1288        ScriptToEmbedderChan(embedder_callback)
1289    }
1290
1291    /// Send a message to and wake the Embedder
1292    pub fn send(&self, msg: EmbedderMsg) -> SendResult {
1293        self.0.send(msg)
1294    }
1295}
embedder_traits/lib.rs

embedder_traits/
lib.rs
