notesmachine/server/nm-store/src/store/api.rs

// This Source Code Form is subject to the terms of the Mozilla Public
// License, v. 2.0. If a copy of the MPL was not distributed with this
// file, You can obtain one at http://mozilla.org/MPL/2.0/.

//! # Storage layer for Notesmachine
//!
//! This library implements the core functionality of Notesmachine and
//! describes that functionality to a storage layer.  There's a bit of
//! intermingling in here which can't be helped, although it may make
//! sense in the future to separate the decomposition of the note
//! content into a higher layer.
//!
//! Notesmachine storage notes consist of two items: Note and Page.
//! This distinction is somewhat arbitrary, as structurally these two
//! items are stored in the same table.
//!
//! - Boxes have titles (and date metadata)
//! - Notes have content and a type (and date metadata)
//! - Notes are stored in boxes
//!   - Notes are positioned with respect to other notes.
//!   - There are two positions:
//!     - Siblings, creating lists
//!     - Children, creating trees like this one
//! - Notes may have references (pointers) to other boxes
//! - Notes may be moved around
//! - Notes may be deleted
//! - Boxes may be deleted
//! - When a box is renamed, every reference to that box is auto-edited to
//!   reflect the change. If a box is renamed to match an existing box, the
//!   notes in both boxes are merged.
//!   
//! Note-to-note relationships form trees, and are kept in a SQL database of
//! (`parent_id`, `child_id`, `position`, `relationship_type`). The
//! `position` is a monotonic index on the parent (that is, every pair
//! (`parent_id`, `position`) must be unique).  The `relationship_type` is
//! an enum and can specify that the relationship is *original*,
//! *embedding*, or *referencing*.  An embedded or referenced note may be
//! read/write or read-only with respect to the original, but there is only
//! one original note at any time.
//!
//! Note-to-box relationships form a graph, and are kept in the SQL database
//! as a collection of *edges* from the note to the box (and naturally
//! vice-versa).
//!
//! - Decision: When an original note is deleted, do all references and
//!   embeddings also get deleted, or is the oldest one elevated to be a new
//!   "original"?  Or is that something the user may choose?
//!
//! - Decision: Should the merging issue be handled at this layer, or would
//!   it make sense to move this to a higher layer, and only provide the
//!   hooks for it here?
//!
#![allow(clippy::len_zero)]
use crate::errors::NoteStoreError;
use crate::parser::build_references;
use crate::store::private::*;
use crate::structs::*;
use sqlx::sqlite::SqlitePool;
use std::sync::Arc;

/// A handle to our Sqlite database.
#[derive(Clone, Debug)]
pub struct NoteStore(Arc<SqlitePool>);

pub type NoteResult<T> = core::result::Result<T, NoteStoreError>;

// After wrestling for a while with the fact that 'box' is a reserved
// word in Rust, I decided to just go with Note (note) and Page
// (box).

impl NoteStore {
    /// Initializes a new instance of the note store.  Note that the
    /// note store holds an Arc internally; this code is (I think)
    /// safe to Send.
    pub async fn new(url: &str) -> NoteResult<Self> {
        let pool = SqlitePool::connect(url).await?;
        Ok(NoteStore(Arc::new(pool)))
    }
    /// Erase all the data in the database and restore it
    /// to its original empty form.  Do not use unless you
    /// really, really want that to happen.
    pub async fn reset_database(&self) -> NoteResult<()> {
        reset_database(&*self.0).await.map_err(NoteStoreError::DBError)
    }

    /// Fetch page by slug
    ///
    /// Supports the use case of the user navigating to a known place
    /// via a bookmark or other URL.  Since the title isn't clear from
    /// the slug, the slug is insufficient to generate a new page, so
    /// this use case says that in the event of a failure to find the
    /// requested page, return a basic NotFound.
    pub async fn get_page_by_slug(&self, slug: &str) -> NoteResult<(Vec<Note>, Vec<Note>)> {
        let page = select_page_by_slug(&*self.0, slug).await?;
        if page.is_empty() {
            return Err(NoteStoreError::NotFound);
        }

        let note_id = &page[0].id;
        let backreferences = select_backreferences_for_page(&*self.0, &note_id).await?;
        Ok((page, backreferences))
    }

    /// Fetch page by title
    ///
    /// The most common use case: the user is navigating by requesting
    /// a page.  The page either exists or it doesn't.  If it
    /// doesn't, we go out and make it.  Since we know it doesn't exist,
    /// we also know no backreferences to it exist, so in that case you
    /// get back two empty vecs.
    pub async fn get_page_by_title(&self, title: &str) -> NoteResult<(Vec<Note>, Vec<Note>)> {
        if title.is_empty() {
            return Err(NoteStoreError::NotFound);
        }

        let page = select_page_by_title(&*self.0, title).await?;
        if page.len() > 0 {
            let note_id = &page[0].id;
            let backreferences = select_backreferences_for_page(&*self.0, &note_id).await?;
            return Ok((page, backreferences));
        }

        // Sanity check!
        let references = build_references(&title);
        if references.len() > 0 {
            return Err(NoteStoreError::InvalidNoteStructure(
                "Titles may not contain nested references.".to_string(),
            ));
        }

        let mut tx = self.0.begin().await?;
        let slug = generate_slug(&mut tx, title).await?;
        let page = create_page(&title, &slug);
        insert_note(&mut tx, &page).await?;
        tx.commit().await?;

        Ok((vec![Note::from(page)], vec![]))
    }

