///|
///|
/// Position in the resource change feed.
#derive(Eq, Debug)
pub(all) struct UiCursor {
generation : Int32
seq : Int32
}
///|
pub extend UiCursor with Eq::{not_equal, equal}
///|
pub extend UiCursor with Debug::{to_repr}
///|
/// One consistent read of the UI protocol: every live resource, every pending
/// interaction, and the cursors the host continues from.
#derive(Eq, Debug)
pub(all) struct UiBaseline {
/// Continue-from position of the resource feed.
cursor : UiCursor
/// Continue-from position of the interaction feed.
interaction_cursor : UiCursor
resources : Array[UiResourceSnapshot]
pending_interactions : Array[UiInteractionSnapshot]
}
///|
pub extend UiBaseline with Eq::{not_equal, equal}
///|
pub extend UiBaseline with Debug::{to_repr}
///|
/// Changes accepted strictly after the supplied cursor, with the cursor to
/// continue from.
#derive(Eq, Debug)
pub(all) struct UiChanges {
cursor : UiCursor
changes : Array[UiResourceChange]
}
///|
pub extend UiChanges with Eq::{not_equal, equal}
///|
pub extend UiChanges with Debug::{to_repr}
///|
/// Host intent to run one declared action of one resource.
#derive(Eq, Debug)
pub(all) struct UiActionRequest {
resource : UiResourceRef
action : String
/// Revision the host rendered. A resource that moved on rejects the action.
expected_revision : Int32
/// Host-supplied idempotency key across the whole host runtime: reuse
/// returns the stored outcome, reuse with different content is `Conflict`.
request_id : String
payload : Json?
}
///|
pub extend UiActionRequest with Eq::{not_equal, equal}
///|
pub extend UiActionRequest with Debug::{to_repr}
///|
/// Receipt of one accepted action.
#derive(Eq, Debug)
pub(all) struct UiActionResult {
request_id : String
resource : UiResourceRef
action : String
/// Resource revision the action was accepted against.
revision : Int32
/// True when `request_id` was already accepted and the stored outcome is
/// returned instead of running the handler again.
replayed : Bool
}
///|
pub extend UiActionResult with Eq::{not_equal, equal}
///|
pub extend UiActionResult with Debug::{to_repr}
///|
/// Interaction changes accepted after the supplied interaction cursor.
#derive(Eq, Debug)
pub(all) struct UiInteractionChanges {
cursor : UiCursor
changes : Array[UiInteractionChange]
}
///|
pub extend UiInteractionChanges with Eq::{not_equal, equal}
///|
pub extend UiInteractionChanges with Debug::{to_repr}
///|
/// One change of the ordered push feed.
#derive(Eq, Debug)
pub(all) enum UiChange {
Resource(change~ : UiResourceChange)
Interaction(change~ : UiInteractionChange)
}
///|
pub extend UiChange with Eq::{not_equal, equal}
///|
pub extend UiChange with Debug::{to_repr}
///|
/// One delivered change plus the cursor of its own family.
#derive(Eq, Debug)
pub(all) struct UiFeedBatch {
cursor : UiCursor
change : UiChange
}
///|
pub extend UiFeedBatch with Eq::{not_equal, equal}
///|
pub extend UiFeedBatch with Debug::{to_repr}
///|
/// Reported when a subscriber's own listener fails; the failing subscription
/// is dropped and the host must subscribe again.
#derive(Eq, Debug)
pub(all) struct UiListenerFailure {
subscription : Int32
/// Feed position of the batch that failed.
seq : Int32
detail : String
}
///|
pub extend UiListenerFailure with Eq::{not_equal, equal}
///|
pub extend UiListenerFailure with Debug::{to_repr}
///|
/// Live push subscription delivering changes in commit order.
pub struct UiSubscription {
priv id_ : Int32
priv is_active_ : () -> Bool
priv unsubscribe_ : () -> Unit
}
///|
/// Framework construction hook. Hosts obtain the value from the Agent.
pub fn UiSubscription::from_callbacks(
id~ : Int32,
is_active~ : () -> Bool,
unsubscribe~ : () -> Unit,
) -> UiSubscription {
{ id_: id, is_active_: is_active, unsubscribe_: unsubscribe, }
}
///|
/// Subscription id, as reported by `UiListenerFailure`.
pub fn UiSubscription::id(self : UiSubscription) -> Int32 {
self.id_
}
///|
/// False once unsubscribed, dropped after a listener failure, or closed by
/// `Agent::shutdown`.
pub fn UiSubscription::is_active(self : UiSubscription) -> Bool {
(self.is_active_)()
}
///|
/// Stop delivery. Idempotent, and safe to call from inside the listener itself;
/// no change is delivered after it returns.
pub fn UiSubscription::unsubscribe(self : UiSubscription) -> Unit {
(self.unsubscribe_)()
}
///|
/// The atomic handoff of a push subscription: the baseline cut plus the handle
/// for everything accepted after it.
pub(all) struct UiObservation {
baseline : UiBaseline
/// Subscription id; also the id carried by `UiListenerFailure`.
subscription : UiSubscription
}
///|
/// Host observation, interaction and action handle, owned by the Agent.
pub struct UiHost {
priv snapshot_ : () -> Result[UiBaseline, UiResourceError]
priv changes_since_ : (UiCursor) -> Result[UiChanges, UiResourceError]
priv interactions_since_ : (UiCursor) -> Result[
UiInteractionChanges,
UiResourceError,
]
priv dispatch_ : async (UiActionRequest) -> Result[
UiActionResult,
UiResourceError,
] noraise
priv answer_ : (UiInteractionAnswerRequest) -> Result[
UiInteractionAnswerReceipt,
UiInteractionError,
]
priv dismiss_ : (UiInteractionRef, String) -> Result[
UiInteractionOutcome,
UiInteractionError,
]
priv subscribe_ : (
(UiFeedBatch) -> Result[Unit, String],
(UiListenerFailure) -> Unit,
) -> Result[UiObservation, UiResourceError]
priv connect_ : (UiHostCapabilities) -> Result[
UiHostConnection,
UiInteractionError,
]
}
///|
/// Read the current baseline. Cheap, side-effect free and repeatable.
pub fn UiHost::snapshot(self : UiHost) -> Result[UiBaseline, UiResourceError] {
(self.snapshot_)()
}
///|
/// Changes accepted after `cursor`. The caller must treat `SnapshotRequired`
/// as "re-read `snapshot`", never as "nothing changed".
pub fn UiHost::changes_since(
self : UiHost,
cursor~ : UiCursor,
) -> Result[UiChanges, UiResourceError] {
(self.changes_since_)(cursor)
}
///|
/// Interaction changes accepted after `cursor`. Same window and generation
/// rules as `changes_since`, on the interaction feed.
pub fn UiHost::interactions_since(
self : UiHost,
cursor~ : UiCursor,
) -> Result[UiInteractionChanges, UiResourceError] {
(self.interactions_since_)(cursor)
}
///|
/// Route one action to the resource's owner. Validation happens before the
/// owner handler is awaited; a duplicate request id replays the stored receipt
/// instead of running the handler twice.
pub async fn UiHost::dispatch(
self : UiHost,
request~ : UiActionRequest,
) -> Result[UiActionResult, UiResourceError] noraise {
(self.dispatch_)(request)
}
///|
/// Answer one pending interaction. The first valid answer settles it; the same
/// value again replays the stored receipt, a different value is `Conflict`,
/// and a question that already ended is `AlreadySettled`.
pub fn UiHost::answer(
self : UiHost,
request~ : UiInteractionAnswerRequest,
) -> Result[UiInteractionAnswerReceipt, UiInteractionError] {
(self.answer_)(request)
}
///|
/// Dismiss one pending interaction: the user closed the prompt without
/// choosing; the owner's waiter resumes with `Dismissed`. Re-dismissing a
/// settled question is `AlreadySettled`.
pub fn UiHost::dismiss(
self : UiHost,
interaction~ : UiInteractionRef,
reason~ : String = "",
) -> Result[UiInteractionOutcome, UiInteractionError] {
(self.dismiss_)(interaction, reason)
}
///|
/// Subscribe to every change accepted from now on. The returned baseline
/// already contains everything committed before the subscription; the listener
/// receives everything after it, in commit order, synchronously inside the
/// accepting mutation. Returning `Err(detail)` keeps the change accepted,
/// calls `on_failure` once and drops the subscription.
pub fn UiHost::subscribe(
self : UiHost,
listener~ : (UiFeedBatch) -> Result[Unit, String],
on_failure~ : (UiListenerFailure) -> Unit,
) -> Result[UiObservation, UiResourceError] {
(self.subscribe_)(listener, on_failure)
}
///|
/// Attach an explicit host lease with the capabilities this host declares.
/// A subscription is observation only; only a connection whose `interactions`
/// include the question's body kind keeps a blocking `wait` blocked. Detaching
/// releases the lease and wakes waiters that lost their last matching host.
pub fn UiHost::connect(
self : UiHost,
capabilities~ : UiHostCapabilities,
) -> Result[UiHostConnection, UiInteractionError] {
(self.connect_)(capabilities)
}
///|
/// Framework construction hook. Hosts obtain the value from the Agent.
pub fn UiHost::from_callbacks(
snapshot~ : () -> Result[UiBaseline, UiResourceError],
changes_since~ : (UiCursor) -> Result[UiChanges, UiResourceError],
interactions_since~ : (UiCursor) -> Result[
UiInteractionChanges,
UiResourceError,
],
dispatch~ : async (UiActionRequest) -> Result[UiActionResult, UiResourceError] noraise,
answer~ : (UiInteractionAnswerRequest) -> Result[
UiInteractionAnswerReceipt,
UiInteractionError,
],
dismiss~ : (UiInteractionRef, String) -> Result[
UiInteractionOutcome,
UiInteractionError,
],
subscribe~ : (
(UiFeedBatch) -> Result[Unit, String],
(UiListenerFailure) -> Unit,
) -> Result[UiObservation, UiResourceError],
connect? : (UiHostCapabilities) -> Result[
UiHostConnection,
UiInteractionError,
],
) -> UiHost {
let connect_callback = match connect {
Some(callback) => callback
None =>
fn(_capabilities) {
Err(
HostUnavailable(
reason="this UiHost adapter does not support host connections",
),
)
}
}
{
snapshot_: snapshot,
changes_since_: changes_since,
interactions_since_: interactions_since,
dispatch_: dispatch,
answer_: answer,
dismiss_: dismiss,
subscribe_: subscribe,
connect_: connect_callback,
}
}