]> git.hungrycats.org Git - bees/commitdiff
state: rename state.hash.create to state.create and auto-create path.home
authorZygo Blaxell <bees@furryterror.org>
Sun, 26 Apr 2026 21:56:44 +0000 (17:56 -0400)
committerZygo Blaxell <bees@furryterror.org>
Tue, 6 Oct 2026 05:51:40 +0000 (01:51 -0400)
The boolean that gates "create state files if they don't exist" really
applies to both path.home and beeshash.dat — they are the two files
that bees writes under [state] when persistent=yes.  Promote the key
from [state.hash] up to [state] so it sits alongside state.persistent
and covers both files.

The new state.create=yes also asks BeesContext::home_fd() to create
path.home itself when the directory is missing, instead of throwing
ENOENT and forcing the operator to mkdir it by hand.  path.home is
created subvolume-first via BTRFS_IOC_SUBVOL_CREATE so it gets
independent snapshot/quota lifecycle from the surrounding filesystem;
on a non-btrfs parent or kernels that reject the ioctl,
btrfs_subvol_create_at returns false and home_fd() falls back to a
plain mkdir().  Only the final path component is created — the parent
of path.home must already exist — and the subvolume path is taken
only when path.home is a relative single-component name (the common
".beeshome" shape); absolute paths and embedded '/' go straight to
mkdir().

home_fd() now branches on (state.persistent, state.create) when the
initial open hits ENOENT:

  - persistent=no                    -> return Fd() (inert mode)
  - persistent=yes && create=no      -> throw with path.home named
  - persistent=yes && create=yes     -> subvol-or-mkdir, then retry

Other open errors (EACCES, EROFS, ENOTDIR, ...) still throw — only
ENOENT triggers the new logic.  errno is captured locally because Fd
construction can clobber it on the failure path.

The inert-Fd return path is safe because the prior commit
("bees-util: make BeesStringFile inert when dir fd is unset") makes
BeesStringFile read/write no-op when m_dir_fd is empty and m_name is
relative — exactly the shape the state files end up with when
home_fd() returns Fd().

bees-hash.cc still gates file creation on m_create (set via
BeesHashTable::set_create) for now; the setter is just fed from the
renamed config key in bees.cc.  The error message in
BeesHashTable::open_file refers to the new key name.

Assisted-by: Claude-Code:claude-opus-4-7
Signed-off-by: Zygo Blaxell <bees@furryterror.org>
docs/config-file.md
src/bees-config-v1.cc
src/bees-context.cc
src/bees-hash.cc
src/bees.cc

index 871298ffcb8786db490272d20f5416214ae0d135..f89d0fd8ef6110d010a320136302622f728e5a3a 100644 (file)
@@ -421,7 +421,7 @@ files in detail.
 * **`persistent`**
   Enable on-disk persistence of both the hash table and the crawl checkpoint.
   * `yes` (default) — bees reads `beeshash.dat` and `beespoint.ini` at startup
-    (creating them if necessary, subject to `state.hash.create`) and writes
+    (creating them if necessary, subject to `state.create`) and writes
     them back as the daemon runs.
   * `no` — bees runs entirely from an in-memory hash table and starts every
     crawl from the beginning.  No state files are read or written.  Combine
@@ -431,6 +431,24 @@ files in detail.
   * When `persistent = no`, the keys in `[state.hash]` and `[state.point]`
     have no effect.
 
+* **`create`**
+  Auto-create `path.home` and `beeshash.dat` if they do not already exist.
+  * `yes` (default) — bees creates the `path.home` directory at startup
+    if it is missing.  It first attempts `BTRFS_IOC_SUBVOL_CREATE` so
+    `path.home` becomes its own subvolume, with independent
+    snapshot/quota lifecycle from the surrounding filesystem.  On a
+    non-btrfs parent (or older kernels that reject the ioctl) it falls
+    back to a plain `mkdir()`.  Only the final path component is
+    created — the parent of `path.home` must already exist.  Once
+    `path.home` exists, `beeshash.dat` is created on first run, sized
+    to `state.hash.size`.
+  * `no` — startup fails if `path.home` or `beeshash.dat` is missing.
+    Useful to detect a misconfigured `path.home` before bees writes a
+    fresh empty hash table to the wrong location.
+  * Has no effect when `state.persistent = no` (no on-disk state is
+    read or written) or when `path.home` already exists (the create
+    step is idempotent).
+
 ## [state.hash] section
 
 The `[state.hash]` section configures `beeshash.dat`: its size, whether bees
