thegeneralist01/archivr
1
Fork 0
mirror of https://github.com/thegeneralist01/archivr synced 2026-07-22 03:05:32 +02:00
Code Issues Activity

feat: add db and multi-archive web UI foundation (#8)

Browse source 
* Add SQLite metadata database support

* Implement archive metadata database

* chore: let's guess cargoHash because there's something wrong with nixpkgs!

* Gate test-only database helpers behind cfg(test)

* Fix archive database row identity

* Use serde for archive metadata JSON

* Finalize archive runs at command level

* Handle archive command errors without panics

* Cover tweet entry metadata recording

* Document static regex invariants

* docs: add web UI design spec

* docs: add web UI implementation plan

* chore: move cli into workspace crate

* chore: track workspace crates directory

* refactor: extract archive core crate

* refactor: add core archive opening APIs

* refactor: rename taxonomy model to tags

* feat: add archive query APIs

* feat: add web server registry

* feat: expose archive server APIs

* feat: add archive table web UI

* fix: complete web UI smoke path

* docs: add architecture mental model

* docs: remove private superpowers plans

* nix: split cli and server packages

* chore: remove PLAN.md
This commit is contained in:
TheGeneralist 2026-06-14 00:27:16 +02:00 • committed by GitHub
parent cc380ec5ba
commit b56c969624
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
25 changed files with 3928 additions and 171 deletions
Download patch file Download diff file Expand all files Collapse all files

438
crates/archivr-core/src/archive.rs Normal file
View file

@ -0,0 +1,438 @@
use anyhow::{Context, Result, bail};
use rusqlite::OptionalExtension;
use std::{
env, fs,
path::{Path, PathBuf},
};
use crate::database;
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct ArchivePaths {
pub archive_path: PathBuf,
pub store_path: PathBuf,
pub name: String,
}
#[derive(Debug, Clone, PartialEq, Eq, serde::Serialize)]
pub struct EntrySummary {
pub entry_uid: String,
pub archived_at: String,
pub source_kind: String,
pub entity_kind: String,
pub title: Option<String>,
pub visibility: String,
pub original_url: Option<String>,
pub artifact_count: i64,
pub total_artifact_bytes: i64,
}
#[derive(Debug, Clone, PartialEq, Eq, serde::Serialize)]
pub struct EntryDetail {
pub summary: EntrySummary,
pub structured_root_relpath: String,
pub source_metadata_json: String,
pub display_metadata_json: Option<String>,
pub artifacts: Vec<EntryArtifactSummary>,
}
#[derive(Debug, Clone, PartialEq, Eq, serde::Serialize)]
pub struct EntryArtifactSummary {
pub artifact_role: String,
pub storage_area: String,
pub relpath: String,
pub byte_size: Option<i64>,
}
#[derive(Debug, Clone, PartialEq, Eq, serde::Serialize)]
pub struct RunSummary {
pub run_uid: String,
pub started_at: String,
pub finished_at: Option<String>,
pub status: String,
pub requested_count: i64,
pub discovered_count: i64,
pub completed_count: i64,
pub failed_count: i64,
pub error_summary: Option<String>,
}
pub fn find_archive_path_from(start: &Path) -> Result<Option<PathBuf>> {
let mut dir = start.to_path_buf();
loop {
let candidate = dir.join(".archivr");
if candidate.is_dir() {
return Ok(Some(candidate));
}
if !dir.pop() {
return Ok(None);
}
}
}
pub fn find_archive_path() -> Result<Option<PathBuf>> {
let cwd = env::current_dir().context("failed to read current working directory")?;
find_archive_path_from(&cwd)
}
pub fn read_archive_paths(archive_path: &Path) -> Result<ArchivePaths> {
if !archive_path.is_dir() {
bail!("archive path does not exist: {}", archive_path.display());
}
let name = fs::read_to_string(archive_path.join("name"))
.with_context(|| format!("failed to read archive name in {}", archive_path.display()))?
.trim()
.to_string();
let store_path = fs::read_to_string(archive_path.join("store_path"))
.with_context(|| format!("failed to read store path in {}", archive_path.display()))?;
Ok(ArchivePaths {
archive_path: archive_path.to_path_buf(),
store_path: PathBuf::from(store_path.trim()),
name,
})
}
pub fn initialize_archive(
archive_parent: &Path,
store_path: &Path,
archive_name: &str,
force_with_info_removal: bool,
) -> Result<ArchivePaths> {
let archive_path = archive_parent.join(".archivr");
if archive_path.exists() {
if !archive_path.is_dir() {
bail!(
"Archive path exists and is not a directory: {}",
archive_path.display()
);
}
if force_with_info_removal {
fs::remove_dir_all(&archive_path)?;
} else if fs::read_dir(&archive_path)?.next().is_some() {
bail!(
"Archive already exists at {} and is not empty. Use --force-with-info-removal to reinitialize.",
archive_path.display()
);
}
}
if store_path.exists() && !force_with_info_removal {
bail!("Store path already exists at {}", store_path.display());
}
fs::create_dir_all(&archive_path)?;
fs::create_dir_all(store_path)?;
fs::write(archive_path.join("name"), archive_name)?;
let canonical_store_path = store_path
.canonicalize()
.with_context(|| format!("failed to canonicalize {}", store_path.display()))?;
fs::write(
archive_path.join("store_path"),
canonical_store_path
.to_str()
.context("store path is not valid UTF-8")?,
)?;
initialize_store_directories(&canonical_store_path)?;
let conn = database::open_or_initialize(&archive_path)?;
let _ = database::ensure_default_user(&conn)?;
Ok(ArchivePaths {
archive_path,
store_path: canonical_store_path,
name: archive_name.to_string(),
})
}
pub fn initialize_store_directories(store_path: &Path) -> Result<()> {
fs::create_dir_all(store_path.join("raw"))?;
fs::create_dir_all(store_path.join("raw_tweets"))?;
fs::create_dir_all(store_path.join("structured"))?;
fs::create_dir_all(store_path.join("temp"))?;
Ok(())
}
pub fn list_root_entries(conn: &rusqlite::Connection) -> Result<Vec<EntrySummary>> {
let mut stmt = conn.prepare(
"SELECT
e.entry_uid,
e.archived_at,
e.source_kind,
e.entity_kind,
e.title,
e.visibility,
si.canonical_url,
COUNT(ea.id) AS artifact_count,
COALESCE(SUM(b.byte_size), 0) AS total_artifact_bytes
FROM archived_entries e
JOIN source_identities si ON si.id = e.source_identity_id
LEFT JOIN entry_artifacts ea ON ea.entry_id = e.id
LEFT JOIN blobs b ON b.id = ea.blob_id
WHERE e.parent_entry_id IS NULL
GROUP BY e.id
ORDER BY e.archived_at DESC, e.id DESC",
)?;
let entries = stmt
.query_map([], |row| {
Ok(EntrySummary {
entry_uid: row.get(0)?,
archived_at: row.get(1)?,
source_kind: row.get(2)?,
entity_kind: row.get(3)?,
title: row.get(4)?,
visibility: row.get(5)?,
original_url: row.get(6)?,
artifact_count: row.get(7)?,
total_artifact_bytes: row.get(8)?,
})
})?
.collect::<rusqlite::Result<Vec<_>>>()?;
Ok(entries)
}
pub fn get_entry_detail(
conn: &rusqlite::Connection,
entry_uid: &str,
) -> Result<Option<EntryDetail>> {
let Some((entry_id, structured_root_relpath, source_metadata_json, display_metadata_json)) =
conn.query_row(
"SELECT id, structured_root_relpath, source_metadata_json, display_metadata_json
FROM archived_entries
WHERE entry_uid = ?1",
[entry_uid],
|row| {
Ok((
row.get::<_, i64>(0)?,
row.get::<_, String>(1)?,
row.get::<_, String>(2)?,
row.get::<_, Option<String>>(3)?,
))
},
)
.optional()?
else {
return Ok(None);
};
let summary = list_root_entries(conn)?
.into_iter()
.find(|entry| entry.entry_uid == entry_uid)
.context("entry disappeared while loading detail")?;
let mut stmt = conn.prepare(
"SELECT ea.artifact_role, ea.storage_area, ea.relpath, b.byte_size
FROM entry_artifacts ea
LEFT JOIN blobs b ON b.id = ea.blob_id
WHERE ea.entry_id = ?1
ORDER BY ea.id ASC",
)?;
let artifacts = stmt
.query_map([entry_id], |row| {
Ok(EntryArtifactSummary {
artifact_role: row.get(0)?,
storage_area: row.get(1)?,
relpath: row.get(2)?,
byte_size: row.get(3)?,
})
})?
.collect::<rusqlite::Result<Vec<_>>>()?;
Ok(Some(EntryDetail {
summary,
structured_root_relpath,
source_metadata_json,
display_metadata_json,
artifacts,
}))
}
pub fn list_runs(conn: &rusqlite::Connection) -> Result<Vec<RunSummary>> {
let mut stmt = conn.prepare(
"SELECT run_uid, started_at, finished_at, status, requested_count,
discovered_count, completed_count, failed_count, error_summary
FROM archive_runs
ORDER BY started_at DESC, id DESC",
)?;
let runs = stmt
.query_map([], |row| {
Ok(RunSummary {
run_uid: row.get(0)?,
started_at: row.get(1)?,
finished_at: row.get(2)?,
status: row.get(3)?,
requested_count: row.get(4)?,
discovered_count: row.get(5)?,
completed_count: row.get(6)?,
failed_count: row.get(7)?,
error_summary: row.get(8)?,
})
})?
.collect::<rusqlite::Result<Vec<_>>>()?;
Ok(runs)
}
#[cfg(test)]
mod tests {
use super::*;
use std::time::{SystemTime, UNIX_EPOCH};
fn unique_path(prefix: &str) -> PathBuf {
let nanos = SystemTime::now()
.duration_since(UNIX_EPOCH)
.unwrap()
.as_nanos();
env::temp_dir().join(format!("{prefix}-{nanos}-{}", std::process::id()))
}
#[test]
fn find_archive_path_walks_up_to_dot_archivr() {
let root = unique_path("archivr-core-find");
let nested = root.join("a").join("b");
fs::create_dir_all(root.join(".archivr")).unwrap();
fs::create_dir_all(&nested).unwrap();
let found = find_archive_path_from(&nested).unwrap().unwrap();
assert_eq!(found, root.join(".archivr"));
let _ = fs::remove_dir_all(root);
}
#[test]
fn read_archive_paths_returns_name_and_store_path() {
let root = unique_path("archivr-core-open");
let archive_path = root.join(".archivr");
let store_path = root.join("store");
fs::create_dir_all(&archive_path).unwrap();
fs::create_dir_all(&store_path).unwrap();
fs::write(archive_path.join("name"), "Personal").unwrap();
fs::write(
archive_path.join("store_path"),
store_path.display().to_string(),
)
.unwrap();
let paths = read_archive_paths(&archive_path).unwrap();
assert_eq!(paths.archive_path, archive_path);
assert_eq!(paths.store_path, store_path);
assert_eq!(paths.name, "Personal");
let _ = fs::remove_dir_all(root);
}
#[test]
fn initialize_archive_creates_database_store_and_metadata() {
let root = unique_path("archivr-core-init");
let archive_parent = root.join("archive");
let store_path = root.join("store");
let paths = initialize_archive(&archive_parent, &store_path, "Personal", false).unwrap();
assert_eq!(paths.archive_path, archive_parent.join(".archivr"));
assert!(
paths
.archive_path
.join(database::DATABASE_FILE_NAME)
.is_file()
);
assert!(paths.store_path.join("raw").is_dir());
assert!(paths.store_path.join("raw_tweets").is_dir());
assert!(paths.store_path.join("structured").is_dir());
assert!(paths.store_path.join("temp").is_dir());
let _ = fs::remove_dir_all(root);
}
#[test]
fn list_root_entries_returns_entry_details_and_runs() {
let conn = rusqlite::Connection::open_in_memory().unwrap();
database::initialize_schema(&conn).unwrap();
let user_id = database::ensure_default_user(&conn).unwrap();
let run = database::create_archive_run(&conn, user_id, 1).unwrap();
let item = database::create_archive_run_item(
&conn,
run.id,
None,
0,
"https://example.com/saved",
Some("https://example.com/saved"),
"web",
"page",
)
.unwrap();
let source_identity_id = database::upsert_source_identity(
&conn,
"web",
"page",
Some("saved-article"),
Some("https://example.com/saved"),
"https://example.com/saved",
)
.unwrap();
let entry = database::create_archived_entry(
&conn,
&database::NewEntry {
source_identity_id,
archive_run_id: run.id,
parent_entry_id: None,
root_entry_id: None,
created_by_user_id: user_id,
owned_by_user_id: user_id,
source_kind: "web".to_string(),
entity_kind: "page".to_string(),
title: Some("Saved Article".to_string()),
visibility: "private".to_string(),
representation_kind: "html".to_string(),
source_metadata_json: r#"{"source":"test"}"#.to_string(),
display_metadata_json: Some(r#"{"reading_time":"4m"}"#.to_string()),
},
)
.unwrap();
let blob_id = database::upsert_blob(
&conn,
&database::BlobRecord {
sha256: "abc123".to_string(),
byte_size: 123,
mime_type: Some("text/html".to_string()),
extension: Some("html".to_string()),
raw_relpath: "raw/a/b/abc123.html".to_string(),
},
)
.unwrap();
database::add_entry_artifact(
&conn,
&database::NewArtifact {
entry_id: entry.id,
artifact_role: "primary_media".to_string(),
storage_area: "raw".to_string(),
relpath: "raw/a/b/abc123.html".to_string(),
blob_id: Some(blob_id),
logical_path: None,
metadata_json: None,
},
)
.unwrap();
database::complete_archive_run_item(&conn, item.id, entry.id).unwrap();
database::finish_archive_run(&conn, run.id).unwrap();
let entries = list_root_entries(&conn).unwrap();
assert_eq!(entries.len(), 1);
assert_eq!(entries[0].title.as_deref(), Some("Saved Article"));
assert_eq!(entries[0].artifact_count, 1);
let detail = get_entry_detail(&conn, &entries[0].entry_uid)
.unwrap()
.unwrap();
assert_eq!(detail.artifacts.len(), 1);
assert_eq!(detail.artifacts[0].artifact_role, "primary_media");
let runs = list_runs(&conn).unwrap();
assert_eq!(runs.len(), 1);
assert_eq!(runs[0].status, "completed");
}
}

1000
crates/archivr-core/src/database.rs Normal file
View file

File diff suppressed because it is too large Load diff

28
crates/archivr-core/src/downloader/local.rs Normal file
View file

@ -0,0 +1,28 @@
use anyhow::{Context, Result, bail};
use std::{path::Path, process::Command};
use crate::hash::hash_file;
pub fn save(path: String, store_path: &Path, timestamp: &String) -> Result<String> {
println!("Saving path: {path}");
let temp_dir = store_path.join("temp").join(timestamp);
std::fs::create_dir_all(&temp_dir)?;
let in_file = Path::new(path.trim_start_matches("file://"));
let extension = in_file
.extension()
.map_or(String::new(), |ext| format!(".{}", ext.to_string_lossy()));
let out_file = temp_dir.join(format!("{timestamp}{extension}"));
let mut binding = Command::new("cp");
let cmd = binding.arg(in_file).arg(&out_file);
let out = cmd.output().with_context(|| "failed to spawn cp process")?;
if !out.status.success() {
let stderr = String::from_utf8_lossy(&out.stderr);
bail!("yt-dlp failed: {stderr}");
}
hash_file(&out_file)
}

4
crates/archivr-core/src/downloader/mod.rs Normal file
View file

@ -0,0 +1,4 @@
pub mod local;
pub mod store;
pub mod tweets;
pub mod ytdlp;

75
crates/archivr-core/src/downloader/store.rs Normal file
View file

@ -0,0 +1,75 @@
use anyhow::{Context, Result};
use std::{
fs,
path::{Path, PathBuf},
};
use crate::hash::hash_file;
/// Moves `file` into the content-addressed raw store under `store_path`.
///
/// The destination path is derived from the file's SHA-256 hash:
/// `raw/<first-char>/<second-char>/<hash><ext>`. If the destination already
/// exists the source file is removed (deduplication); otherwise it is renamed.
/// Returns the store-relative destination path.
pub fn archive_staged_file(file: &Path, store_path: &Path) -> Result<PathBuf> {
let hash = hash_file(file)?;
let destination = raw_relative_path(file, &hash)?;
let absolute_destination = store_path.join(&destination);
if let Some(parent) = absolute_destination.parent() {
fs::create_dir_all(parent)?;
}
if absolute_destination.exists() {
fs::remove_file(file)?;
} else {
fs::rename(file, &absolute_destination)?;
}
Ok(destination)
}
/// Computes the store-relative path for a file given its `hash`.
/// The layout is `raw/<c1>/<c2>/<hash><ext>` where `c1`/`c2` are the first
/// two characters of the hash, providing a two-level Trie.
fn raw_relative_path(file: &Path, hash: &str) -> Result<PathBuf> {
let mut chars = hash.chars();
let first_letter = chars.next().context("hash must not be empty")?;
let second_letter = chars
.next()
.context("hash must be at least two characters")?;
let extension = file
.extension()
.map_or(String::new(), |ext| format!(".{}", ext.to_string_lossy()));
Ok(PathBuf::from("raw")
.join(first_letter.to_string())
.join(second_letter.to_string())
.join(format!("{hash}{extension}")))
}
#[cfg(test)]
mod tests {
use super::*;
use std::{env, fs};
#[test]
fn test_archive_staged_file_moves_into_raw_store() {
let root = env::temp_dir().join(format!("archivr-store-test-{}", std::process::id()));
let _ = fs::remove_dir_all(&root);
fs::create_dir_all(root.join("temp")).unwrap();
let staged = root.join("temp").join("photo.jpg");
fs::write(&staged, b"image-bytes").unwrap();
let relative = archive_staged_file(&staged, &root).unwrap();
let absolute = root.join(&relative);
assert!(absolute.is_file());
assert!(!staged.exists());
assert!(relative.starts_with("raw"));
let _ = fs::remove_dir_all(&root);
}
}

557
crates/archivr-core/src/downloader/tweets.rs Normal file
View file

@ -0,0 +1,557 @@
use anyhow::{Context, Result, bail};
use regex::Regex;
use std::{
collections::{HashMap, HashSet},
env,
ffi::OsString,
fs,
path::{Path, PathBuf},
process::Command,
sync::OnceLock,
};
use crate::{downloader::store, twitter::parse_tweet_id};
/// Extracts a tweet ID from an archivr path like `"tweet:123"` by taking the
/// last colon-separated segment and validating it as a numeric ID.
fn tweet_id_from_path(path: &str) -> Option<String> {
path.split(':').next_back().and_then(parse_tweet_id)
}
/// Resolves `path` relative to `cwd` if it is not already absolute.
fn absolutize_path_from_cwd(path: PathBuf, cwd: &Path) -> PathBuf {
if path.is_absolute() {
path
} else {
cwd.join(path)
}
}
/// Builds the CLI argument list for the Python tweet scraper.
/// When `thread` is true, recursive flags are added to follow reply chains.
fn build_scraper_args(
tweet_id: &str,
thread: bool,
output_dir: &Path,
temp_dir: &Path,
credentials_file: &Path,
) -> Vec<String> {
let mut args = vec![
"--tweet-ids".to_string(),
tweet_id.to_string(),
"--output-dir".to_string(),
output_dir.display().to_string(),
"--media-dir".to_string(),
temp_dir.join("media").display().to_string(),
"--download-media".to_string(),
"--credentials-file".to_string(),
credentials_file.display().to_string(),
];
if thread {
args.push("--recursive-replied-to-tweets".to_string());
args.push("--recursive-replied-to-tweets-quotes-retweets".to_string());
args.push("--download-replied-to-tweets-media".to_string());
} else {
args.push("--no-recursive".to_string());
}
args
}
/// Archives a tweet (or full thread) identified by `path` (e.g. `"tweet:123"`).
///
/// Invokes the Python scraper, then moves all produced media assets into the
/// content-addressed raw store and rewrites the JSON output to use the new
/// store-relative paths. Returns `true` if new content was archived, `false`
/// if the tweet was already present and `thread` is `false`.
///
/// Requires `ARCHIVR_TWITTER_CREDENTIALS_FILE` to be set. The scraper binary
/// can be overridden via `ARCHIVR_TWEET_SCRAPER` and `ARCHIVR_TWEET_PYTHON`.
pub fn archive(path: &str, thread: bool, store_path: &Path, timestamp: &str) -> Result<bool> {
let invocation_cwd = env::current_dir().context("Failed to read current working directory")?;
// Output directory for Tweet JSON files.
let output_dir = store_path.join("raw_tweets");
// Temporary directory for media assets downloaded by the scraper in `temp/...`.
let temp_dir = store_path.join("temp").join(timestamp).join("tweets");
let tweet_id = tweet_id_from_path(path).context("Invalid tweet ID")?;
fs::create_dir_all(&output_dir)?;
fs::create_dir_all(&temp_dir)?;
// Path to the root - the to-be-archived tweet's JSON file.
let root_json = output_dir.join(format!("tweet-{tweet_id}.json"));
if !thread && root_json.exists() {
return Ok(false);
}
let before = tweet_json_files(&output_dir)?;
let python = env::var_os("ARCHIVR_TWEET_PYTHON").unwrap_or_else(|| OsString::from("python3"));
let scraper_path = env::var_os("ARCHIVR_TWEET_SCRAPER")
.map(PathBuf::from)
.unwrap_or_else(|| PathBuf::from("vendor/twitter/scrape_user_tweet_contents.py"));
let scraper_path = absolutize_path_from_cwd(scraper_path, &invocation_cwd);
let credentials_file = if let Some(credentials_file) =
env::var_os("ARCHIVR_TWITTER_CREDENTIALS_FILE")
{
absolutize_path_from_cwd(PathBuf::from(credentials_file), &invocation_cwd)
} else {
bail!(
"Twitter scraping requires ARCHIVR_TWITTER_CREDENTIALS_FILE to point to a cookies file."
);
};
if !credentials_file.is_file() {
bail!(
"Twitter credentials file not found: {}",
credentials_file.display()
);
}
let mut cmd = Command::new(&python);
cmd.current_dir(&temp_dir).arg(&scraper_path);
for arg in build_scraper_args(&tweet_id, thread, &output_dir, &temp_dir, &credentials_file) {
cmd.arg(arg);
}
let output = cmd.output().with_context(|| {
format!(
"Failed to spawn tweet scraper at {}",
scraper_path.display()
)
})?;
if !output.status.success() {
let stderr = String::from_utf8_lossy(&output.stderr);
let stdout = String::from_utf8_lossy(&output.stdout);
bail!(
"Tweet scraper failed.\nstdout:\n{}\nstderr:\n{}",
stdout.trim(),
stderr.trim()
);
}
if !root_json.exists() {
let stderr = String::from_utf8_lossy(&output.stderr);
let stdout = String::from_utf8_lossy(&output.stdout);
bail!(
"Tweet scraper completed but did not create expected JSON file: {}\nstdout:\n{}\nstderr:\n{}",
root_json.display(),
stdout.trim(),
stderr.trim()
);
}
cleanup_summary(&output_dir)?;
let after = tweet_json_files(&output_dir)?;
let new_jsons = new_tweet_jsons(&before, &after);
rewrite_tweet_outputs(&new_jsons, &output_dir, &temp_dir, store_path)?;
let _ = fs::remove_dir_all(store_path.join("temp").join(timestamp));
Ok(true)
}
/// Removes the `scraping_summary.json` file left by the scraper, if present.
fn cleanup_summary(output_dir: &Path) -> Result<()> {
let summary_path = output_dir.join("scraping_summary.json");
if summary_path.exists() {
fs::remove_file(summary_path)?;
}
Ok(())
}
/// Returns the set of `tweet-*.json` files present in `output_dir`.
fn tweet_json_files(output_dir: &Path) -> Result<HashSet<PathBuf>> {
let mut files = HashSet::new();
for entry in fs::read_dir(output_dir)? {
let entry = entry?;
let path = entry.path();
if path.is_file()
&& path
.file_name()
.and_then(|name| name.to_str())
.is_some_and(|name| name.starts_with("tweet-") && name.ends_with(".json"))
{
files.insert(path);
}
}
Ok(files)
}
/// Returns the sorted list of JSON files present in `after` but not in `before`.
fn new_tweet_jsons(before: &HashSet<PathBuf>, after: &HashSet<PathBuf>) -> Vec<PathBuf> {
let mut files = after.difference(before).cloned().collect::<Vec<_>>();
files.sort();
files
}
/// Returns a lazily-compiled regex matching `"avatar_local_path": "..."` in JSON.
fn avatar_regex() -> &'static Regex {
static REGEX: OnceLock<Regex> = OnceLock::new();
REGEX.get_or_init(|| Regex::new(r#""avatar_local_path": "([^"\n]+)""#).unwrap())
}
/// Returns a lazily-compiled regex matching `"local_path": "..."` in JSON.
fn media_regex() -> &'static Regex {
static REGEX: OnceLock<Regex> = OnceLock::new();
REGEX.get_or_init(|| Regex::new(r#"(?m)"local_path": "([^"\n]+)""#).unwrap())
}
/// Rewrites asset paths in each newly-created JSON file, moving assets into
/// the content-addressed store. Files are written back only if content changed.
fn rewrite_tweet_outputs(
tweet_jsons: &[PathBuf],
output_dir: &Path,
temp_dir: &Path,
store_path: &Path,
) -> Result<()> {
let mut archived_assets = HashMap::new();
for path in tweet_jsons {
let contents = fs::read_to_string(path)?;
let rewritten = rewrite_json_asset_paths(
&contents,
output_dir,
temp_dir,
store_path,
&mut archived_assets,
)?;
if rewritten != contents {
fs::write(path, rewritten)?;
}
}
Ok(())
}
/// Rewrites all `avatar_local_path` and `local_path` references in `contents`,
/// archiving each referenced file into the raw store and returning the updated
/// JSON string. `archived_assets` is a cache to avoid re-archiving the same
/// file when it is referenced by multiple tweets.
fn rewrite_json_asset_paths(
contents: &str,
output_dir: &Path,
temp_dir: &Path,
store_path: &Path,
archived_assets: &mut HashMap<String, String>,
) -> Result<String> {
let mut rewritten = contents.to_string();
for captures in avatar_regex().captures_iter(contents) {
let old_path = captures[1].to_string();
let new_path =
archive_asset_reference(&old_path, output_dir, store_path, "avatar", archived_assets)?;
rewritten = rewritten.replace(
&format!(r#""avatar_local_path": "{old_path}""#),
&format!(r#""avatar_local_path": "{new_path}""#),
);
}
for captures in media_regex().captures_iter(contents) {
let old_path = captures[1].to_string();
let new_path =
archive_asset_reference(&old_path, temp_dir, store_path, "media", archived_assets)?;
rewritten = rewritten.replace(
&format!(r#""local_path": "{old_path}""#),
&format!(r#""local_path": "{new_path}""#),
);
}
Ok(rewritten)
}
/// Archives the asset at `old_path` (relative to `base_dir`) into the raw store
/// and returns its new store-relative path. Already-archived paths (starting
/// with `"raw/"`) are returned unchanged. Results are cached in `archived_assets`
/// by `"<kind>:<old_path>"` key to deduplicate work across TOML files.
fn archive_asset_reference(
old_path: &str,
base_dir: &Path,
store_path: &Path,
kind: &str,
archived_assets: &mut HashMap<String, String>,
) -> Result<String> {
if old_path.starts_with("raw/") {
return Ok(old_path.to_string());
}
let key = format!("{kind}:{old_path}");
if let Some(existing) = archived_assets.get(&key) {
return Ok(existing.clone());
}
let absolute_path = base_dir.join(old_path);
if !absolute_path.exists() {
bail!(
"Referenced tweet asset not found: {}",
absolute_path.display()
);
}
let relative_path = store::archive_staged_file(&absolute_path, store_path)?;
let relative_path = relative_path.to_string_lossy().replace('\\', "/");
archived_assets.insert(key, relative_path.clone());
Ok(relative_path)
}
#[cfg(test)]
mod tests {
use super::*;
use std::{
sync::{Mutex, MutexGuard},
time::{SystemTime, UNIX_EPOCH},
};
fn env_lock() -> MutexGuard<'static, ()> {
static LOCK: OnceLock<Mutex<()>> = OnceLock::new();
LOCK.get_or_init(|| Mutex::new(())).lock().unwrap()
}
fn unique_path(prefix: &str) -> PathBuf {
let nanos = SystemTime::now()
.duration_since(UNIX_EPOCH)
.unwrap()
.as_nanos();
env::temp_dir().join(format!("{prefix}-{nanos}-{}", std::process::id()))
}
fn set_test_env(key: &str, value: impl AsRef<std::ffi::OsStr>) {
unsafe {
env::set_var(key, value);
}
}
fn remove_test_env(key: &str) {
unsafe {
env::remove_var(key);
}
}
#[test]
fn test_build_scraper_args_for_single_tweet() {
let args = build_scraper_args(
"1234567890",
false,
Path::new("/tmp/raw_tweets"),
Path::new("/tmp/temp/tweets"),
Path::new("/tmp/twitter-creds.txt"),
);
assert!(args.contains(&"--tweet-ids".to_string()));
assert!(args.contains(&"1234567890".to_string()));
assert!(args.contains(&"--output-dir".to_string()));
assert!(args.contains(&"--download-media".to_string()));
assert!(args.contains(&"--credentials-file".to_string()));
assert!(args.contains(&"--no-recursive".to_string()));
assert!(!args.contains(&"--recursive-replied-to-tweets".to_string()));
assert!(!args.contains(&"--recursive-replied-to-tweets-quotes-retweets".to_string()));
assert!(!args.contains(&"--download-replied-to-tweets-media".to_string()));
}
#[test]
fn test_build_scraper_args_for_thread() {
let args = build_scraper_args(
"1234567890",
true,
Path::new("/tmp/raw_tweets"),
Path::new("/tmp/temp/tweets"),
Path::new("/tmp/twitter-creds.txt"),
);
assert!(args.contains(&"--recursive-replied-to-tweets".to_string()));
assert!(args.contains(&"--recursive-replied-to-tweets-quotes-retweets".to_string()));
assert!(args.contains(&"--download-replied-to-tweets-media".to_string()));
assert!(!args.contains(&"--no-recursive".to_string()));
}
#[test]
fn test_cleanup_summary_removes_summary_only() {
let output_dir = unique_path("archivr-tweet-summary");
fs::create_dir_all(&output_dir).unwrap();
fs::write(output_dir.join("scraping_summary.json"), "summary").unwrap();
fs::write(output_dir.join("tweet-1.json"), "tweet").unwrap();
cleanup_summary(&output_dir).unwrap();
assert!(!output_dir.join("scraping_summary.json").exists());
assert!(output_dir.join("tweet-1.json").exists());
let _ = fs::remove_dir_all(output_dir);
}
#[test]
fn test_rewrite_json_asset_paths_rearchives_assets() {
let store_path = unique_path("archivr-tweet-store");
let output_dir = store_path.join("raw_tweets");
let temp_dir = store_path.join("temp").join("ts").join("tweets");
fs::create_dir_all(&output_dir).unwrap();
fs::create_dir_all(temp_dir.join("media").join("avatars")).unwrap();
fs::create_dir_all(temp_dir.join("media").join("123")).unwrap();
fs::write(
temp_dir.join("media").join("avatars").join("avatar.jpg"),
b"avatar",
)
.unwrap();
fs::write(
temp_dir.join("media").join("123").join("media_1.jpg"),
b"media",
)
.unwrap();
let contents = r#"{
"entities": { "media": [{ "local_path": "media/123/media_1.jpg" }] },
"author": { "avatar_local_path": "../temp/ts/tweets/media/avatars/avatar.jpg" }
}"#;
let rewritten = rewrite_json_asset_paths(
contents,
&output_dir,
&temp_dir,
&store_path,
&mut HashMap::new(),
)
.unwrap();
assert!(rewritten.contains(r#""avatar_local_path": "raw/"#));
assert!(rewritten.contains(r#""local_path": "raw/"#));
assert!(
!temp_dir
.join("media")
.join("avatars")
.join("avatar.jpg")
.exists()
);
assert!(
!temp_dir
.join("media")
.join("123")
.join("media_1.jpg")
.exists()
);
let _ = fs::remove_dir_all(store_path);
}
#[test]
fn test_resolve_from_cwd_keeps_absolute_paths() {
let path = absolutize_path_from_cwd(PathBuf::from("/tmp/creds.txt"), Path::new("/work"));
assert_eq!(path, PathBuf::from("/tmp/creds.txt"));
}
#[test]
fn test_resolve_from_cwd_expands_relative_paths() {
let path = absolutize_path_from_cwd(PathBuf::from("creds.txt"), Path::new("/work"));
assert_eq!(path, PathBuf::from("/work/creds.txt"));
}
#[test]
fn test_archive_skips_existing_flat_tweet() {
let _guard = env_lock();
let store_path = unique_path("archivr-tweet-skip");
let output_dir = store_path.join("raw_tweets");
fs::create_dir_all(&output_dir).unwrap();
fs::create_dir_all(store_path.join("temp")).unwrap();
fs::write(output_dir.join("tweet-123.json"), r#"{"id":"123"}"#).unwrap();
let credentials = store_path.join("creds.txt");
fs::write(&credentials, "ct0=test;auth_token=test").unwrap();
set_test_env("ARCHIVR_TWITTER_CREDENTIALS_FILE", &credentials);
let archived = archive("tweet:123", false, &store_path, "ts").unwrap();
assert!(!archived);
remove_test_env("ARCHIVR_TWITTER_CREDENTIALS_FILE");
let _ = fs::remove_dir_all(store_path);
}
#[test]
fn test_archive_flattens_tweets_and_rewrites_assets_with_stub_scraper() {
let _guard = env_lock();
let store_path = unique_path("archivr-tweet-integration");
let output_dir = store_path.join("raw_tweets");
fs::create_dir_all(&output_dir).unwrap();
fs::create_dir_all(store_path.join("temp")).unwrap();
let credentials = store_path.join("creds.txt");
fs::write(&credentials, "ct0=test;auth_token=test").unwrap();
let script = store_path.join("stub_scraper.sh");
fs::write(
&script,
r#"#!/bin/sh
set -eu
tweet_id=""
output_dir=""
media_dir=""
while [ "$#" -gt 0 ]; do
case "$1" in
--tweet-ids)
tweet_id="$2"
shift 2
;;
--output-dir)
output_dir="$2"
shift 2
;;
--media-dir)
media_dir="$2"
shift 2
;;
*)
shift
;;
esac
done
mkdir -p "$output_dir" "$media_dir/avatars" "$media_dir/$tweet_id"
printf 'avatar' > "$media_dir/avatars/author.jpg"
printf 'media' > "$media_dir/$tweet_id/media_1.jpg"
printf '{"summary":true}\n' > "$output_dir/scraping_summary.json"
cat > "$output_dir/tweet-$tweet_id.json" <<EOF
{
"id": "$tweet_id",
"entities": { "media": [{ "local_path": "media/$tweet_id/media_1.jpg" }] },
"author": { "avatar_local_path": "../temp/ts/tweets/media/avatars/author.jpg" }
}
EOF
"#,
)
.unwrap();
Command::new("chmod")
.arg("+x")
.arg(&script)
.status()
.unwrap();
set_test_env("ARCHIVR_TWITTER_CREDENTIALS_FILE", &credentials);
set_test_env("ARCHIVR_TWEET_SCRAPER", &script);
set_test_env("ARCHIVR_TWEET_PYTHON", "/bin/sh");
let archived = archive("tweet:123", false, &store_path, "ts").unwrap();
let tweet_file = output_dir.join("tweet-123.json");
let contents = fs::read_to_string(&tweet_file).unwrap();
assert!(archived);
assert!(tweet_file.exists());
assert!(!output_dir.join("scraping_summary.json").exists());
assert!(contents.contains(r#""avatar_local_path": "raw/"#));
assert!(contents.contains(r#""local_path": "raw/"#));
assert!(!store_path.join("temp").join("ts").exists());
remove_test_env("ARCHIVR_TWITTER_CREDENTIALS_FILE");
remove_test_env("ARCHIVR_TWEET_SCRAPER");
remove_test_env("ARCHIVR_TWEET_PYTHON");
let _ = fs::remove_dir_all(store_path);
}
}

33
crates/archivr-core/src/downloader/ytdlp.rs Normal file
View file

@ -0,0 +1,33 @@
use anyhow::{Context, Result, bail};
use std::{env, path::Path, process::Command};
use crate::hash::hash_file;
pub fn download(path: String, store_path: &Path, timestamp: &String) -> Result<String> {
println!("Downloading with yt-dlp: {path}");
let ytdlp = env::var("ARCHIVR_YT_DLP").unwrap_or_else(|_| "yt-dlp".to_string());
let temp_dir = store_path.join("temp").join(timestamp);
std::fs::create_dir_all(&temp_dir)?;
let out_file = temp_dir.join(format!("{timestamp}.mp4"));
let out = Command::new(&ytdlp)
.arg(&path)
.arg("-f")
.arg("bestvideo+bestaudio/best")
.arg("--merge-output-format")
.arg("mp4")
.arg("-o")
.arg(&out_file)
.output()
.with_context(|| format!("failed to spawn {ytdlp} process"))?;
if !out.status.success() {
let stderr = String::from_utf8_lossy(&out.stderr);
bail!("yt-dlp failed: {stderr}");
}
hash_file(&out_file)
}

17
crates/archivr-core/src/hash.rs Normal file
View file

@ -0,0 +1,17 @@
use anyhow::Result;
use sha3::{Digest, Sha3_256};
use std::{fs::File, io::Read, path::Path};
pub fn hash_file(path: &Path) -> Result<String> {
let mut file = File::open(path)?;
let mut buf = Vec::new();
file.read_to_end(&mut buf)?;
Ok(hash(String::from_utf8_lossy(&buf).to_string()))
}
pub fn hash(path: String) -> String {
let mut hasher = Sha3_256::new();
hasher.update(path.as_bytes());
let result = hasher.finalize();
hex::encode(result)
}

5
crates/archivr-core/src/lib.rs Normal file
View file

@ -0,0 +1,5 @@
pub mod archive;
pub mod database;
pub mod downloader;
pub mod hash;
pub mod twitter;

8
crates/archivr-core/src/twitter.rs Normal file
View file

@ -0,0 +1,8 @@
/// Returns the tweet ID if `id` is non-empty and contains only ASCII digits.
pub fn parse_tweet_id(id: &str) -> Option<String> {
if !id.is_empty() && id.chars().all(|char| char.is_ascii_digit()) {
Some(id.to_string())
} else {
None
}
}