tilo_app/framework/

rows.rs

//! Live external rows: what a surface shows that lives outside the
//! resource's document — processes, devices, containers, journal entries,
//! fetched catalogue rows, running jobs — published beneath the resource for
//! the palette, agents and scripts.

use tilo_actions::{ActionSpec, ResourcePresentation, ResourceSemanticIdentity, ResourceSpec};
use tilo_resource::Effect;

/// One live external entity a surface publishes beneath its resource, with
/// the view and effect operations it offers (inspect a process, stop a
/// container).
///
/// A row is not document state: it has no history, no undo and nothing to
/// sync, so it can never carry a document mutation. A change to the
/// document is the resource's `Action` through the
/// [`Dispatcher`](super::Dispatcher), bound to a row's item through
/// [`Publishes::row_edits`](super::Publishes::row_edits) or the resource's
/// `children`.
///
/// Rows are merged by id into the resource's published children: a row with
/// the id of a document child adds its operations to that child instead of
/// publishing a second resource under the same id.
///
/// A row is shared, not copied: a surface that keeps the rows it made while
/// what they show holds hands the same rows to every publication, and the
/// publication reuses what it built from each one instead of building it
/// again.
#[derive(Clone)]
pub struct LiveRow {
    resource: std::rc::Rc<ResourceSpec>,
}

impl LiveRow {
    /// A row with a stable `id` (unique within the resource, and naming the
    /// same entity for as long as it lives: a process id with its start
    /// time, a container id), a `kind` tag and a human `label`.
    pub fn new(id: impl Into<String>, kind: impl Into<String>, label: impl Into<String>) -> Self {
        Self {
            resource: std::rc::Rc::new(ResourceSpec::new(id, kind, label)),
        }
    }

    /// A row of the declared type `R` (a resource type of `R`'s kind), whose
    /// noun its type publishes, of the app the type is declared in: its
    /// `id`, its `label`, and the [`ResourceType`](tilo_actions::ResourceType)
    /// search matches "videos of …" against. A row an app declares an item of
    /// a `#[resource]` type publishes (`Video`, `Channel`) is one of these,
    /// so what it is is the type's and the search's, nothing the app writes.
    pub fn typed<R: tilo_resource::words::RowType>(
        id: impl Into<String>,
        label: impl Into<String>,
    ) -> Self {
        Self {
            resource: std::rc::Rc::new(ResourceSpec::new(id, R::KIND, label).with_type(R::words())),
        }
    }

    /// This row's type, saying what it is as people name it ([`Self::typed`]);
    /// a row made with [`Self::new`] says nothing.
    #[must_use]
    pub fn with_type(mut self, words: tilo_actions::ResourceType) -> Self {
        std::rc::Rc::make_mut(&mut self.resource).resource_type = Some(words);
        self
    }

    /// Attach the stable source-domain identity used to find this row across
    /// live dispatch aliases. It is descriptive metadata only and grants no
    /// permission or authority. Invalid identities are omitted at this
    /// publication boundary.
    #[must_use]
    pub fn semantic_identity(mut self, identity: ResourceSemanticIdentity) -> Self {
        std::rc::Rc::make_mut(&mut self.resource).semantic_identity =
            identity.is_valid().then_some(identity);
        self
    }

    /// `resource`, an entity the surface already describes as a resource
    /// (a search hit, a catalogue entry), as a row: its presentation,
    /// views, operations and children. Its document actions are dropped at
    /// any depth: the resource's own publication carries them.
    pub fn from_resource(resource: ResourceSpec) -> Self {
        Self {
            resource: std::rc::Rc::new(resolved_outside_document(resource)),
        }
    }

    /// Offer a view or effect operation on the row.
    ///
    /// # Panics
    /// In a debug build, when `operation` is a document mutation; a release
    /// build drops it.
    #[must_use]
    pub fn operation(mut self, operation: ActionSpec) -> Self {
        if admits(&operation, self.id()) {
            std::rc::Rc::make_mut(&mut self.resource)
                .actions
                .push(operation);
        }
        self
    }

    /// How the entity stands right now (a process's CPU use, what a timer
    /// has left), shown beside its label. A row merged into a document child
    /// that has no presentation of its own lends it this one.
    #[must_use]
    pub fn presentation(mut self, presentation: ResourcePresentation) -> Self {
        std::rc::Rc::make_mut(&mut self.resource).presentation = Some(presentation);
        self
    }

    /// Offer `effect`, bound to this row's entity (stop *this* process):
    /// invoked here, it reaches the surface's or view's handler of `E` as
    /// that value, under the effect's declared contract.
    #[must_use]
    pub fn effect<E: Effect>(self, effect: &E) -> Self {
        self.operation(effect.bound())
    }