@@ -460,15 +478,6 @@ may create or resize it, and how aggressively it is written back to disk.
     (combined with `state.hash.resize = yes`) rather than editing the
     config file in place.
 
-* **`create`**
-  Create `beeshash.dat` if it does not already exist.
-  * `yes` (default) — bees creates the file at startup, sized to
-    `state.hash.size`.
-  * `no` — startup fails if the file is missing.  Useful to detect a
-    misconfigured `path.home` before bees writes a fresh empty hash table
-    to the wrong location.
-  * Has no effect when `state.persistent = no`.
-
 * **`resize`**
   Resize the on-disk hash table when `state.hash.size` does not match the
   existing file size.
index 6bc261da0fd7d46d6970f277c69cdf6b09f04edf..6d33929d3f6e008b89351ed6b56f1aa848e31c54 100644 (file)
@@ -310,6 +310,13 @@ static const char bees_config_v1[] = R"--v1-config--(
         # hash table.
         persistent = yes
 
+        # Auto-create path.home and beeshash.dat if they do not exist.
+        # When yes, bees creates the path.home directory at startup if
+        # it is missing.  When no, startup fails if path.home or
+        # beeshash.dat is missing.
+        # Has no effect when state.persistent = no.
+        create = yes
+
 # The [state.hash] section controls hash table file options.
 
 [state.hash]
@@ -323,10 +330,6 @@ static const char bees_config_v1[] = R"--v1-config--(
         # other substitutions (see docs/config-format.md).
         size = min(${RAM_BYTES} / 16, ${FS_BYTES} / 16384)
 
-        # Create beeshash.dat if it does not exist.
-        # Set to no to require the file to be present at startup.
-        create = yes
-
         # Resize the on-disk hash table to state.hash.size on startup.
         # Uses reverse-LRU rebuild to preserve the most-recently-used entries.
         # When no, a size mismatch is logged as a warning and the existing
index c5cfc205d44b5df90e3186785102689b82b45f2c..307e818d1c5ec431a85454ef032c6e07215678f3 100644 (file)
@@ -122,23 +122,79 @@ BeesContext::home_fd()
        BEESTRACE("Opening home directory");
        const auto home_dir = m_config->get_trusted("path.home", [](const string &s) { return s; } );
        BEESTRACE("Opening home directory '" << home_dir << "'");
