Skip to content

Your Android phone and your Windows PC, working as one. Local-first, end-to-end encrypted, no account.

15.0 KB
Raw Blame
// SPDX-License-Identifier: MPL-2.0
//! Local timeline of items shared between paired devices: files and folders,
//! clipboard items (linked by ID without duplicating content), links opened,
//! saved photos, voice recordings, and mirroring / webcam sessions.

use nectarlink_protocol::DeviceId;
use serde::{Deserialize, Serialize};

/// Default retention window in days (90 days).
pub const DEFAULT_TIMELINE_MAX_DAYS: u32 = 90;
/// Default maximum number of entries kept in the local timeline (5,000).
pub const DEFAULT_TIMELINE_MAX_ENTRIES: u32 = 5_000;
/// Default page size when querying the timeline.
pub const DEFAULT_TIMELINE_PAGE_LIMIT: u32 = 100;
/// Maximum page size allowed in a single query.
pub const MAX_TIMELINE_PAGE_LIMIT: u32 = 250;

/// What kind of item a timeline entry represents.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "lowercase")]
pub enum TimelineKind {
    /// One or more files or a folder transferred either way.
    File,
    /// A synced text or image clip (linked by `ref_id` to `ClipboardHistoryStore`;
    /// its content is never duplicated in SQLite).
    Clip,
    /// A web link opened on the other device or received from it.
    Link,
    /// One or more photos or videos saved from a paired phone.
    Photo,
    /// A voice recording sent from a phone to a PC.
    Recording,
    /// A screen/app mirroring or webcam session (recorded on start, updated
    /// with `duration_secs` when the stream ends).
    Session,
}

impl TimelineKind {
    pub fn as_str(self) -> &'static str {
        match self {
            TimelineKind::File => "file",
            TimelineKind::Clip => "clip",
            TimelineKind::Link => "link",
            TimelineKind::Photo => "photo",
            TimelineKind::Recording => "recording",
            TimelineKind::Session => "session",
        }
    }

    pub fn from_str_opt(s: &str) -> Option<TimelineKind> {
        match s.trim().to_ascii_lowercase().as_str() {
            "file" | "files" | "folder" => Some(TimelineKind::File),
            "clip" | "clips" | "clipboard" => Some(TimelineKind::Clip),
            "link" | "links" => Some(TimelineKind::Link),
            "photo" | "photos" => Some(TimelineKind::Photo),
            "recording" | "recordings" => Some(TimelineKind::Recording),
            "session" | "sessions" | "mirror" | "webcam" => Some(TimelineKind::Session),
            _ => None,
        }
    }
}

/// Retention policy for the local timeline.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct TimelineRetention {
    /// Auto-purge entries older than `max_days` days (`0` disables age limit).
    pub max_days: u32,
    /// Auto-purge oldest entries beyond `max_entries` (`0` disables count cap).
    pub max_entries: u32,
}

impl Default for TimelineRetention {
    fn default() -> Self {
        TimelineRetention { max_days: DEFAULT_TIMELINE_MAX_DAYS, max_entries: DEFAULT_TIMELINE_MAX_ENTRIES }
    }
}

/// Search, kind, device, and pagination parameters for querying the timeline.
#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct TimelineQuery {
    /// Filter to a single kind (`None` returns all kinds).
    pub kind: Option<TimelineKind>,
    /// Filter to a single peer device (`None` returns all devices).
    pub device: Option<DeviceId>,
    /// Case-insensitive substring search across title, detail, device name,
    /// and linked clipboard text.
    pub search: Option<String>,
    /// Number of newest matching rows to skip.
    pub offset: u32,
    /// Maximum rows to return (clamped to `1..=MAX_TIMELINE_PAGE_LIMIT`).
    pub limit: u32,
}

