A repository kept on a store: oxy init --store d069701a4997

- **A repository kept on a store (#68).** `oxy init --store URL` keeps a repository's objects and operation log on `dir://`, S3, GCS or Azure, behind a local cache of `storage.cache` bytes (2 GiB by default) that can be deleted at any time. Checked against the real services: a commit takes 0.5 to 0.9 seconds, and reopening with no cache about half a second.

    /// `storage.url`: the store the repository's objects and operation

    /// head are kept on (`dir://`, `s3://`, …) instead of `.oxy/objects`

    /// (oxygen#68).

    pub storage_url: Option<String>,

    /// `storage.cache`: the most the local cache in front of that store

    /// holds, in bytes.

    pub storage_cache: u64,

            storage_url: None,

            storage_cache: DEFAULT_STORAGE_CACHE,

            "storage.url" => {

                self.storage_url = (!value.is_empty()).then(|| value.to_string());

            }

            "storage.cache" => {

                self.storage_cache = if value.is_empty() {

                    DEFAULT_STORAGE_CACHE

                } else {

                    parse_size(value)?

                }

            }

/// `storage.cache` when unset: 2 GiB.

pub const DEFAULT_STORAGE_CACHE: u64 = 2 << 30;

/// The object store of the repository directory `oxy`: `.oxy/objects`,

/// or the store `storage.url` names behind a cache of `storage.cache`

/// bytes in `.oxy/cache` (oxygen#68). `.oxy/objects` is then only

/// scratch space: packs being written, and derived caches.

fn open_objects(oxy: &Path, config: &Config) -> Result<Store> {

    let Some(url) = &config.storage_url else {

        return Ok(Store::open(oxy.join("objects"))?);

    };

    let options = crate::protocol::RemoteOptions {

        cache_dir: Some(oxy.join("cache")),

        ..Default::default()

    };

    let remote = crate::protocol::open_store(url, &options)

        .ok_or_else(|| {

            RepoError::Msg(format!(

                "storage.url {url}: this oxy cannot open that kind of store (dir://, or s3://, gs:// and az:// in builds with cloud stores)"

            ))

        })?

        .map_err(|e| RepoError::Msg(format!("open the repository's store {url}: {e}")))?;

    let cached = crate::strata::CachingStore::open(

        std::sync::Arc::from(remote),

        oxy.join("cache"),

        config.storage_cache,

    )

    .map_err(|e| RepoError::Msg(format!("open the cache for {url}: {e}")))?;

    Ok(Store::open_on(

        std::sync::Arc::new(cached),

        oxy.join("objects"),

    )?)

}

        Self::init_on(root, id, None)

    }

    /// A new repository with a fresh id, bare or not, on `storage` or in

    /// `.oxy/objects` (`oxy init [--bare] [--store URL]`).

    pub fn init_new(root: &Path, bare: bool, storage: Option<&str>) -> Result<Repo> {

        let mut id = [0u8; 16];

        rand::rngs::OsRng.fill_bytes(&mut id);

        if bare {

            Self::init_bare_on(root, id, storage)

        } else {

            Self::init_on(root, id, storage)

        }

    }

    /// Initialize a repository whose objects and operation head are kept

    /// on the store at `storage` (`storage.url`), or in `.oxy/objects`.

    pub fn init_on(root: &Path, id: [u8; 16], storage: Option<&str>) -> Result<Repo> {

        let mut config = Config::load(Some(&default_user_config()), &oxy.join("config"))?;

        if let Some(url) = storage {

            config.set("storage.url", url)?;

        }

        let store = open_objects(&oxy, &config)?;

        Self::init_bare_on(root, id, None)

    }

    /// [`Repo::init_on`] for a bare repository.

    pub fn init_bare_on(root: &Path, id: [u8; 16], storage: Option<&str>) -> Result<Repo> {

        let mut config = Config::load(Some(&default_user_config()), &oxy.join("config"))?;

        if let Some(url) = storage {

            config.set("storage.url", url)?;

        }

        let store = open_objects(&oxy, &config)?;

                let store = open_objects(&shared, &config)?;

                let store = open_objects(&oxy, &config)?;

/// oxygen#68: a repository kept on a store (`storage.url`) holds its

/// objects and operation head there, with `.oxy/cache` in front: it works

/// as one on disk does, reopens, and survives losing its cache.

#[test]

fn a_repository_runs_on_a_store_with_a_cache_in_front() {

    hermetic();

    if std::env::var_os("OXY_STORE_BACKEND").is_some() {

        return;

    }

    let dir = tempfile::tempdir().unwrap();

    let (root, bucket) = (dir.path().join("work"), dir.path().join("bucket"));

    let url = format!("dir://{}", bucket.display());

    let repo = Repo::init_on(&root, [7; 16], Some(&url)).unwrap();

    assert_eq!(repo.config.storage_url.as_deref(), Some(url.as_str()));

    write(&root, "a.txt", b"one\n");

    let h1 = repo.commit("First", &[]).unwrap();

    write(&root, "a.txt", b"one\ntwo\n");

    let h2 = repo.commit("Second", &[]).unwrap();

    assert!(

        !root.join(".oxy/ops/head").exists(),

        "the head is in the store"

    );

    assert!(bucket.join("ops/head").is_file());

    assert!(root.join(".oxy/cache").is_dir());

    drop(repo);

    // Reopened, and again with no cache at all: everything comes from the store.

    for drop_cache in [false, true] {

        if drop_cache {

            std::fs::remove_dir_all(root.join(".oxy/cache")).unwrap();

        }

        let repo = Repo::open(&root).unwrap();

        let log: Vec<String> = repo

            .op_log()

            .unwrap()

            .into_iter()

            .map(|(_, op)| op.command)

            .collect();

        assert!(log.len() >= 3, "{log:?}");

        assert_eq!(repo.store().get_change(&h1).unwrap().message, "First");

        let heads = repo

            .store()

            .get_state(&repo.view().unwrap().bookmarks["main"])

            .unwrap()

            .heads;

        assert_eq!(heads, vec![h2]);

        assert_eq!(

            repo.load_state(&heads).unwrap().materialize().files.len(),

            1

        );

    }

    // A second repository cannot start on the same store.

    let err = Repo::init_on(&dir.path().join("other"), [8; 16], Some(&url))

        .err()

        .unwrap()

        .to_string();

    assert!(

        err.contains("already holds a repository's operation log"),

        "{err}"

    );

    let err = Repo::init_on(&dir.path().join("third"), [9; 16], Some("nope://x"))

        .err()

        .unwrap()

        .to_string();

    assert!(err.contains("cannot open that kind of store"), "{err}");

}

/// oxygen#68: a small repository kept on each store (`storage.url`), with

/// the local cache in front: commits, a reopen with the cache dropped, and

/// the time each step took. Then every key the test wrote is removed.

#[test]

fn a_repository_runs_on_every_configured_store() {

    for (url, base_store) in each_store() {

        remove_stale(&base_store);

        let dir = tempfile::tempdir().unwrap();

        let root = dir.path();

        std::fs::create_dir_all(root.join("home")).unwrap();

        std::env::set_var("OXY_HOME", root.join("home"));

        let (base, query) = match url.split_once('?') {

            Some((b, q)) => (b.to_string(), format!("?{q}")),

            None => (url.clone(), String::new()),

        };

        let store_url = format!("{base}/repo-{}{query}", std::process::id());

        let plain = format!("{base}/repo-{}", std::process::id());

        let store = CloudStore::open(&store_url).unwrap();

        let t = std::time::Instant::now();

        let repo = Repo::init_new(&root.join("w"), false, Some(&store_url))

            .unwrap_or_else(|e| panic!("{plain}: init: {e}"));

        let init_ms = t.elapsed().as_millis();

        let t = std::time::Instant::now();

        let mut last = None;

        for i in 0..5 {

            write(

                root,

                "w/f.txt",

                format!("line {i}\n").repeat(i + 1).as_bytes(),

            );

            last = Some(repo.commit(&format!("commit {i}"), &[]).unwrap());

        }

        let commit_ms = t.elapsed().as_millis() / 5;

        drop(repo);

        std::fs::remove_dir_all(root.join("w/.oxy/cache")).unwrap();

        let t = std::time::Instant::now();

        let repo = Repo::open(&root.join("w")).unwrap();

        let heads = repo.bookmark_heads().unwrap();

        let state = repo.load_state(&heads).unwrap().materialize();

        let cold_ms = t.elapsed().as_millis();

        assert_eq!(heads, vec![last.unwrap()], "{plain}");

        assert_eq!(state.files.len(), 1);

        assert!(

            store.read_ref("ops/head").unwrap().is_some(),

            "{plain}: the head is in the store"

        );

        let keys = store.list("").unwrap();

        let total: u64 = keys.iter().map(|e| e.size).sum();

        eprintln!(

            "{plain}: init {init_ms} ms, commit {commit_ms} ms each, cold open and read {cold_ms} ms; {} keys, {total} bytes",

            keys.len()

        );

        remove_all(&store, "");

        assert!(store.list("").unwrap().is_empty(), "{plain}: cleanup");

    }

}

- **A repository on a store** (B2, 2026-10-05): `oxy init --store URL`

  (or `storage.url` in `.oxy/config`, set at init) keeps the objects and

  the operation head on that store, behind a cache in `.oxy/cache` of

  `storage.cache` bytes (2 GiB by default). `.oxy/objects` then holds

  only scratch: packs being written and derived caches. The cache can be

  deleted at any time. A second repository cannot start on a store that

  already holds one. Measured from the workstation against the real

  services with five small commits (`a_repository_runs_on_every_configured_store`):

  | Store | init | each commit | open with no cache, read the files |

  |---|---|---|---|

  | S3 | 441 ms | 703 ms | 481 ms |

  | GCS | 769 ms | 857 ms | 570 ms |

  | Azure | 664 ms | 511 ms | 639 ms |

  A commit writes its objects one request each and moves the head, so

  its cost is round trips, not bytes; batching a commit's objects into

  one pack is the next step for speed.

## A repository kept on a store

A store can also hold a repository itself rather than a copy of it.

Start one with `--store`:

```sh

oxy init myproject --store s3://my-bucket/repos/myproject?profile=work

```

- **Where things live:** the objects and the operation log are in the

  store. `.oxy/cache` keeps the objects this machine has used, up to

  `storage.cache` (2 GiB unless you set it, for example

  `oxy config storage.cache 10G`).

- **The cache:** you can delete `.oxy/cache` at any time. Objects come

  back from the store as they are needed.

- **One repository per prefix:** `oxy init --store` refuses a prefix

  that already holds a repository's operation log.

- **Speed:** each command that records something makes a few requests to

  the store, so a commit takes about half a second to a second.

- **Choose at init:** set `storage.url` only when the repository is

  created. Changing it later does not move the objects.

        /// Keep the objects and the operation log on this store

        /// (dir://PATH, s3://BUCKET/PREFIX, gs://…, az://…) instead of

        /// in .oxy, with a local cache in front (storage.cache, 2 GiB)

        #[arg(long, value_name = "URL")]

        store: Option<String>,

        Cmd::Init { path, bare, store } => workspace::init(path, bare, store.as_deref()),

pub fn init(path: Option<PathBuf>, bare: bool, store: Option<&str>) -> Result<i32> {

    let repo = Repo::init_new(&path, bare, store)?;

    if let Some(url) = &repo.config.storage_url {

        println!(

            "{}",

            ui::kv(

                "store",

                format!(

                    "{url} (cache in {}, up to {} MiB)",

                    ui::path(repo.root().join(".oxy/cache").display()),

                    repo.config.storage_cache >> 20

                )

            )

        );

    }