Use a temporary directory under GNUPGHOME to prevent contaminating or
relying on the host's global keyring during integration testing. Ensure
the background gpg-agent is terminated and the directory is cleaned up
afterwards.
Isolate original path tracking to the archive currently being loaded.
This prevents hardlinks in one archive from accidentally resolving to
nodes in another archive when their original paths collide before
renaming.
Also optimize memory by explicitly swapping out temporary tracking
structures after the loading phase is complete.
Instead of overwriting PATH with a hardcoded list, iterate through the
existing PATH and keep only recognized safe system locations. This
provides more flexibility while maintaining security for external
filters.
Also add -o unsafe_path to allow non-standard filter locations.
When name collisions occur within an archive, fuse-archive renames the
offending nodes to ensure VFS integrity. However, this previously broke
hardlink resolution for any link pointing to a renamed target, as the
target's path in the Tree index no longer matched the path stored in the
hardlink metadata.
This change introduces an auxiliary index, `nodes_by_original_path_`,
which tracks nodes that have undergone renaming.
Key changes:
- Add `renamed` flag to `Node` struct.
- Implement `FindNodeByOriginalPath` which performs a transparent lookup
in the original path index.
- Update `ResolveHardlinks` to use the original path for target lookups.
- Implement recursive path verification in `OriginalName::HasPath` to
ensure correct parent hierarchy matching.
- Clear the auxiliary index after hardlink resolution to minimize memory
footprint during the FUSE session.
This ensures that hardlinks are correctly resolved even in complex
archives with numerous name collisions.
- Improve clarity of the option name: 'default_permissions' is a
misnomer as it must be explicitly requested and actually signals that
the kernel should enforce standard UNIX permissions.
- Maintain 'default_permissions' as a hidden alias for backward
compatibility.
- Update documentation and integration tests.
- Align internal variable names for consistency.
- Prevent local code execution via PATH poisoning by hardcoding a safe
system PATH (/usr/bin:/bin:/usr/local/bin) when external filters are
enabled.
- Include Homebrew and MacPorts paths in sanitized PATH on macOS.
- External filters remain enabled by default for parity with standard
tools like bsdcat, but are now isolated from the ambient environment.
- Add integration test to verify that parasitic programs in the caller's
PATH are ignored.
- Update documentation to accurately reflect PATH sanitization.
- Introduce the 'noexternal' mount option which clears the PATH
environment variable. This prevents libarchive from finding and
executing external programs (like gzip, xz, etc.) for decompression.
- Update PrintUsage() and README.md to document the new option.
- Add integration test case in tests/test.py to verify environmental
isolation.
- Add error handling to GetTree when scanning directories. This allows
capturing and verifying OSErrors (stored as 'errno' in the tree)
instead of crashing the test runner.
- Align GetTree logic with mount-zip for better project consistency.
- Reformat long lines and remove redundant whitespace for PEP 8
compliance.
- Improve logging messages in TestBigArchiveStreamed.
- Test both SEEK_DATA and SEEK_HOLE for out-of-bounds errors.
- Use actual file size (st.st_size) instead of a hardcoded offset.
- Fix platform-specific errno verification to correctly use want_errno
(EINVAL on macOS, ENXIO on Linux).
- Add GetHoleMap to verify the actual sparse structure using lseek().
- Implement a has_holes guard based on FUSE version and OS platform.
- Add TestSparse() to verify sparseness preservation for precache/memcache
and proper fallback for lazycache/nocache.
- Move path definitions to the top of the script for better maintainability.
- Update Makefile to detect gtest using pkg-config.
- Suppress pkg-config error messages when gtest is missing.
- Conditionally build and run unit tests only if gtest is found.
- Update INSTALL.md to list gtest as a dependency for unit tests.
- Fix readdir filler lambda signature for FUSE 2 in unit tests.
- Change '-ho' to '-h' for FUSE 2 help output.
- Use _exit(EXIT_SUCCESS) in help/version paths for FUSE 2 to bypass
known libfuse2 leaks caught by ASAN.
- Add GetAttrByFi test to verify attribute retrieval via fuse_file_info.
- Add OpenDir tests to verify error handling for non-existent paths and
non-directory nodes.
Expand GetXattr unit tests
- Add a test case for requesting an attribute that exists on a different node.
- Define ENOATTR for better compatibility on Linux.
- Use ENOATTR instead of ENODATA in expectations to match fuse_ops.cc.
- Direct-map FUSE options to Context fields using offsetof.
- Use explicit int casts for scoped enums in the fuse_opt table.
- Add static assertions to ensure enum/int size compatibility.
- Add '-o precache' option for explicit default cache selection.
- Simplify ProcessArg by removing manual enum mapping logic.
This commit consolidates several improvements to library robustness and
FUSE compliance:
- Core Logic: Centralized SEEK_DATA/SEEK_HOLE navigation in
Node::SparseSeek and verified with exhaustive boundary tests.
- Testing: Expanded test/unit_tests.cc to cover Path normalization
(including UTF-8/ZWJ safety), Tree trimming, and Reader recycling
logic.
- FUSE Integration: Standardized callback return codes (EINVAL for
readlink on non-symlinks, ENOATTR for missing attributes) and improved
exception handling to distinguish OOM (ENOMEM) from internal errors.
- Diagnostics: Configured coverage reports to include DEBUG-only paths
and verified all enum-to-string mappings.
- Automation: Added FUSE-level negative tests to verify error
propagation across the filesystem boundary.
- Define 'format' target to apply clang-format to all C++ files.
- Define 'check-format' target to verify formatting without modifying files.
- Use '.clang-format' configuration file for style rules.
- Update DEVELOPMENT.md with formatting targets
- Update INSTALL.md with clang-format prerequisite
- Add Google Test (gtest) and gtest_main as dependencies in the
Makefile.
- Define a new 'unit_test' target that builds and runs a C++ unit test
program.
- Integrate 'unit_test' into 'make check' and 'make check-fast' to
ensure unit tests run before Python integration tests.
- Add an initial 'test/unit_test.cc' with a dummy test case to verify
the framework setup.
- Update DEVELOPMENT.md to distinguish between Unit Tests (C++) and
Integration Tests (Python).
- Update INSTALL.md to list GoogleTest as a build prerequisite and
include the libgtest-dev package for Debian systems.
- Implement comprehensive unit tests for 'Path' (normalization,
splitting, extensions), 'HashedString' (deduplication, hashing), and
'Util' (safe arithmetic, string manipulation, hole accounting).
- Correct 'Path' test expectations to align with the library's security-
conscious normalization logic (e.g., converting '..' components to
'?').
- Add 'friend' declarations to 'FileDescriptor' and 'Tree' classes to
enable targeted unit testing of internal logic.
- Implement 'FileDescriptorTest' to verify sparse file write logic
(WriteBytesAndSkipHoles) and basic I/O operations.
- Implement 'TreeTest' using a test fixture with protected wrapper
methods to verify private directory management (GetOrCreateDirNode)
and collision resolution (RenameIfCollision).
- Implement 'NodeTest' to verify 'GetBlockCount' logic, covering empty,
dense, sparse, and terminal hole cases.
- Implement 'TreeTest::Trim' to verify the collapsing of redundant
single-child directory hierarchies.
- Refined test setup to correctly establish parent-child relationships
and path metadata when manually constructing the virtual tree.
- Implement 'TreeTest::ResolveHardlinks' to verify the two-phase hardlink
resolution logic, ensuring correct inode sharing and nlink counts.
- Implement 'TreeTest::ReaderRecycling' to verify that Reader objects are
properly returned to the pool and reused.
- Implement 'TreeTest::ReaderBestMatch' to verify the optimization logic in
'GetReader' that selects the best available reader based on its current
position and buffer coverage.
- Add 'friend' declaration to 'Reader' to enable detailed state verification.
Transition to a dynamic terminal hole model where sparse regions at the
end of a file are tracked via Node::last_hole_start instead of being
stored in the interior holes vector. This optimization applies to
terminal holes of any size and streamlines filesystem statistics and
navigation.
Key changes:
- Implement Node::IsFullyCached() and Node::GetSizeToLastHole() for
dynamic sparse region detection.
- Refine GetBlockCount to correctly exclude the terminal hole from tree-
wide statistics.
- Update lib/fuse_ops.cc:Seek to correctly navigate both interior and
terminal holes for SEEK_DATA and SEEK_HOLE.
- Atomize cache state updates within Reader::CacheEntryData and improve
error recovery for partial cache states.
- Simplify Hole::GetSavedBlocks to calculate savings solely from hole
boundaries.
- Add diagnostic logging to Seek tests in test/test.py.
This comprehensive refactoring transforms the monolithic fuse-archive
into a modular, memory-safe library (libfuse-archive.a) and a
lightweight CLI wrapper.
Key Improvements:
- **State Encapsulation**: All virtual filesystem state (options, nodes,
readers, cache, and passwords) is now managed within a self-contained
'Tree' class.
- **Memory Safety**: Redesigned command-line option parsing to prevent
heap corruption during 'fuse_opt_parse' and verified clean execution
with ASAN and UBSAN.
- **Automated Resource Management**: Leveraged intrusive containers and
RAII-compliant nested destructors to automate the lifecycles of Nodes
and Readers.
- **Component Isolation**: Extracted FUSE operations, archive reading,
and utility functions into dedicated modules (tree, reader, node,
fuse_ops, util, etc.).
- **Refined API**: Simplified the library interface; 'Tree::Load' now
accepts simple paths, internalizing the complexity of descriptor
management and archive configuration.
- **Technical Integrity**: Maintained 100% functional parity with the
original implementation, as verified by the full test suite.
Added a 'valgrind' target to the Makefile and support for a
'MOUNT_WRAPPER' environment variable in test.py. This allows wrapping
the fuse-archive process with Valgrind during integration tests to check
for memory leaks.
This commit aligns fuse-archive with mount-zip's optimized architectural
model:
- Establishes parent-child relationships and path hashes before tree
attachment.
- Standardizes on RAII memory management using Node::Ptr (unique_ptr).
- Transitioned from time_t to timespec for full nanosecond precision.
- Reordered Node members for optimal alignment (16/8/pointer/4
grouping).
- Modernized logging with a throttled Beat class and ephemeral progress
updates.
- Adjusted test suite to handle nanosecond precision gracefully. Updated
CheckTree to allow second-precision matching when the expected
timestamp has zero nanoseconds. This ensures that tests remain robust
across different archive formats and library versions that may or may
not provide nanosecond resolution, while still allowing for exact
matching if non-zero nanoseconds are specified in the test
expectations.
- Honor FUSE_READDIR_PLUS flag in ReadDir: only provide stat info if
requested.
- Fix bug where uninitialized stat buffer was passed to the filler in
non-plus mode.
- Correctly handle '.' and '..' entries with conditional metadata
preparation.
- Refined README.md to map external tools to specific extensions.
- Explicitly mentioned that UU, Lzip, XZ, etc., are handled natively.
- Updated INSTALL.md to distinguish between core requirements and
optional test tools.
- Regenerated man page.
- Added recognition for many application packages (apk, aab, ipa, whl,
xpi) and document formats (epub, docx, odt, etc.).
- Renamed filtered_zip to is_seekable_format and pruned seekable_exts to
core archive types (7z, zip, jar, war, ear).
- Added TAR shorthands: tlrz (LRZIP), tlzo (LZOP), and tlzop (LZOP).
- Added format aliases: cbr (RAR-based) and lzh (LHA-based).
- Checked in permanent test symlinks in test/data for all new
extensions, including mixed-case .taZ and .apk.gpg.
- Added TestFilteredOpaque to verify that specialized formats remain
opaque when filtered.
- Added cross-archive collision test case to TestMultiArchive.
- Updated documentation with categorized and alphabetized extension
lists.
- Register only likely LZ-based filters (lzma, lzip, lzop, lz4) for .tlz
files.
- Omit r.Check() to allow mounting even if some filters are not
supported by the local libarchive build.
- This ensures maximum compatibility across different Linux
distributions while strictly honoring the 'LZ' hint in the extension.
- Moved g_unique_strings to heap-allocated pointer to control
destruction order.
- Ensure all virtual node children are cleared before tree disposal.
- Added Reader::EmptyRecycleBin() to deallocate cached reader objects.
- Explicitly delete the string pool during teardown.
- This ensures a perfectly clean state for AddressSanitizer at exit.
- Renamed 'cleanup' to 'mount_point_guard' for clarity in main().
- Updated DEVELOPMENT.md with comprehensive shutdown teardown details.
- Created DEVELOPMENT.md as a generic technical guide for all
contributors.
- Documented project overview, versioning, build system, and technical
standards.
- Updated release.py to maintain version in DEVELOPMENT.md.
- Implement release.py to automate version bumping, date updating, man
page regeneration, and Git operations.
- Support automatic version detection and suggestion for the next stable
release.
- Add confirmation prompt to release.py for safety.
- Integrate release script into Makefile via 'release' target.
- Make man page preview optional in 'make doc' via QUIET=1 and use it in
the release script.
- Add sed post-processing to Makefile to produce compact lists in the
man page.
- Fix Markdown formatting in README.md by adding missing blank lines
before lists.
- Implement standard DESTDIR and PREFIX handling for installations.
- Separate mandatory build flags from user-provided variables (CXXFLAGS,
LDFLAGS).
- Add ASAN=1 option for AddressSanitizer support.
- Fix memory leaks in g_unique_strings and the Node tree for ASAN
compliance.
- Implement conditional RAII cleanup in main() using Boost Intrusive
dispose logic, active only in ASAN builds for optimal exit
performance.
- Fix a memory safety bug in main() when handling --help/--version by
avoiding unsafe const_cast and ensuring heap-allocated argv[0] is
restored before freeing.
- Add -D_TIME_BITS=64 to support 64-bit timestamps on 32-bit systems
(Year 2038).
- Add clean-data target for optional removal of large test archives.
- Add test target as an alias for check.
- Update .PHONY list with all non-file targets.
- Use rm -f and standard paths in uninstall target.
- Added USAGE EXAMPLES with common and advanced scenarios.
- Added detailed FEATURES list.
- Enhanced GPG and native ENCRYPTION documentation.
- Expanded CACHING section with strategy and storage details.
- Added ARCHIVE TREE STRUCTURE explaining merging and trimming.
- Added LOG MESSAGES section for troubleshooting.
- Refined ARCHIVE FORMATS to reflect dependency-based support.
- Documented automatic mount point creation and cleanup.
- Added COMPARISON table with similar tools.
Fixed typos, grammar, and punctuation in README.md and INSTALL.md.
Standardized header formatting in INSTALL.md.
Clarified that -o memcache is Linux-only in README.md.
Add GPG INTEGRATION section to README.md
Updated documentation date to April 2026.
Modified CreateCacheFile() to use memfd_create(2) on Linux when memcache
is enabled.
Integrated memcache cases into the test suite in test/test.py.
Added has_memcache check in test.py to skip memcache tests on non-Linux
platforms.
- Implemented TestMultiArchive to verify -o nomerge and -o notrim behavior.
- Added gzipped multi1.tar.gz and multi2.tar.gz for path-related testing.
- Implemented TestSpecialPermissions to verify SUID, SGID and sticky bits.
- Added gzipped special_perms.tar.gz with various permission combinations.
- Added FUSE version detection in test.py to skip TestSeek on FUSE < 3.
- Updated TODO.md to mark these tasks as completed.
Added TestSeek to verify lseek(SEEK_DATA) and lseek(SEEK_HOLE).
Created seek.tar.gz with complex sparse file patterns.
Fixed Seek() to correctly return ENXIO when SEEK_HOLE is called at EOF.
Implemented MountArchive context manager in test.py for better test hygiene.
- Updated test/test.py to capture blocks and xattrs during scans.
- Added compressed xattr_hardlinks.tar.gz archive for attribute testing.
- Updated TestHardlinks to verify attribute consistency for hardlinks,
conditioned on gzip/zlib availability.
- Updated existing TestHardlinks expectations to include blocks and xattrs.
- Replaced manual sys.argv check with argparse for --fast and added --verbose.
Update CacheEntryData to accept an optional Node pointer instead of a
Holes vector pointer. This allows CacheEntryData to update the node's
saved_blocks count directly within the hole-discovery callback,
avoiding a redundant post-caching loop in ProcessEntry.
Updated ListXattr, GetXattr and ReadDir to look at the target node for
each directory entry. This ensures that hardlinks correctly report
metadata updates (such as reduced block counts from sparse hole
detection) that occur on their target node during lazy caching,
maintaining consistency between directory listings and direct stat
calls.
Replaced `std::function<void(Reader&)>` with lightweight function
pointers `void (*)(Reader&)` in format mapping dictionaries. This avoids
dynamic allocation and overhead from std::function, making the static
initialization more efficient and idiomatic.