cryptomator / jfuse

Java bindings for FUSE using the FFM API

jFUSE

Zero-Dependency Java bindings for FUSE using JEP 454.

Status

This lib makes use of the Foreign Function & Memory API, requiring at least JDK 22. Older JDK versions are not supported. Please refer to an older version of this lib, if you are interested in using it with an older JDK (with --enable-preview). Older versions will not receive patches or any kind of support, though!

We attempt to support libfuse 3.x on Linux and Windows while also remaining compatible with libfuse 2.x on macOS, leading to some compromises in the API.

For libfuse 3 to ensure that the readdir operation runs in readdirplus mode, you have to add FuseOperations.Operation.INIT to the set returend by FuseOperations::supportedOperations method to the supported operations. An implementation of init is not necessary.

Supported fuse_operations

Not all fuse_operations are supported yet.

	Status
getattr	✅
fgetattr	use getattr
readlink	✅
getdir	use readdir
mknod	use create
mkdir	✅
unlink	✅
rmdir	✅
symlink	✅
rename	✅
link	❌
chmod	✅
chown	✅
truncate	✅
ftruncate	use truncate
utime	use utimens
open	✅
read	✅
write	✅
statfs	✅
flush	✅
release	✅
fsync	✅
setxattr	✅
getxattr	✅
listxattr	✅
removexattr	✅
opendir	✅
readdir	✅
releasedir	✅
fsyncdir	✅
init	✅
destroy	✅
access	✅ (ignored on Windows)
create	✅
lock	❌
utimens	✅
bmap	❌
ioctl	❌
poll	❌
write_buf	❌
read_buf	❌
flock	❌
fallocate	❌
copy_file_range	❌
lseek	❌

Usage

Usage examples can be found under /jfuse-examples/. You basically need to implement FuseOperations and pass it to the Fuse.builder():

<dependency>
	<groupId>org.cryptomator</groupId>
	<artifactId>jfuse</artifactId>
	<version>x.y.z</version>
</dependency>

var builder = Fuse.builder();
var fs = new MyFileSystem(builder.errno());
try (var fuse = builder.build(fs)) {
	fuse.mount("my-awesome-fs", mountPoint);
	// wait as long as the mounted volume is in use
} // closing will force-unmount (previous graceful unmount recommended)

During runtime, you will need to add allow native access from platform-specific implementations via --enable-native-access, e.g.:

java -p path/to/mods \
  -m com.example.mymodule/com.example.mymodule \
  --enable-native-access=org.cryptomator.jfuse.mac \

Supported Platforms

Due to slight differences in memory layout, each platform needs its own implementation. Currently, the following operating systems and architectures are supported:

	Linux	Mac (macFUSE)	Windows (WinFSP)
x86_64	jfuse-linux-amd64	jfuse-mac	jfuse-win
arm64	jfuse-linux-aarch64	jfuse-mac	jfuse-win

Building

Changing Java implementation

Due to the magic of the Foreign Function & Memory API, you can build all modules on any platform that you can find a JDK for.

Running jextract (on demand)

Each platform has its own module. In rare cases, we need to update jextracted classes.

In most cases this requires you to run the build on the target platform, as you need access to its system-specific header files and (most likely) build tools. See module readme for specific requirements.

In order to run jextract, use the corresponding Maven profile (e.g. -Pjextract-win).

Adding a new platform

Before adding a new module, you might want to change the header search path in one of the existing modules and run jextract. If there is no diff at all, you can most likely add a @SupportedPlatform annotation to its FuseBuilder and check if it works.

Otherwise, you'd need to add a copy of the module. Make sure to open it to the api in the module-info.java, as the api module needs reflective access.

Alternatives

Over the past few years, we relied on jnr-fuse ourselves and can recommend using it for platforms that aren't supported by jFUSE. It has also become the benchmark that we wanted to beat regarding performance and API design.

jfuse's Issues

`chown` support

Add support for chown as well as st_uid and st_gid fields in stat.

Office 2003 (doc, xls) file save failed!

Hello,
I have tested the example you provided and found that WindowsMirrorFileSystem encounters errors when saving office excel 2003 files (xls) and office word 2003 files (doc). This issue is reproducible every time. Can this problem be fixed? Additionally, office versions 2007 and above can be saved normally. The tool used for editing documents is WPS.

Thank you very much.

this exception log :

