Struct myxine_core::Page

pub struct Page { /* fields omitted */ }

A proxy for a page in the browser, encapsulating all the state and connections necessary to set its content, listen for events, and evaluate JavaScript within it. At any given time, a Page object may be connected to zero, one, or more actual browser windows, each of which will exactly mirror whatever is being done to the Page object.

To actually connect a Page to a real browser window, this library must be used in concert with a web server to serve JavaScript that communicates with the server to consume its streams of Commands and send it back browser events. None of this functionality is contained in this crate, but for ease of description, we will refer to the abstractions provided by a Page in terms of its interactions with a real browser, even though this must be enabled elsewhere (canonically, in the Myxine server).

A Page can correspond to dynamic or static content, and can be changed between those two at will, though changing a page from static content to dynamic content will necessitate a manual browser refresh to be noticeable, since static content is served without any "magic" to make it automatically change.

Implementations

impl Page

pub fn new(buffer_size: usize) -> Page

Make a new empty (dynamic) page with a given internal event buffer size. This can be altered later by means of the set_buffer_size method.

pub async fn is_empty<'_>(&'_ self) -> bool

Test if this page is empty, where "empty" means that it is dynamic, with an empty title, empty body, and no subscribers waiting on its page events.

pub async fn commands<'_>(&'_ self) -> Option<impl Stream<Item = Command>>

Get the stream of commands to this page, starting at the moment this function was called. These commands provide all the dynamic information necessary for a consumer of this stream to reconstruct the exact state of the page at any given moment. If the page is static, returns None.

pub async fn static_content<'_>(&'_ self) -> Option<(Option<String>, Bytes)>

If the page is static, return a pair of its Content-Type (if it has one), and its static content. If the page is dynamic, returns None.

pub async fn events<'_>(
    &'_ self,
    subscription: Subscription
) -> impl Stream<Item = Arc<Event>>

Get a stream of events which match the specified Subscription, starting at the next event after the moment this function is called.

pub async fn event_after<'_>(
    &'_ self,
    subscription: Subscription,
    moment: u64
) -> Result<(u64, Arc<Event>), u64>

Get a specific event, at or after a particular moment in time, given a subscription specification that it must match. If the event is available in the buffer, this returns immediately, otherwise it may block until the event is available. If the request is for a moment which lies before the buffer, returns Err(u64), to indicate the canonical moment for the event requested. The user-agent is responsible for retrying a request redirected to this moment.

pub async fn next_event<'_>(
    &'_ self,
    subscription: Subscription
) -> (u64, Arc<Event>)

Get the next event for a particular subscription, bypassing the buffer of pre-existing events and blocking until a new event arrives after the time this function was called.

pub async fn send_event<'_>(&'_ self, event: Event)

Send an event to all subscribers to events on this page which are waiting on an event of this kind.

pub async fn set_content<'_>(
    &'_ self,
    new_title: impl Into<String>,
    new_body: impl Into<String>,
    refresh: RefreshMode
)

Tell all clients to change the title and body, if necessary. This converts the page into a dynamic page, overwriting any static content that previously existed, if any.

pub async fn set_static<'_>(
    &'_ self,
    content_type: Option<String>,
    raw_contents: Bytes
)

Set the contents of the page to be a static raw set of bytes with no self-refreshing functionality. All clients will be told to refresh their page to load the new static content (which will not be able to update itself until a client refreshes their page again).

pub async fn clear<'_>(&'_ self)

Clear the page entirely, removing all subscribers and resetting the page title and body to empty.

pub async fn refresh<'_>(&'_ self)

Tell the page, if it is dynamic, to refresh its content in full from the server.

pub async fn evaluate<'_, '_>(
    &'_ self,
    expression: &'_ str,
    statement_mode: bool,
    abort: impl Future<Output = ()>
) -> Option<Result<Value, String>>

Tell the page to evaluate a given piece of JavaScript, as either an expression or a statement, with an optional explicit timeout (defaults to the timeout duration specified when this page was constructed).

pub async fn send_eval_result<'_>(
    &'_ self,
    id: Uuid,
    result: Result<Value, String>
)

Notify waiting clients of the result to some in-page JavaScript evaluation they have requested, either with an error or a valid response.

pub async fn set_buffer_size<'_>(
    &'_ self,
    size: usize,
    deallocation_rate: usize
)

Set the size of the page's internal event buffer. This will not actually de-allocate memory immediately, but rather will mean that future incoming events will incrementally trigger downsizing of the event buffer. When the event buffer actually reaches its new target size, one single re-allocation will occur to free the used memory.

The deallocation_rate parameter determines how aggressively the buffer size is changed. A value of 2 means that for every incoming event, 2 old events are freed; a value of usize::max_value() means that the buffer is instantly resized at the next incoming event; anything in between cause incremental behavior, freeing N old events for each 1 new event. A deallocation rate of 0 or 1 is not valid, and will cause this function to panic.

Trait Implementations

impl Debug for Page

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.