/// One row in the local timeline.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct TimelineEntry {
    /// Monotonic SQLite row ID.
    pub id: i64,
    /// Kind of activity.
    pub kind: TimelineKind,
    /// The paired device involved.
    pub device_id: DeviceId,
    /// Display name of the paired device.
    pub device_name: String,
    /// `true` if received from `device_id`; `false` if sent/started from here.
    pub incoming: bool,
    /// Unix timestamp in seconds when the item occurred (or started, for sessions).
    pub timestamp: i64,
    /// Primary title (file/folder name, URL, photo name, recording name, or
    /// session name). For `Clip`, this is empty in SQLite and populated at
    /// query time from `ClipboardHistoryStore`.
    pub title: String,
    /// Secondary detail (e.g. `"Folder · 4 files"`, `"text"` / `"image"`, host,
    /// resolution, or marker count).
    pub detail: String,
    /// Local path(s) (newline-separated when multiple) or URL for links.
    pub target: String,
    /// Total byte size for files, photos, and recordings (`0` otherwise).
    pub size_bytes: u64,
    /// Duration in seconds for mirroring/webcam sessions (`0` while active or N/A).
    pub duration_secs: u64,
    /// Reference ID linking to `ClipboardHistoryStore` (for clips) or `Transfer.id`
    /// (for files, photos, and recordings).
    pub ref_id: Option<String>,
    /// For `Clip` entries: whether the referenced clip is still present in
    /// `ClipboardHistoryStore`.
    pub clip_available: bool,
    /// For image `Clip` entries: a `data:image/png;base64,...` preview resolved
    /// from `ClipboardHistoryStore` at query time (never stored in SQLite).
    #[serde(skip_serializing_if = "Option::is_none")]
    pub image_data_url: Option<String>,
}

/// A single page of timeline query results.
#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct TimelinePage {
    /// Entries in this page, newest first.
    pub entries: Vec<TimelineEntry>,
    /// Total number of entries matching the filter across all pages.
    pub total: u32,
    /// Whether additional older entries exist beyond `offset + entries.len()`.
    pub has_more: bool,
}

/// Parameters for inserting a new timeline row into SQLite.
#[derive(Debug, Clone)]
pub(crate) struct NewTimelineEntry {
    pub kind: TimelineKind,
    pub device_id: DeviceId,
    pub device_name: String,
    pub incoming: bool,
    pub timestamp: i64,
    pub title: String,
    pub detail: String,
    pub target: String,
    pub size_bytes: u64,
    pub duration_secs: u64,
    pub ref_id: Option<String>,
}

/// Encodes `(mime, bytes)` as a `data:<mime>;base64,...` URI for image clip previews.
pub(crate) fn encode_data_url(mime: &str, bytes: &[u8]) -> String {
    const TABLE: &[u8; 64] = b"ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/";
    let mut out = String::with_capacity(6 + mime.len() + 8 + bytes.len().div_ceil(3) * 4);
    out.push_str("data:");
    out.push_str(mime);
    out.push_str(";base64,");
    let (chunks, rem) = bytes.as_chunks::<3>();
    for &[b0, b1, b2] in chunks {
        let n = (u32::from(b0) << 16) | (u32::from(b1) << 8) | u32::from(b2);
        out.push(TABLE[((n >> 18) & 0x3F) as usize] as char);
        out.push(TABLE[((n >> 12) & 0x3F) as usize] as char);
        out.push(TABLE[((n >> 6) & 0x3F) as usize] as char);
        out.push(TABLE[(n & 0x3F) as usize] as char);
    }
    if rem.len() == 1 {
        let n = u32::from(rem[0]) << 16;
        out.push(TABLE[((n >> 18) & 0x3F) as usize] as char);
        out.push(TABLE[((n >> 12) & 0x3F) as usize] as char);
        out.push('=');
        out.push('=');
    } else if rem.len() == 2 {
        let n = (u32::from(rem[0]) << 16) | (u32::from(rem[1]) << 8);
        out.push(TABLE[((n >> 18) & 0x3F) as usize] as char);
        out.push(TABLE[((n >> 12) & 0x3F) as usize] as char);
        out.push(TABLE[((n >> 6) & 0x3F) as usize] as char);
        out.push('=');
    }
    out
}

