Linkleaf

Manage protobuf-only Linkleaf feeds (linkleaf.v1)

A tiny library for storing, updating, and querying a personal link feed backed by a compact Protocol Buffers file. It gives you ergonomic helpers to:

• Add or update links (upsert) and keep them newest-first
• List links with optional tag and date filters
• Read and write feeds from disk (atomic write, best-effort)
• Parse tags from a comma-separated string

It’s built on prost (for protobuf).

Data model

// Generated by prost (simplified):
pub struct Link {
    pub id: String,            // UUID v4 (string)
    pub title: String,
    pub url: String,
    pub date: String,          // "YYYY-MM-DD HH:MM:SS" (local time)
    pub summary: String,
    pub tags: Vec<String>,     // normalized via parse_tags
    pub via: String,           // attribution/source
}

pub struct Feed {
    pub version: i32,          // currently initialized to 1 on new feeds
    pub links: Vec<Link>,      // newest-first
    // (other fields like `title` may exist; not required by the helpers)
}

Feed and Link Schemas

Defined in feed.proto:

• Link

  • id (string) — auto-derived if omitted
  • title (string, required)
  • url (string, required)
  • date (string, YYYY-MM-DD)
  • summary (optional string)
  • tags (optional repeated strings)
  • via (optional string)

• Feed

  • title (string)
  • version (uint32)
  • links (repeated Link, newest first)

Examples

# run the minimal flow
cargo run --example quickstart

# upsert by id (moves updated link to front)
cargo run --example upsert_by_id

# upsert by URL when id=None
cargo run --example upsert_by_url

# tag & date filtering
cargo run --example filter

Design notes

• Timestamps are stored as local time strings ("YYYY-MM-DD HH:MM:SS"). Filtering compares the date component only.
• Ordering is newest-first (index 0). Inserts and updates are re-inserted at the front.
• Concurrency: writes are not lock-guarded; concurrent writers can race. Add a lock if multiple processes may write at once.

TODO

• add function -> accepts tags as Vec instead of Option
• add tag next release
• use git-cliff