    /// Offer `view` of the row's entity: a way to show it (a message in
    /// its conversation, a range of its text) that a link or an agent
    /// navigates to, opened by one of the row's own operations.
    #[must_use]
    pub fn view(mut self, view: tilo_actions::ResourceViewSpec) -> Self {
        std::rc::Rc::make_mut(&mut self.resource).views.push(view);
        self
    }

    /// Nest `row` beneath this one (a container's logs).
    #[must_use]
    pub fn row(mut self, row: LiveRow) -> Self {
        std::rc::Rc::make_mut(&mut self.resource)
            .children
            .push(std::rc::Rc::unwrap_or_clone(row.resource));
        self
    }

    pub fn id(&self) -> &str {
        self.resource.id.as_str()
    }

    /// The row as the published tree carries it.
    pub fn into_resource(self) -> ResourceSpec {
        let mut resource = std::rc::Rc::unwrap_or_clone(self.resource);
        tilo_resource::share::offer_tree(&mut resource);
        resource
    }

    /// Whether `self` and `other` are the same row, handed out again: a
    /// clone of one row, not two rows that read alike.
    pub fn same_row(&self, other: &Self) -> bool {
        std::rc::Rc::ptr_eq(&self.resource, &other.resource)
    }
}

use ui_core::resources::admits_outside_document as admits;
pub(crate) use ui_core::resources::{outside_document, resolved_outside_document};

/// Merge `rows` by id into `children`: a row naming an existing child adds
/// the operations and rows that child lacks, and its presentation when the
/// child has none; any other row is appended. The first publisher of an id
/// keeps its label and kind.
pub(crate) fn merge(
    children: &mut Vec<ResourceSpec>,
    rows: impl IntoIterator<Item = ResourceSpec>,
) {
    for row in rows {
        match children.iter_mut().find(|child| child.id == row.id) {
            Some(existing) => join(existing, row),
            None => children.push(row),
        }
    }
}

/// Add to `existing` the presentation, semantic identity, operations, views and rows of `row`,
/// which names it, that it lacks.
pub(crate) fn join(existing: &mut ResourceSpec, row: ResourceSpec) {
    if existing.presentation.is_none() {
        existing.presentation = row.presentation;
    }
    if existing.semantic_identity.is_none() {
        existing.semantic_identity = row
            .semantic_identity
            .filter(ResourceSemanticIdentity::is_valid);
    }
    for action in row.actions {
        if !existing.actions.iter().any(|known| known.id == action.id) {
            existing.actions.push(action);
        }
    }
    let mut views_added = false;
    for view in row.views {
        if !existing.views.iter().any(|known| known.id == view.id) {
            existing.views.push(view);
            views_added = true;
        }
    }
    if views_added {
        // The link actions name the views they were offered with.
        tilo_resource::share::reoffer(existing);
    }
    merge(&mut existing.children, row.children);
}

pub(crate) fn find(resources: &[ResourceSpec], id: &str) -> Option<ResourceSpec> {
    resources.iter().find_map(|resource| {
        if resource.id.as_str() == id {
            Some(resource.clone())
        } else {
            find(&resource.children, id)
        }
    })
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn merging_retains_the_selector_identity_without_overwriting_the_first_publisher() {
        let identity = ResourceSemanticIdentity::new("chat.agent", "chat.agent:scribe").unwrap();
        let row = || {
            LiveRow::new("agent:1", "chat.agent", "Scribe")
                .semantic_identity(identity.clone())
                .into_resource()
        };
        let mut children = vec![ResourceSpec::new("agent:1", "chat.agent", "Document label")];
        merge(&mut children, [row()]);
        assert_eq!(children.len(), 1);
        assert_eq!(children[0].semantic_identity, Some(identity.clone()));
        assert_eq!(children[0].label, "Document label");

        let first = ResourceSemanticIdentity::new("chat.agent", "chat.agent:reed").unwrap();
        children[0].semantic_identity = Some(first.clone());
        merge(&mut children, [row()]);
        assert_eq!(children[0].semantic_identity, Some(first));
    }

    #[test]
    fn live_row_retains_only_a_valid_typed_semantic_identity() {
        let identity = ResourceSemanticIdentity::new("chat.agent", "chat.agent:scribe")
            .expect("the bounded typed identity is valid");
        let resource = LiveRow::new("opaque:1", "chat.agent", "Scribe")
            .semantic_identity(identity.clone())
            .into_resource();
        assert_eq!(resource.semantic_identity, Some(identity));

        let invalid = ResourceSemanticIdentity {
            kind: "chat agent".into(),
            key: "chat.agent:scribe".into(),
        };
        assert!(
            LiveRow::new("opaque:2", "chat.agent", "Scribe")
                .semantic_identity(invalid)
                .into_resource()
                .semantic_identity
                .is_none(),
            "a live row never publishes malformed selector metadata"
        );
    }
}