Repository navigation
Description
Overview
A lock file stops two processes from writing to the same archive path at the same time. This work is part of milestone M5.
Background & Motivation
Archive.create replaces a stale partial file. Without a lock, it cannot tell a stale file from a file that another export writes at the same time. A lock file that holds the process id solves this. Morango uses the same process check to resume sync sessions.
Design: spec. Plan: implementation plan, Task 18.
Description & Expected Outcomes
Archive.create makes <path>.lock with an exclusive create, and writes its process id into it. If the lock file exists and its process is alive, create raises MorangoArchiveLocked. If the process is not alive, the lock is stale, and create replaces it. finalize and discard delete the lock file.
Deliverables & Contracts
The change delivers these capabilities:
- The error
MorangoArchiveLocked, a subclass ofMorangoArchiveError. - Lock handling in
Archive.create,Archive.finalize, andArchive.discard. - An error message that names the lock file, so that an operator can remove it.
Acceptance Criteria
- A lock file with the id of a live process from another program makes
createraiseMorangoArchiveLocked. - A lock file with the id of a dead process is replaced, and
createsucceeds. - After
discard, no<path>.lockfile remains. - The error message contains the path of the lock file.
- The lock tests also run in the
windowstox environment.
Technical Pointers & Architecture
- Target Components / Context:
morango/sync/archive.py,morango/errors.py. - Related Patterns:
pid_existsinmorango/utils.py, used byresume_sync_sessionatmorango/sync/syncsession.py:304-312. - Data Model & Schema Considerations: None.
- Resilience & Failure Modes: If the operating system reuses a process id,
createcan report a false lock. The error message names the lock file for this case.
Notes & Tradeoffs
- Dependencies: Blocked by: Create and discard an archive database file #378 (
Archive.createanddiscard). Blocks: Finalize archives into a compact file at the final path #382. - Testing Requirements: Patch
morango.sync.archive.pid_existsto control whether the process is alive. - Tradeoffs & Alternatives Considered: Operating system file locks do not work the same on all platforms. A lock file with a process id works on Linux, macOS, and Windows.
- Compatibility & Migrations: None.
Metadata
- Complexity: Low
- Target Branch: release-v0.9.x
AI Usage
Drafted with Claude (Claude Code) from the approved design spec and implementation plan. The author reviewed the requirements, and the code references were checked against the release-v0.9.x codebase.
Activity
ArpitaSamanta10 commentedon Nov 19, 2026
@bjester
I would love to work on this issue can you assign this for me
/assign
learning-equality-bot commentedon Nov 19, 2026
Hi! 👋
Thanks so much for your interest! This issue is not open for contribution. Visit Contributing guidelines to learn about the contributing process and how to find suitable issues. If there are no unassigned 'help wanted' issues available, please wait until new ones are added.
We really appreciate your willingness to help. 😊
Are you preparing for Google Summer of Code? See our GSoC guidelines.