feat(cli): fluree server run --memory for a throwaway in-memory server - #1968

fluree-db-server/src/config_file.rs:1055 — optional, but the one I care about most.

settle_memory_storage erases a configured storage path or connection config without saying so anywhere. In the (_, false) arm we set config.storage_path = None and config.connection_config = None, and nothing downstream ever mentions that a durable storage configuration was dropped — the only trace is the storage = "memory" field on one info line at startup.

The precedence itself I'm fine with, and it's in the table in the PR body. What bothers me is the direction: FLUREE_MEMORY_STORAGE=true outranks a storage path that came from the config file or from the environment, so an env var can silently turn a durable deployment into a volatile one. The Docker entrypoint is fluree server run "$@", so the concrete shape is a compose file or base image that still carries FLUREE_MEMORY_STORAGE=true from a CI recipe (which these docs now teach) alongside a mounted /var/lib/fluree and FLUREE_STORAGE_PATH — the server comes up healthy, serves normally, and loses everything on the next restart. Compare validate() two hundred lines up, which does tracing::warn!("--storage-path is ignored when --connection-config is set") for the strictly milder durable→durable case.

One wrinkle if you go looking: a bare tracing::warn! here would be swallowed. On both paths this runs before logging exists — main.rs calls load_and_merge_config at :33 and init_logging at :56, and run_foreground calls build_server_config before init_logging at :190. That's presumably why config_file.rs has no tracing/eprintln calls at all today and surfaces everything through the returned ConfigFileError. So either follow that convention (hand the discard back as a warning the caller eprintln!s, the way main.rs:38 already prints non-fatal config errors), or stash what was displaced on the config and log it right after init_logging, next to where storage_type_str() already goes out.

// e.g. in the `(_, false)` arm, recording rather than logging:
if let Some(path) = config.storage_path.take() {
  config.memory_displaced = Some(format!("storage path {}", path.display()));
}

Minor and non-blocking — but if you agree it's right, I'd rather see it in this PR than lost in the backlog.

Folded in (30db74c), using the second shape you described. settle_memory_storage records what it displaced on the config (ServerConfig::memory_displaced, e.g. storage path /var/lib/fluree), since it runs before logging exists. The server logs a warn! next to its other startup warnings, which runs after init_logging for both fluree server run and the standalone binary.

memory_settles_against_other_storage_by_source now asserts what gets recorded, including nothing when nothing was configured. configuration.md and cli/server.md mention the warning.

fluree-db-server/src/config.rs:1184 — optional. This is more of a question than a suggestion, but I think the answer is "add the check."

Two lines below where I'm commenting, validate() refuses raft.enabled=true with storage-access-mode=proxy (config.rs:1219-1223). Nothing refuses raft.enabled=true with --memory, and build_fluree_with_nameservice → build_direct_fluree takes the new memory branch first (state.rs:493), so the node would keep its raft log and snapshots on disk at raft_storage_path while its ledger content store lives in per-process memory. The existing path-overlap guard doesn't catch it either — it's inside if let (Some(raft_path), Some(storage_path)), and by then settle_memory_storage has nulled the storage path.

The failing shape: fluree-server --raft-enabled --raft-node-id 1 --raft-storage-path /srv/raft --raft-listen-addr … --memory starts cleanly. The nameservice replicates through raft, so a follower learns about a commit the leader wrote into its own memory and can't read it; and after a restart the replayed log points at content that evaporated. It's narrow — raft isn't a default feature and only runs in the standalone binary — but it's a new footgun this PR opens, and the guard is a four-line sibling of one that already lives right there:

if self.memory {
  return Err("raft.enabled=true is incompatible with --memory (the raft log \
              replicates references into a content store that must outlive the \
              process)".to_string());
}

I recognize this is minor and non-blocking — but if you agree it's right, I'd rather see it folded in now than tracked and forgotten.

Added (30db74c). validate() refuses raft.enabled=true with --memory, next to the proxy check, and rejects_raft_with_memory_storage covers it. It ran under the raft feature in CI.

I also closed a sibling you didn't raise. A query peer (server_role=peer) with --memory is refused too, because a peer reads the transaction server's storage, which a per-process store can never share. In proxy mode the proxy silently won instead. memory_on_a_query_peer_does_not_validate covers that, and configuration.md lists both refusals.

