Skip to content

Add cross-process file locking for persistent OCI cache #145

Description

@em-redhat

Problem / Motivation

The persistent OCI cache introduced in PR #127 does not include cross-process file locking. While oci.Store from oras-go provides file-level atomicity for individual blob writes (content-addressable, write-to-temp-then-rename), concurrent CLI invocations or parallel agentic workflows operating on the same cache directory could encounter race conditions on:

  • Simultaneous pull operations writing to the same cache
  • A cache clean running while a pull or mcp serve is reading
  • Multiple MCP server instances sharing the same cache directory

Proposed Solution

Add a cross-platform advisory lock (e.g., flock on Linux/macOS, LockFileEx on Windows) around critical cache operations:

  1. Acquire a shared (read) lock before reading from the cache (loadBundleArtifacts)
  2. Acquire an exclusive (write) lock before writing to the cache (oras.Copy, cache clean)
  3. Use a well-known lockfile path within the cache directory (e.g., $CACHE_DIR/.lock)

Acceptance Criteria

  • Concurrent complypack pull invocations do not corrupt the cache
  • complypack cache clean waits for in-flight reads/writes to complete
  • Locking works on Linux and macOS (Windows support can be a follow-up)
  • Lock acquisition has a configurable timeout with a sensible default

Context

Raised by @trevor-vaughan in PR #127: #127 (comment)

Metadata

Metadata

Assignees

No one assigned

    Labels

    enhancementNew feature or request

    Type

    No type

    Fields

    Priority

    Low

    Effort

    None yet

    Projects

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions