theirongolddev/gitlore
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

refactor: Remove redundant doc comments throughout codebase

Browse Source 
Removes module-level doc comments (//! lines) and excessive inline doc
comments that were duplicating information already evident from:
- Function/struct names (self-documenting code)
- Type signatures (the what is clear from types)
- Implementation context (the how is clear from code)

Affected modules:
- cli/* - Removed command descriptions duplicating clap help text
- core/* - Removed module headers and obvious function docs
- documents/* - Removed extractor/regenerator/truncation docs
- embedding/* - Removed pipeline and chunking docs
- gitlab/* - Removed client and transformer docs (kept type definitions)
- ingestion/* - Removed orchestrator and ingestion docs
- search/* - Removed FTS and vector search docs

Philosophy: Code should be self-documenting. Comments should explain
"why" (business decisions, non-obvious constraints) not "what" (which
the code itself shows). This change reduces noise and maintenance burden
while keeping the codebase just as understandable.

Retains comments for:
- Non-obvious business logic
- Important safety invariants
- Complex algorithm explanations
- Public API boundaries where generated docs matter

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
Taylor Eernisse
2026-02-05 00:04:32 -05:00
parent 976ad92ef0
commit 65583ed5d6
57 changed files with 143 additions and 1693 deletions
Download Patch File Download Diff File Expand all files Collapse all files

21
src/core/backoff.rs
View File

@@ -1,24 +1,10 @@
use rand::Rng;
/// Compute next_attempt_at with exponential backoff and jitter.
///
/// Formula: now + min(3600000, 1000 * 2^attempt_count) * (0.9 to 1.1)
/// - Capped at 1 hour to prevent runaway delays
/// - ±10% jitter prevents synchronized retries after outages
///
/// Used by:
/// - `dirty_sources` retry scheduling (document regeneration failures)
/// - `pending_discussion_fetches` retry scheduling (API fetch failures)
///
/// Having one implementation prevents subtle divergence between queues
/// (e.g., different caps or jitter ranges).
pub fn compute_next_attempt_at(now: i64, attempt_count: i64) -> i64 {
// Cap attempt_count to prevent overflow (2^30 > 1 hour anyway)
let capped_attempts = attempt_count.min(30) as u32;
let base_delay_ms = 1000_i64.saturating_mul(1 << capped_attempts);
let capped_delay_ms = base_delay_ms.min(3_600_000); // 1 hour cap
let capped_delay_ms = base_delay_ms.min(3_600_000);
// Add ±10% jitter
let jitter_factor = rand::thread_rng().gen_range(0.9..=1.1);
let delay_with_jitter = (capped_delay_ms as f64 * jitter_factor) as i64;
@@ -34,7 +20,6 @@ mod tests {
#[test]
fn test_exponential_curve() {
let now = 1_000_000_000_i64;
// Each attempt should roughly double the delay (within jitter)
for attempt in 1..=10 {
let result = compute_next_attempt_at(now, attempt);
let delay = result - now;
@@ -65,7 +50,7 @@ mod tests {
#[test]
fn test_jitter_range() {
let now = 1_000_000_000_i64;
let attempt = 5; // base = 32000
let attempt = 5;
let base = 1000_i64 * (1 << attempt);
let min_delay = (base as f64 * 0.89) as i64;
let max_delay = (base as f64 * 1.11) as i64;
@@ -85,7 +70,6 @@ mod tests {
let now = 1_000_000_000_i64;
let result = compute_next_attempt_at(now, 1);
let delay = result - now;
// attempt 1: base = 2000ms, with jitter: 1800-2200ms
assert!(
(1800..=2200).contains(&delay),
"first retry delay: {delay}ms"
@@ -95,7 +79,6 @@ mod tests {
#[test]
fn test_overflow_safety() {
let now = i64::MAX / 2;
// Should not panic even with very large attempt_count
let result = compute_next_attempt_at(now, i64::MAX);
assert!(result > now);
}

19
src/core/config.rs
View File

@@ -1,7 +1,3 @@
//! Configuration loading and validation.
//!
//! Config schema mirrors the TypeScript version with serde for deserialization.
use serde::Deserialize;
use std::fs;
use std::path::Path;
@@ -9,7 +5,6 @@ use std::path::Path;
use super::error::{LoreError, Result};
use super::paths::get_config_path;
/// GitLab connection settings.
#[derive(Debug, Clone, Deserialize)]
pub struct GitLabConfig {
#[serde(rename = "baseUrl")]
@@ -23,13 +18,11 @@ fn default_token_env_var() -> String {
"GITLAB_TOKEN".to_string()
}
/// Project to sync.
#[derive(Debug, Clone, Deserialize)]
pub struct ProjectConfig {
pub path: String,
}
/// Sync behavior settings.
#[derive(Debug, Clone, Deserialize)]
#[serde(default)]
pub struct SyncConfig {
@@ -77,7 +70,6 @@ impl Default for SyncConfig {
}
}
/// Storage settings.
#[derive(Debug, Clone, Deserialize, Default)]
#[serde(default)]
pub struct StorageConfig {
@@ -98,7 +90,6 @@ fn default_compress_raw_payloads() -> bool {
true
}
/// Embedding provider settings.
#[derive(Debug, Clone, Deserialize)]
#[serde(default)]
pub struct EmbeddingConfig {
@@ -120,19 +111,15 @@ impl Default for EmbeddingConfig {
}
}
/// Logging and observability settings.
#[derive(Debug, Clone, Deserialize)]
#[serde(default)]
pub struct LoggingConfig {
/// Directory for log files. Default: ~/.local/share/lore/logs/
#[serde(rename = "logDir")]
pub log_dir: Option<String>,
/// Days to retain log files. Default: 30. Set to 0 to disable file logging.
#[serde(rename = "retentionDays", default = "default_retention_days")]
pub retention_days: u32,
/// Enable JSON log files. Default: true.
#[serde(rename = "fileLogging", default = "default_file_logging")]
pub file_logging: bool,
}
@@ -155,7 +142,6 @@ impl Default for LoggingConfig {
}
}
/// Main configuration structure.
#[derive(Debug, Clone, Deserialize)]
pub struct Config {
pub gitlab: GitLabConfig,
@@ -175,7 +161,6 @@ pub struct Config {
}
impl Config {
/// Load and validate configuration from file.
pub fn load(cli_override: Option<&str>) -> Result<Self> {
let config_path = get_config_path(cli_override);
@@ -188,7 +173,6 @@ impl Config {
Self::load_from_path(&config_path)
}
/// Load configuration from a specific path.
pub fn load_from_path(path: &Path) -> Result<Self> {
let content = fs::read_to_string(path).map_err(|e| LoreError::ConfigInvalid {
details: format!("Failed to read config file: {e}"),
@@ -199,7 +183,6 @@ impl Config {
details: format!("Invalid JSON: {e}"),
})?;
// Validate required fields
if config.projects.is_empty() {
return Err(LoreError::ConfigInvalid {
details: "At least one project is required".to_string(),
@@ -214,7 +197,6 @@ impl Config {
}
}
// Validate URL format
if url::Url::parse(&config.gitlab.base_url).is_err() {
return Err(LoreError::ConfigInvalid {
details: format!("Invalid GitLab URL: {}", config.gitlab.base_url),
@@ -225,7 +207,6 @@ impl Config {
}
}
/// Minimal config for writing during init (relies on defaults when loaded).
#[derive(Debug, serde::Serialize)]
pub struct MinimalConfig {
pub gitlab: MinimalGitLabConfig,

33
src/core/db.rs
View File

@@ -1,7 +1,3 @@
//! Database connection and migration management.
//!
//! Uses rusqlite with WAL mode for crash safety.
use rusqlite::Connection;
use sqlite_vec::sqlite3_vec_init;
use std::fs;
@@ -10,11 +6,8 @@ use tracing::{debug, info};
use super::error::{LoreError, Result};
/// Latest schema version, derived from the embedded migrations count.
/// Used by the health check to verify databases are up-to-date.
pub const LATEST_SCHEMA_VERSION: i32 = MIGRATIONS.len() as i32;
/// Embedded migrations - compiled into the binary.
const MIGRATIONS: &[(&str, &str)] = &[
("001", include_str!("../../migrations/001_initial.sql")),
("002", include_str!("../../migrations/002_issues.sql")),
@@ -53,9 +46,7 @@ const MIGRATIONS: &[(&str, &str)] = &[
),
];
/// Create a database connection with production-grade pragmas.
pub fn create_connection(db_path: &Path) -> Result<Connection> {
// Register sqlite-vec extension globally (safe to call multiple times)
#[allow(clippy::missing_transmute_annotations)]
unsafe {
rusqlite::ffi::sqlite3_auto_extension(Some(std::mem::transmute(
@@ -63,30 +54,26 @@ pub fn create_connection(db_path: &Path) -> Result<Connection> {
)));
}
// Ensure parent directory exists
if let Some(parent) = db_path.parent() {
fs::create_dir_all(parent)?;
}
let conn = Connection::open(db_path)?;
// Production-grade pragmas for single-user CLI
conn.pragma_update(None, "journal_mode", "WAL")?;
conn.pragma_update(None, "synchronous", "NORMAL")?; // Safe for WAL on local disk
conn.pragma_update(None, "synchronous", "NORMAL")?;
conn.pragma_update(None, "foreign_keys", "ON")?;
conn.pragma_update(None, "busy_timeout", 5000)?; // 5s wait on lock contention
conn.pragma_update(None, "temp_store", "MEMORY")?; // Small speed win
conn.pragma_update(None, "cache_size", -64000)?; // 64MB cache (negative = KB)
conn.pragma_update(None, "mmap_size", 268_435_456)?; // 256MB memory-mapped I/O
conn.pragma_update(None, "busy_timeout", 5000)?;
conn.pragma_update(None, "temp_store", "MEMORY")?;
conn.pragma_update(None, "cache_size", -64000)?;
conn.pragma_update(None, "mmap_size", 268_435_456)?;
debug!(db_path = %db_path.display(), "Database connection created");
Ok(conn)
}
/// Run all pending migrations using embedded SQL.
pub fn run_migrations(conn: &Connection) -> Result<()> {
// Get current schema version
let has_version_table: bool = conn
.query_row(
"SELECT COUNT(*) > 0 FROM sqlite_master WHERE type='table' AND name='schema_version'",
@@ -114,9 +101,6 @@ pub fn run_migrations(conn: &Connection) -> Result<()> {
continue;
}
// Wrap each migration in a transaction to prevent partial application.
// If the migration SQL already contains BEGIN/COMMIT, execute_batch handles
// it, but wrapping in a savepoint ensures atomicity for those that don't.
let savepoint_name = format!("migration_{}", version);
conn.execute_batch(&format!("SAVEPOINT {}", savepoint_name))
.map_err(|e| LoreError::MigrationFailed {
@@ -150,7 +134,6 @@ pub fn run_migrations(conn: &Connection) -> Result<()> {
Ok(())
}
/// Run migrations from filesystem (for testing or custom migrations).
#[allow(dead_code)]
pub fn run_migrations_from_dir(conn: &Connection, migrations_dir: &Path) -> Result<()> {
let has_version_table: bool = conn
@@ -194,8 +177,6 @@ pub fn run_migrations_from_dir(conn: &Connection, migrations_dir: &Path) -> Resu
let sql = fs::read_to_string(entry.path())?;
// Wrap each migration in a savepoint to prevent partial application,
// matching the safety guarantees of run_migrations().
let savepoint_name = format!("migration_{}", version);
conn.execute_batch(&format!("SAVEPOINT {}", savepoint_name))
.map_err(|e| LoreError::MigrationFailed {
@@ -229,8 +210,6 @@ pub fn run_migrations_from_dir(conn: &Connection, migrations_dir: &Path) -> Resu
Ok(())
}
/// Verify database pragmas are set correctly.
/// Used by lore doctor command.
pub fn verify_pragmas(conn: &Connection) -> (bool, Vec<String>) {
let mut issues = Vec::new();
@@ -258,7 +237,6 @@ pub fn verify_pragmas(conn: &Connection) -> (bool, Vec<String>) {
let synchronous: i32 = conn
.pragma_query_value(None, "synchronous", |row| row.get(0))
.unwrap_or(0);
// NORMAL = 1
if synchronous != 1 {
issues.push(format!("synchronous is {synchronous}, expected 1 (NORMAL)"));
}
@@ -266,7 +244,6 @@ pub fn verify_pragmas(conn: &Connection) -> (bool, Vec<String>) {
(issues.is_empty(), issues)
}
/// Get current schema version.
pub fn get_schema_version(conn: &Connection) -> i32 {
let has_version_table: bool = conn
.query_row(

33
src/core/dependent_queue.rs
View File

@@ -1,8 +1,3 @@
//! Generic dependent fetch queue for resource events, MR closes, and MR diffs.
//!
//! Provides enqueue, claim, complete, fail (with exponential backoff), and
//! stale lock reclamation operations against the `pending_dependent_fetches` table.
use std::collections::HashMap;
use rusqlite::Connection;
@@ -10,7 +5,6 @@ use rusqlite::Connection;
use super::error::Result;
use super::time::now_ms;
/// A pending job from the dependent fetch queue.
#[derive(Debug)]
pub struct PendingJob {
pub id: i64,
@@ -23,9 +17,6 @@ pub struct PendingJob {
pub attempts: i32,
}
/// Enqueue a dependent fetch job. Idempotent via UNIQUE constraint (INSERT OR IGNORE).
///
/// Returns `true` if actually inserted (not deduped).
pub fn enqueue_job(
conn: &Connection,
project_id: i64,
@@ -54,10 +45,6 @@ pub fn enqueue_job(
Ok(changes > 0)
}
/// Claim a batch of jobs for processing, scoped to a specific project.
///
/// Atomically selects and locks jobs within a transaction. Only claims jobs
/// where `locked_at IS NULL` and `(next_retry_at IS NULL OR next_retry_at <= now)`.
pub fn claim_jobs(
conn: &Connection,
job_type: &str,
@@ -70,8 +57,6 @@ pub fn claim_jobs(
let now = now_ms();
// Use UPDATE ... RETURNING to atomically select and lock in one statement.
// This eliminates the race between SELECT and UPDATE.
let mut stmt = conn.prepare_cached(
"UPDATE pending_dependent_fetches
SET locked_at = ?1
@@ -109,7 +94,6 @@ pub fn claim_jobs(
Ok(jobs)
}
/// Mark a job as complete (DELETE the row).
pub fn complete_job(conn: &Connection, job_id: i64) -> Result<()> {
conn.execute(
"DELETE FROM pending_dependent_fetches WHERE id = ?1",
@@ -119,17 +103,9 @@ pub fn complete_job(conn: &Connection, job_id: i64) -> Result<()> {
Ok(())
}
/// Mark a job as failed. Increments attempts, sets next_retry_at with exponential
/// backoff, clears locked_at, and records the error.
///
/// Backoff: 30s * 2^(attempts), capped at 480s. Uses a single atomic UPDATE
/// to avoid a read-then-write race on the `attempts` counter.
pub fn fail_job(conn: &Connection, job_id: i64, error: &str) -> Result<()> {
let now = now_ms();
// Atomic increment + backoff calculation in one UPDATE.
// MIN(attempts, 4) caps the shift to prevent overflow; the overall
// backoff is clamped to 480 000 ms via MIN(..., 480000).
let changes = conn.execute(
"UPDATE pending_dependent_fetches
SET attempts = attempts + 1,
@@ -149,9 +125,6 @@ pub fn fail_job(conn: &Connection, job_id: i64, error: &str) -> Result<()> {
Ok(())
}
/// Reclaim stale locks (locked_at older than threshold).
///
/// Returns count of reclaimed jobs.
pub fn reclaim_stale_locks(conn: &Connection, stale_threshold_minutes: u32) -> Result<usize> {
let threshold_ms = now_ms() - (i64::from(stale_threshold_minutes) * 60 * 1000);
@@ -163,7 +136,6 @@ pub fn reclaim_stale_locks(conn: &Connection, stale_threshold_minutes: u32) -> R
Ok(changes)
}
/// Count pending jobs by job_type, optionally scoped to a project.
pub fn count_pending_jobs(
conn: &Connection,
project_id: Option<i64>,
@@ -205,11 +177,6 @@ pub fn count_pending_jobs(
Ok(counts)
}
/// Count jobs that are actually claimable right now, by job_type.
///
/// Only counts jobs where `locked_at IS NULL` and `(next_retry_at IS NULL OR next_retry_at <= now)`,
/// matching the exact WHERE clause used by [`claim_jobs`]. This gives an accurate total
/// for progress bars — unlike [`count_pending_jobs`] which includes locked and backing-off jobs.
pub fn count_claimable_jobs(conn: &Connection, project_id: i64) -> Result<HashMap<String, usize>> {
let now = now_ms();
let mut counts = HashMap::new();

18
src/core/error.rs
View File

@@ -1,11 +1,6 @@
//! Custom error types for gitlore.
//!
//! Uses thiserror for ergonomic error definitions with structured error codes.
use serde::Serialize;
use thiserror::Error;
/// Error codes for programmatic error handling.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum ErrorCode {
ConfigNotFound,
@@ -55,7 +50,6 @@ impl std::fmt::Display for ErrorCode {
}
impl ErrorCode {
/// Get the exit code for this error (for robot mode).
pub fn exit_code(&self) -> i32 {
match self {
Self::InternalError => 1,
@@ -80,7 +74,6 @@ impl ErrorCode {
}
}
/// Main error type for gitlore.
#[derive(Error, Debug)]
pub enum LoreError {
#[error("Config file not found at {path}. Run \"lore init\" first.")]
@@ -163,7 +156,6 @@ pub enum LoreError {
}
impl LoreError {
/// Get the error code for programmatic handling.
pub fn code(&self) -> ErrorCode {
match self {
Self::ConfigNotFound { .. } => ErrorCode::ConfigNotFound,
@@ -190,7 +182,6 @@ impl LoreError {
}
}
/// Get a suggestion for how to fix this error, including inline examples.
pub fn suggestion(&self) -> Option<&'static str> {
match self {
Self::ConfigNotFound { .. } => Some(
@@ -240,21 +231,14 @@ impl LoreError {
}
}
/// Whether this error represents a permanent API failure that should not be retried.
///
/// Only 404 (not found) is truly permanent: the resource doesn't exist and never will.
/// 403 and auth errors are NOT permanent — they may be environmental (VPN down,
/// token rotation, temporary restrictions) and should be retried with backoff.
pub fn is_permanent_api_error(&self) -> bool {
matches!(self, Self::GitLabNotFound { .. })
}
/// Get the exit code for this error.
pub fn exit_code(&self) -> i32 {
self.code().exit_code()
}
/// Convert to robot-mode JSON error output.
pub fn to_robot_error(&self) -> RobotError {
RobotError {
code: self.code().to_string(),
@@ -264,7 +248,6 @@ impl LoreError {
}
}
/// Structured error for robot mode JSON output.
#[derive(Debug, Serialize)]
pub struct RobotError {
pub code: String,
@@ -273,7 +256,6 @@ pub struct RobotError {
pub suggestion: Option<String>,
}
/// Wrapper for robot mode error output.
#[derive(Debug, Serialize)]
pub struct RobotErrorOutput {
pub error: RobotError,

17
src/core/events_db.rs
View File

@@ -1,15 +1,9 @@
//! Database upsert functions for resource events (state, label, milestone).
use rusqlite::Connection;
use super::error::{LoreError, Result};
use super::time::iso_to_ms_strict;
use crate::gitlab::types::{GitLabLabelEvent, GitLabMilestoneEvent, GitLabStateEvent};
/// Upsert state events for an entity.
///
/// Uses INSERT OR REPLACE keyed on UNIQUE(gitlab_id, project_id).
/// Caller is responsible for wrapping in a transaction if atomicity is needed.
pub fn upsert_state_events(
conn: &Connection,
project_id: i64,
@@ -52,8 +46,6 @@ pub fn upsert_state_events(
Ok(count)
}
/// Upsert label events for an entity.
/// Caller is responsible for wrapping in a transaction if atomicity is needed.
pub fn upsert_label_events(
conn: &Connection,
project_id: i64,
@@ -93,8 +85,6 @@ pub fn upsert_label_events(
Ok(count)
}
/// Upsert milestone events for an entity.
/// Caller is responsible for wrapping in a transaction if atomicity is needed.
pub fn upsert_milestone_events(
conn: &Connection,
project_id: i64,
@@ -135,8 +125,6 @@ pub fn upsert_milestone_events(
Ok(count)
}
/// Resolve entity type string to (issue_id, merge_request_id) pair.
/// Exactly one is Some, the other is None.
fn resolve_entity_ids(
entity_type: &str,
entity_local_id: i64,
@@ -150,11 +138,9 @@ fn resolve_entity_ids(
}
}
/// Count resource events by type for the count command.
pub fn count_events(conn: &Connection) -> Result<EventCounts> {
let mut counts = EventCounts::default();
// State events
let row: (i64, i64) = conn
.query_row(
"SELECT
@@ -168,7 +154,6 @@ pub fn count_events(conn: &Connection) -> Result<EventCounts> {
counts.state_issue = row.0 as usize;
counts.state_mr = row.1 as usize;
// Label events
let row: (i64, i64) = conn
.query_row(
"SELECT
@@ -182,7 +167,6 @@ pub fn count_events(conn: &Connection) -> Result<EventCounts> {
counts.label_issue = row.0 as usize;
counts.label_mr = row.1 as usize;
// Milestone events
let row: (i64, i64) = conn
.query_row(
"SELECT
@@ -199,7 +183,6 @@ pub fn count_events(conn: &Connection) -> Result<EventCounts> {
Ok(counts)
}
/// Event counts broken down by type and entity.
#[derive(Debug, Default)]
pub struct EventCounts {
pub state_issue: usize,

32
src/core/lock.rs
View File

@@ -1,7 +1,3 @@
//! Crash-safe single-flight lock using heartbeat pattern.
//!
//! Prevents concurrent sync operations and allows recovery from crashed processes.
use rusqlite::{Connection, TransactionBehavior};
use std::path::PathBuf;
use std::sync::Arc;
@@ -15,17 +11,14 @@ use super::db::create_connection;
use super::error::{LoreError, Result};
use super::time::{ms_to_iso, now_ms};
/// Maximum consecutive heartbeat failures before signaling error.
const MAX_HEARTBEAT_FAILURES: u32 = 3;
/// Lock configuration options.
pub struct LockOptions {
pub name: String,
pub stale_lock_minutes: u32,
pub heartbeat_interval_seconds: u32,
}
/// App lock with heartbeat for crash recovery.
pub struct AppLock {
conn: Connection,
db_path: PathBuf,
@@ -40,7 +33,6 @@ pub struct AppLock {
}
impl AppLock {
/// Create a new app lock instance.
pub fn new(conn: Connection, options: LockOptions) -> Self {
let db_path = conn.path().map(PathBuf::from).unwrap_or_default();
@@ -58,23 +50,17 @@ impl AppLock {
}
}
/// Check if heartbeat has failed (indicates lock may be compromised).
pub fn is_heartbeat_healthy(&self) -> bool {
!self.heartbeat_failed.load(Ordering::SeqCst)
}
/// Attempt to acquire the lock atomically.
///
/// Returns Ok(true) if lock acquired, Err if lock is held by another active process.
pub fn acquire(&mut self, force: bool) -> Result<bool> {
let now = now_ms();
// Use IMMEDIATE transaction to prevent race conditions
let tx = self
.conn
.transaction_with_behavior(TransactionBehavior::Immediate)?;
// Check for existing lock within the transaction
let existing: Option<(String, i64, i64)> = tx
.query_row(
"SELECT owner, acquired_at, heartbeat_at FROM app_locks WHERE name = ?",
@@ -85,7 +71,6 @@ impl AppLock {
match existing {
None => {
// No lock exists, acquire it
tx.execute(
"INSERT INTO app_locks (name, owner, acquired_at, heartbeat_at) VALUES (?, ?, ?, ?)",
(&self.name, &self.owner, now, now),
@@ -96,7 +81,6 @@ impl AppLock {
let is_stale = now - heartbeat_at > self.stale_lock_ms;
if is_stale || force {
// Lock is stale or force override, take it
tx.execute(
"UPDATE app_locks SET owner = ?, acquired_at = ?, heartbeat_at = ? WHERE name = ?",
(&self.owner, now, now, &self.name),
@@ -108,13 +92,11 @@ impl AppLock {
"Lock acquired (override)"
);
} else if existing_owner == self.owner {
// Re-entrant, update heartbeat
tx.execute(
"UPDATE app_locks SET heartbeat_at = ? WHERE name = ?",
(now, &self.name),
)?;
} else {
// Lock held by another active process - rollback and return error
drop(tx);
return Err(LoreError::DatabaseLocked {
owner: existing_owner,
@@ -124,20 +106,17 @@ impl AppLock {
}
}
// Commit the transaction atomically
tx.commit()?;
self.start_heartbeat();
Ok(true)
}
/// Release the lock.
pub fn release(&mut self) {
if self.released.swap(true, Ordering::SeqCst) {
return; // Already released
return;
}
// Stop heartbeat thread
if let Some(handle) = self.heartbeat_handle.take() {
let _ = handle.join();
}
@@ -150,7 +129,6 @@ impl AppLock {
info!(owner = %self.owner, "Lock released");
}
/// Start the heartbeat thread to keep the lock alive.
fn start_heartbeat(&mut self) {
let name = self.name.clone();
let owner = self.owner.clone();
@@ -161,11 +139,10 @@ impl AppLock {
let db_path = self.db_path.clone();
if db_path.as_os_str().is_empty() {
return; // In-memory database, skip heartbeat
return;
}
self.heartbeat_handle = Some(thread::spawn(move || {
// Open a new connection with proper pragmas
let conn = match create_connection(&db_path) {
Ok(c) => c,
Err(e) => {
@@ -175,11 +152,9 @@ impl AppLock {
}
};
// Poll frequently for early exit, but only update heartbeat at full interval
const POLL_INTERVAL: Duration = Duration::from_millis(100);
loop {
// Sleep in small increments, checking released flag frequently
let mut elapsed = Duration::ZERO;
while elapsed < interval {
thread::sleep(POLL_INTERVAL);
@@ -189,7 +164,6 @@ impl AppLock {
}
}
// Check once more after full interval elapsed
if released.load(Ordering::SeqCst) {
break;
}
@@ -203,12 +177,10 @@ impl AppLock {
match result {
Ok(rows_affected) => {
if rows_affected == 0 {
// Lock was stolen or deleted
warn!(owner = %owner, "Heartbeat failed: lock no longer held");
heartbeat_failed.store(true, Ordering::SeqCst);
break;
}
// Reset failure count on success
failure_count.store(0, Ordering::SeqCst);
debug!(owner = %owner, "Heartbeat updated");
}

38
src/core/logging.rs
View File

@@ -1,29 +1,13 @@
//! Logging infrastructure: dual-layer subscriber setup and log file retention.
//!
//! Provides a layered tracing subscriber with:
//! - **stderr layer**: Human-readable or JSON format, controlled by `-v` flags
//! - **file layer**: Always-on JSON output to daily-rotated log files
use std::fs;
use std::path::Path;
use tracing_subscriber::EnvFilter;
/// Build an `EnvFilter` from the verbosity count.
///
/// | Count | App Level | Dep Level |
/// |-------|-----------|-----------|
/// | 0 | INFO | WARN |
/// | 1 | DEBUG | WARN |
/// | 2 | DEBUG | INFO |
/// | 3+ | TRACE | DEBUG |
pub fn build_stderr_filter(verbose: u8, quiet: bool) -> EnvFilter {
// RUST_LOG always wins if set
if std::env::var("RUST_LOG").is_ok() {
return EnvFilter::from_default_env();
}
// -q overrides -v for stderr
if quiet {
return EnvFilter::new("lore=warn,error");
}
@@ -38,10 +22,6 @@ pub fn build_stderr_filter(verbose: u8, quiet: bool) -> EnvFilter {
EnvFilter::new(directives)
}
/// Build an `EnvFilter` for the file layer.
///
/// Always captures DEBUG+ for `lore::*` and WARN+ for dependencies,
/// unless `RUST_LOG` is set (which overrides everything).
pub fn build_file_filter() -> EnvFilter {
if std::env::var("RUST_LOG").is_ok() {
return EnvFilter::from_default_env();
@@ -50,10 +30,6 @@ pub fn build_file_filter() -> EnvFilter {
EnvFilter::new("lore=debug,warn")
}
/// Delete log files older than `retention_days` from the given directory.
///
/// Only deletes files matching the `lore.YYYY-MM-DD.log` pattern.
/// Returns the number of files deleted.
pub fn cleanup_old_logs(log_dir: &Path, retention_days: u32) -> usize {
if retention_days == 0 || !log_dir.exists() {
return 0;
@@ -72,7 +48,6 @@ pub fn cleanup_old_logs(log_dir: &Path, retention_days: u32) -> usize {
let file_name = entry.file_name();
let name = file_name.to_string_lossy();
// Match pattern: lore.YYYY-MM-DD.log or lore.YYYY-MM-DD (tracing-appender format)
if let Some(date_str) = extract_log_date(&name)
&& date_str < cutoff_date
&& fs::remove_file(entry.path()).is_ok()
@@ -84,28 +59,20 @@ pub fn cleanup_old_logs(log_dir: &Path, retention_days: u32) -> usize {
deleted
}
/// Extract the date portion from a log filename.
///
/// Matches: `lore.YYYY-MM-DD.log` or `lore.YYYY-MM-DD`
fn extract_log_date(filename: &str) -> Option<String> {
let rest = filename.strip_prefix("lore.")?;
// Must have at least YYYY-MM-DD (10 ASCII chars).
// Use get() to avoid panicking on non-ASCII filenames.
let date_part = rest.get(..10)?;
// Validate it looks like a date
let parts: Vec<&str> = date_part.split('-').collect();
if parts.len() != 3 || parts[0].len() != 4 || parts[1].len() != 2 || parts[2].len() != 2 {
return None;
}
// Check all parts are numeric (also ensures ASCII)
if !parts.iter().all(|p| p.chars().all(|c| c.is_ascii_digit())) {
return None;
}
// After the date, must be end-of-string or ".log"
let suffix = rest.get(10..)?;
if suffix.is_empty() || suffix == ".log" {
Some(date_part.to_string())
@@ -153,16 +120,13 @@ mod tests {
fn test_cleanup_old_logs_deletes_old_files() {
let dir = TempDir::new().unwrap();
// Create old log files (well before any reasonable retention)
File::create(dir.path().join("lore.2020-01-01.log")).unwrap();
File::create(dir.path().join("lore.2020-01-15.log")).unwrap();
// Create a recent log file (today)
let today = chrono::Utc::now().format("%Y-%m-%d").to_string();
let recent_name = format!("lore.{today}.log");
File::create(dir.path().join(&recent_name)).unwrap();
// Create a non-log file that should NOT be deleted
File::create(dir.path().join("other.txt")).unwrap();
let deleted = cleanup_old_logs(dir.path(), 7);
@@ -192,7 +156,6 @@ mod tests {
#[test]
fn test_build_stderr_filter_default() {
// Can't easily assert filter contents, but verify it doesn't panic
let _filter = build_stderr_filter(0, false);
}
@@ -206,7 +169,6 @@ mod tests {
#[test]
fn test_build_stderr_filter_quiet_overrides_verbose() {
// Quiet should win over verbose
let _filter = build_stderr_filter(3, true);
}

53
src/core/metrics.rs
View File

@@ -1,9 +1,3 @@
//! Performance metrics types and tracing layer for sync pipeline observability.
//!
//! Provides:
//! - [`StageTiming`]: Serializable timing/counter data for pipeline stages
//! - [`MetricsLayer`]: Custom tracing subscriber layer that captures span timing
use std::collections::HashMap;
use std::sync::{Arc, Mutex};
use std::time::Instant;
@@ -14,16 +8,10 @@ use tracing::span::{Attributes, Id, Record};
use tracing_subscriber::layer::{Context, Layer};
use tracing_subscriber::registry::LookupSpan;
/// Returns true when value is zero (for serde `skip_serializing_if`).
fn is_zero(v: &usize) -> bool {
*v == 0
}
/// Timing and counter data for a single pipeline stage.
///
/// Supports nested sub-stages for hierarchical timing breakdowns.
/// Fields with zero/empty values are omitted from JSON output to
/// keep robot-mode payloads compact.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct StageTiming {
pub name: String,
@@ -43,11 +31,6 @@ pub struct StageTiming {
pub sub_stages: Vec<StageTiming>,
}
// ============================================================================
// MetricsLayer: custom tracing subscriber layer
// ============================================================================
/// Internal data tracked per open span.
struct SpanData {
name: String,
parent_id: Option<u64>,
@@ -57,19 +40,12 @@ struct SpanData {
retries: usize,
}
/// Completed span data with its original ID and parent ID.
struct CompletedSpan {
id: u64,
parent_id: Option<u64>,
timing: StageTiming,
}
/// Custom tracing layer that captures span timing and structured fields.
///
/// Collects data from `#[instrument]` spans and materializes it into
/// a `Vec<StageTiming>` tree via [`extract_timings`].
///
/// Thread-safe via `Arc<Mutex<>>` — suitable for concurrent span operations.
#[derive(Debug, Clone)]
pub struct MetricsLayer {
spans: Arc<Mutex<HashMap<u64, SpanData>>>,
@@ -90,45 +66,34 @@ impl MetricsLayer {
}
}
/// Extract timing tree for a completed run.
///
/// Returns the top-level stages with sub-stages nested.
/// Call after the root span closes.
pub fn extract_timings(&self) -> Vec<StageTiming> {
let completed = self.completed.lock().unwrap_or_else(|e| e.into_inner());
if completed.is_empty() {
return Vec::new();
}
// Build children map: parent_id -> Vec<StageTiming>
let mut children_map: HashMap<u64, Vec<StageTiming>> = HashMap::new();
let mut roots = Vec::new();
let mut id_to_timing: HashMap<u64, StageTiming> = HashMap::new();
// First pass: collect all timings by ID
for entry in completed.iter() {
id_to_timing.insert(entry.id, entry.timing.clone());
}
// Second pass: process in reverse order (children close before parents)
// to build the tree bottom-up
for entry in completed.iter() {
// Attach any children that were collected for this span
if let Some(timing) = id_to_timing.get_mut(&entry.id)
&& let Some(children) = children_map.remove(&entry.id)
{
timing.sub_stages = children;
}
if let Some(parent_id) = entry.parent_id {
// This is a child span — attach to parent's children
if let Some(timing) = id_to_timing.remove(&entry.id) {
children_map.entry(parent_id).or_default().push(timing);
}
if let Some(parent_id) = entry.parent_id
&& let Some(timing) = id_to_timing.remove(&entry.id)
{
children_map.entry(parent_id).or_default().push(timing);
}
}
// Remaining entries in id_to_timing are roots
for entry in completed.iter() {
if entry.parent_id.is_none()
&& let Some(mut timing) = id_to_timing.remove(&entry.id)
@@ -144,7 +109,6 @@ impl MetricsLayer {
}
}
/// Visitor that extracts field values from span attributes.
struct FieldVisitor<'a>(&'a mut HashMap<String, serde_json::Value>);
impl tracing::field::Visit for FieldVisitor<'_> {
@@ -182,7 +146,6 @@ impl tracing::field::Visit for FieldVisitor<'_> {
}
}
/// Visitor that extracts event fields for rate-limit/retry detection.
#[derive(Default)]
struct EventVisitor {
status_code: Option<u64>,
@@ -248,7 +211,6 @@ where
}
fn on_event(&self, event: &tracing::Event<'_>, ctx: Context<'_, S>) {
// Count rate-limit and retry events on the current span
if let Some(span_ref) = ctx.event_span(event) {
let id = span_ref.id();
if let Some(data) = self
@@ -317,7 +279,6 @@ where
}
}
// Manual Debug impl since SpanData and CompletedSpan don't derive Debug
impl std::fmt::Debug for SpanData {
fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
f.debug_struct("SpanData")
@@ -376,7 +337,6 @@ mod tests {
assert_eq!(json["rate_limit_hits"], 2);
assert_eq!(json["retries"], 5);
// Sub-stage present
let sub = &json["sub_stages"][0];
assert_eq!(sub["name"], "ingest_issues");
assert_eq!(sub["project"], "group/repo");
@@ -400,7 +360,6 @@ mod tests {
let json = serde_json::to_value(&timing).unwrap();
let obj = json.as_object().unwrap();
// Zero fields must be absent
assert!(!obj.contains_key("items_skipped"));
assert!(!obj.contains_key("errors"));
assert!(!obj.contains_key("rate_limit_hits"));
@@ -408,7 +367,6 @@ mod tests {
assert!(!obj.contains_key("sub_stages"));
assert!(!obj.contains_key("project"));
// Required fields always present
assert!(obj.contains_key("name"));
assert!(obj.contains_key("elapsed_ms"));
assert!(obj.contains_key("items_processed"));
@@ -539,13 +497,12 @@ mod tests {
tracing::subscriber::with_default(subscriber, || {
let span = tracing::info_span!("test_stage");
let _guard = span.enter();
// Simulate work
});
let timings = metrics.extract_timings();
assert_eq!(timings.len(), 1);
assert_eq!(timings[0].name, "test_stage");
assert!(timings[0].elapsed_ms < 100); // Should be near-instant
assert!(timings[0].elapsed_ms < 100);
}
#[test]

29
src/core/paths.rs
View File

@@ -1,50 +1,31 @@
//! XDG-compliant path resolution for config and data directories.
use std::path::PathBuf;
/// Get the path to the config file.
///
/// Resolution order:
/// 1. CLI flag override (if provided)
/// 2. LORE_CONFIG_PATH environment variable
/// 3. XDG default (~/.config/lore/config.json)
/// 4. Local fallback (./lore.config.json) if exists
/// 5. Returns XDG default even if not exists
pub fn get_config_path(cli_override: Option<&str>) -> PathBuf {
// 1. CLI flag override
if let Some(path) = cli_override {
return PathBuf::from(path);
}
// 2. Environment variable
if let Ok(path) = std::env::var("LORE_CONFIG_PATH") {
return PathBuf::from(path);
}
// 3. XDG default
let xdg_path = get_xdg_config_dir().join("lore").join("config.json");
if xdg_path.exists() {
return xdg_path;
}
// 4. Local fallback (for development)
let local_path = PathBuf::from("lore.config.json");
if local_path.exists() {
return local_path;
}
// 5. Return XDG path (will trigger not-found error if missing)
xdg_path
}
/// Get the data directory path.
/// Uses XDG_DATA_HOME or defaults to ~/.local/share/lore
pub fn get_data_dir() -> PathBuf {
get_xdg_data_dir().join("lore")
}
/// Get the database file path.
/// Uses config override if provided, otherwise uses default in data dir.
pub fn get_db_path(config_override: Option<&str>) -> PathBuf {
if let Some(path) = config_override {
return PathBuf::from(path);
@@ -52,8 +33,6 @@ pub fn get_db_path(config_override: Option<&str>) -> PathBuf {
get_data_dir().join("lore.db")
}
/// Get the log directory path.
/// Uses config override if provided, otherwise uses default in data dir.
pub fn get_log_dir(config_override: Option<&str>) -> PathBuf {
if let Some(path) = config_override {
return PathBuf::from(path);
@@ -61,8 +40,6 @@ pub fn get_log_dir(config_override: Option<&str>) -> PathBuf {
get_data_dir().join("logs")
}
/// Get the backup directory path.
/// Uses config override if provided, otherwise uses default in data dir.
pub fn get_backup_dir(config_override: Option<&str>) -> PathBuf {
if let Some(path) = config_override {
return PathBuf::from(path);
@@ -70,7 +47,6 @@ pub fn get_backup_dir(config_override: Option<&str>) -> PathBuf {
get_data_dir().join("backups")
}
/// Get XDG config directory, falling back to ~/.config
fn get_xdg_config_dir() -> PathBuf {
std::env::var("XDG_CONFIG_HOME")
.map(PathBuf::from)
@@ -81,7 +57,6 @@ fn get_xdg_config_dir() -> PathBuf {
})
}
/// Get XDG data directory, falling back to ~/.local/share
fn get_xdg_data_dir() -> PathBuf {
std::env::var("XDG_DATA_HOME")
.map(PathBuf::from)
@@ -102,8 +77,4 @@ mod tests {
let path = get_config_path(Some("/custom/path.json"));
assert_eq!(path, PathBuf::from("/custom/path.json"));
}
// Note: env var tests removed - mutating process-global env vars
// in parallel tests is unsafe in Rust 2024. The env var code path
// is trivial (std::env::var) and doesn't warrant the complexity.
}

20
src/core/payloads.rs
View File

@@ -1,5 +1,3 @@
//! Raw payload storage with optional compression and deduplication.
use flate2::Compression;
use flate2::read::GzDecoder;
use flate2::write::GzEncoder;
@@ -10,26 +8,21 @@ use std::io::{Read, Write};
use super::error::Result;
use super::time::now_ms;
/// Options for storing a payload.
pub struct StorePayloadOptions<'a> {
pub project_id: Option<i64>,
pub resource_type: &'a str, // 'project' | 'issue' | 'mr' | 'note' | 'discussion'
pub gitlab_id: &'a str, // TEXT because discussion IDs are strings
pub resource_type: &'a str,
pub gitlab_id: &'a str,
pub json_bytes: &'a [u8],
pub compress: bool,
}
/// Store a raw API payload with optional compression and deduplication.
/// Returns the row ID (either new or existing if duplicate).
pub fn store_payload(conn: &Connection, options: StorePayloadOptions) -> Result<i64> {
let json_bytes = options.json_bytes;
// 2. SHA-256 hash the JSON bytes (pre-compression)
let mut hasher = Sha256::new();
hasher.update(json_bytes);
let payload_hash = format!("{:x}", hasher.finalize());
// 3. Check for duplicate by (project_id, resource_type, gitlab_id, payload_hash)
let existing: Option<i64> = conn
.query_row(
"SELECT id FROM raw_payloads
@@ -44,12 +37,10 @@ pub fn store_payload(conn: &Connection, options: StorePayloadOptions) -> Result<
)
.ok();
// 4. If duplicate, return existing ID
if let Some(id) = existing {
return Ok(id);
}
// 5. Compress if requested
let (encoding, payload_bytes): (&str, std::borrow::Cow<'_, [u8]>) = if options.compress {
let mut encoder = GzEncoder::new(Vec::new(), Compression::default());
encoder.write_all(json_bytes)?;
@@ -58,7 +49,6 @@ pub fn store_payload(conn: &Connection, options: StorePayloadOptions) -> Result<
("identity", std::borrow::Cow::Borrowed(json_bytes))
};
// 6. INSERT with content_encoding
conn.execute(
"INSERT INTO raw_payloads
(source, project_id, resource_type, gitlab_id, fetched_at, content_encoding, payload_hash, payload)
@@ -77,8 +67,6 @@ pub fn store_payload(conn: &Connection, options: StorePayloadOptions) -> Result<
Ok(conn.last_insert_rowid())
}
/// Read a raw payload by ID, decompressing if necessary.
/// Returns None if not found.
pub fn read_payload(conn: &Connection, id: i64) -> Result<Option<serde_json::Value>> {
let row: Option<(String, Vec<u8>)> = conn
.query_row(
@@ -92,7 +80,6 @@ pub fn read_payload(conn: &Connection, id: i64) -> Result<Option<serde_json::Val
return Ok(None);
};
// Decompress if needed
let json_bytes = if encoding == "gzip" {
let mut decoder = GzDecoder::new(&payload_bytes[..]);
let mut decompressed = Vec::new();
@@ -117,7 +104,6 @@ mod tests {
let db_path = dir.path().join("test.db");
let conn = create_connection(&db_path).unwrap();
// Create minimal schema for testing
conn.execute_batch(
"CREATE TABLE raw_payloads (
id INTEGER PRIMARY KEY,
@@ -212,6 +198,6 @@ mod tests {
)
.unwrap();
assert_eq!(id1, id2); // Same payload returns same ID
assert_eq!(id1, id2);
}
}

14
src/core/project.rs
View File

@@ -2,14 +2,7 @@ use rusqlite::Connection;
use super::error::{LoreError, Result};
/// Resolve a project string to a project_id using cascading match:
/// 1. Exact match on path_with_namespace
/// 2. Case-insensitive exact match
/// 3. Suffix match (e.g., "auth-service" matches "group/auth-service") — only if unambiguous
/// 4. Substring match (e.g., "typescript" matches "vs/typescript-code") — only if unambiguous
/// 5. Error with available projects list
pub fn resolve_project(conn: &Connection, project_str: &str) -> Result<i64> {
// Step 1: Exact match
let exact = conn.query_row(
"SELECT id FROM projects WHERE path_with_namespace = ?1",
rusqlite::params![project_str],
@@ -19,7 +12,6 @@ pub fn resolve_project(conn: &Connection, project_str: &str) -> Result<i64> {
return Ok(id);
}
// Step 2: Case-insensitive exact match
let ci = conn.query_row(
"SELECT id FROM projects WHERE LOWER(path_with_namespace) = LOWER(?1)",
rusqlite::params![project_str],
@@ -29,7 +21,6 @@ pub fn resolve_project(conn: &Connection, project_str: &str) -> Result<i64> {
return Ok(id);
}
// Step 3: Suffix match (unambiguous)
let mut suffix_stmt = conn.prepare(
"SELECT id, path_with_namespace FROM projects
WHERE path_with_namespace LIKE '%/' || ?1
@@ -59,7 +50,6 @@ pub fn resolve_project(conn: &Connection, project_str: &str) -> Result<i64> {
_ => {}
}
// Step 4: Case-insensitive substring match (unambiguous)
let mut substr_stmt = conn.prepare(
"SELECT id, path_with_namespace FROM projects
WHERE LOWER(path_with_namespace) LIKE '%' || LOWER(?1) || '%'",
@@ -88,7 +78,6 @@ pub fn resolve_project(conn: &Connection, project_str: &str) -> Result<i64> {
_ => {}
}
// Step 5: No match — list available projects
let mut all_stmt =
conn.prepare("SELECT path_with_namespace FROM projects ORDER BY path_with_namespace")?;
let all_projects: Vec<String> = all_stmt
@@ -211,7 +200,6 @@ mod tests {
let conn = setup_db();
insert_project(&conn, 1, "vs/python-code");
insert_project(&conn, 2, "vs/typescript-code");
// "code" matches both projects
let err = resolve_project(&conn, "code").unwrap_err();
let msg = err.to_string();
assert!(
@@ -225,11 +213,9 @@ mod tests {
#[test]
fn test_suffix_preferred_over_substring() {
// Suffix match (step 3) should resolve before substring (step 4)
let conn = setup_db();
insert_project(&conn, 1, "backend/auth-service");
insert_project(&conn, 2, "backend/auth-service-v2");
// "auth-service" is an exact suffix of project 1
let id = resolve_project(&conn, "auth-service").unwrap();
assert_eq!(id, 1);
}

14
src/core/sync_run.rs
View File

@@ -1,25 +1,14 @@
//! Sync run lifecycle recorder.
//!
//! Encapsulates the INSERT-on-start, UPDATE-on-finish lifecycle for the
//! `sync_runs` table, enabling sync history tracking and observability.
use rusqlite::Connection;
use super::error::Result;
use super::metrics::StageTiming;
use super::time::now_ms;
/// Records a single sync run's lifecycle in the `sync_runs` table.
///
/// Created via [`start`](Self::start), then finalized with either
/// [`succeed`](Self::succeed) or [`fail`](Self::fail). Both finalizers
/// consume `self` to enforce single-use at compile time.
pub struct SyncRunRecorder {
row_id: i64,
}
impl SyncRunRecorder {
/// Insert a new `sync_runs` row with `status='running'`.
pub fn start(conn: &Connection, command: &str, run_id: &str) -> Result<Self> {
let now = now_ms();
conn.execute(
@@ -31,7 +20,6 @@ impl SyncRunRecorder {
Ok(Self { row_id })
}
/// Mark run as succeeded with full metrics.
pub fn succeed(
self,
conn: &Connection,
@@ -57,7 +45,6 @@ impl SyncRunRecorder {
Ok(())
}
/// Mark run as failed with error message and optional partial metrics.
pub fn fail(
self,
conn: &Connection,
@@ -158,7 +145,6 @@ mod tests {
assert_eq!(total_items, 50);
assert_eq!(total_errors, 2);
// Verify metrics_json is parseable
let parsed: Vec<StageTiming> = serde_json::from_str(&metrics_json.unwrap()).unwrap();
assert_eq!(parsed.len(), 1);
assert_eq!(parsed[0].name, "ingest");

26
src/core/time.rs
View File

@@ -1,39 +1,24 @@
//! Time utilities for consistent timestamp handling.
//!
//! All database *_at columns use milliseconds since epoch for consistency.
use chrono::{DateTime, Utc};
/// Convert GitLab API ISO 8601 timestamp to milliseconds since epoch.
pub fn iso_to_ms(iso_string: &str) -> Option<i64> {
DateTime::parse_from_rfc3339(iso_string)
.ok()
.map(|dt| dt.timestamp_millis())
}
/// Convert milliseconds since epoch to ISO 8601 string.
pub fn ms_to_iso(ms: i64) -> String {
DateTime::from_timestamp_millis(ms)
.map(|dt| dt.to_rfc3339())
.unwrap_or_else(|| "Invalid timestamp".to_string())
}
/// Get current time in milliseconds since epoch.
pub fn now_ms() -> i64 {
Utc::now().timestamp_millis()
}
/// Parse a relative time string (7d, 2w, 1m) or ISO date into ms epoch.
///
/// Returns the timestamp as of which to filter (cutoff point).
/// - `7d` = 7 days ago
/// - `2w` = 2 weeks ago
/// - `1m` = 1 month ago (30 days)
/// - `2024-01-15` = midnight UTC on that date
pub fn parse_since(input: &str) -> Option<i64> {
let input = input.trim();
// Try relative format: Nd, Nw, Nm
if let Some(num_str) = input.strip_suffix('d') {
let days: i64 = num_str.parse().ok()?;
return Some(now_ms() - (days * 24 * 60 * 60 * 1000));
@@ -49,25 +34,20 @@ pub fn parse_since(input: &str) -> Option<i64> {
return Some(now_ms() - (months * 30 * 24 * 60 * 60 * 1000));
}
// Try ISO date: YYYY-MM-DD
if input.len() == 10 && input.chars().filter(|&c| c == '-').count() == 2 {
let iso_full = format!("{input}T00:00:00Z");
return iso_to_ms(&iso_full);
}
// Try full ISO 8601
iso_to_ms(input)
}
/// Convert ISO 8601 timestamp to milliseconds with strict error handling.
/// Returns Err with a descriptive message if the timestamp is invalid.
pub fn iso_to_ms_strict(iso_string: &str) -> Result<i64, String> {
DateTime::parse_from_rfc3339(iso_string)
.map(|dt| dt.timestamp_millis())
.map_err(|_| format!("Invalid timestamp: {}", iso_string))
}
/// Convert optional ISO 8601 timestamp to optional milliseconds (strict).
pub fn iso_to_ms_opt_strict(iso_string: &Option<String>) -> Result<Option<i64>, String> {
match iso_string {
Some(s) => iso_to_ms_strict(s).map(Some),
@@ -75,7 +55,6 @@ pub fn iso_to_ms_opt_strict(iso_string: &Option<String>) -> Result<Option<i64>,
}
}
/// Format milliseconds epoch to human-readable full datetime.
pub fn format_full_datetime(ms: i64) -> String {
DateTime::from_timestamp_millis(ms)
.map(|dt| dt.format("%Y-%m-%d %H:%M UTC").to_string())
@@ -101,7 +80,7 @@ mod tests {
#[test]
fn test_now_ms() {
let now = now_ms();
assert!(now > 1700000000000); // After 2023
assert!(now > 1700000000000);
}
#[test]
@@ -109,7 +88,7 @@ mod tests {
let now = now_ms();
let seven_days = parse_since("7d").unwrap();
let expected = now - (7 * 24 * 60 * 60 * 1000);
assert!((seven_days - expected).abs() < 1000); // Within 1 second
assert!((seven_days - expected).abs() < 1000);
}
#[test]
@@ -132,7 +111,6 @@ mod tests {
fn test_parse_since_iso_date() {
let ms = parse_since("2024-01-15").unwrap();
assert!(ms > 0);
// Should be midnight UTC on that date
let expected = iso_to_ms("2024-01-15T00:00:00Z").unwrap();
assert_eq!(ms, expected);
}