java.nio.file.FileAlreadyExistsException: C:\Users\xxxx\Desktop\fsdownload\test\testExcel~DE996.tmp
	at java.base/sun.nio.fs.WindowsException.translateToIOException(WindowsException.java:87)
	at java.base/sun.nio.fs.WindowsException.rethrowAsIOException(WindowsException.java:103)
	at java.base/sun.nio.fs.WindowsException.rethrowAsIOException(WindowsException.java:108)
	at java.base/sun.nio.fs.WindowsFileSystemProvider.newFileChannel(WindowsFileSystemProvider.java:119)
	at java.base/java.nio.channels.FileChannel.open(FileChannel.java:309)
	at example.WindowsMirrorFileSystem.openFileChannel(WindowsMirrorFileSystem.java:67)
	at example.AbstractMirrorFileSystem.createOrOpen(AbstractMirrorFileSystem.java:457)
	at example.AbstractMirrorFileSystem.create(AbstractMirrorFileSystem.java:442)
	at org.cryptomator.jfuse.api.FuseOperationsDecorator.create(FuseOperationsDecorator.java:182)
	at org.cryptomator.jfuse.win.FuseImpl.create(FuseImpl.java:135)

Naming "struct" interface getter methods

As mentioned in PR #19 (comment), currently the naming convention for getters in struct interfaces is mixedbetween

• record-style: if field is called foo, the getter is also called foo() and
• java-style: if field is called foo, the getter is called getFoo()

Before reaching 1.0.0 we should decide what naming convention to use to offer a unified API.

Read many files at the same time

If you read a lot of files at the same time, it will be very slow when the thread is blocked. Is there any solution?

Check return value of fuse_loop

With the method int fuse_loop() a fuse filesystem can be started, such that filesystem events are handled.

It returns an error code, if it fails. But currently, this error code is not used:

jfuse/jfuse-api/src/main/java/org/cryptomator/jfuse/api/Fuse.java

Lines 120 to 124 in 75c2070

	try {
	var fuseMount = this.mount(args);
	executor.submit(() -> fuseLoop(fuseMount)); // TODO keep reference of future and report result
	waitForMountingToComplete(mountPoint);
	mount.compareAndSet(lock, fuseMount);

Hence, our implementation does not notice premature ends of the loops and waits indefinitely in the method waitForMountingToComplete.

We must check, if fuse_loop is aready finished in the code, before we wait or return.

Unneeded read method call

I’m using the jfuse Java library to create a Windows application similar to OneDrive that manages user files. My files are on the cloud, and I’ve overridden the read function in this library to stream files. However, I have an issue: when I open a directory, the library starts to read files without the user opening them. This causes a ‘not responding’ issue and consumes unneeded internet data. Do anyone have any ideas on how to resolve such an issue? @overheadhunter

`flush`, `fsync`, `fsyncdir` support

Add `S_IFMT` to Stat

Add S_IFMT.

The mask may be useful, e.g. to quickly erase all bits when setting the file mode via toggleMode(S_IFMT, false).

Windows: Start testing classes with multithreading enabled fails

Omitting the FUSE single thread option (-s), activates mulithreading.

But on Windows all adequate test classes fail to start with:

org.cryptomator.jfuse.api.FuseMountFailedException: Exception when starting fuse_loop. Message: unresolved symbol: fuse3_loop_mt
	at [email protected]/org.cryptomator.jfuse.api.Fuse.mount(Fuse.java:138)
	at [email protected]/org.cryptomator.jfuse.win.FuseImpl.mount(FuseImpl.java:37)
	at [email protected]/org.cryptomator.jfuse.examples.WindowsMirrorFileSystem.main(WindowsMirrorFileSystem.java:34)

I believe this is related to the fact, that in the winfsp DLL, fuse3_loop_mt and fuse3_loop_mt_31 map to the same virtual address, as it can be see with the Dependencies app:

add `fuse_config` to `init(...)`

Add a second parameter @Nullable FuseConfig fuseConfig to init:

jfuse/jfuse-api/src/main/java/org/cryptomator/jfuse/api/FuseOperations.java

Lines 523 to 525 in 99c0bbc

	default void init(FuseConnInfo conn) { // TODO: add @Nullable FuseConfig for libfuse3
	// no-op
	}

Document in the JavaDoc that this is not set when using the libfuse2 API.

`xattr` support

Add support for the following fuse_operations:

• setxattr
• getxattr
• listxattr
• removexattr