-       if (home_dir.at(0) == '/') {
-               // Absolute paths use plain openat (dirfd is ignored
-               // for absolute paths, symlinks are allowed).
-               // Use an anonymous Fd here because the absolute/relative Fd path
-               // code will be confused if it's not under the root
-               m_home_fd = openat(root_fd(), home_dir.c_str(), FLAGS_OPEN_DIR);
-               if (!m_home_fd) {
-                       THROW_ERRNO("openat: " << home_dir);
+       const bool persistent = m_config->get_trusted("state.persistent", bees_parse_bool);
+       const bool create = m_config->get_trusted("state.create", bees_parse_bool);
+
+       const bool absolute = (home_dir.at(0) == '/');
+
+       // First attempt: open paths.home if it already exists.
+       // Absolute paths use plain openat (dirfd is ignored for absolute
+       // paths, symlinks are allowed); relative paths use bees_openat,
+       // which tries openat2(RESOLVE_BENEATH | RESOLVE_NO_SYMLINKS |
+       // RESOLVE_NO_XDEV) and silently falls back to openat on kernels
+       // that predate openat2 (< 5.6).  Returns the raw file descriptor
+       // and the errno from the failing open so the caller can inspect
+       // errno without worrying about Fd construction clobbering it.
+       auto try_open = [&](int &out_errno) -> Fd {
+               const int raw = absolute
+                       ? openat(root_fd(), home_dir.c_str(), FLAGS_OPEN_DIR)
+                       : bees_openat(root_fd(), home_dir.c_str(), FLAGS_OPEN_DIR);
+               out_errno = (raw < 0) ? errno : 0;
+               if (absolute) {
+                       // Use an anonymous Fd here because the absolute/relative
+                       // Fd path code will be confused if it's not under the root.
+                       return Fd(raw);
                }
-       } else {
-               // Relative paths use bees_openat, which tries openat2(RESOLVE_BENEATH |
-               // RESOLVE_NO_SYMLINKS | RESOLVE_NO_XDEV) and silently falls back to
-               // openat on kernels that predate openat2 (< 5.6).
-               m_home_fd = Fd(bees_openat(root_fd(), home_dir.c_str(), FLAGS_OPEN_DIR), home_dir, m_root_fd);
+               return Fd(raw, home_dir, m_root_fd);
+       };
+
+       int open_errno = 0;
+       m_home_fd = try_open(open_errno);
+       if (!m_home_fd && open_errno == ENOENT) {
+               if (!persistent) {
+                       // state.persistent=no: paths.home is optional.  Run
+                       // inert: BeesStringFile reads return "" and writes
+                       // no-op when m_dir_fd is empty.  Logged once at
+                       // INFO so it's audible without paying every reconnect.
+                       BEESLOGINFO("paths.home '" << home_dir << "' does not exist; running inert (state.persistent=no)");
+                       return m_home_fd;
+               }
+               if (!create) {
+                       THROW_ERROR(runtime_error, "paths.home '" << home_dir << "' does not exist and state.create=no");
+               }
+
+               // state.persistent=yes && state.create=yes: create paths.home.
+               // Try BTRFS_IOC_SUBVOL_CREATE first (so paths.home is its own
+               // subvolume with independent snapshot/quota lifecycle), then
+               // fall back to mkdir().  Subvol creation only applies when the
+               // parent is root_fd() and the name is a single path component;
+               // for absolute paths or paths with embedded '/', skip straight
+               // to mkdir().
+               const bool single_component = !absolute && home_dir.find('/') == string::npos;
+               bool created = false;
+               if (single_component) {
+                       BEESLOGINFO("paths.home '" << home_dir << "' missing; creating subvolume");
+                       created = btrfs_subvol_create_at(root_fd(), home_dir);
+               }
+               if (!created) {
+                       BEESLOGINFO("paths.home '" << home_dir << "' missing; creating directory");
+                       const int mkdir_rv = absolute
+                               ? mkdir(home_dir.c_str(), 0700)
+                               : mkdirat(root_fd(), home_dir.c_str(), 0700);
+                       if (mkdir_rv != 0) {
+                               THROW_ERRNO("mkdir: " << home_dir);
+                       }
+               }
+               // Retry the open now that paths.home exists.
+               m_home_fd = try_open(open_errno);
                if (!m_home_fd) {
-                       THROW_ERRNO("openat: " << name_fd(root_fd()) << "/" << home_dir);
+                       errno = open_errno;
+                       THROW_ERRNO("openat after create: " << home_dir);
                }
+       } else if (!m_home_fd) {
+               // Real error (EACCES, EROFS, ENOTDIR, etc.) — surface it.
+               errno = open_errno;
+               THROW_ERRNO("openat: " << (absolute ? string() : (name_fd(root_fd()) + "/")) << home_dir);
        }
        BEESLOGDEBUG("opened home dir '" << home_dir << "' at '" << name_fd(m_home_fd) << "'");
        return m_home_fd;
index 37a320fa7caa7ef6262292fe52cb4c862d087e9c..4ca2a13d209fbeca8a32b800458961fb2991230e 100644 (file)
@@ -757,7 +757,7 @@ BeesHashTable::open_file()
        // If that doesn't work, try to make a new one
        if (!new_fd) {
                if (!m_create) {
-                       THROW_ERRNO("hash table '" << m_filename << "' does not exist and state.hash.create = no");
+                       THROW_ERRNO("hash table '" << m_filename << "' does not exist and state.create = no");
                }
                string tmp_filename = m_filename + ".tmp";
                BEESNOTE("creating new hash table '" << tmp_filename << "'");
index 85666feba59f7b84bf2c4bc393aeaca5bbd09f4e..91903146319dd9ecc8866fb41523b0d42e734ab0 100644 (file)
@@ -576,7 +576,7 @@ bees_main(int argc, char *argv[])
                        // File-backed mode: open (or create) beeshash.dat.
                        bc->init_hash_table("beeshash.dat", hash_size);
                        auto ht = bc->hash_table();
-                       ht->set_create(bc->get_config().get("state.hash.create", bees_parse_bool));
+                       ht->set_create(bc->get_config().get("state.create", bees_parse_bool));
                        ht->set_resize(bc->get_config().get("state.hash.resize", bees_parse_bool));
                        ht->set_writeback_fsync(bc->get_config().get("state.hash.writeback-fsync", bees_parse_bool));
                        ht->set_writeback_unreadahead(bc->get_config().get("state.hash.writeback-unreadahead", bees_parse_bool));