pub mod cache;
mod paths;
pub use paths::{
assert_contained, assert_safe_segment, github_store_path, lexical_clean, llms_txt_store_path,
normalize_url, npm_store_path, resolve_ask_home, web_store_path,
};
use std::path::{Path, PathBuf};
use std::sync::atomic::{AtomicU64, Ordering};
use std::time::{Duration, Instant, SystemTime};
use sha2::{Digest, Sha256};
const HASH_FILE: &str = ".ask-hash";
const STORE_VERSION_FILE: &str = "STORE_VERSION";
const CURRENT_STORE_VERSION: &str = "2";
pub struct EntryFile {
pub path: String,
pub content: String,
}
fn rand_hex8() -> String {
static COUNTER: AtomicU64 = AtomicU64::new(0);
let nanos = SystemTime::now()
.duration_since(SystemTime::UNIX_EPOCH)
.map(|d| d.as_nanos() as u64)
.unwrap_or(0);
let n = nanos
^ (COUNTER
.fetch_add(1, Ordering::Relaxed)
.wrapping_mul(0x9E37_79B9_7F4A_7C15));
format!("{:08x}", (n as u32))
}
fn atomic_swap(tmp_dir: &Path, target: &Path) -> std::io::Result<()> {
if target.exists() {
let backup = sibling(target, ".bak-");
std::fs::rename(target, &backup)?;
if let Err(e) = std::fs::rename(tmp_dir, target) {
let _ = std::fs::rename(&backup, target);
return Err(e);
}
let _ = std::fs::remove_dir_all(&backup);
} else {
std::fs::rename(tmp_dir, target)?;
}
Ok(())
}
fn sibling(target: &Path, infix: &str) -> PathBuf {
let name = target
.file_name()
.map(|n| n.to_string_lossy().into_owned())
.unwrap_or_default();
target.with_file_name(format!("{name}{infix}{}", rand_hex8()))
}
pub fn write_entry_atomic(target_dir: &Path, files: &[EntryFile]) -> anyhow::Result<()> {
let tmp_dir = sibling(target_dir, ".tmp-");
std::fs::create_dir_all(&tmp_dir)?;
let result = (|| -> anyhow::Result<()> {
for file in files {
let file_path = tmp_dir.join(&file.path);
assert_contained(&tmp_dir, &file_path)?;
if let Some(parent) = file_path.parent() {
std::fs::create_dir_all(parent)?;
}
std::fs::write(&file_path, &file.content)?;
}
atomic_swap(&tmp_dir, target_dir)?;
Ok(())
})();
if result.is_err() {
let _ = std::fs::remove_dir_all(&tmp_dir);
}
result
}
pub fn cp_dir_atomic(source_dir: &Path, target_dir: &Path) -> anyhow::Result<()> {
let tmp_dir = sibling(target_dir, ".tmp-");
if let Some(parent) = tmp_dir.parent() {
std::fs::create_dir_all(parent)?;
}
let result = (|| -> anyhow::Result<()> {
copy_tree_verbatim(source_dir, source_dir, &tmp_dir)?;
atomic_swap(&tmp_dir, target_dir)?;
Ok(())
})();
if result.is_err() {
let _ = std::fs::remove_dir_all(&tmp_dir);
}
result
}
fn copy_tree_verbatim(root: &Path, src: &Path, dst: &Path) -> anyhow::Result<()> {
std::fs::create_dir_all(dst)?;
for entry in std::fs::read_dir(src)? {
let entry = entry?;
let file_type = entry.file_type()?;
let from = entry.path();
let to = dst.join(entry.file_name());
if file_type.is_symlink() {
let target = std::fs::read_link(&from)?;
symlink_verbatim(root, &target, &from, &to)?;
} else if file_type.is_dir() {
copy_tree_verbatim(root, &from, &to)?;
} else {
std::fs::copy(&from, &to)?;
}
}
Ok(())
}
#[cfg(unix)]
fn symlink_verbatim(
_root: &Path,
target: &Path,
_src_link: &Path,
link: &Path,
) -> std::io::Result<()> {
std::os::unix::fs::symlink(target, link)
}
#[cfg(not(unix))]
fn symlink_verbatim(
root: &Path,
target: &Path,
src_link: &Path,
link: &Path,
) -> std::io::Result<()> {
let resolved = if target.is_absolute() {
target.to_path_buf()
} else {
src_link
.parent()
.unwrap_or_else(|| Path::new("."))
.join(target)
};
match (
std::fs::canonicalize(root),
std::fs::canonicalize(&resolved),
) {
(Ok(real_root), Ok(real_target)) if real_target.starts_with(&real_root) => {
std::fs::copy(&real_target, link).map(|_| ())
}
_ => Ok(()), }
}
const LOCK_TIMEOUT: Duration = Duration::from_secs(60);
const LOCK_INITIAL_DELAY: Duration = Duration::from_millis(100);
const LOCK_MAX_DELAY: Duration = Duration::from_millis(1600);
pub struct EntryLock {
lock_path: PathBuf,
}
impl Drop for EntryLock {
fn drop(&mut self) {
let _ = std::fs::remove_file(&self.lock_path);
}
}
pub fn acquire_entry_lock(entry_dir: &Path) -> anyhow::Result<Option<EntryLock>> {
let lock_path = {
let name = entry_dir
.file_name()
.map(|n| n.to_string_lossy().into_owned())
.unwrap_or_default();
entry_dir.with_file_name(format!("{name}.lock"))
};
if let Some(parent) = lock_path.parent() {
std::fs::create_dir_all(parent)?;
}
let deadline = Instant::now() + LOCK_TIMEOUT;
let mut delay = LOCK_INITIAL_DELAY;
loop {
match std::fs::OpenOptions::new()
.write(true)
.create_new(true)
.open(&lock_path)
{
Ok(_) => return Ok(Some(EntryLock { lock_path })),
Err(e) if e.kind() == std::io::ErrorKind::AlreadyExists => {
if entry_dir.exists() {
return Ok(None);
}
if Instant::now() >= deadline {
anyhow::bail!(
"Timed out waiting for lock: {}. Another ask install may be in progress. \
If no other process is running, remove it manually.",
lock_path.display()
);
}
std::thread::sleep(delay);
delay = (delay * 2).min(LOCK_MAX_DELAY);
}
Err(e) => return Err(e.into()),
}
}
}
pub fn stamp_entry(entry_dir: &Path) -> anyhow::Result<String> {
let hash = hash_dir(entry_dir)?;
std::fs::write(entry_dir.join(HASH_FILE), &hash)?;
Ok(hash)
}
pub fn verify_entry(entry_dir: &Path) -> bool {
let hash_path = entry_dir.join(HASH_FILE);
let Ok(recorded) = std::fs::read_to_string(&hash_path) else {
return false;
};
match hash_dir(entry_dir) {
Ok(actual) => recorded.trim() == actual,
Err(_) => false,
}
}
fn hash_dir(dir: &Path) -> anyhow::Result<String> {
let mut files = collect_files(dir, "")?;
files.sort();
let mut hasher = Sha256::new();
for rel in &files {
if Path::new(rel).file_name().and_then(|n| n.to_str()) == Some(HASH_FILE) {
continue;
}
hasher.update(rel.as_bytes());
hasher.update([0u8]);
hasher.update(std::fs::read(dir.join(rel))?);
hasher.update([0u8]);
}
Ok(format!("sha256-{:x}", hasher.finalize()))
}
fn collect_files(dir: &Path, prefix: &str) -> anyhow::Result<Vec<String>> {
let mut out = Vec::new();
for entry in std::fs::read_dir(dir)? {
let entry = entry?;
let name = entry.file_name().to_string_lossy().into_owned();
let rel = if prefix.is_empty() {
name.clone()
} else {
format!("{prefix}/{name}")
};
if entry.file_type()?.is_dir() {
out.extend(collect_files(&entry.path(), &rel)?);
} else {
out.push(rel);
}
}
Ok(out)
}
pub fn write_store_version(ask_home: &Path) {
let file = ask_home.join(STORE_VERSION_FILE);
let _ = std::fs::create_dir_all(ask_home);
let existing = std::fs::read_to_string(&file)
.ok()
.map(|s| s.trim().to_string());
if existing.as_deref() != Some(CURRENT_STORE_VERSION) {
let _ = std::fs::write(&file, format!("{CURRENT_STORE_VERSION}\n"));
}
}
pub fn read_store_version(ask_home: &Path) -> Option<String> {
std::fs::read_to_string(ask_home.join(STORE_VERSION_FILE))
.ok()
.map(|s| s.trim().to_string())
}
pub fn quarantine_entry(ask_home: &Path, store_dir: &Path) {
let ts = SystemTime::now()
.duration_since(SystemTime::UNIX_EPOCH)
.map(|d| d.as_secs())
.unwrap_or(0);
let quarantine_dir = ask_home
.join(".quarantine")
.join(format!("{ts}-{}", rand_hex8()));
if let Some(parent) = quarantine_dir.parent() {
let _ = std::fs::create_dir_all(parent);
}
if std::fs::rename(store_dir, &quarantine_dir).is_err() {
let _ = std::fs::remove_dir_all(store_dir);
}
}
#[cfg(test)]
mod tests {
use super::*;
fn ef(path: &str, content: &str) -> EntryFile {
EntryFile {
path: path.into(),
content: content.into(),
}
}
#[test]
fn write_then_verify_roundtrip() {
let dir = tempfile::tempdir().unwrap();
let target = dir.path().join("entry");
write_entry_atomic(&target, &[ef("INDEX.md", "hi"), ef("sub/a.md", "x")]).unwrap();
assert_eq!(
std::fs::read_to_string(target.join("INDEX.md")).unwrap(),
"hi"
);
assert_eq!(
std::fs::read_to_string(target.join("sub/a.md")).unwrap(),
"x"
);
stamp_entry(&target).unwrap();
assert!(verify_entry(&target));
std::fs::write(target.join("INDEX.md"), "changed").unwrap();
assert!(!verify_entry(&target));
}
#[test]
fn write_entry_rejects_escaping_path() {
let dir = tempfile::tempdir().unwrap();
let target = dir.path().join("entry");
assert!(write_entry_atomic(&target, &[ef("../escape.md", "x")]).is_err());
}
#[test]
fn write_entry_overwrites_existing_atomically() {
let dir = tempfile::tempdir().unwrap();
let target = dir.path().join("entry");
write_entry_atomic(&target, &[ef("a.md", "1")]).unwrap();
write_entry_atomic(&target, &[ef("b.md", "2")]).unwrap();
assert!(!target.join("a.md").exists());
assert_eq!(std::fs::read_to_string(target.join("b.md")).unwrap(), "2");
}
#[cfg(unix)]
#[test]
fn cp_dir_preserves_symlinks_verbatim() {
let dir = tempfile::tempdir().unwrap();
let src = dir.path().join("src");
std::fs::create_dir_all(&src).unwrap();
std::fs::write(src.join("AGENTS.md"), "agents").unwrap();
std::os::unix::fs::symlink("AGENTS.md", src.join("CLAUDE.md")).unwrap();
let target = dir.path().join("dst");
cp_dir_atomic(&src, &target).unwrap();
let link = target.join("CLAUDE.md");
assert!(link.symlink_metadata().unwrap().file_type().is_symlink());
assert_eq!(std::fs::read_link(&link).unwrap(), Path::new("AGENTS.md"));
assert_eq!(std::fs::read_to_string(&link).unwrap(), "agents");
}
#[test]
fn lock_acquire_release_and_hit() {
let dir = tempfile::tempdir().unwrap();
let entry = dir.path().join("e");
let lock = acquire_entry_lock(&entry).unwrap().unwrap();
assert!(dir.path().join("e.lock").exists());
drop(lock);
assert!(!dir.path().join("e.lock").exists());
std::fs::create_dir_all(&entry).unwrap();
let _held = std::fs::OpenOptions::new()
.write(true)
.create_new(true)
.open(dir.path().join("e.lock"))
.unwrap();
assert!(acquire_entry_lock(&entry).unwrap().is_none());
}
#[test]
fn store_version_roundtrip() {
let dir = tempfile::tempdir().unwrap();
assert_eq!(read_store_version(dir.path()), None);
write_store_version(dir.path());
assert_eq!(read_store_version(dir.path()).as_deref(), Some("2"));
}
#[test]
fn quarantine_moves_entry_out() {
let dir = tempfile::tempdir().unwrap();
let store = dir.path().join("npm").join("bad@1.0.0");
std::fs::create_dir_all(&store).unwrap();
std::fs::write(store.join("x"), "y").unwrap();
quarantine_entry(dir.path(), &store);
assert!(!store.exists());
assert!(dir
.path()
.join(".quarantine")
.read_dir()
.unwrap()
.next()
.is_some());
}
}