fluree-db-server/src/config.rs:1040 — optional / nit. (Real location is config.rs:1029, a few lines above this hunk.)

storage_type_str() just stopped inferring "no path means memory" — but is_file_storage() at :1029 still does exactly that: self.storage_path.is_some() && self.connection_config.is_none(), doc-commented "Check if using file storage (vs memory)". With no --storage-path the server builds file storage in .fluree/storage, and that helper says false.

Nothing in the repo calls it (nor has_connection_config() at :1034 — I grepped the workspace and both have zero callers), so nothing is broken today; but they're public API on a library crate, so an embedder gets the stale answer, and it'd be a shame to leave the same wrong inference sitting in the same impl block as the fix. Either delegate it to the one function that now knows the build order, or just delete the pair since nothing uses them:

  /// Check if using file storage (vs memory)
  pub fn is_file_storage(&self) -> bool {
      self.storage_type_str() == "file"
  }

(Shown as a block rather than a suggestion because it spans several lines and the anchor is single-line — applying it as a one-click suggestion would duplicate the surrounding code.)

Your call which way — deleting them is probably the cleaner answer.

Deleted both (30db74c). Neither had callers anywhere in the workspace, so there was nothing worth keeping.

fluree-db-cli/src/commands/server.rs:420 — optional / accuracy.

The commit body and docs/cli/server.md:69 both say start and restart refuse memory mode "whether it comes from the flag, -- --memory, or the env var." For start that's exactly true and the e2e test proves all three. For restart I think only the explicit flag is refused: run() checks the parsed ServerAction::Restart { memory } at :128, but with a server.meta.json present run_restart hands off to run_start_with_child_args here, which never builds a ServerConfig and so has no memory check at all.

I don't think anything unsafe falls out of it — I traced it and the spawned child is rescued downstream: the replayed args always carry --storage-path or --connection-config (the original start filled the .fluree/storage default before build_child_args ran), so in the child that's a ValueSource::CommandLine value and settle_memory_storage's (false, true) arm clears memory. So restart under FLUREE_MEMORY_STORAGE=true quietly ignores the env var rather than refusing it, and restart -- --memory sends the child into validate()'s "--memory cannot be combined with --storage-path" rather than the friendly pointer at memory_needs_foreground().

Cheapest fix is probably to resolve and check before the handoff — or, if you'd rather not add a resolution pass to the restart path, soften the sentence in docs/cli/server.md:69 and the commit body to say start refuses every source and restart refuses the flag. Either is fine by me; I'd just like the docs and the code to agree.

Good catch. It turned out worse than a silent ignore. With a daemon running, restart -- --memory went through run_restart, which stops the server first. The replayed child then failed validate() on --memory plus the saved --storage-path, so the daemon was left down.

Fixed in code rather than in the docs (30db74c). run_restart now resolves its own arguments the way start does and refuses memory mode before it stops anything. It checks this command's own arguments, because the replayed ones always name a storage path, which would otherwise outrank the env var. So docs/cli/server.md is accurate now: restart refuses the flag, -- --memory and FLUREE_MEMORY_STORAGE.

The new e2e test restart_refuses_memory_without_stopping_the_daemon starts a real daemon with fluree server start, tries restart -- --memory and restart under FLUREE_MEMORY_STORAGE=true, and checks the daemon is still healthy after each. It passes in CI.

fluree-db-server/src/state.rs:1 — praise. Deleting the "Thread Safety Note" is correct, and I checked rather than assumed: MemoryNameService has all four of its maps behind Arc<RwLock<HashMap<..>>> (fluree-db-nameservice/src/memory.rs:27-36) and its own doc already says it suits multi-threaded runtimes, so the LocalSet-or-refactor caveat was stale rather than load-bearing. Nice catch that it was still sitting there.

Thanks for checking it rather than taking it on trust.

fluree-db-cli/tests/server_memory.rs:41 — praise. Redirecting HOME and TMPDIR outside the working directory and stripping every FLUREE_* / XDG_* variable off the child is what makes assert_empty(cwd) actually mean something rather than accidentally pass. This is the bit that makes the "writes nothing where it runs" claim testable, and it's worth keeping exactly as-is if this test ever gets refactored.

Agreed. The new restart test uses the same isolation: HOME/TMPDIR outside the working directory and every FLUREE_*/XDG_* variable stripped.