/// Formats a clipboard text string for display in the Timeline UI:
/// - Local file paths (including `"C:\..."` quoted paths from Explorer's "Copy as path")
///   return `("Copied <filename>", Some(unquoted_path))`.
/// - Web/geo URLs (`http://`, `https://`, `geo:`) return `("Link · <domain>", Some(raw_url))`.
/// - Long or multi-line text returns `("Copied text: <first words>", Some(raw_first_line))`.
#[must_use]
pub fn format_clip_display(raw_text: &str) -> (String, Option<String>) {
    let first_line =
        raw_text.lines().map(str::trim).find(|l| !l.is_empty()).unwrap_or_else(|| raw_text.trim());
    let unquoted = first_line
        .strip_prefix('"')
        .map(|s| s.strip_suffix('"').unwrap_or(s))
        .or_else(|| first_line.strip_prefix('\'').map(|s| s.strip_suffix('\'').unwrap_or(s)))
        .unwrap_or(first_line)
        .trim();

    // Up to 8 characters: `geo:0,0` is shorter than that.
    let lower_prefix: String = unquoted.chars().take(8).collect::<String>().to_ascii_lowercase();
    if (lower_prefix.starts_with("http://")
        || lower_prefix.starts_with("https://")
        || lower_prefix.starts_with("geo:"))
        && !unquoted.contains(char::is_whitespace)
    {
        if lower_prefix.starts_with("geo:") {
            let (title, raw) = crate::handoff::timeline_link_title_and_detail(unquoted, None);
            return (title, Some(raw));
        }
        let host = unquoted
            .split("://")
            .nth(1)
            .unwrap_or(unquoted)
            .split(['/', '?', '#'])
            .next()
            .unwrap_or(unquoted);
        let clean_host = host.strip_prefix("www.").unwrap_or(host);
        if !clean_host.is_empty() {
            return (format!("Link · {clean_host}"), Some(unquoted.to_owned()));
        }
    }

    let bytes = unquoted.as_bytes();
    let is_win_drive = bytes.len() >= 3
        && bytes[0].is_ascii_alphabetic()
        && bytes[1] == b':'
        && (bytes[2] == b'\\' || bytes[2] == b'/');
    let is_unc = unquoted.starts_with("\\\\") && unquoted.len() > 3;
    let is_unix_path = (unquoted.starts_with('/') && !unquoted.starts_with("//") && unquoted.len() > 2)
        || unquoted.starts_with("~/");
    if is_win_drive || is_unc || is_unix_path {
        let cleaned = unquoted.trim_end_matches(['\\', '/']);
        if let Some(name) = cleaned.rsplit(['\\', '/']).find(|seg| !seg.is_empty())
            && !name.ends_with(':')
        {
            return (format!("Copied file {name}"), Some(unquoted.to_owned()));
        }
    }

    let collapsed: String = unquoted.split_whitespace().collect::<Vec<_>>().join(" ");
    if collapsed.chars().count() > 44 {
        let mut snippet = String::new();
        for word in collapsed.split_whitespace() {
            if !snippet.is_empty() && snippet.chars().count() + 1 + word.chars().count() > 38 {
                break;
            }
            if !snippet.is_empty() {
                snippet.push(' ');
            }
            snippet.push_str(word);
        }
        if snippet.is_empty() {
            snippet = collapsed.chars().take(38).collect();
        }
        return (format!("Copied text: {snippet}…"), Some(collapsed));
    }

    (collapsed, None)
}

/// What a [`TimelineKind::Session`] entry was. Its `title` is English for
/// whoever reads the store directly; an app shows its own words for these.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum SessionKind {
    /// A phone's screen, mirrored on this device.
    PhoneScreen,
    /// One of a phone's apps in a window of its own (its mirroring session).
    AppWindow(u32),
    /// This device's screen, shared with a phone.
    PcScreen,
    /// A phone's camera used as a webcam.
    Webcam,
    /// A phone's microphone used on this device.
    Microphone,
}

