Function add 

pub fn add<P, S, T>(
    file: P,
    title: S,
    url: S,
    summary: Option<Summary>,
    tags: T,
    via: Option<Via>,
    id: Option<Uuid>,
) -> Result<Link>
where
    P: AsRef<Path>,
    S: Into<String>,
    T: IntoIterator<Item = S>,

Add or update a link in a protobuf feed file, then persist the feed.

Behavior

• Reads the feed at file. If it doesn’t exist, a new feed is initialized (version = 1).
• If an id is provided:
  • Updates the existing link with that id if found (title, url, summary, tags, via), sets its date to today (local datetime, YYYY-MM-DD HH:MM:SS), and moves it to the front (newest-first).
  • Otherwise inserts a new link at the front with that explicit id.
• If no id is provided:
  • Updates the first link whose url matches; sets date to today and moves it to the front.
  • Otherwise inserts a new link at the front with a freshly generated UUID v4 id.

Persists the entire feed by calling write_feed, which writes atomically via a temporary file and rename.

Arguments

• file: Path to the .pb feed file to update/create.
• title: Human-readable title for the link.
• url: Target URL for the link.
• summary: Optional blurb/notes (None -> empty string).
• tags: Zero or more tags as an iterator of strings (e.g., ["rust", "async", "tokio"]).
• via: Optional source/attribution (None -> empty string).
• id: Optional stable identifier. If present, performs an upsert by id.

Returns

The newly created or updated Link.

Ordering

Links are kept newest-first; both inserts and updates end up at index 0.

Errors

• Propagates any error from read_feed (except “not found”, which initializes a new feed).
• Propagates any error from write_feed.
• No inter-process locking is performed; concurrent writers may race.

Example

use std::path::PathBuf;
use linkleaf_core::*;
use linkleaf_core::linkleaf_proto::Summary;
use uuid::Uuid;

let file = PathBuf::from("mylinks.pb");

// Create a new link
let a = add(
    file.clone(),
    "Tokio - Asynchronous Rust",
    "https://tokio.rs/",
    None,
    ["rust", "async", "tokio"],
    None,
    None, // no id -> create (may update if URL already exists)
)?;

// Update the same link by id (upsert)
let _id = Uuid::parse_str(&a.id)?;
let a2 = add(
    file.clone(),
    "Tokio • Async Rust",
    "https://tokio.rs/",
    Some(Summary::new("A runtime for reliable async apps")),
    [],                 // no tags change
    None,
    Some(_id),          // provide id -> update or insert with that id
)?;

assert_eq!(a2.id, a.id);
Ok::<(), anyhow::Error>(())
// After update, the item is at the front (index 0).

Notes

• Providing an id gives the item a stable identity; updates by id will also update the stored url to the new value you pass.
• date is always set to “today” in local time on both create and update.