Skip to content

Self-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.

fix(storage): 用文件锁替代本地存储 PID 检查 (#5159)

Qin Haojief316f2756916
diff --git a/docs/en/guides/01-configuration.md b/docs/en/guides/01-configuration.md
index 482a1c17a..c78ea01f0 100644
--- a/docs/en/guides/01-configuration.md
+++ b/docs/en/guides/01-configuration.md
@@ -1035,7 +1035,7 @@ Storage configuration for context data, including file storage (RAGFS) and vecto
| Parameter | Type | Description | Default |
|-----------|------|-------------|---------|
| `workspace` | str | Local data storage path (main configuration) | "./data" |
-| `skip_process_lock` | bool | Whether to skip the startup process-lock check for `storage.workspace`. When enabled, OpenViking will not check or create the `.openviking.pid` lock file. | `false` |
+| `skip_process_lock` | bool | Skip the exclusive `.openviking.lock` file lock on `storage.workspace` for embedded vector backends (`local`, `cuvs`). Other backends do not acquire this lock. Skipping it does not make embedded vector storage safe for multiple processes. | `false` |
| `agfs` | object | RAGFS (Rust-based AGFS) configuration | {} |
| `vectordb` | object | Vector database storage configuration | {} |
diff --git a/docs/en/guides/03-deployment.md b/docs/en/guides/03-deployment.md
index 3fde1fefb..e9f90cb10 100644
--- a/docs/en/guides/03-deployment.md
+++ b/docs/en/guides/03-deployment.md
@@ -281,10 +281,16 @@ After startup, you can access:
### Multi-instance notes
+With an embedded vector backend (`local` or `cuvs`), OpenViking holds an exclusive OS file lock on `storage.workspace` by default. The `.openviking.lock` file remains on disk; its presence does not mean a server is running. The OS releases the lock when the server closes it or the process terminates. Do not manually delete a running server's lock file.
+
+Remote vector backends (`http`, `volcengine`, `vikingdb`) do not acquire this workspace lock, including when files are stored on a shared NAS. They do not require `storage.skip_process_lock=true`. Placing an embedded vector database on NAS does not make it safe to share between processes.
+
+For embedded vector backends, when upgrading from a version that uses `.openviking.pid`, stop all older servers using the workspace before starting the new version. The new version does not use leftover PIDs to determine ownership; the two locking protocols cannot be mixed.
+
For multi-instance deployments, prefer these settings:
- Set `server.temp_upload.default_mode` to `"shared"` so uploaded temporary files can be consumed by a different replica.
-- Only set `storage.skip_process_lock` to `true` when multiple instances intentionally share the same `storage.workspace`. When enabled, OpenViking will no longer check or create `.openviking.pid`.
+- Use a remote vector backend for shared storage. The existing `storage.skip_process_lock` option only disables the embedded-backend startup guard; it does not add multi-process support to embedded vector storage.
- For QueueFS, prefer an explicit per-instance local SQLite path via `storage.agfs.queuefs.db_path`. If usage audit is enabled, prefer an explicit per-instance local SQLite path via `server.observability.usage_audit.sqlite_path` instead of mixing these files into a shared workspace volume.
Example:
@@ -297,12 +303,15 @@ Example:
}
},
"storage": {
- "skip_process_lock": true
+ "vectordb": {
+ "backend": "http",
+ "url": "http://vector-db:5000"
+ }
}
}
```
-This example only applies when multiple instances intentionally share the same `workspace`. If each instance has its own local `workspace`, do not enable `skip_process_lock`.
+This example uses a remote HTTP vector service. Replace its URL with your deployment's vector-service address, or configure a `volcengine` or `vikingdb` backend.
Example with explicit local SQLite paths for QueueFS and usage audit:
@@ -319,7 +328,10 @@ Example with explicit local SQLite paths for QueueFS and usage audit:
}
},
"storage": {
- "skip_process_lock": true,
+ "vectordb": {
+ "backend": "http",
+ "url": "http://vector-db:5000"
+ },
"agfs": {
"queuefs": {
"db_path": "/var/lib/openviking-local/queue.db"
diff --git a/docs/zh/guides/01-configuration.md b/docs/zh/guides/01-configuration.md
index a7d1f389e..f68e2d09f 100644
--- a/docs/zh/guides/01-configuration.md
+++ b/docs/zh/guides/01-configuration.md
@@ -1003,7 +1003,7 @@ Glob 引擎配置,用于路径模式匹配。这些设置为服务端配置,
| 参数 | 类型 | 说明 | 默认值 |
|------|------|------|--------|
| `workspace` | str | 本地数据存储路径(主要配置) | "./data" |
-| `skip_process_lock` | bool | 是否跳过 `storage.workspace` 的启动进程锁检查。启用后,OpenViking 不会检查或创建 `.openviking.pid` 锁文件。 | `false` |
+| `skip_process_lock` | bool | 是否跳过本地向量后端(`local`、`cuvs`)对 `storage.workspace` 的 `.openviking.lock` 独占文件锁。其他后端不会获取此锁。跳过检查不代表本地向量存储支持多进程共享。 | `false` |
| `agfs` | object | RAGFS(Rust 实现的 AGFS)配置 | {} |
| `vectordb` | object | 向量库存储配置 | {} |
diff --git a/docs/zh/guides/03-deployment.md b/docs/zh/guides/03-deployment.md
index 9dff06169..8dbe4253b 100644
--- a/docs/zh/guides/03-deployment.md
+++ b/docs/zh/guides/03-deployment.md
@@ -279,10 +279,16 @@ docker compose up -d
### 多实例部署注意事项
+使用本地向量后端(`local` 或 `cuvs`)时,OpenViking 默认通过操作系统文件锁独占 `storage.workspace`。`.openviking.lock` 文件会保留在磁盘上,文件存在不代表服务正在运行;正常关闭或进程终止后,操作系统会释放锁。不要手动删除运行中服务的锁文件。
+
+远程向量后端(`http`、`volcengine`、`vikingdb`)不会获取此 workspace 锁,包括文件存放在共享 NAS 上的情况,无需设置 `storage.skip_process_lock=true`。把本地向量数据库放在 NAS 上,并不会使它支持多进程共享。
+
+使用本地向量后端从 `.openviking.pid` 旧版本升级时,必须先停止所有使用该 workspace 的旧版服务,再启动新版。新版不再根据遗留 PID 判断目录是否被占用,新旧锁机制不支持混用。
+
多实例部署时,通常建议注意这几项配置:
- 把 `server.temp_upload.default_mode` 设为 `"shared"`,这样临时上传文件可以被其他副本消费。
-- 只有在多个实例明确共享同一个 `storage.workspace` 时,才考虑把 `storage.skip_process_lock` 设为 `true`。启用后,OpenViking 不会再检查或创建 `.openviking.pid`。
+- 共享存储应使用远程向量后端。保留的 `storage.skip_process_lock` 开关只关闭本地后端的启动保护,不会使本地向量存储支持多进程共享。
- 对 QueueFS,建议通过 `storage.agfs.queuefs.db_path` 显式指定实例本地的 SQLite 路径。如果启用了 usage audit,建议通过 `server.observability.usage_audit.sqlite_path` 显式指定实例本地的 SQLite 路径,不要默认和共享 workspace 卷混用。
示例:
@@ -295,12 +301,15 @@ docker compose up -d
}
},
"storage": {
- "skip_process_lock": true
+ "vectordb": {
+ "backend": "http",
+ "url": "http://vector-db:5000"
+ }
}
}
```
-这个示例只适用于多个实例明确共享同一个 `workspace` 的场景。如果每个实例都有自己的本地 `workspace`,不要开启 `skip_process_lock`。
+这个示例使用远程 HTTP 向量服务。请将 URL 替换为实际的向量服务地址,或配置 `volcengine`、`vikingdb` 后端。
如果你还需要为 QueueFS 和 usage audit 显式指定本地 SQLite 路径,可以参考:
@@ -317,7 +326,10 @@ docker compose up -d
}
},
"storage": {
- "skip_process_lock": true,
+ "vectordb": {
+ "backend": "http",
+ "url": "http://vector-db:5000"
+ },
"agfs": {
"queuefs": {
"db_path": "/var/lib/openviking-local/queue.db"
diff --git a/examples/claude-code-memory-plugin/skills/ov-memory-doctor/SKILL.md b/examples/claude-code-memory-plugin/skills/ov-memory-doctor/SKILL.md
index 275e4c92e..abec61d5d 100644
--- a/examples/claude-code-memory-plugin/skills/ov-memory-doctor/SKILL.md
+++ b/examples/claude-code-memory-plugin/skills/ov-memory-doctor/SKILL.md
@@ -94,7 +94,7 @@ Work top-down; fix the first ✗ and rerun before chasing the next.
| `recall is pinned to the legacy /search/recall endpoint` | One 4xx mentioning "mode" pins recall for 6h | `rm ~/.openviking/state/context-face.json`. |
| `no hook log … debug is on but no hook has run` | Hooks are not being spawned at all | Registration/enablement/node problem, not a server problem. |
| `ov.conf has a top-level '<harness>' block` / `server.url is rejected` | Plugin-only keys in the server's own config — a top-level block named after any harness (`claude_code`, `codex`, `cursor`, `trae`, `trae_cn`, `zcode`, `opencode`, `dsh`, `pi`) plus `server.url`; the server refuses to start at its next restart (`Unknown config field` / `Extra inputs are not permitted`) | Move them to ovcli.conf (`plugin.<harness>`, `url`) and delete them from ov.conf. Ignore only if this ov.conf never starts a server. |
-| `nothing listens on port … — the server is not running` | Server down or never started; a stale `.openviking.pid` means it died | Start it (`openviking-server`; first time `openviking-server init`) in a terminal and read the startup output. Ask before restarting a server the user runs. |
+| `nothing listens on port … — the server is not running` | Server down or never started; the presence of `.openviking.lock` does not indicate whether the server is running | Start it (`openviking-server`; first time `openviking-server init`) in a terminal and read the startup output. Ask before restarting a server the user runs. |
| `/ready: embedding → error …` | The running server cannot call its embedding provider: recall searches nothing, commits extract nothing | Fix `embedding.*` (api_key/api_base/model) in ov.conf and restart; `openviking-server doctor` prints the provider's reply. |
| `/ready: vectordb → …` / `/ready: agfs → …` | Storage broken: disk full, two servers on one workspace, corrupted index | Server log; stop the duplicate; free disk. |
| `server is still initializing (503 /ready)` | First start downloads a local embedding model, or init is slow | Wait and rerun; if it never finishes, the server log. |
diff --git a/examples/claude-code-memory-plugin/skills/ov-memory-doctor/reference.md b/examples/claude-code-memory-plugin/skills/ov-memory-doctor/reference.md
index 6b33ca6a7..d363dcaf2 100644
--- a/examples/claude-code-memory-plugin/skills/ov-memory-doctor/reference.md
+++ b/examples/claude-code-memory-plugin/skills/ov-memory-doctor/reference.md
@@ -174,7 +174,7 @@ Startup failures (printed by the server; exit 1 unless noted):
| `Unknown config field '…' in OpenVikingConfig` / `Extra inputs are not permitted` | Unknown key — including a top-level block named after any harness (`claude_code`, `codex`, `cursor`, `trae`, `trae_cn`, `zcode`, `opencode`, `dsh`, `pi`) and `server.url`, which only the plugins read |
| `SECURITY: server.auth_mode='dev' requires server.host to be localhost` | Dev mode (no `auth_mode`, no `root_api_key`) on a non-loopback bind |
| `Invalid server.root_api_key: empty string is not allowed` | `""` instead of `null` |
-| `Another OpenViking process (PID n) is already using the data directory` | Two servers on one workspace (exit 3, `Application startup failed. Exiting.`) |
+| `Another OpenViking process is already using the data directory` | Two servers on one workspace (exit 3, `Application startup failed. Exiting.`) |
| `EmbeddingRebuildRequiredError` / `embedding dimension (…) does not match current configuration` | Embedding model changed on an existing workspace (exit 3) |
| `[Errno 48] / [Errno 98] Address already in use` | Port taken — `lsof -nP -iTCP:1933 -sTCP:LISTEN` |
| `FATAL: AUTHENTICATION HEALTH CHECK FAILED` | OIDC/LDAP backend unreachable |
diff --git a/examples/codex-memory-plugin/skills/ov-memory-doctor/SKILL.md b/examples/codex-memory-plugin/skills/ov-memory-doctor/SKILL.md
index c2276e994..1386c3825 100644
--- a/examples/codex-memory-plugin/skills/ov-memory-doctor/SKILL.md
+++ b/examples/codex-memory-plugin/skills/ov-memory-doctor/SKILL.md
@@ -101,7 +101,7 @@ Work top-down; fix the first ✗ and rerun before chasing the next.
| `no session has ever captured a turn` / idle sessions piling up | Stop hook runs but writes fail, or commits fail | Fix the Connection findings; state files are kept and replay when the server is back. |
| `MCP proxy last started against <other url>` | The proxy is a long-lived process; a changed url only takes effect after restart | Restart Codex. |
| `ov.conf has a top-level '<harness>' block` / `server.url is rejected` | Plugin-only keys in the server's own config — a top-level block named after any harness (`claude_code`, `codex`, `cursor`, `trae`, `trae_cn`, `zcode`, `opencode`, `dsh`, `pi`) plus `server.url`; the server refuses to start at its next restart (`Unknown config field` / `Extra inputs are not permitted`) | Move them to ovcli.conf (`plugin.<harness>`, `url`) and delete them from ov.conf. Ignore only if this ov.conf never starts a server. |
-| `nothing listens on port … — the server is not running` | Server down or never started; a stale `.openviking.pid` means it died | Start it (`openviking-server`; first time `openviking-server init`) in a terminal and read the startup output. Ask before restarting a server the user runs. |
+| `nothing listens on port … — the server is not running` | Server down or never started; the presence of `.openviking.lock` does not indicate whether the server is running | Start it (`openviking-server`; first time `openviking-server init`) in a terminal and read the startup output. Ask before restarting a server the user runs. |
| `/ready: embedding → error …` | The running server cannot call its embedding provider: recall searches nothing, commits extract nothing | Fix `embedding.*` (api_key/api_base/model) in ov.conf and restart; `openviking-server doctor` prints the provider's reply. |
| `/ready: vectordb → …` / `/ready: agfs → …` | Storage broken: disk full, two servers on one workspace, corrupted index | Server log; stop the duplicate; free disk. |
| `server is still initializing (503 /ready)` | First start downloads a local embedding model, or init is slow | Wait and rerun; if it never finishes, the server log. |
diff --git a/examples/codex-memory-plugin/skills/ov-memory-doctor/reference.md b/examples/codex-memory-plugin/skills/ov-memory-doctor/reference.md
index c929cb9b4..1ce749321 100644
--- a/examples/codex-memory-plugin/skills/ov-memory-doctor/reference.md
+++ b/examples/codex-memory-plugin/skills/ov-memory-doctor/reference.md
@@ -167,7 +167,7 @@ Startup failures (printed by the server; exit 1 unless noted):
| `Unknown config field '…' in OpenVikingConfig` / `Extra inputs are not permitted` | Unknown key — including a top-level block named after any harness (`claude_code`, `codex`, `cursor`, `trae`, `trae_cn`, `zcode`, `opencode`, `dsh`, `pi`) and `server.url`, which only the plugins read |
| `SECURITY: server.auth_mode='dev' requires server.host to be localhost` | Dev mode (no `auth_mode`, no `root_api_key`) on a non-loopback bind |
| `Invalid server.root_api_key: empty string is not allowed` | `""` instead of `null` |
-| `Another OpenViking process (PID n) is already using the data directory` | Two servers on one workspace (exit 3, `Application startup failed. Exiting.`) |
+| `Another OpenViking process is already using the data directory` | Two servers on one workspace (exit 3, `Application startup failed. Exiting.`) |
| `EmbeddingRebuildRequiredError` / `embedding dimension (…) does not match current configuration` | Embedding model changed on an existing workspace (exit 3) |
| `[Errno 48] / [Errno 98] Address already in use` | Port taken — `lsof -nP -iTCP:1933 -sTCP:LISTEN` |
| `FATAL: AUTHENTICATION HEALTH CHECK FAILED` | OIDC/LDAP backend unreachable |
diff --git a/openviking/service/core.py b/openviking/service/core.py
index 413ec0047..455833441 100644
--- a/openviking/service/core.py
+++ b/openviking/service/core.py
@@ -129,8 +129,7 @@ class OpenVikingService:
# State
self._initialized = False
- # Acquire the data-dir lock before encryption bootstrap so first-run root-key creation is
- # serialized with storage initialization across processes.
+ # Acquire local-storage exclusivity before encryption and storage initialization.
self._ensure_data_dir_lock_acquired()
# Resolve encryption config (root_key) BEFORE building the agfs client, so the binding
@@ -227,19 +226,23 @@ class OpenVikingService:
)
def _ensure_data_dir_lock_acquired(self) -> None:
- """Acquire the process-level data directory lock once for this service instance."""
+ """Protect embedded vector storage from concurrent processes in one workspace."""
if self._data_dir_lock_acquired:
return
- # contention (see https://github.com/volcengine/OpenViking/issues/473).
- if not self._config.storage.skip_process_lock:
+ storage = self._config.storage
+ if storage.vectordb.backend not in {"local", "cuvs"}:
+ return
+
+ if not storage.skip_process_lock:
from openviking.utils.process_lock import acquire_data_dir_lock
- self._data_dir_lock_path = acquire_data_dir_lock(self._config.storage.workspace)
+ self._data_dir_lock_path = acquire_data_dir_lock(storage.workspace)
else:
logger.warning(
- "Skipping workspace process lock for '%s'; multi-process access may corrupt data",
- self._config.storage.workspace,
+ "Skipping workspace process lock for '%s'; multi-process access may corrupt "
+ "embedded vector storage",
+ storage.workspace,
)
self._data_dir_lock_acquired = True
@@ -610,9 +613,8 @@ class OpenVikingService:
if get_service_or_none() is self:
set_service(None)
- # The PID lock protects every live workspace resource above. If any
- # cleanup step failed or was cancelled, keep the lock so another
- # process cannot enter while this service may still own storage state.
+ # Keep embedded storage exclusive until cleanup succeeds. If cleanup
+ # fails or is cancelled, this service may still own live storage state.
self._release_data_dir_lock()
logger.info("OpenVikingService closed")
diff --git a/openviking/utils/process_lock.py b/openviking/utils/process_lock.py
index 288f1c677..ee8ebe052 100644
--- a/openviking/utils/process_lock.py
+++ b/openviking/utils/process_lock.py
@@ -1,12 +1,12 @@
# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.
# SPDX-License-Identifier: AGPL-3.0
-"""PID-based advisory lock for data directory exclusivity.
+"""OS-backed file lock for exclusive access to a workspace.
-Prevents multiple OpenViking processes from contending for the same data
-directory, which causes silent failures in AGFS and VectorDB.
+The file stays on disk; only the held OS lock indicates ownership. All instances
+must use this protocol: stop older PID-lock-based servers before upgrading.
"""
-import atexit
+import errno
import os
import sys
import threading
@@ -15,171 +15,89 @@ from openviking_cli.utils import get_logger
logger = get_logger(__name__)
-LOCK_FILENAME = ".openviking.pid"
+LOCK_FILENAME = ".openviking.lock"
-# A PID file protects the whole process, while multiple service instances may
-# legitimately share that process and workspace. Keep process-local ownership
-# counts so closing one service cannot expose another live service to a second
-# process. The file remains the cross-process source of truth.
+# Multiple services in one process can share a workspace. Hold one descriptor
+# until the last service closes; process exit also closes it, including crashes.
_LOCK_STATE_GUARD = threading.Lock()
-_LOCK_REF_COUNTS: dict[str, int] = {}
-_ATEXIT_REGISTERED: set[str] = set()
+_LOCKS: dict[str, tuple[int, int]] = {} # normalized path -> (descriptor, references)
class DataDirectoryLocked(RuntimeError):
- """Raised when another OpenViking process holds the data directory lock."""
+ """Raised when another OpenViking process holds the workspace lock."""
-def _normalize_lock_path(lock_path: str) -> str:
- """Return one process-local identity for aliases of the same PID file."""
- return os.path.realpath(os.path.abspath(lock_path))
-
-
-def _read_pid_file(lock_path: str) -> int:
- """Read PID from lock file. Returns 0 if unreadable."""
- try:
- with open(lock_path) as f:
- return int(f.read().strip())
- except (OSError, ValueError):
- return 0
-
-
-def _is_pid_alive(pid: int) -> bool:
- """Check whether a process with the given PID is still running."""
- if pid <= 0:
- return False
- if sys.platform == "win32":
- import _winapi
-
- # Unlike POSIX, os.kill(pid, 0) sends CTRL_C_EVENT on Windows.
- try:
- handle = _winapi.OpenProcess(_winapi.SYNCHRONIZE, False, pid)
- except OSError as exc:
- # ERROR_INVALID_PARAMETER confirms there is no such PID. Access
- # denied and other query failures must not discard a live lock.
- return exc.winerror != 87
- try:
- return _winapi.WaitForSingleObject(handle, 0) != _winapi.WAIT_OBJECT_0
- except OSError:
- return True
- finally:
- _winapi.CloseHandle(handle)
-
- try:
- os.kill(pid, 0)
- except ProcessLookupError:
- return False
- except PermissionError:
- # Process exists but we can't signal it.
- pass
-
- # PID exists, but on Linux PIDs are recycled. Verify this is actually
- # an OpenViking process by checking /proc/{pid}/cmdline to avoid false
- # positives from PID reuse (see issue #1088).
- if sys.platform.startswith("linux"):
- try:
- with open(f"/proc/{pid}/cmdline", "rb") as f:
- cmdline = f.read().decode("utf-8", errors="replace").lower()
- if "openviking" not in cmdline and "openviking-server" not in cmdline:
- logger.info(
- "PID %d is alive but not an OpenViking process (cmdline: %.100s). "
- "Assuming stale lock from recycled PID.",
- pid,
- cmdline[:100],
- )
- return False
- except OSError:
- # /proc not available or process exited between kill and open
- pass
-
- return True
-
-
-def _remove_owned_lock(lock_path: str, owner_pid: int) -> None:
- """Remove *lock_path* only while it still belongs to *owner_pid*."""
- try:
- if os.path.isfile(lock_path) and _read_pid_file(lock_path) == owner_pid:
- os.remove(lock_path)
- except OSError:
- pass
-
-
-def release_data_dir_lock(lock_path: str, *, pid: int | None = None) -> None:
- """Release a data-directory lock when it is still owned by *pid*.
-
- The ownership check keeps a delayed cleanup callback from removing a lock
- that a replacement process has already acquired.
- """
- owner_pid = os.getpid() if pid is None else pid
- normalized_path = _normalize_lock_path(lock_path)
-
+def release_data_dir_lock(lock_path: str) -> None:
+ """Release this process's lock after its last workspace user has closed."""
+ lock_path = os.path.realpath(lock_path)
with _LOCK_STATE_GUARD:
- holder_count = _LOCK_REF_COUNTS.get(normalized_path, 0)
- if holder_count > 1:
- _LOCK_REF_COUNTS[normalized_path] = holder_count - 1
+ held = _LOCKS.get(lock_path)
+ if held is None:
+ return
+ descriptor, references = held
+ if references > 1:
+ _LOCKS[lock_path] = (descriptor, references - 1)
return
- if holder_count == 1:
- _LOCK_REF_COUNTS.pop(normalized_path, None)
- # A zero count is retained as a compatibility path for callers that
- # acquired the lock before this module state was initialized/reloaded.
- _remove_owned_lock(normalized_path, owner_pid)
+ del _LOCKS[lock_path]
+ try:
+ if sys.platform == "win32":
+ import msvcrt
+ msvcrt.locking(descriptor, msvcrt.LK_UNLCK, 1)
+ finally:
+ os.close(descriptor)
+ # Never unlink the file: contenders must all lock the same file, even
+ # when one has opened it before the previous owner releases its lock.
-def acquire_data_dir_lock(data_dir: str) -> str:
- """Acquire an advisory PID lock on *data_dir*.
- Returns the path to the lock file on success.
+def acquire_data_dir_lock(data_dir: str) -> str:
+ """Hold an exclusive, non-blocking OS lock until release or process exit.
- Raises ``DataDirectoryLocked`` if another live process already holds the
- lock, with a message that explains the situation and suggests HTTP mode.
- Raises ``OSError`` when the PID file cannot be created or updated; callers
- must never continue as if an exclusivity lock had been acquired.
+ Returns the lock path. Contention raises ``DataDirectoryLocked``; filesystem
+ or unsupported-lock errors propagate instead of allowing an unlocked start.
"""
- normalized_data_dir = os.path.realpath(os.path.abspath(data_dir))
- lock_path = _normalize_lock_path(os.path.join(normalized_data_dir, LOCK_FILENAME))
- my_pid = os.getpid()
-
+ data_dir = os.path.realpath(data_dir)
+ lock_path = os.path.realpath(os.path.join(data_dir, LOCK_FILENAME))
with _LOCK_STATE_GUARD:
- existing_pid = _read_pid_file(lock_path)
- if existing_pid and existing_pid != my_pid and _is_pid_alive(existing_pid):
- raise DataDirectoryLocked(
- f"Another OpenViking process (PID {existing_pid}) is already using "
- f"the data directory '{data_dir}'. Running multiple OpenViking "
- f"instances on the same data directory causes silent storage "
- f"contention and data corruption.\n\n"
- f"To fix this, use one of these approaches:\n"
- f" 1. Start a single OpenViking server and connect clients over HTTP "
- f"(recommended for multi-session hosts)\n"
- f" 2. Use separate data directories for each instance\n"
- f" 3. Stop the other process (PID {existing_pid}) first"
- )
-
- # Write our PID (overwrites stale lock from a dead process). Reentrant
- # acquisitions still refresh the file in case an external actor
- # removed it while this process remained alive.
+ held = _LOCKS.get(lock_path)
+ if held is not None:
+ descriptor, references = held
+ _LOCKS[lock_path] = (descriptor, references + 1)
+ return lock_path
+
+ os.makedirs(data_dir, exist_ok=True)
+ # os.open creates a non-inheritable descriptor, so exec/spawn children
+ # cannot keep the workspace locked after this server exits.
+ descriptor = os.open(lock_path, os.O_CREAT | os.O_RDWR, 0o600)
try:
- os.makedirs(normalized_data_dir, exist_ok=True)
- with open(lock_path, "w") as f:
- f.write(str(my_pid))
- except OSError as exc:
- logger.warning("Could not write PID lock %s: %s", lock_path, exc)
- raise
-
- _LOCK_REF_COUNTS[lock_path] = _LOCK_REF_COUNTS.get(lock_path, 0) + 1
+ if sys.platform == "win32":
+ import msvcrt
- # One force-cleanup callback per path is enough. At interpreter exit
- # every in-process holder is terminal, so refcounts must not prevent
- # cleanup.
- if lock_path not in _ATEXIT_REGISTERED:
+ # Windows can lock a byte beyond EOF; no file content is needed.
+ msvcrt.locking(descriptor, msvcrt.LK_NBLCK, 1)
+ else:
+ import fcntl
- def _cleanup(*_args: object) -> None:
- with _LOCK_STATE_GUARD:
- _LOCK_REF_COUNTS.pop(lock_path, None)
- _remove_owned_lock(lock_path, my_pid)
+ fcntl.flock(descriptor, fcntl.LOCK_EX | fcntl.LOCK_NB)
+ except OSError as exc:
+ os.close(descriptor)
+ if exc.errno not in (errno.EACCES, errno.EAGAIN):
+ raise
+ raise DataDirectoryLocked(
+ f"Another OpenViking process is already using the data directory '{data_dir}'. "
+ "Running multiple OpenViking instances on the same data directory causes "
+ "storage contention and data corruption.\n\n"
+ "To fix this, use one of these approaches:\n"
+ " 1. Start a single OpenViking server and connect clients over HTTP\n"
+ " 2. Use separate data directories for each instance\n"
+ " 3. Stop the other OpenViking process first"
+ ) from exc
+ except BaseException:
+ os.close(descriptor)
+ raise
- atexit.register(_cleanup)
- _ATEXIT_REGISTERED.add(lock_path)
+ _LOCKS[lock_path] = (descriptor, 1)
- logger.debug("Acquired data directory lock: %s (PID %d)", lock_path, my_pid)
+ logger.debug("Acquired data directory lock: %s", lock_path)
return lock_path
diff --git a/openviking_cli/utils/config/storage_config.py b/openviking_cli/utils/config/storage_config.py
index 2c10cf20e..4f447e1f4 100644
--- a/openviking_cli/utils/config/storage_config.py
+++ b/openviking_cli/utils/config/storage_config.py
@@ -26,8 +26,9 @@ class StorageConfig(BaseModel):
skip_process_lock: bool = Field(
default=False,
description=(
- "Skip the startup PID lock for the workspace directory. Use only when you "
- "explicitly accept the risk of multi-process storage contention."
+ "Skip the workspace file lock for embedded vector backends ('local', 'cuvs'). "
+ "Other backends do not acquire this lock. Use only when you explicitly accept "
+ "the risk of multi-process contention on embedded vector storage."
),
)
diff --git a/tests/misc/test_process_lock.py b/tests/misc/test_process_lock.py
deleted file mode 100644
index 8fbbf5a36..000000000
--- a/tests/misc/test_process_lock.py
+++ /dev/null
@@ -1,61 +0,0 @@
-"""Tests for PID-based advisory lock on data directories."""
-
-import os
-import tempfile
-
-from openviking.utils.process_lock import (
- LOCK_FILENAME,
- DataDirectoryLocked,
- acquire_data_dir_lock,
-)
-
-
-class TestProcessLock:
- def test_acquires_lock_on_empty_dir(self):
- with tempfile.TemporaryDirectory() as tmpdir:
- lock_path = acquire_data_dir_lock(tmpdir)
- assert os.path.isfile(lock_path)
- with open(lock_path) as f:
- assert int(f.read().strip()) == os.getpid()
-
- def test_same_pid_can_reacquire(self):
- with tempfile.TemporaryDirectory() as tmpdir:
- acquire_data_dir_lock(tmpdir)
- # Should not raise when same process re-acquires.
- acquire_data_dir_lock(tmpdir)
-
- def test_stale_lock_is_replaced(self):
- with tempfile.TemporaryDirectory() as tmpdir:
- lock_path = os.path.join(tmpdir, LOCK_FILENAME)
- # Write a PID that does not exist (very high number).
- with open(lock_path, "w") as f:
- f.write("999999999")
- # Should succeed because the PID is dead.
- acquire_data_dir_lock(tmpdir)
- with open(lock_path) as f:
- assert int(f.read().strip()) == os.getpid()
-
- def test_live_pid_blocks_acquisition(self):
- with tempfile.TemporaryDirectory() as tmpdir:
- lock_path = os.path.join(tmpdir, LOCK_FILENAME)
- # PID 1 (init/launchd) is always alive.
- with open(lock_path, "w") as f:
- f.write("1")
- try:
- acquire_data_dir_lock(tmpdir)
- raise AssertionError("Should have raised DataDirectoryLocked")
- except DataDirectoryLocked as exc:
- assert "PID 1" in str(exc)
- assert "connect clients over HTTP" in str(exc)
-
- def test_error_message_includes_remediation(self):
- with tempfile.TemporaryDirectory() as tmpdir:
- lock_path = os.path.join(tmpdir, LOCK_FILENAME)
- with open(lock_path, "w") as f:
- f.write("1")
- try:
- acquire_data_dir_lock(tmpdir)
- except DataDirectoryLocked as exc:
- msg = str(exc)
- assert "OpenViking server" in msg
- assert "separate data directories" in msg
diff --git a/tests/unit/service/test_core_encryption_startup.py b/tests/unit/service/test_core_encryption_startup.py
index 539200de8..0d0ba20c5 100644
--- a/tests/unit/service/test_core_encryption_startup.py
+++ b/tests/unit/service/test_core_encryption_startup.py
@@ -11,6 +11,7 @@ import pytest
from openviking.service.core import OpenVikingService
from openviking.utils.agfs_utils import RagfsBindingConfig
+from openviking.utils.process_lock import LOCK_FILENAME
class _FakeCacheConfig:
@@ -100,19 +101,24 @@ async def test_build_ragfs_binding_config_works_inside_running_event_loop(monkey
assert isinstance(service._encryptor, _FakeEncryptor)
-def test_ensure_data_dir_lock_acquired_once(monkeypatch, tmp_path):
[email protected]("backend", ["local", "cuvs"])
+def test_ensure_data_dir_lock_acquired_once(monkeypatch, tmp_path, backend):
"""Acquire the data-dir lock once before startup encryption bootstrap."""
calls = []
def _acquire(path: str) -> str:
calls.append(path)
- return str(tmp_path / ".openviking.pid")
+ return str(tmp_path / LOCK_FILENAME)
monkeypatch.setattr("openviking.utils.process_lock.acquire_data_dir_lock", _acquire)
service = OpenVikingService.__new__(OpenVikingService)
service._config = SimpleNamespace(
- storage=SimpleNamespace(workspace=str(tmp_path), skip_process_lock=False)
+ storage=SimpleNamespace(
+ workspace=str(tmp_path),
+ skip_process_lock=False,
+ vectordb=SimpleNamespace(backend=backend),
+ )
)
service._data_dir_lock_acquired = False
service._data_dir_lock_path = None
@@ -121,36 +127,41 @@ def test_ensure_data_dir_lock_acquired_once(monkeypatch, tmp_path):
service._ensure_data_dir_lock_acquired()
assert calls == [str(tmp_path)]
- assert service._data_dir_lock_path == str(tmp_path / ".openviking.pid")
+ assert service._data_dir_lock_path == str(tmp_path / LOCK_FILENAME)
-def test_ensure_data_dir_lock_respects_skip_process_lock(monkeypatch, tmp_path):
- """Skip lock acquisition entirely when storage.skip_process_lock is enabled."""
-
- calls = []
+ "backend,skip_process_lock",
+ [("local", True), ("cuvs", True), ("http", False), ("volcengine", False), ("vikingdb", False)],
+)
+def test_ensure_data_dir_lock_skips_shared_backends_and_explicit_opt_out(
+ monkeypatch, tmp_path, backend, skip_process_lock
+):
+ """Shared backends and explicit opt-out must never attempt a workspace lock."""
def _acquire(path: str) -> str:
- calls.append(path)
- return str(tmp_path / ".openviking.pid")
+ pytest.fail("Shared backends and explicit opt-out must not access the workspace lock")
monkeypatch.setattr("openviking.utils.process_lock.acquire_data_dir_lock", _acquire)
service = OpenVikingService.__new__(OpenVikingService)
service._config = SimpleNamespace(
- storage=SimpleNamespace(workspace=str(tmp_path), skip_process_lock=True)
+ storage=SimpleNamespace(
+ workspace=str(tmp_path),
+ skip_process_lock=skip_process_lock,
+ vectordb=SimpleNamespace(backend=backend),
+ )
)
service._data_dir_lock_acquired = False
service._data_dir_lock_path = None
service._ensure_data_dir_lock_acquired()
- assert calls == []
- assert service._data_dir_lock_acquired is True
assert service._data_dir_lock_path is None
def test_release_data_dir_lock_resets_service_state(monkeypatch, tmp_path):
calls = []
- lock_path = str(tmp_path / ".openviking.pid")
+ lock_path = str(tmp_path / LOCK_FILENAME)
monkeypatch.setattr("openviking.utils.process_lock.release_data_dir_lock", calls.append)
service = OpenVikingService.__new__(OpenVikingService)
service._data_dir_lock_acquired = True
diff --git a/tests/unit/test_process_lock.py b/tests/unit/test_process_lock.py
index 42848815e..bd4700a14 100644
--- a/tests/unit/test_process_lock.py
+++ b/tests/unit/test_process_lock.py
@@ -1,13 +1,13 @@
# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.
# SPDX-License-Identifier: AGPL-3.0
-"""Tests for PID-based process lock utility."""
+"""Workspace exclusivity and recovery contracts, exercised with real processes."""
+import errno
+import multiprocessing
import os
+import subprocess
import sys
-from pathlib import Path
-from types import SimpleNamespace
-from unittest.mock import Mock
import pytest
@@ -15,390 +15,156 @@ import openviking.utils.process_lock as process_lock_module
from openviking.utils.process_lock import (
LOCK_FILENAME,
DataDirectoryLocked,
- _is_pid_alive,
- _read_pid_file,
acquire_data_dir_lock,
release_data_dir_lock,
)
-class TestReadPidFile:
- """Test _read_pid_file function."""
-
- def test_read_valid_pid(self, tmp_path: Path):
- """Test reading a valid PID from file."""
- lock_file = tmp_path / LOCK_FILENAME
- lock_file.write_text("12345")
-
- pid = _read_pid_file(str(lock_file))
- assert pid == 12345
-
- def test_read_nonexistent_file(self, tmp_path: Path):
- """Test reading from nonexistent file returns 0."""
- lock_file = tmp_path / "nonexistent.pid"
-
- pid = _read_pid_file(str(lock_file))
- assert pid == 0
-
- def test_read_invalid_pid(self, tmp_path: Path):
- """Test reading invalid PID returns 0."""
- lock_file = tmp_path / LOCK_FILENAME
- lock_file.write_text("not_a_number")
-
- pid = _read_pid_file(str(lock_file))
- assert pid == 0
-
- def test_read_empty_file(self, tmp_path: Path):
- """Test reading empty file returns 0."""
- lock_file = tmp_path / LOCK_FILENAME
- lock_file.write_text("")
-
- pid = _read_pid_file(str(lock_file))
- assert pid == 0
-
- def test_read_pid_with_whitespace(self, tmp_path: Path):
- """Test reading PID with leading/trailing whitespace."""
- lock_file = tmp_path / LOCK_FILENAME
- lock_file.write_text(" 12345 \n")
-
- pid = _read_pid_file(str(lock_file))
- assert pid == 12345
-
- def test_read_pid_with_newline(self, tmp_path: Path):
- """Test reading PID with newline."""
- lock_file = tmp_path / LOCK_FILENAME
- lock_file.write_text("12345\n")
-
- pid = _read_pid_file(str(lock_file))
- assert pid == 12345
-
-
-class TestIsPidAlive:
- """Test _is_pid_alive function."""
-
- def test_current_pid_is_alive(self):
- """Test that current process PID is detected as alive."""
- current_pid = os.getpid()
- assert _is_pid_alive(current_pid) is True
-
- def test_pid_1_is_alive(self):
- """Test that PID 1 (init) is typically alive."""
- # PID 1 is usually init process on Linux
- assert _is_pid_alive(1) is True
-
- def test_nonexistent_pid_not_alive(self):
- """Test that nonexistent PID is not alive."""
- # Use a very high PID that's unlikely to exist
- assert _is_pid_alive(999999) is False
-
- def test_pid_zero_not_alive(self):
- """Test that PID 0 is not alive."""
- assert _is_pid_alive(0) is False
-
- def test_negative_pid_not_alive(self):
- """Test that negative PID is not alive."""
- assert _is_pid_alive(-1) is False
-
- @pytest.mark.parametrize(
- "open_error, wait_result, wait_error, expected",
+def _probe_lock(workspace):
+ return subprocess.run(
[
- (None, 258, None, True), # WAIT_TIMEOUT: still running
- (None, 0, None, False), # WAIT_OBJECT_0: exited
- (87, None, None, False), # no such PID
- (5, None, None, True), # access denied
- (6, None, None, True), # unknown query failure
- (None, None, OSError("wait failed"), True),
+ sys.executable,
+ "-c",
+ "import sys\n"
+ "from openviking.utils.process_lock import (\n"
+ " acquire_data_dir_lock, release_data_dir_lock, DataDirectoryLocked)\n"
+ "try:\n"
+ " path = acquire_data_dir_lock(sys.argv[1])\n"
+ "except DataDirectoryLocked as exc:\n"
+ " print(exc)\n"
+ " sys.exit(2)\n"
+ "release_data_dir_lock(path)\n",
+ str(workspace),
],
+ capture_output=True,
+ text=True,
+ timeout=20,
)
- def test_windows_probe_never_signals(
- self, monkeypatch, open_error, wait_result, wait_error, expected
- ):
- api = SimpleNamespace(
- SYNCHRONIZE=0x100000,
- WAIT_OBJECT_0=0,
- OpenProcess=Mock(return_value=123),
- WaitForSingleObject=Mock(return_value=wait_result, side_effect=wait_error),
- CloseHandle=Mock(),
- )
- if open_error is not None:
- error = OSError("open failed")
- error.winerror = open_error
- api.OpenProcess.side_effect = error
- with monkeypatch.context() as patch:
- patch.setattr(process_lock_module.sys, "platform", "win32")
- patch.setitem(sys.modules, "_winapi", api)
- patch.setattr(os, "kill", Mock(side_effect=AssertionError("must not signal")))
- assert _is_pid_alive(os.getpid()) is expected
- api.OpenProcess.assert_called_once_with(api.SYNCHRONIZE, False, os.getpid())
- if open_error is None:
- api.WaitForSingleObject.assert_called_once_with(123, 0)
- api.CloseHandle.assert_called_once_with(123)
- else:
- api.WaitForSingleObject.assert_not_called()
- api.CloseHandle.assert_not_called()
-
- @pytest.mark.skipif(sys.platform != "win32", reason="requires native Windows APIs")
- def test_windows_native_current_pid_never_signals(self, monkeypatch):
- monkeypatch.setattr(os, "kill", Mock(side_effect=AssertionError("must not signal")))
- assert _is_pid_alive(os.getpid()) is True
-
- def test_non_windows_system_error_bubbles_up(self, monkeypatch):
- """Non-Windows should not downgrade unexpected SystemError values."""
- def _raise_system_error(_pid: int, _sig: int) -> None:
- raise SystemError("unexpected failure")
- monkeypatch.setattr(process_lock_module.sys, "platform", "linux")
- monkeypatch.setattr(process_lock_module.os, "kill", _raise_system_error)
-
- with pytest.raises(SystemError):
- _is_pid_alive(12345)
+def _contend_for_lock(workspace, start, release, results):
+ start.wait(timeout=20)
+ try:
+ lock_path = acquire_data_dir_lock(workspace)
+ except DataDirectoryLocked:
+ results.put((os.getpid(), "locked"))
+ return
+ try:
+ results.put((os.getpid(), "acquired"))
+ if not release.poll(30):
+ raise TimeoutError("lock owner was not released")
+ release.recv()
+ finally:
+ release.close()
+ release_data_dir_lock(lock_path)
class TestAcquireDataDirLock:
- """Test acquire_data_dir_lock function."""
-
- def test_acquire_creates_lock_file(self, tmp_path: Path):
- """Test acquiring lock creates lock file."""
- lock_path = acquire_data_dir_lock(str(tmp_path))
-
- assert lock_path == str(tmp_path / LOCK_FILENAME)
- assert (tmp_path / LOCK_FILENAME).exists()
-
- def test_acquire_writes_current_pid(self, tmp_path: Path):
- """Test lock file contains current PID."""
- acquire_data_dir_lock(str(tmp_path))
- my_pid = os.getpid()
-
- stored_pid = int((tmp_path / LOCK_FILENAME).read_text().strip())
- assert stored_pid == my_pid
-
- def test_acquire_same_pid_succeeds(self, tmp_path: Path):
- """Test acquiring lock with same PID succeeds."""
- my_pid = os.getpid()
- (tmp_path / LOCK_FILENAME).write_text(str(my_pid))
-
- # Should succeed since it's our own PID
- lock_path = acquire_data_dir_lock(str(tmp_path))
- assert lock_path == str(tmp_path / LOCK_FILENAME)
-
- def test_acquire_with_stale_lock_succeeds(self, tmp_path: Path):
- """Test acquiring lock with stale (dead process) lock succeeds."""
- # Write a PID that doesn't exist
- (tmp_path / LOCK_FILENAME).write_text("999999")
-
- lock_path = acquire_data_dir_lock(str(tmp_path))
- assert lock_path == str(tmp_path / LOCK_FILENAME)
-
- def test_acquire_with_live_process_raises(self, tmp_path: Path):
- """Test acquiring lock with live process raises DataDirectoryLocked."""
- # Use PID 1 (init) which is typically alive
- (tmp_path / LOCK_FILENAME).write_text("1")
-
- with pytest.raises(DataDirectoryLocked) as exc_info:
- acquire_data_dir_lock(str(tmp_path))
-
- assert "Another OpenViking process" in str(exc_info.value)
- assert "PID 1" in str(exc_info.value)
-
- def test_acquire_creates_directory(self, tmp_path: Path):
- """Test acquiring lock creates directory if it doesn't exist."""
- new_dir = tmp_path / "new_subdir"
-
- acquire_data_dir_lock(str(new_dir))
- assert new_dir.exists()
- assert (new_dir / LOCK_FILENAME).exists()
-
- def test_acquire_write_failure_is_not_reported_as_success(self, tmp_path: Path, monkeypatch):
- """A failed PID-file write must fail closed instead of claiming exclusivity."""
-
- def _deny_makedirs(*_args, **_kwargs) -> None:
- raise PermissionError("read-only workspace")
-
- workspace = tmp_path / "missing"
- monkeypatch.setattr(process_lock_module.os, "makedirs", _deny_makedirs)
-
- with pytest.raises(PermissionError, match="read-only workspace"):
- acquire_data_dir_lock(str(workspace))
-
- assert not (workspace / LOCK_FILENAME).exists()
-
- def test_error_message_suggests_http_server(self, tmp_path: Path):
- """Test error message suggests using one HTTP server."""
- (tmp_path / LOCK_FILENAME).write_text("1")
-
- with pytest.raises(DataDirectoryLocked) as exc_info:
- acquire_data_dir_lock(str(tmp_path))
-
- error_msg = str(exc_info.value)
- assert "OpenViking server" in error_msg
- assert "connect clients over HTTP" in error_msg
-
- def test_error_message_shows_pid(self, tmp_path: Path):
- """Test error message shows conflicting PID."""
- (tmp_path / LOCK_FILENAME).write_text("1")
-
- with pytest.raises(DataDirectoryLocked) as exc_info:
- acquire_data_dir_lock(str(tmp_path))
-
- error_msg = str(exc_info.value)
- assert "PID 1" in error_msg
+ @pytest.mark.parametrize("failure", ["open", "lock"])
+ def test_filesystem_errors_fail_acquisition(self, tmp_path, monkeypatch, failure):
+ """Filesystem permission and unsupported-lock errors must fail startup."""
+ error = PermissionError(errno.EACCES, "read-only workspace")
+ if failure == "open":
+ target, name = process_lock_module.os, "open"
+ else:
+ error = OSError(errno.ENOTSUP, "locking unsupported")
+ if sys.platform == "win32":
+ import msvcrt
- def test_error_message_shows_directory(self, tmp_path: Path):
- """Test error message shows directory path."""
- (tmp_path / LOCK_FILENAME).write_text("1")
+ target, name = msvcrt, "locking"
+ else:
+ import fcntl
- with pytest.raises(DataDirectoryLocked) as exc_info:
- acquire_data_dir_lock(str(tmp_path))
+ target, name = fcntl, "flock"
- error_msg = str(exc_info.value)
- assert str(tmp_path) in error_msg
+ def fail(*args, **kwargs):
+ raise error
- @pytest.mark.parametrize("winerror", [87, 5])
- def test_windows_lock_reclaimed_only_for_missing_pid(self, tmp_path, monkeypatch, winerror):
- lock_file = tmp_path / LOCK_FILENAME
- lock_file.write_text("12345")
- error = OSError("process query failed")
- error.winerror = winerror
- api = SimpleNamespace(SYNCHRONIZE=0x100000, OpenProcess=Mock(side_effect=error))
with monkeypatch.context() as patch:
- patch.setattr(process_lock_module.sys, "platform", "win32")
- patch.setitem(sys.modules, "_winapi", api)
- patch.setattr(os, "kill", Mock(side_effect=AssertionError("must not signal")))
- if winerror == 87:
+ patch.setattr(target, name, fail)
+ with pytest.raises(OSError) as raised:
acquire_data_dir_lock(str(tmp_path))
- assert int(lock_file.read_text()) == os.getpid()
- else:
- with pytest.raises(DataDirectoryLocked):
- acquire_data_dir_lock(str(tmp_path))
- assert lock_file.read_text() == "12345"
-
-
-class TestAcquireDataDirLockEdgeCases:
- """Test edge cases for acquire_data_dir_lock."""
-
- def test_acquire_nested_directory(self, tmp_path: Path):
- """Test acquiring lock in nested directory."""
- nested = tmp_path / "a" / "b" / "c"
-
- acquire_data_dir_lock(str(nested))
- assert nested.exists()
- assert (nested / LOCK_FILENAME).exists()
-
- def test_acquire_overwrites_stale_lock(self, tmp_path: Path):
- """Test that acquiring overwrites stale lock with current PID."""
- my_pid = os.getpid()
- (tmp_path / LOCK_FILENAME).write_text("999999")
+ assert raised.value is error
- acquire_data_dir_lock(str(tmp_path))
-
- stored_pid = int((tmp_path / LOCK_FILENAME).read_text().strip())
- assert stored_pid == my_pid
-
- def test_lock_filename_constant(self):
- """Test LOCK_FILENAME constant is correct."""
- assert LOCK_FILENAME == ".openviking.pid"
-
- def test_acquire_with_pathlib_path(self, tmp_path: Path):
- """Test acquiring with pathlib.Path instead of string."""
+ # Failed acquisition must not leave a process-local owner behind.
lock_path = acquire_data_dir_lock(str(tmp_path))
- assert lock_path == str(tmp_path / LOCK_FILENAME)
-
- def test_acquire_permissions_on_readonly_parent(self, tmp_path: Path):
- """Test handling when parent directory is read-only."""
- # This test may not work on all systems
- # Just verify it doesn't crash
- lock_path = acquire_data_dir_lock(str(tmp_path))
- assert lock_path.endswith(LOCK_FILENAME)
+ try:
+ result = _probe_lock(tmp_path)
+ assert result.returncode == 2, result.stderr
+ finally:
+ release_data_dir_lock(lock_path)
+ assert _probe_lock(tmp_path).returncode == 0
class TestReleaseDataDirLock:
- """Test explicit process-lock release used by service shutdown."""
-
- def test_release_removes_owned_lock(self, tmp_path: Path):
- lock_path = acquire_data_dir_lock(str(tmp_path))
-
- release_data_dir_lock(lock_path)
-
- assert not (tmp_path / LOCK_FILENAME).exists()
-
- def test_release_preserves_replacement_owner(self, tmp_path: Path):
- lock_path = acquire_data_dir_lock(str(tmp_path))
- (tmp_path / LOCK_FILENAME).write_text("999999")
-
- release_data_dir_lock(lock_path)
-
- assert (tmp_path / LOCK_FILENAME).read_text() == "999999"
-
- def test_release_is_idempotent(self, tmp_path: Path):
- lock_path = acquire_data_dir_lock(str(tmp_path))
-
- release_data_dir_lock(lock_path)
- release_data_dir_lock(lock_path)
-
- assert not (tmp_path / LOCK_FILENAME).exists()
-
- def test_release_keeps_lock_until_last_same_process_holder(self, tmp_path: Path):
- lock_path = acquire_data_dir_lock(str(tmp_path))
- assert acquire_data_dir_lock(str(tmp_path)) == lock_path
-
- release_data_dir_lock(lock_path)
-
- assert (tmp_path / LOCK_FILENAME).read_text() == str(os.getpid())
-
- release_data_dir_lock(lock_path)
-
- assert not (tmp_path / LOCK_FILENAME).exists()
-
- def test_symlink_alias_shares_the_same_process_local_refcount(self, tmp_path: Path):
- """Workspace aliases must not let one service release another's PID lock."""
+ @pytest.mark.parametrize("use_alias", [False, True])
+ def test_symlink_alias_shares_the_same_process_local_refcount(self, tmp_path, use_alias):
workspace = tmp_path / "workspace"
workspace.mkdir()
- alias = tmp_path / "workspace-alias"
- try:
- alias.symlink_to(workspace, target_is_directory=True)
- except OSError as exc:
- pytest.skip(f"directory symlinks are unavailable: {exc}")
+ alias = workspace
+ if use_alias:
+ alias = tmp_path / "alias"
+ try:
+ alias.symlink_to(workspace, target_is_directory=True)
+ except OSError as exc:
+ pytest.skip(f"directory symlinks are unavailable: {exc}")
lock_path = acquire_data_dir_lock(str(workspace))
- assert acquire_data_dir_lock(str(alias)) == lock_path
-
- release_data_dir_lock(lock_path)
- assert (workspace / LOCK_FILENAME).read_text() == str(os.getpid())
+ try:
+ assert acquire_data_dir_lock(str(alias)) == lock_path
+ release_data_dir_lock(lock_path)
+ result = _probe_lock(workspace)
+ assert result.returncode == 2, result.stderr
+ assert "connect clients over HTTP" in result.stdout
+ assert str(workspace) in result.stdout
+ finally:
+ release_data_dir_lock(lock_path)
+ release_data_dir_lock(lock_path)
- release_data_dir_lock(lock_path)
- assert not (workspace / LOCK_FILENAME).exists()
+ assert (workspace / LOCK_FILENAME).exists()
+ assert _probe_lock(workspace).returncode == 0
class TestProcessLockIntegration:
- """Integration tests for process lock."""
-
- def test_multiple_acquires_same_process(self, tmp_path: Path):
- """Test multiple acquires from same process."""
- lock_path1 = acquire_data_dir_lock(str(tmp_path))
- lock_path2 = acquire_data_dir_lock(str(tmp_path))
-
- assert lock_path1 == lock_path2
-
- def test_lock_file_cleanup_on_exit_simulation(self, tmp_path: Path):
- """Test that lock file would be cleaned up on exit."""
- acquire_data_dir_lock(str(tmp_path))
- assert (tmp_path / LOCK_FILENAME).exists()
-
- # Note: Actual cleanup happens via atexit, which we can't easily test
- # in unit tests without process termination
-
- def test_reentrant_lock_same_pid(self, tmp_path: Path):
- """Test that same PID can re-acquire lock."""
- my_pid = os.getpid()
-
- # First acquire
- lock_path1 = acquire_data_dir_lock(str(tmp_path))
-
- # Write PID again
- (tmp_path / LOCK_FILENAME).write_text(str(my_pid))
-
- # Second acquire should succeed
- lock_path2 = acquire_data_dir_lock(str(tmp_path))
-
- assert lock_path1 == lock_path2
+ @pytest.mark.parametrize("crash", [False, True])
+ def test_concurrent_start_and_exit_release_lock(self, tmp_path, crash):
+ """Only one simultaneous starter enters; graceful exit and kill release it."""
+ ctx = multiprocessing.get_context("spawn")
+ start, results = ctx.Barrier(4), ctx.Queue()
+ pipes = [ctx.Pipe(duplex=False) for _ in range(4)]
+ processes = [
+ ctx.Process(target=_contend_for_lock, args=(str(tmp_path), start, reader, results))
+ for reader, _ in pipes
+ ]
+ try:
+ for process in processes:
+ process.start()
+ outcomes = [results.get(timeout=20) for _ in processes]
+ owners = [pid for pid, status in outcomes if status == "acquired"]
+ assert len(owners) == 1, outcomes
+ assert sum(status == "locked" for _, status in outcomes) == 3
+ owner_index = next(i for i, process in enumerate(processes) if process.pid == owners[0])
+ owner = processes[owner_index]
+ if crash:
+ owner.kill()
+ else:
+ pipes[owner_index][1].send(None)
+ for process in processes:
+ process.join(timeout=20)
+ assert not process.is_alive()
+ if not crash or process is not owner:
+ assert process.exitcode == 0
+ assert (tmp_path / LOCK_FILENAME).exists()
+ result = _probe_lock(tmp_path)
+ assert result.returncode == 0, result.stderr
+ finally:
+ for process in processes:
+ if process.pid is not None:
+ if process.is_alive():
+ process.kill()
+ process.join(timeout=5)
+ for reader, writer in pipes:
+ reader.close()
+ writer.close()
+ results.close()
+ results.join_thread()
diff --git a/tests/utils/test_process_lock.py b/tests/utils/test_process_lock.py
index 8e7f2bb42..4f84a86f8 100644
--- a/tests/utils/test_process_lock.py
+++ b/tests/utils/test_process_lock.py
@@ -12,16 +12,18 @@ import time
import pytest
-from openviking.utils.process_lock import acquire_data_dir_lock
+from openviking.utils.process_lock import acquire_data_dir_lock, release_data_dir_lock
def test_acquire_does_not_override_sigterm_handler(tmp_path):
"""Uvicorn must retain ownership of SIGTERM for graceful lifespan shutdown."""
original_handler = signal.getsignal(signal.SIGTERM)
- acquire_data_dir_lock(str(tmp_path))
-
- assert signal.getsignal(signal.SIGTERM) is original_handler
+ lock_path = acquire_data_dir_lock(str(tmp_path))
+ try:
+ assert signal.getsignal(signal.SIGTERM) is original_handler
+ finally:
+ release_data_dir_lock(lock_path)
@pytest.mark.skipif(sys.platform == "win32", reason="SIGTERM lifecycle is POSIX-specific")
@@ -87,6 +89,7 @@ def test_uvicorn_sigterm_runs_lifespan_and_releases_process_lock(tmp_path):
assert process.returncode in {0, -signal.SIGTERM}, output
assert "Application shutdown complete" in output
assert "Finished server process" in output
- assert not (workspace / ".openviking.pid").exists()
+ lock_path = acquire_data_dir_lock(str(workspace))
+ release_data_dir_lock(lock_path)
assert "SystemExit" not in output
assert "CancelledError" not in output