    pub async fn add_note(&self, note: &NewNote, parent_id: &str, location: Option<i64>) -> NoteResult<String> {
        let kind = RelationshipKind::Direct;
        let new_id = self.insert_note(note, parent_id, location, kind).await?;
        Ok(new_id)
    }

    /// Move a note from one location to another.
    pub async fn move_note(
        &self,
        note_id: &str,
        old_parent_id: &str,
        new_parent_id: &str,
        new_location: i64,
    ) -> NoteResult<()> {
        let mut tx = self.0.begin().await?;

        let old_note = select_note_to_note_relationship(&mut tx, &old_parent_id, &note_id).await?;
        let old_note_location = old_note.location;
        let old_note_kind = old_note.kind;

        delete_note_to_note_relationship(&mut tx, &old_parent_id, &note_id).await?;
        close_hole_for_deleted_note_relationship(&mut tx, &old_parent_id, old_note_location).await?;
        let new_location = determine_max_child_location_for_note(&mut tx, &new_parent_id, Some(new_location)).await?;
        make_room_for_new_note_relationship(&mut tx, &new_parent_id, new_location).await?;
        insert_note_to_note_relationship(&mut tx, &new_parent_id, &note_id, new_location, &old_note_kind).await?;
        tx.commit().await?;
        Ok(())
    }

    /// Updates a note's content.  Completely rebuilds the note's
    /// outgoing edge reference list every time.
    pub async fn update_note_content(&self, note_id: &str, content: &str) -> NoteResult<()> {
        let references = build_references(&content);
        let mut tx = self.0.begin().await?;
        update_note_content(&mut tx, &note_id, &content).await?;
        delete_bulk_note_to_page_relationships(&mut tx, &note_id).await?;
        let known_reference_ids = validate_or_generate_all_found_references(&mut tx, &references).await?;
        insert_bulk_note_to_page_relationships(&mut tx, &note_id, &known_reference_ids).await?;
        tx.commit().await?;
        Ok(())
    }

    /// Deletes a note.  If the note's relationship drops to zero, all
    /// references from that note to pages are also deleted.
    pub async fn delete_note(&self, note_id: &str, note_parent_id: &str) -> NoteResult<()> {
        let mut tx = self.0.begin().await?;

        let note_id = note_id.to_string();
        let parent_id = note_parent_id.to_string();

        if parent_id != note_id {
            delete_note_to_note_relationship(&mut tx, &parent_id, &note_id).await?;
        }
        // The big one: if zero parents report having an interest in this note, then it,
        // *and any sub-relationships*, go away.
        if count_existing_note_relationships(&mut tx, &note_id).await? == 0 {
            delete_note_to_page_relationships(&mut tx, &note_id).await?;
            delete_note(&mut tx, &note_id).await?;
        }
        tx.commit().await?;
        Ok(())
    }
}

// The Private stuff

impl NoteStore {
    // Pretty much the most dangerous function in our system. Has to
    // have ALL the error checking.
    async fn insert_note(
        &self,
        note: &NewNote,
        parent_id: &str,
        location: Option<i64>,
        kind: RelationshipKind,
    ) -> NoteResult<String> {
        if let Some(location) = location {
            if location < 0 {
                return Err(NoteStoreError::InvalidNoteStructure(
                    "Add note: A negative location is not valid.".to_string(),
                ));
            }
        }

        if parent_id.is_empty() {
            return Err(NoteStoreError::InvalidNoteStructure(
                "Add note: A parent note ID is required.".to_string(),
            ));
        }

        if note.id.is_empty() {
            return Err(NoteStoreError::InvalidNoteStructure(
                "Add note: Your note should have an id already".to_string(),
            ));
        }

        if note.content.is_empty() {
            return Err(NoteStoreError::InvalidNoteStructure(
                "Add note: Empty notes are not supported.".to_string(),
            ));
        }

        let references = build_references(&note.content);

        let mut tx = self.0.begin().await?;
        let location = determine_max_child_location_for_note(&mut tx, parent_id, location).await?;
        insert_note(&mut tx, &note).await?;
        make_room_for_new_note_relationship(&mut tx, &parent_id, location).await?;
        insert_note_to_note_relationship(&mut tx, &parent_id, &note.id, location, &kind).await?;
        let known_reference_ids = validate_or_generate_all_found_references(&mut tx, &references).await?;
        insert_bulk_note_to_page_relationships(&mut tx, &note.id, &known_reference_ids).await?;
        tx.commit().await?;
        Ok(note.id.to_string())
    }
}