/// The title the core gives an app window's session entry.
const APP_WINDOW_TITLE: &str = "App window #";

impl TimelineEntry {
    /// What this entry was, if it is a session; from what the core recorded
    /// (`target` and the direction), so it holds for entries made before
    /// this existed too.
    #[must_use]
    pub fn session_kind(&self) -> Option<SessionKind> {
        if self.kind != TimelineKind::Session {
            return None;
        }
        match self.target.as_str() {
            "webcam" => Some(SessionKind::Webcam),
            "mic" => Some(SessionKind::Microphone),
            "mirror" if !self.incoming => Some(SessionKind::PcScreen),
            "mirror" => Some(
                self.title
                    .strip_prefix(APP_WINDOW_TITLE)
                    .and_then(|n| n.parse().ok())
                    .map_or(SessionKind::PhoneScreen, SessionKind::AppWindow),
            ),
            _ => None,
        }
    }
}

#[cfg(test)]
mod tests {
    #[test]
    fn sessions_say_what_they_were_whatever_their_title() {
        use super::{SessionKind, TimelineEntry, TimelineKind};
        let entry = |kind, incoming, title: &str, target: &str| TimelineEntry {
            id: 1,
            kind,
            device_id: nectarlink_protocol::DeviceId([1; 32]),
            device_name: "Pixel".into(),
            incoming,
            timestamp: 0,
            title: title.into(),
            detail: String::new(),
            target: target.into(),
            size_bytes: 0,
            duration_secs: 0,
            ref_id: None,
            clip_available: false,
            image_data_url: None,
        };
        let session =
            |incoming, title, target| entry(TimelineKind::Session, incoming, title, target).session_kind();
        assert_eq!(session(true, "Phone webcam", "webcam"), Some(SessionKind::Webcam));
        assert_eq!(session(false, "Phone microphone", "mic"), Some(SessionKind::Microphone));
        assert_eq!(session(true, "Screen mirroring", "mirror"), Some(SessionKind::PhoneScreen));
        assert_eq!(session(false, "Screen mirroring", "mirror"), Some(SessionKind::PcScreen));
        assert_eq!(session(true, "App window #3", "mirror"), Some(SessionKind::AppWindow(3)));
        // The title isn't what decides.
        assert_eq!(session(true, "Bildschirm", "webcam"), Some(SessionKind::Webcam));
        assert_eq!(session(true, "Something", "other"), None);
        assert_eq!(entry(TimelineKind::File, true, "Phone webcam", "webcam").session_kind(), None);
    }

    use super::*;

    #[test]
    fn formats_quoted_paths_urls_and_text_for_timeline() {
        let (t1, d1) = format_clip_display("\"C:\\Users\\Alice\\Videos\\Sample Clip.mp4\"");
        assert_eq!(t1, "Copied file Sample Clip.mp4");
        assert_eq!(d1.as_deref(), Some("C:\\Users\\Alice\\Videos\\Sample Clip.mp4"));

        let (t2, d2) = format_clip_display("https://example.com/posts/12345");
        assert_eq!(t2, "Link · example.com");
        assert_eq!(d2.as_deref(), Some("https://example.com/posts/12345"));

        let (geo_title, geo_raw) = format_clip_display("geo:0,0");
        assert_eq!(geo_raw.as_deref(), Some("geo:0,0"), "a short map link is still a link: {geo_title}");
        let (t3, d3) = format_clip_display("Short note");
        assert_eq!(t3, "Short note");
        assert_eq!(d3, None);

        let long_note =
            "This is a much longer copied paragraph that should be truncated cleanly with a colon";
        let (t4, d4) = format_clip_display(long_note);
        assert!(t4.starts_with("Copied text: "), "expected colon prefix, got {t4}");
        assert_eq!(d4.as_deref(), Some(long_note));
    }
}