snapshot of https://github.com/seaweedfs/seaweedfs.git (master, 2026-09-16; blobs > 131072B omitted)

other/java/client/pom.xml

@@ -0,0 +1,186 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
+    <modelVersion>4.0.0</modelVersion>
+
+    <groupId>com.seaweedfs</groupId>
+    <artifactId>seaweedfs-client</artifactId>
+    <version>4.38</version>
+
+    <name>SeaweedFS Java Client</name>
+    <description>A java client for SeaweedFS.</description>
+    <url>https://github.com/seaweedfs/seaweedfs</url>
+    <licenses>
+        <license>
+            <name>The Apache License, Version 2.0</name>
+            <url>http://www.apache.org/licenses/LICENSE-2.0.txt</url>
+        </license>
+    </licenses>
+    <developers>
+        <developer>
+            <name>Chris Lu</name>
+            <email>chris.lu@gmail.com</email>
+            <organization>SeaweedFS</organization>
+            <organizationUrl>https://seaweedfs.com</organizationUrl>
+        </developer>
+    </developers>
+    <scm>
+        <connection>scm:git:git://github.com/seaweedfs/seaweedfs.git</connection>
+        <developerConnection>scm:git:ssh://github.com:seaweedfs/seaweedfs.git</developerConnection>
+        <url>https://github.com/seaweedfs/seaweedfs/tree/master</url>
+    </scm>
+
+    <properties>
+        <protobuf.version>3.25.5</protobuf.version>
+        <!-- follow https://github.com/grpc/grpc-java -->
+        <grpc.version>1.77.0</grpc.version>
+        <guava.version>32.0.0-jre</guava.version>
+    </properties>
+
+    <dependencies>
+        <dependency>
+            <groupId>com.moandjiezana.toml</groupId>
+            <artifactId>toml4j</artifactId>
+            <version>0.7.2</version>
+        </dependency>
+        <!-- https://mvnrepository.com/artifact/com.google.protobuf/protobuf-java -->
+        <dependency>
+            <groupId>com.google.protobuf</groupId>
+            <artifactId>protobuf-java</artifactId>
+            <version>${protobuf.version}</version>
+        </dependency>
+        <dependency>
+            <groupId>com.google.guava</groupId>
+            <artifactId>guava</artifactId>
+            <version>${guava.version}</version>
+        </dependency>
+        <dependency>
+            <groupId>io.grpc</groupId>
+            <artifactId>grpc-netty-shaded</artifactId>
+            <version>${grpc.version}</version>
+        </dependency>
+        <dependency>
+            <groupId>io.grpc</groupId>
+            <artifactId>grpc-protobuf</artifactId>
+            <version>${grpc.version}</version>
+        </dependency>
+        <dependency>
+            <groupId>io.grpc</groupId>
+            <artifactId>grpc-stub</artifactId>
+            <version>${grpc.version}</version>
+        </dependency>
+        <dependency>
+            <groupId>org.slf4j</groupId>
+            <artifactId>slf4j-api</artifactId>
+            <version>1.7.25</version>
+        </dependency>
+        <dependency>
+            <groupId>org.apache.httpcomponents</groupId>
+            <artifactId>httpmime</artifactId>
+            <version>4.5.13</version>
+        </dependency>
+        <dependency>
+            <groupId>junit</groupId>
+            <artifactId>junit</artifactId>
+            <version>4.13.1</version>
+            <scope>test</scope>
+        </dependency>
+        <dependency>
+            <groupId>javax.annotation</groupId>
+            <artifactId>javax.annotation-api</artifactId>
+            <version>1.3.2</version>
+        </dependency>
+    </dependencies>
+
+    <build>
+        <extensions>
+            <extension>
+                <groupId>kr.motd.maven</groupId>
+                <artifactId>os-maven-plugin</artifactId>
+                <version>1.6.2</version>
+            </extension>
+        </extensions>
+        <plugins>
+            <plugin>
+                <groupId>org.apache.maven.plugins</groupId>
+                <artifactId>maven-compiler-plugin</artifactId>
+                <configuration>
+                    <source>8</source>
+                    <target>8</target>
+                    <release>8</release>
+                </configuration>
+            </plugin>
+            <plugin>
+                <groupId>org.xolstice.maven.plugins</groupId>
+                <artifactId>protobuf-maven-plugin</artifactId>
+                <version>0.6.1</version>
+                <configuration>
+                    <protocArtifact>com.google.protobuf:protoc:${protobuf.version}:exe:${os.detected.classifier}
+                    </protocArtifact>
+                    <pluginId>grpc-java</pluginId>
+                    <pluginArtifact>io.grpc:protoc-gen-grpc-java:${grpc.version}:exe:${os.detected.classifier}
+                    </pluginArtifact>
+                </configuration>
+                <executions>
+                    <execution>
+                        <goals>
+                            <goal>compile</goal>
+                            <goal>compile-custom</goal>
+                        </goals>
+                    </execution>
+                </executions>
+            </plugin>
+            <plugin>
+                <groupId>org.apache.maven.plugins</groupId>
+                <artifactId>maven-gpg-plugin</artifactId>
+                <version>3.2.4</version>
+                <executions>
+                    <execution>
+                        <id>sign-artifacts</id>
+                        <phase>verify</phase>
+                        <goals>
+                            <goal>sign</goal>
+                        </goals>
+                    </execution>
+                </executions>
+            </plugin>
+            <plugin>
+                <groupId>org.sonatype.central</groupId>
+                <artifactId>central-publishing-maven-plugin</artifactId>
+                <version>0.5.0</version>
+                <extensions>true</extensions>
+                <configuration>
+                    <publishingServerId>central</publishingServerId>
+                    <autoPublish>true</autoPublish>
+                </configuration>
+            </plugin>
+            <plugin>
+                <groupId>org.apache.maven.plugins</groupId>
+                <artifactId>maven-source-plugin</artifactId>
+                <version>2.2.1</version>
+                <executions>
+                    <execution>
+                        <id>attach-sources</id>
+                        <goals>
+                            <goal>jar-no-fork</goal>
+                        </goals>
+                    </execution>
+                </executions>
+            </plugin>
+            <plugin>
+                <groupId>org.apache.maven.plugins</groupId>
+                <artifactId>maven-javadoc-plugin</artifactId>
+                <version>3.0.1</version>
+                <executions>
+                    <execution>
+                        <id>attach-javadocs</id>
+                        <goals>
+                            <goal>jar</goal>
+                        </goals>
+                    </execution>
+                </executions>
+            </plugin>
+        </plugins>
+    </build>
+
+</project>

other/java/client/pom.xml.deploy

@@ -0,0 +1,186 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
+    <modelVersion>4.0.0</modelVersion>
+
+    <groupId>com.seaweedfs</groupId>
+    <artifactId>seaweedfs-client</artifactId>
+    <version>3.80</version>
+
+    <name>SeaweedFS Java Client</name>
+    <description>A java client for SeaweedFS.</description>
+    <url>https://github.com/seaweedfs/seaweedfs</url>
+    <licenses>
+        <license>
+            <name>The Apache License, Version 2.0</name>
+            <url>http://www.apache.org/licenses/LICENSE-2.0.txt</url>
+        </license>
+    </licenses>
+    <developers>
+        <developer>
+            <name>Chris Lu</name>
+            <email>chris.lu@gmail.com</email>
+            <organization>SeaweedFS</organization>
+            <organizationUrl>https://seaweedfs.com</organizationUrl>
+        </developer>
+    </developers>
+    <scm>
+        <connection>scm:git:git://github.com/seaweedfs/seaweedfs.git</connection>
+        <developerConnection>scm:git:ssh://github.com:seaweedfs/seaweedfs.git</developerConnection>
+        <url>https://github.com/seaweedfs/seaweedfs/tree/master</url>
+    </scm>
+
+    <properties>
+        <protobuf.version>3.25.5</protobuf.version>
+        <!-- follow https://github.com/grpc/grpc-java -->
+        <grpc.version>1.68.1</grpc.version>
+        <guava.version>32.0.0-jre</guava.version>
+    </properties>
+
+    <dependencies>
+        <dependency>
+            <groupId>com.moandjiezana.toml</groupId>
+            <artifactId>toml4j</artifactId>
+            <version>0.7.2</version>
+        </dependency>
+        <!-- https://mvnrepository.com/artifact/com.google.protobuf/protobuf-java -->
+        <dependency>
+            <groupId>com.google.protobuf</groupId>
+            <artifactId>protobuf-java</artifactId>
+            <version>${protobuf.version}</version>
+        </dependency>
+        <dependency>
+            <groupId>com.google.guava</groupId>
+            <artifactId>guava</artifactId>
+            <version>${guava.version}</version>
+        </dependency>
+        <dependency>
+            <groupId>io.grpc</groupId>
+            <artifactId>grpc-netty-shaded</artifactId>
+            <version>${grpc.version}</version>
+        </dependency>
+        <dependency>
+            <groupId>io.grpc</groupId>
+            <artifactId>grpc-protobuf</artifactId>
+            <version>${grpc.version}</version>
+        </dependency>
+        <dependency>
+            <groupId>io.grpc</groupId>
+            <artifactId>grpc-stub</artifactId>
+            <version>${grpc.version}</version>
+        </dependency>
+        <dependency>
+            <groupId>org.slf4j</groupId>
+            <artifactId>slf4j-api</artifactId>
+            <version>1.7.25</version>
+        </dependency>
+        <dependency>
+            <groupId>org.apache.httpcomponents</groupId>
+            <artifactId>httpmime</artifactId>
+            <version>4.5.13</version>
+        </dependency>
+        <dependency>
+            <groupId>junit</groupId>
+            <artifactId>junit</artifactId>
+            <version>4.13.1</version>
+            <scope>test</scope>
+        </dependency>
+        <dependency>
+            <groupId>javax.annotation</groupId>
+            <artifactId>javax.annotation-api</artifactId>
+            <version>1.3.2</version>
+        </dependency>
+    </dependencies>
+
+    <build>
+        <extensions>
+            <extension>
+                <groupId>kr.motd.maven</groupId>
+                <artifactId>os-maven-plugin</artifactId>
+                <version>1.6.2</version>
+            </extension>
+        </extensions>
+        <plugins>
+            <plugin>
+                <groupId>org.apache.maven.plugins</groupId>
+                <artifactId>maven-compiler-plugin</artifactId>
+                <configuration>
+                    <source>8</source>
+                    <target>8</target>
+                    <release>8</release>
+                </configuration>
+            </plugin>
+            <plugin>
+                <groupId>org.xolstice.maven.plugins</groupId>
+                <artifactId>protobuf-maven-plugin</artifactId>
+                <version>0.6.1</version>
+                <configuration>
+                    <protocArtifact>com.google.protobuf:protoc:${protobuf.version}:exe:${os.detected.classifier}
+                    </protocArtifact>
+                    <pluginId>grpc-java</pluginId>
+                    <pluginArtifact>io.grpc:protoc-gen-grpc-java:${grpc.version}:exe:${os.detected.classifier}
+                    </pluginArtifact>
+                </configuration>
+                <executions>
+                    <execution>
+                        <goals>
+                            <goal>compile</goal>
+                            <goal>compile-custom</goal>
+                        </goals>
+                    </execution>
+                </executions>
+            </plugin>
+            <plugin>
+                <groupId>org.apache.maven.plugins</groupId>
+                <artifactId>maven-gpg-plugin</artifactId>
+                <version>1.5</version>
+                <executions>
+                    <execution>
+                        <id>sign-artifacts</id>
+                        <phase>verify</phase>
+                        <goals>
+                            <goal>sign</goal>
+                        </goals>
+                    </execution>
+                </executions>
+            </plugin>
+            <plugin>
+                <groupId>org.sonatype.central</groupId>
+                <artifactId>central-publishing-maven-plugin</artifactId>
+                <version>0.5.0</version>
+                <extensions>true</extensions>
+                <configuration>
+                    <publishingServerId>central</publishingServerId>
+                    <autoPublish>true</autoPublish>
+                </configuration>
+            </plugin>
+            <plugin>
+                <groupId>org.apache.maven.plugins</groupId>
+                <artifactId>maven-source-plugin</artifactId>
+                <version>2.2.1</version>
+                <executions>
+                    <execution>
+                        <id>attach-sources</id>
+                        <goals>
+                            <goal>jar-no-fork</goal>
+                        </goals>
+                    </execution>
+                </executions>
+            </plugin>
+            <plugin>
+                <groupId>org.apache.maven.plugins</groupId>
+                <artifactId>maven-javadoc-plugin</artifactId>
+                <version>3.0.1</version>
+                <executions>
+                    <execution>
+                        <id>attach-javadocs</id>
+                        <goals>
+                            <goal>jar</goal>
+                        </goals>
+                    </execution>
+                </executions>
+            </plugin>
+        </plugins>
+    </build>
+
+</project>

other/java/client/pom_debug.xml

@@ -0,0 +1,145 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
+    <modelVersion>4.0.0</modelVersion>
+
+    <groupId>com.seaweedfs</groupId>
+    <artifactId>seaweedfs-client</artifactId>
+    <version>3.80</version>
+
+    <parent>
+        <groupId>org.sonatype.oss</groupId>
+        <artifactId>oss-parent</artifactId>
+        <version>9</version>
+    </parent>
+
+    <properties>
+        <protobuf.version>3.25.5</protobuf.version>
+        <!-- follow https://github.com/grpc/grpc-java -->
+        <grpc.version>1.68.1</grpc.version>
+        <guava.version>28.0-jre</guava.version>
+    </properties>
+
+    <dependencies>
+        <dependency>
+            <groupId>com.moandjiezana.toml</groupId>
+            <artifactId>toml4j</artifactId>
+            <version>0.7.2</version>
+        </dependency>
+        <!-- https://mvnrepository.com/artifact/com.google.protobuf/protobuf-java -->
+        <dependency>
+            <groupId>com.google.protobuf</groupId>
+            <artifactId>protobuf-java</artifactId>
+            <version>${protobuf.version}</version>
+        </dependency>
+        <dependency>
+            <groupId>com.google.guava</groupId>
+            <artifactId>guava</artifactId>
+            <version>${guava.version}</version>
+        </dependency>
+        <dependency>
+            <groupId>io.grpc</groupId>
+            <artifactId>grpc-netty-shaded</artifactId>
+            <version>${grpc.version}</version>
+        </dependency>
+        <dependency>
+            <groupId>io.grpc</groupId>
+            <artifactId>grpc-protobuf</artifactId>
+            <version>${grpc.version}</version>
+        </dependency>
+        <dependency>
+            <groupId>io.grpc</groupId>
+            <artifactId>grpc-stub</artifactId>
+            <version>${grpc.version}</version>
+        </dependency>
+        <dependency>
+            <groupId>org.slf4j</groupId>
+            <artifactId>slf4j-api</artifactId>
+            <version>1.7.25</version>
+        </dependency>
+        <dependency>
+            <groupId>org.apache.httpcomponents</groupId>
+            <artifactId>httpmime</artifactId>
+            <version>4.5.13</version>
+        </dependency>
+        <dependency>
+            <groupId>junit</groupId>
+            <artifactId>junit</artifactId>
+            <version>4.13.1</version>
+            <scope>test</scope>
+        </dependency>
+        <dependency>
+            <groupId>javax.annotation</groupId>
+            <artifactId>javax.annotation-api</artifactId>
+            <version>1.3.2</version>
+        </dependency>
+    </dependencies>
+
+    <build>
+        <extensions>
+            <extension>
+                <groupId>kr.motd.maven</groupId>
+                <artifactId>os-maven-plugin</artifactId>
+                <version>1.6.2</version>
+            </extension>
+        </extensions>
+        <plugins>
+            <plugin>
+                <groupId>org.apache.maven.plugins</groupId>
+                <artifactId>maven-compiler-plugin</artifactId>
+                <configuration>
+                    <source>8</source>
+                    <target>8</target>
+                    <release>8</release>
+                </configuration>
+            </plugin>
+            <plugin>
+                <groupId>org.xolstice.maven.plugins</groupId>
+                <artifactId>protobuf-maven-plugin</artifactId>
+                <version>0.6.1</version>
+                <configuration>
+                    <protocArtifact>com.google.protobuf:protoc:${protobuf.version}:exe:${os.detected.classifier}
+                    </protocArtifact>
+                    <pluginId>grpc-java</pluginId>
+                    <pluginArtifact>io.grpc:protoc-gen-grpc-java:${grpc.version}:exe:${os.detected.classifier}
+                    </pluginArtifact>
+                </configuration>
+                <executions>
+                    <execution>
+                        <goals>
+                            <goal>compile</goal>
+                            <goal>compile-custom</goal>
+                        </goals>
+                    </execution>
+                </executions>
+            </plugin>
+            <plugin>
+                <groupId>org.apache.maven.plugins</groupId>
+                <artifactId>maven-source-plugin</artifactId>
+                <version>2.2.1</version>
+                <executions>
+                    <execution>
+                        <id>attach-sources</id>
+                        <goals>
+                            <goal>jar-no-fork</goal>
+                        </goals>
+                    </execution>
+                </executions>
+            </plugin>
+            <plugin>
+                <groupId>org.apache.maven.plugins</groupId>
+                <artifactId>maven-javadoc-plugin</artifactId>
+                <version>3.0.1</version>
+                <executions>
+                    <execution>
+                        <id>attach-javadocs</id>
+                        <goals>
+                            <goal>jar</goal>
+                        </goals>
+                    </execution>
+                </executions>
+            </plugin>
+        </plugins>
+    </build>
+
+</project>

other/java/client/src/main/java/seaweedfs/client/BasicAuthInterceptor.java

@@ -0,0 +1,35 @@
+package seaweedfs.client;
+
+import io.grpc.CallOptions;
+import io.grpc.Channel;
+import io.grpc.ClientCall;
+import io.grpc.ClientInterceptor;
+import io.grpc.ForwardingClientCall;
+import io.grpc.Metadata;
+import io.grpc.MethodDescriptor;
+
+// Adds an HTTP Basic Auth "Authorization" header to every gRPC call so the filer can be
+// reached through an Nginx reverse proxy with auth_basic enabled.
+public class BasicAuthInterceptor implements ClientInterceptor {
+
+    private static final Metadata.Key<String> AUTHORIZATION_KEY =
+            Metadata.Key.of("authorization", Metadata.ASCII_STRING_MARSHALLER);
+
+    private final String headerValue;
+
+    public BasicAuthInterceptor(String headerValue) {
+        this.headerValue = headerValue;
+    }
+
+    @Override
+    public <ReqT, RespT> ClientCall<ReqT, RespT> interceptCall(
+            MethodDescriptor<ReqT, RespT> method, CallOptions callOptions, Channel next) {
+        return new ForwardingClientCall.SimpleForwardingClientCall<ReqT, RespT>(next.newCall(method, callOptions)) {
+            @Override
+            public void start(Listener<RespT> responseListener, Metadata headers) {
+                headers.put(AUTHORIZATION_KEY, headerValue);
+                super.start(responseListener, headers);
+            }
+        };
+    }
+}

other/java/client/src/main/java/seaweedfs/client/ByteBufferOutputStream.java

@@ -0,0 +1,21 @@
+package seaweedfs.client;
+
+import java.io.IOException;
+import java.io.OutputStream;
+import java.nio.ByteBuffer;
+
+public class ByteBufferOutputStream extends OutputStream {
+    private final ByteBuffer buf;
+
+    public ByteBufferOutputStream(ByteBuffer buf) {
+        this.buf = buf;
+    }
+
+    public void write(int b) throws IOException {
+        this.buf.put((byte)b);
+    }
+
+    public void write(byte[] b, int off, int len) throws IOException {
+        this.buf.put(b, off, len);
+    }
+}

other/java/client/src/main/java/seaweedfs/client/ByteBufferPool.java

@@ -0,0 +1,42 @@
+package seaweedfs.client;
+
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+
+import java.nio.Buffer;
+import java.nio.ByteBuffer;
+import java.util.ArrayList;
+import java.util.List;
+
+public class ByteBufferPool {
+
+    private static final int MIN_BUFFER_SIZE = 1 * 1024 * 1024;
+    private static final Logger LOG = LoggerFactory.getLogger(ByteBufferPool.class);
+
+    private static final List<ByteBuffer> bufferList = new ArrayList<>();
+
+    public static synchronized ByteBuffer request(int bufferSize) {
+        if (bufferSize < MIN_BUFFER_SIZE) {
+            bufferSize = MIN_BUFFER_SIZE;
+        }
+        LOG.debug("requested new buffer {}", bufferSize);
+        if (bufferList.isEmpty()) {
+            return ByteBuffer.allocate(bufferSize);
+        }
+        ByteBuffer buffer = bufferList.remove(bufferList.size() - 1);
+        if (buffer.capacity() >= bufferSize) {
+            return buffer;
+        }
+
+        LOG.info("add new buffer from {} to {}", buffer.capacity(), bufferSize);
+        bufferList.add(0, buffer);
+        return ByteBuffer.allocate(bufferSize);
+
+    }
+
+    public static synchronized void release(ByteBuffer obj) {
+        ((Buffer)obj).clear();
+        bufferList.add(0, obj);
+    }
+
+}

other/java/client/src/main/java/seaweedfs/client/ChunkCache.java

@@ -0,0 +1,36 @@
+package seaweedfs.client;
+
+import com.google.common.cache.Cache;
+import com.google.common.cache.CacheBuilder;
+
+import java.util.concurrent.TimeUnit;
+
+public class ChunkCache {
+
+    private Cache<String, byte[]> cache = null;
+
+    public ChunkCache(int maxEntries) {
+        if (maxEntries == 0) {
+            return;
+        }
+        this.cache = CacheBuilder.newBuilder()
+                .maximumSize(maxEntries)
+                .expireAfterWrite(1, TimeUnit.HOURS)
+                .build();
+    }
+
+    public byte[] getChunk(String fileId) {
+        if (this.cache == null) {
+            return null;
+        }
+        return this.cache.getIfPresent(fileId);
+    }
+
+    public void setChunk(String fileId, byte[] data) {
+        if (this.cache == null) {
+            return;
+        }
+        this.cache.put(fileId, data);
+    }
+
+}

other/java/client/src/main/java/seaweedfs/client/FileChunkManifest.java

@@ -0,0 +1,141 @@
+package seaweedfs.client;
+
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+
+import java.io.IOException;
+import java.util.ArrayList;
+import java.util.List;
+
+public class FileChunkManifest {
+
+    private static final Logger LOG = LoggerFactory.getLogger(FileChunkManifest.class);
+
+    private static final int mergeFactor = 1000;
+
+    public static boolean hasChunkManifest(List<FilerProto.FileChunk> chunks) {
+        for (FilerProto.FileChunk chunk : chunks) {
+            if (chunk.getIsChunkManifest()) {
+                return true;
+            }
+        }
+        return false;
+    }
+
+    public static List<FilerProto.FileChunk> resolveChunkManifest(
+            final FilerClient filerClient, List<FilerProto.FileChunk> chunks) throws IOException {
+
+        List<FilerProto.FileChunk> dataChunks = new ArrayList<>();
+
+        for (FilerProto.FileChunk chunk : chunks) {
+            if (!chunk.getIsChunkManifest()) {
+                dataChunks.add(chunk);
+                continue;
+            }
+
+            // IsChunkManifest
+            LOG.debug("fetching chunk manifest:{}", chunk);
+            byte[] data = fetchChunk(filerClient, chunk);
+            FilerProto.FileChunkManifest m = FilerProto.FileChunkManifest.newBuilder().mergeFrom(data).build();
+            List<FilerProto.FileChunk> resolvedChunks = new ArrayList<>();
+            for (FilerProto.FileChunk t : m.getChunksList()) {
+                // avoid deprecated chunk.getFileId()
+                resolvedChunks.add(t.toBuilder().setFileId(FilerClient.toFileId(t.getFid())).build());
+            }
+            dataChunks.addAll(resolveChunkManifest(filerClient, resolvedChunks));
+        }
+
+        return dataChunks;
+    }
+
+    private static byte[] fetchChunk(final FilerClient filerClient, FilerProto.FileChunk chunk) throws IOException {
+
+        String vid = "" + chunk.getFid().getVolumeId();
+        FilerProto.Locations locations = filerClient.vidLocations.get(vid);
+        if (locations == null) {
+            FilerProto.LookupVolumeRequest.Builder lookupRequest = FilerProto.LookupVolumeRequest.newBuilder();
+            lookupRequest.addVolumeIds(vid);
+            FilerProto.LookupVolumeResponse lookupResponse = filerClient
+                    .getBlockingStub().lookupVolume(lookupRequest.build());
+            locations = lookupResponse.getLocationsMapMap().get(vid);
+            filerClient.vidLocations.put(vid, locations);
+            LOG.debug("fetchChunk vid:{} locations:{}", vid, locations);
+        }
+
+        SeaweedRead.ChunkView chunkView = new SeaweedRead.ChunkView(
+                FilerClient.toFileId(chunk.getFid()), // avoid deprecated chunk.getFileId()
+                0,
+                -1,
+                0,
+                true,
+                chunk.getCipherKey().toByteArray(),
+                chunk.getIsCompressed());
+
+        byte[] chunkData = SeaweedRead.chunkCache.getChunk(chunkView.fileId);
+        if (chunkData == null) {
+            LOG.debug("doFetchFullChunkData:{}", chunkView);
+            chunkData = SeaweedRead.doFetchFullChunkData(filerClient, chunkView, locations);
+        }
+        if (chunk.getIsChunkManifest()){
+            LOG.debug("chunk {} size {}", chunkView.fileId, chunkData.length);
+            SeaweedRead.chunkCache.setChunk(chunkView.fileId, chunkData);
+        }
+
+        return chunkData;
+
+    }
+
+    public static List<FilerProto.FileChunk> maybeManifestize(
+            final FilerClient filerClient, List<FilerProto.FileChunk> inputChunks, String parentDirectory) throws IOException {
+        // the return variable
+        List<FilerProto.FileChunk> chunks = new ArrayList<>();
+
+        List<FilerProto.FileChunk> dataChunks = new ArrayList<>();
+        for (FilerProto.FileChunk chunk : inputChunks) {
+            if (!chunk.getIsChunkManifest()) {
+                dataChunks.add(chunk);
+            } else {
+                chunks.add(chunk);
+            }
+        }
+
+        int remaining = dataChunks.size();
+        for (int i = 0; i + mergeFactor < dataChunks.size(); i += mergeFactor) {
+            FilerProto.FileChunk chunk = mergeIntoManifest(filerClient, dataChunks.subList(i, i + mergeFactor), parentDirectory);
+            chunks.add(chunk);
+            remaining -= mergeFactor;
+        }
+
+        // remaining
+        for (int i = dataChunks.size() - remaining; i < dataChunks.size(); i++) {
+            chunks.add(dataChunks.get(i));
+        }
+        return chunks;
+    }
+
+    private static FilerProto.FileChunk mergeIntoManifest(final FilerClient filerClient, List<FilerProto.FileChunk> dataChunks, String parentDirectory) throws IOException {
+        // create and serialize the manifest
+        dataChunks = FilerClient.beforeEntrySerialization(dataChunks);
+        FilerProto.FileChunkManifest.Builder m = FilerProto.FileChunkManifest.newBuilder().addAllChunks(dataChunks);
+        byte[] data = m.build().toByteArray();
+
+        long minOffset = Long.MAX_VALUE;
+        long maxOffset = -1;
+        for (FilerProto.FileChunk chunk : dataChunks) {
+            minOffset = Math.min(minOffset, chunk.getOffset());
+            maxOffset = Math.max(maxOffset, chunk.getSize() + chunk.getOffset());
+        }
+
+        FilerProto.FileChunk.Builder manifestChunk = SeaweedWrite.writeChunk(
+                filerClient.getReplication(),
+                filerClient.getCollection(),
+                filerClient,
+                minOffset,
+                data, 0, data.length, parentDirectory);
+        manifestChunk.setIsChunkManifest(true);
+        manifestChunk.setSize(maxOffset - minOffset);
+        return manifestChunk.build();
+
+    }
+
+}

other/java/client/src/main/java/seaweedfs/client/FilerClient.java

@@ -0,0 +1,378 @@
+package seaweedfs.client;
+
+import com.google.common.base.Strings;
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+
+import java.util.ArrayList;
+import java.util.Arrays;
+import java.util.Iterator;
+import java.util.List;
+
+public class FilerClient extends FilerGrpcClient {
+
+    private static final Logger LOG = LoggerFactory.getLogger(FilerClient.class);
+
+    public FilerClient(String filerHost, int filerGrpcPort) {
+        this(filerHost, filerGrpcPort-10000, filerGrpcPort, "");
+    }
+    public FilerClient(String filerHost, int filerGrpcPort, String cn) { this(filerHost, filerGrpcPort-10000, filerGrpcPort, cn); }
+    public FilerClient(String filerHost, int filerPort, int filerGrpcPort) { this(filerHost, filerPort, filerGrpcPort, ""); }
+
+    public FilerClient(String filerHost, int filerPort, int filerGrpcPort, String cn) {
+        super(filerHost, filerPort, filerGrpcPort, cn);
+    }
+
+    public static String toFileId(FilerProto.FileId fid) {
+        if (fid == null) {
+            return null;
+        }
+        return String.format("%d,%x%08x", fid.getVolumeId(), fid.getFileKey(), fid.getCookie());
+    }
+
+    public static FilerProto.FileId toFileIdObject(String fileIdStr) {
+        if (fileIdStr == null || fileIdStr.length() == 0) {
+            return null;
+        }
+        int commaIndex = fileIdStr.lastIndexOf(',');
+        String volumeIdStr = fileIdStr.substring(0, commaIndex);
+        String fileKeyStr = fileIdStr.substring(commaIndex + 1, fileIdStr.length() - 8);
+        String cookieStr = fileIdStr.substring(fileIdStr.length() - 8);
+
+        return FilerProto.FileId.newBuilder()
+                .setVolumeId(Integer.parseInt(volumeIdStr))
+                .setFileKey(Long.parseLong(fileKeyStr, 16))
+                .setCookie((int) Long.parseLong(cookieStr, 16))
+                .build();
+    }
+
+    public static List<FilerProto.FileChunk> beforeEntrySerialization(List<FilerProto.FileChunk> chunks) {
+        List<FilerProto.FileChunk> cleanedChunks = new ArrayList<>();
+        for (FilerProto.FileChunk chunk : chunks) {
+            FilerProto.FileChunk.Builder chunkBuilder = chunk.toBuilder();
+            chunkBuilder.clearFileId();
+            chunkBuilder.clearSourceFileId();
+            chunkBuilder.setFid(toFileIdObject(chunk.getFileId()));
+            FilerProto.FileId sourceFid = toFileIdObject(chunk.getSourceFileId());
+            if (sourceFid != null) {
+                chunkBuilder.setSourceFid(sourceFid);
+            }
+            cleanedChunks.add(chunkBuilder.build());
+        }
+        return cleanedChunks;
+    }
+
+    public static FilerProto.Entry afterEntryDeserialization(FilerProto.Entry entry) {
+        if (entry.getChunksList().size() <= 0) {
+            if (entry.getContent().isEmpty()) {
+                return entry;
+            } else {
+                if (entry.getAttributes().getFileSize() <= 0) {
+                    FilerProto.Entry.Builder entryBuilder = entry.toBuilder();
+                    FilerProto.FuseAttributes.Builder attrBuilder = entry.getAttributes().toBuilder();
+                    attrBuilder.setFileSize(entry.getContent().size());
+                    entryBuilder.setAttributes(attrBuilder);
+                    return entryBuilder.build();
+                }
+            }
+            return entry;
+        } else {
+            FilerProto.Entry.Builder entryBuilder = entry.toBuilder();
+            entryBuilder.clearChunks();
+            long fileSize = 0;
+            for (FilerProto.FileChunk chunk : entry.getChunksList()) {
+                fileSize = Math.max(fileSize, chunk.getOffset()+chunk.getSize());
+                FilerProto.FileChunk.Builder chunkBuilder = chunk.toBuilder();
+                chunkBuilder.setFileId(toFileId(chunk.getFid()));
+                String sourceFileId = toFileId(chunk.getSourceFid());
+                if (sourceFileId != null) {
+                    chunkBuilder.setSourceFileId(sourceFileId);
+                }
+                entryBuilder.addChunks(chunkBuilder);
+            }
+            if (entry.getAttributes().getFileSize() <= 0) {
+                FilerProto.FuseAttributes.Builder attrBuilder = entry.getAttributes().toBuilder();
+                attrBuilder.setFileSize(fileSize);
+                entryBuilder.setAttributes(attrBuilder);
+            }
+            return entryBuilder.build();
+        }
+    }
+
+    public boolean mkdirs(String path, int mode) {
+        String currentUser = System.getProperty("user.name");
+        return mkdirs(path, mode, 0, 0, currentUser, new String[]{});
+    }
+
+    public boolean mkdirs(String path, int mode, String userName, String[] groupNames) {
+        return mkdirs(path, mode, 0, 0, userName, groupNames);
+    }
+
+    public boolean mkdirs(String path, int mode, int uid, int gid, String userName, String[] groupNames) {
+
+        if ("/".equals(path)) {
+            return true;
+        }
+        String[] dirAndName = SeaweedUtil.toDirAndName(path);
+        String parent = dirAndName[0];
+        String name = dirAndName[1];
+
+        mkdirs(parent, mode, uid, gid, userName, groupNames);
+
+        FilerProto.Entry existingEntry = lookupEntry(parent, name);
+
+        if (existingEntry != null) {
+            return true;
+        }
+
+        return createEntry(
+                parent,
+                newDirectoryEntry(name, mode, uid, gid, userName, groupNames).build()
+        );
+
+    }
+
+    public boolean mv(String oldPath, String newPath) {
+
+        String[] oldDirAndName = SeaweedUtil.toDirAndName(oldPath);
+        String oldParent = oldDirAndName[0];
+        String oldName = oldDirAndName[1];
+
+        String[] newDirAndName = SeaweedUtil.toDirAndName(newPath);
+        String newParent = newDirAndName[0];
+        String newName = newDirAndName[1];
+
+        return atomicRenameEntry(oldParent, oldName, newParent, newName);
+
+    }
+
+    public boolean exists(String path){
+
+        String[] dirAndName = SeaweedUtil.toDirAndName(path);
+        String parent = dirAndName[0];
+        String entryName = dirAndName[1];
+
+        return lookupEntry(parent, entryName) != null;
+    }
+
+    public boolean rm(String path, boolean isRecursive, boolean ignoreRecusiveError) {
+
+        String[] dirAndName = SeaweedUtil.toDirAndName(path);
+        String parent = dirAndName[0];
+        String name = dirAndName[1];
+
+        return deleteEntry(
+                parent,
+                name,
+                true,
+                isRecursive,
+                ignoreRecusiveError);
+    }
+
+    public boolean touch(String path, int mode) {
+
+        String currentUser = System.getProperty("user.name");
+
+        long now = System.currentTimeMillis() / 1000L;
+        return touch(path, now, mode, 0, 0, currentUser, new String[]{});
+
+    }
+
+    public boolean touch(String path, long modifiedTimeSecond, int mode, int uid, int gid, String userName, String[] groupNames) {
+
+        String[] dirAndName = SeaweedUtil.toDirAndName(path);
+        String parent = dirAndName[0];
+        String name = dirAndName[1];
+
+        FilerProto.Entry entry = lookupEntry(parent, name);
+        if (entry == null) {
+            return createEntry(
+                    parent,
+                    newFileEntry(name, modifiedTimeSecond, mode, uid, gid, userName, groupNames).build()
+            );
+        }
+        FilerProto.FuseAttributes.Builder attr = entry.getAttributes().toBuilder();
+        if (modifiedTimeSecond>0) {
+            attr.setMtime(modifiedTimeSecond);
+        }
+        if (uid>0) {
+            attr.setUid(uid);
+        }
+        if (gid>0) {
+            attr.setGid(gid);
+        }
+        if (userName!=null) {
+            attr.setUserName(userName);
+        }
+        if (groupNames!=null) {
+            attr.clearGroupName().addAllGroupName(Arrays.asList(groupNames));
+        }
+        return updateEntry(parent, entry.toBuilder().setAttributes(attr).build());
+    }
+
+    public FilerProto.Entry.Builder newDirectoryEntry(String name, int mode,
+                                                      int uid, int gid, String userName, String[] groupNames) {
+
+        long now = System.currentTimeMillis() / 1000L;
+
+        return FilerProto.Entry.newBuilder()
+                .setName(name)
+                .setIsDirectory(true)
+                .setAttributes(FilerProto.FuseAttributes.newBuilder()
+                        .setMtime(now)
+                        .setCrtime(now)
+                        .setUid(uid)
+                        .setGid(gid)
+                        .setFileMode(mode | 1 << 31)
+                        .setUserName(userName)
+                        .clearGroupName()
+                        .addAllGroupName(Arrays.asList(groupNames)));
+    }
+
+    public FilerProto.Entry.Builder newFileEntry(String name, long modifiedTimeSecond, int mode,
+                                                 int uid, int gid, String userName, String[] groupNames) {
+
+        return FilerProto.Entry.newBuilder()
+                .setName(name)
+                .setIsDirectory(false)
+                .setAttributes(FilerProto.FuseAttributes.newBuilder()
+                        .setMtime(modifiedTimeSecond)
+                        .setCrtime(modifiedTimeSecond)
+                        .setUid(uid)
+                        .setGid(gid)
+                        .setFileMode(mode)
+                        .setUserName(userName)
+                        .clearGroupName()
+                        .addAllGroupName(Arrays.asList(groupNames)));
+    }
+
+    public List<FilerProto.Entry> listEntries(String path) {
+        List<FilerProto.Entry> results = new ArrayList<FilerProto.Entry>();
+        String lastFileName = "";
+        for (int limit = Integer.MAX_VALUE; limit > 0; ) {
+            List<FilerProto.Entry> t = listEntries(path, "", lastFileName, 1024, false);
+            if (t == null) {
+                break;
+            }
+            int nSize = t.size();
+            if (nSize > 0) {
+                limit -= nSize;
+                lastFileName = t.get(nSize - 1).getName();
+            }
+            results.addAll(t);
+            if (t.size() < 1024) {
+                break;
+            }
+        }
+        return results;
+    }
+
+    public List<FilerProto.Entry> listEntries(String path, String entryPrefix, String lastEntryName, int limit, boolean includeLastEntry) {
+        Iterator<FilerProto.ListEntriesResponse> iter = this.getBlockingStub().listEntries(FilerProto.ListEntriesRequest.newBuilder()
+                .setDirectory(path)
+                .setPrefix(entryPrefix)
+                .setStartFromFileName(lastEntryName)
+                .setInclusiveStartFrom(includeLastEntry)
+                .setLimit(limit)
+                .build());
+        List<FilerProto.Entry> entries = new ArrayList<>();
+        while (iter.hasNext()) {
+            FilerProto.ListEntriesResponse resp = iter.next();
+            entries.add(afterEntryDeserialization(resp.getEntry()));
+        }
+        return entries;
+    }
+
+    public FilerProto.Entry lookupEntry(String directory, String entryName) {
+        try {
+            FilerProto.Entry entry = this.getBlockingStub().lookupDirectoryEntry(
+                    FilerProto.LookupDirectoryEntryRequest.newBuilder()
+                            .setDirectory(directory)
+                            .setName(entryName)
+                            .build()).getEntry();
+            if (entry == null) {
+                return null;
+            }
+            return afterEntryDeserialization(entry);
+        } catch (Exception e) {
+            if (e.getMessage().indexOf("filer: no entry is found in filer store") > 0) {
+                return null;
+            }
+            LOG.warn("lookupEntry {}/{}: {}", directory, entryName, e);
+            return null;
+        }
+    }
+
+    public boolean createEntry(String parent, FilerProto.Entry entry) {
+        try {
+            FilerProto.CreateEntryResponse createEntryResponse =
+                    this.getBlockingStub().createEntry(FilerProto.CreateEntryRequest.newBuilder()
+                            .setDirectory(parent)
+                            .setEntry(entry)
+                            .build());
+            if (Strings.isNullOrEmpty(createEntryResponse.getError())) {
+                return true;
+            }
+            LOG.warn("createEntry {}/{} error: {}", parent, entry.getName(), createEntryResponse.getError());
+            return false;
+        } catch (Exception e) {
+            LOG.warn("createEntry {}/{}: {}", parent, entry.getName(), e);
+            return false;
+        }
+    }
+
+    public boolean updateEntry(String parent, FilerProto.Entry entry) {
+        try {
+            this.getBlockingStub().updateEntry(FilerProto.UpdateEntryRequest.newBuilder()
+                    .setDirectory(parent)
+                    .setEntry(entry)
+                    .build());
+        } catch (Exception e) {
+            LOG.warn("updateEntry {}/{}: {}", parent, entry.getName(), e);
+            return false;
+        }
+        return true;
+    }
+
+    public boolean deleteEntry(String parent, String entryName, boolean isDeleteFileChunk, boolean isRecursive, boolean ignoreRecusiveError) {
+        try {
+            this.getBlockingStub().deleteEntry(FilerProto.DeleteEntryRequest.newBuilder()
+                    .setDirectory(parent)
+                    .setName(entryName)
+                    .setIsDeleteData(isDeleteFileChunk)
+                    .setIsRecursive(isRecursive)
+                    .setIgnoreRecursiveError(ignoreRecusiveError)
+                    .build());
+        } catch (Exception e) {
+            LOG.warn("deleteEntry {}/{}: {}", parent, entryName, e);
+            return false;
+        }
+        return true;
+    }
+
+    public boolean atomicRenameEntry(String oldParent, String oldName, String newParent, String newName) {
+        try {
+            this.getBlockingStub().atomicRenameEntry(FilerProto.AtomicRenameEntryRequest.newBuilder()
+                    .setOldDirectory(oldParent)
+                    .setOldName(oldName)
+                    .setNewDirectory(newParent)
+                    .setNewName(newName)
+                    .build());
+        } catch (Exception e) {
+            LOG.warn("atomicRenameEntry {}/{} => {}/{}: {}", oldParent, oldName, newParent, newName, e);
+            return false;
+        }
+        return true;
+    }
+
+    public Iterator<FilerProto.SubscribeMetadataResponse> watch(String prefix, String clientName, long sinceNs) {
+        return this.getBlockingStub().subscribeMetadata(FilerProto.SubscribeMetadataRequest.newBuilder()
+                .setPathPrefix(prefix)
+                .setClientName(clientName)
+                .setSinceNs(sinceNs)
+                .setClientId(this.randomClientId)
+                .build()
+        );
+    }
+
+}

other/java/client/src/main/java/seaweedfs/client/FilerGrpcClient.java

@@ -0,0 +1,191 @@
+package seaweedfs.client;
+
+import io.grpc.ManagedChannel;
+import io.grpc.ManagedChannelBuilder;
+import io.grpc.netty.shaded.io.grpc.netty.NegotiationType;
+import io.grpc.netty.shaded.io.grpc.netty.NettyChannelBuilder;
+import io.grpc.netty.shaded.io.netty.handler.ssl.SslContext;
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+
+import java.util.ArrayList;
+import java.util.HashMap;
+import java.util.List;
+import java.util.Map;
+import java.util.Random;
+import java.util.concurrent.TimeUnit;
+import java.util.concurrent.atomic.AtomicBoolean;
+import java.util.concurrent.atomic.AtomicInteger;
+
+public class FilerGrpcClient {
+
+    private static final Logger logger = LoggerFactory.getLogger(FilerGrpcClient.class);
+    private static final SslContext sslContext;
+    private static final String protocol;
+
+    // gRPC keepalive settings - must be consistent with server-side settings in grpc_client_server.go
+    private static final long KEEP_ALIVE_TIME_SECONDS = 60L;
+    private static final long KEEP_ALIVE_TIMEOUT_SECONDS = 20L;
+
+    static {
+        sslContext = FilerSecurityContext.getGrpcSslContext();
+        protocol = FilerSecurityContext.isHttpSecurityEnabled() ? "https" : "http";
+    }
+
+    public final int VOLUME_SERVER_ACCESS_DIRECT = 0;
+    public final int VOLUME_SERVER_ACCESS_PUBLIC_URL = 1;
+    public final int VOLUME_SERVER_ACCESS_FILER_PROXY = 2;
+    public final Map<String, FilerProto.Locations> vidLocations = new HashMap<>();
+    protected int randomClientId;
+
+    private static final AtomicBoolean plaintextBasicAuthWarned = new AtomicBoolean(false);
+
+    // Connection pool to handle concurrent requests
+    private static final int CHANNEL_POOL_SIZE = 4;
+    private final List<ManagedChannel> channelPool;
+    private final AtomicInteger channelIndex = new AtomicInteger(0);
+
+    private boolean cipher = false;
+    private String collection = "";
+    private String replication = "";
+    private int volumeServerAccess = VOLUME_SERVER_ACCESS_DIRECT;
+    private String filerAddress;
+
+    public FilerGrpcClient(String host, int port, int grpcPort, String cn) {
+        this(host, port, grpcPort, cn, sslContext);
+    }
+
+    public FilerGrpcClient(String host, int port, int grpcPort, String cn, SslContext sslContext) {
+
+        filerAddress = SeaweedUtil.joinHostPort(host, port);
+
+        // Create a pool of channels for better concurrency handling
+        channelPool = new ArrayList<>(CHANNEL_POOL_SIZE);
+
+        for (int i = 0; i < CHANNEL_POOL_SIZE; i++) {
+            channelPool.add(createChannelBuilder(host, grpcPort, sslContext, cn).build());
+        }
+
+        // Get filer configuration using first channel
+        FilerProto.GetFilerConfigurationResponse filerConfigurationResponse = SeaweedFilerGrpc
+                .newBlockingStub(channelPool.get(0)).getFilerConfiguration(
+                        FilerProto.GetFilerConfigurationRequest.newBuilder().build());
+        cipher = filerConfigurationResponse.getCipher();
+        collection = filerConfigurationResponse.getCollection();
+        replication = filerConfigurationResponse.getReplication();
+        randomClientId = new Random().nextInt();
+
+    }
+
+    /**
+     * Creates a NettyChannelBuilder with common gRPC configuration.
+     * Supports plaintext and TLS modes with optional authority override.
+     */
+    private NettyChannelBuilder createChannelBuilder(String host, int grpcPort, SslContext sslContext, String cn) {
+        NettyChannelBuilder builder = NettyChannelBuilder.forAddress(host, grpcPort)
+                .maxInboundMessageSize(1024 * 1024 * 1024)
+                .maxInboundMetadataSize(1024 * 1024)
+                .flowControlWindow(16 * 1024 * 1024)
+                .initialFlowControlWindow(16 * 1024 * 1024)
+                .maxHeaderListSize(16 * 1024 * 1024)
+                .keepAliveTime(KEEP_ALIVE_TIME_SECONDS, TimeUnit.SECONDS)
+                .keepAliveTimeout(KEEP_ALIVE_TIMEOUT_SECONDS, TimeUnit.SECONDS)
+                .keepAliveWithoutCalls(false)
+                .withOption(io.grpc.netty.shaded.io.netty.channel.ChannelOption.SO_RCVBUF, 16 * 1024 * 1024)
+                .withOption(io.grpc.netty.shaded.io.netty.channel.ChannelOption.SO_SNDBUF, 16 * 1024 * 1024);
+
+        if (sslContext == null) {
+            builder.usePlaintext();
+        } else {
+            builder.negotiationType(NegotiationType.TLS).sslContext(sslContext);
+            if (!cn.isEmpty()) {
+                builder.overrideAuthority(cn);
+            }
+        }
+
+        String basicAuthHeader = FilerSecurityContext.getBasicAuthHeaderValue();
+        if (basicAuthHeader != null) {
+            if (sslContext == null && plaintextBasicAuthWarned.compareAndSet(false, true)) {
+                logger.warn("Basic Auth is enabled on a plaintext gRPC channel; credentials are sent in cleartext. Use TLS to the proxy.");
+            }
+            builder.intercept(new BasicAuthInterceptor(basicAuthHeader));
+        }
+        return builder;
+    }
+
+    // Get a channel from the pool using round-robin
+    private ManagedChannel getChannel() {
+        int raw = channelIndex.getAndIncrement();
+        int index = Math.floorMod(raw, CHANNEL_POOL_SIZE);
+        return channelPool.get(index);
+    }
+
+    public boolean isCipher() {
+        return cipher;
+    }
+
+    public String getCollection() {
+        return collection;
+    }
+
+    public String getReplication() {
+        return replication;
+    }
+
+    public void shutdown() throws InterruptedException {
+        for (ManagedChannel channel : channelPool) {
+            channel.shutdown();
+        }
+        for (ManagedChannel channel : channelPool) {
+            channel.awaitTermination(5, TimeUnit.SECONDS);
+        }
+    }
+
+    public SeaweedFilerGrpc.SeaweedFilerBlockingStub getBlockingStub() {
+        // Return a new stub using a channel from the pool (round-robin)
+        return SeaweedFilerGrpc.newBlockingStub(getChannel());
+    }
+
+    public SeaweedFilerGrpc.SeaweedFilerStub getAsyncStub() {
+        return SeaweedFilerGrpc.newStub(getChannel());
+    }
+
+    public SeaweedFilerGrpc.SeaweedFilerFutureStub getFutureStub() {
+        return SeaweedFilerGrpc.newFutureStub(getChannel());
+    }
+
+    public void setAccessVolumeServerDirectly() {
+        this.volumeServerAccess = VOLUME_SERVER_ACCESS_DIRECT;
+    }
+
+    public boolean isAccessVolumeServerDirectly() {
+        return this.volumeServerAccess == VOLUME_SERVER_ACCESS_DIRECT;
+    }
+
+    public void setAccessVolumeServerByPublicUrl() {
+        this.volumeServerAccess = VOLUME_SERVER_ACCESS_PUBLIC_URL;
+    }
+
+    public boolean isAccessVolumeServerByPublicUrl() {
+        return this.volumeServerAccess == VOLUME_SERVER_ACCESS_PUBLIC_URL;
+    }
+
+    public void setAccessVolumeServerByFilerProxy() {
+        this.volumeServerAccess = VOLUME_SERVER_ACCESS_FILER_PROXY;
+    }
+
+    public boolean isAccessVolumeServerByFilerProxy() {
+        return this.volumeServerAccess == VOLUME_SERVER_ACCESS_FILER_PROXY;
+    }
+
+    public String getChunkUrl(String chunkId, String url, String publicUrl) {
+        switch (this.volumeServerAccess) {
+            case VOLUME_SERVER_ACCESS_PUBLIC_URL:
+                return String.format("%s://%s/%s", protocol, publicUrl, chunkId);
+            case VOLUME_SERVER_ACCESS_FILER_PROXY:
+                return String.format("%s://%s/?proxyChunkId=%s", protocol, this.filerAddress, chunkId);
+            default:
+                return String.format("%s://%s/%s", protocol, url, chunkId);
+        }
+    }
+}

other/java/client/src/main/java/seaweedfs/client/FilerSecurityContext.java

@@ -0,0 +1,197 @@
+package seaweedfs.client;
+
+import com.google.common.base.Strings;
+import com.moandjiezana.toml.Toml;
+import io.grpc.netty.shaded.io.grpc.netty.GrpcSslContexts;
+import io.grpc.netty.shaded.io.netty.handler.ssl.SslContext;
+import io.grpc.netty.shaded.io.netty.handler.ssl.SslContextBuilder;
+import org.apache.http.ssl.SSLContextBuilder;
+import org.apache.http.ssl.SSLContexts;
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+
+import javax.net.ssl.*;
+import java.io.File;
+import java.io.IOException;
+import java.nio.charset.StandardCharsets;
+import java.security.GeneralSecurityException;
+import java.security.KeyStore;
+import java.security.PrivateKey;
+import java.security.cert.X509Certificate;
+import java.util.Base64;
+
+public abstract class FilerSecurityContext extends SslContext {
+//extends Netty SslContext to access its protected static utility methods in
+//buildHttpSslContext()
+
+    private static final Logger logger = LoggerFactory.getLogger(FilerSecurityContext.class);
+    private static boolean grpcSecurityEnabled;
+    private static boolean httpSecurityEnabled;
+    private static SslContext grpcSslContext;
+    private static SSLContext httpSslContext;
+
+    private static String grpcTrustCertCollectionFilePath;
+    private static String grpcClientCertChainFilePath;
+    private static String grpcClientPrivateKeyFilePath;
+
+    private static String httpTrustCertCollectionFilePath;
+    private static String httpClientCertChainFilePath;
+    private static String httpClientPrivateKeyFilePath;
+
+    // Optional HTTP Basic Auth for reaching SeaweedFS through an Nginx reverse proxy
+    // that has auth_basic enabled. Applied to both the filer gRPC channel and the
+    // volume/proxy HTTP requests. Precomputed so per-chunk requests don't re-encode.
+    private static volatile String basicAuthHeaderValue;
+
+
+    static {
+        String securityFileName = "security.toml";
+        String home = System.getProperty("user.home");
+        File f1 = new File("./"+securityFileName);
+        File f2 = new File(home + "/.seaweedfs/"+securityFileName);
+        File f3 = new File("/etc/seaweedfs/"+securityFileName);
+
+        File securityFile = f1.exists()? f1 : f2.exists() ? f2 : f3.exists()? f3 : null;
+
+        if (securityFile==null){
+            logger.debug("Security file not found");
+            grpcSecurityEnabled = false;
+            httpSecurityEnabled = false;
+        } else {
+
+            Toml toml = new Toml().read(securityFile);
+            logger.debug("reading ssl setup from {}", securityFile);
+
+            basicAuthHeaderValue = computeBasicAuthHeaderValue(
+                    toml.getString("basic_auth.username"), toml.getString("basic_auth.password"));
+
+            grpcTrustCertCollectionFilePath = toml.getString("grpc.ca");
+            logger.debug("loading gRPC ca from {}", grpcTrustCertCollectionFilePath);
+            grpcClientCertChainFilePath = toml.getString("grpc.client.cert");
+            logger.debug("loading gRPC client ca from {}", grpcClientCertChainFilePath);
+            grpcClientPrivateKeyFilePath = toml.getString("grpc.client.key");
+            logger.debug("loading gRPC client key from {}", grpcClientPrivateKeyFilePath);
+
+            if (Strings.isNullOrEmpty(grpcClientCertChainFilePath) && Strings.isNullOrEmpty(grpcClientPrivateKeyFilePath)) {
+                logger.debug("gRPC private key file locations not set");
+                grpcSecurityEnabled = false;
+            } else {
+                try {
+                    grpcSslContext = buildGrpcSslContext();
+                    grpcSecurityEnabled = true;
+                } catch (Exception e) {
+                    logger.warn("Couldn't initialize gRPC security context, filer operations are likely to fail!", e);
+                    grpcSslContext = null;
+                    grpcSecurityEnabled = false;
+                }
+            }
+
+            if (toml.getBoolean("https.client.enabled")) {
+                httpTrustCertCollectionFilePath = toml.getString("https.client.ca");
+                logger.debug("loading HTTP ca from {}", httpTrustCertCollectionFilePath);
+                httpClientCertChainFilePath = toml.getString("https.client.cert");
+                logger.debug("loading HTTP client ca from {}", httpClientCertChainFilePath);
+                httpClientPrivateKeyFilePath = toml.getString("https.client.key");
+                logger.debug("loading HTTP client key from {}", httpClientPrivateKeyFilePath);
+
+                if (Strings.isNullOrEmpty(httpClientCertChainFilePath) && Strings.isNullOrEmpty(httpClientPrivateKeyFilePath)) {
+                    logger.debug("HTTP private key file locations not set");
+                    httpSecurityEnabled = false;
+                } else {
+                    try {
+                        httpSslContext = buildHttpSslContext();
+                        httpSecurityEnabled = true;
+                    } catch (Exception e) {
+                        logger.warn("Couldn't initialize HTTP security context, volume operations are likely to fail!", e);
+                        httpSslContext = null;
+                        httpSecurityEnabled = false;
+                    }
+                }
+            } else {
+                httpSecurityEnabled = false;
+            }
+        }
+        // possibly fix the format https://netty.io/wiki/sslcontextbuilder-and-private-key.html
+    }
+
+    public static boolean isGrpcSecurityEnabled() {
+        return grpcSecurityEnabled;
+    }
+
+    public static boolean isHttpSecurityEnabled() {
+        return httpSecurityEnabled;
+    }
+
+    public static SslContext getGrpcSslContext() {
+        return grpcSslContext;
+    }
+
+    public static SSLContext getHttpSslContext() {
+        return httpSslContext;
+    }
+
+    // Configure HTTP Basic Auth programmatically instead of via security.toml. Must be
+    // called before constructing a FilerClient so the credentials reach the gRPC channel.
+    public static void setBasicAuth(String username, String password) {
+        basicAuthHeaderValue = computeBasicAuthHeaderValue(username, password);
+    }
+
+    public static boolean isBasicAuthEnabled() {
+        return basicAuthHeaderValue != null;
+    }
+
+    // Returns the "Basic <base64(user:password)>" Authorization header value, or null
+    // when no Basic Auth credentials are configured.
+    public static String getBasicAuthHeaderValue() {
+        return basicAuthHeaderValue;
+    }
+
+    private static String computeBasicAuthHeaderValue(String username, String password) {
+        if (Strings.isNullOrEmpty(username)) {
+            return null;
+        }
+        String credentials = username + ":" + (password == null ? "" : password);
+        return "Basic " + Base64.getEncoder().encodeToString(credentials.getBytes(StandardCharsets.UTF_8));
+    }
+
+    private static SslContext buildGrpcSslContext() throws SSLException {
+        SslContextBuilder builder = GrpcSslContexts.forClient();
+        if (grpcTrustCertCollectionFilePath != null) {
+            builder.trustManager(new File(grpcTrustCertCollectionFilePath));
+        }
+        if (grpcClientCertChainFilePath != null && grpcClientPrivateKeyFilePath != null) {
+            builder.keyManager(new File(grpcClientCertChainFilePath), new File(grpcClientPrivateKeyFilePath));
+        }
+
+        return builder.build();
+    }
+
+    private static SSLContext buildHttpSslContext() throws GeneralSecurityException, IOException {
+        SSLContextBuilder builder = SSLContexts.custom();
+
+        if (httpTrustCertCollectionFilePath != null) {
+            final X509Certificate[] trustCerts = toX509Certificates(new File(httpTrustCertCollectionFilePath));
+            final KeyStore ks = KeyStore.getInstance(KeyStore.getDefaultType());
+            ks.load(null, null);
+
+            int i = 0;
+            for (X509Certificate cert: trustCerts) {
+                String alias = Integer.toString(++i);
+                ks.setCertificateEntry(alias, cert);
+            }
+
+            builder.loadTrustMaterial(ks, null);
+        }
+
+        if (httpClientCertChainFilePath != null && httpClientPrivateKeyFilePath != null) {
+            final X509Certificate[] keyCerts = toX509Certificates(new File(httpClientCertChainFilePath));
+            final PrivateKey key = toPrivateKey(new File(httpClientPrivateKeyFilePath), null);
+            char[] emptyPassword = new char[0];
+            final KeyStore ks = buildKeyStore(keyCerts, key, emptyPassword, null);
+            logger.debug("Loaded {} key certificates", ks.size());
+            builder.loadKeyMaterial(ks, emptyPassword);
+        }
+
+        return builder.build();
+    }
+}

other/java/client/src/main/java/seaweedfs/client/Gzip.java

@@ -0,0 +1,41 @@
+package seaweedfs.client;
+
+import java.io.ByteArrayInputStream;
+import java.io.ByteArrayOutputStream;
+import java.io.IOException;
+import java.io.InputStream;
+import java.util.zip.GZIPInputStream;
+import java.util.zip.GZIPOutputStream;
+
+public class Gzip {
+    public static byte[] compress(byte[] data) throws IOException {
+        ByteArrayOutputStream bos = new ByteArrayOutputStream(data.length);
+        GZIPOutputStream gzip = new GZIPOutputStream(bos);
+        gzip.write(data);
+        gzip.close();
+        byte[] compressed = bos.toByteArray();
+        bos.close();
+        return compressed;
+    }
+
+    public static byte[] decompress(byte[] compressed) {
+        try {
+            ByteArrayInputStream bis = new ByteArrayInputStream(compressed);
+            GZIPInputStream gis = new GZIPInputStream(bis);
+            return readAll(gis);
+        } catch (Exception e) {
+            return compressed;
+        }
+    }
+
+    private static byte[] readAll(InputStream input) throws IOException {
+        try (ByteArrayOutputStream output = new ByteArrayOutputStream()) {
+            byte[] buffer = new byte[4096];
+            int n;
+            while (-1 != (n = input.read(buffer))) {
+                output.write(buffer, 0, n);
+            }
+            return output.toByteArray();
+        }
+    }
+}

other/java/client/src/main/java/seaweedfs/client/ReadChunks.java

@@ -0,0 +1,112 @@
+package seaweedfs.client;
+
+import java.io.IOException;
+import java.util.ArrayList;
+import java.util.Collections;
+import java.util.Comparator;
+import java.util.List;
+
+public class ReadChunks {
+
+    public static List<SeaweedRead.VisibleInterval> readResolvedChunks(List<FilerProto.FileChunk> chunkList) throws IOException {
+        List<Point> points = new ArrayList<>(chunkList.size() * 2);
+        for (FilerProto.FileChunk chunk : chunkList) {
+            points.add(new Point(chunk.getOffset(), chunk, true));
+            points.add(new Point(chunk.getOffset() + chunk.getSize(), chunk, false));
+        }
+
+        Collections.sort(points, new Comparator<Point>() {
+            @Override
+            public int compare(Point a, Point b) {
+                int xComparison = Long.compare(a.x, b.x);
+                if (xComparison != 0) {
+                    return xComparison;
+                }
+
+                // If x values are equal, compare ts
+                int tsComparison = Long.compare(a.ts, b.ts);
+                if (tsComparison != 0) {
+                    return tsComparison;
+                }
+
+                // If both x and ts are equal, prioritize start points
+                return Boolean.compare(b.isStart, a.isStart); // b.isStart first to prioritize starts
+            }
+        });
+
+        long prevX = 0;
+        List<SeaweedRead.VisibleInterval> visibles = new ArrayList<>();
+        ArrayList<Point> queue = new ArrayList<>();
+        for (Point point : points) {
+            if (point.isStart) {
+                if (queue.size() > 0) {
+                    int lastIndex = queue.size() - 1;
+                    Point lastPoint = queue.get(lastIndex);
+                    if (point.x != prevX && lastPoint.ts < point.ts) {
+                        addToVisibles(visibles, prevX, lastPoint, point);
+                        prevX = point.x;
+                    }
+                }
+                // insert into queue
+                for (int i = queue.size(); i >= 0; i--) {
+                    if (i == 0 || queue.get(i - 1).ts <= point.ts) {
+                        if (i == queue.size()) {
+                            prevX = point.x;
+                        }
+                        queue.add(i, point);
+                        break;
+                    }
+                }
+            } else {
+                int lastIndex = queue.size() - 1;
+                int index = lastIndex;
+                Point startPoint = null;
+                for (; index >= 0; index--) {
+                    startPoint = queue.get(index);
+                    if (startPoint.ts == point.ts) {
+                        queue.remove(index);
+                        break;
+                    }
+                }
+                if (index == lastIndex && startPoint != null) {
+                    addToVisibles(visibles, prevX, startPoint, point);
+                    prevX = point.x;
+                }
+            }
+        }
+
+        return visibles;
+
+    }
+
+    private static void addToVisibles(List<SeaweedRead.VisibleInterval> visibles, long prevX, Point startPoint, Point point) {
+        if (prevX < point.x) {
+            FilerProto.FileChunk chunk = startPoint.chunk;
+            visibles.add(new SeaweedRead.VisibleInterval(
+                    prevX,
+                    point.x,
+                    chunk.getFileId(),
+                    chunk.getModifiedTsNs(),
+                    prevX - chunk.getOffset(),
+                    chunk.getOffset() == prevX && chunk.getSize() == prevX - startPoint.x,
+                    chunk.getCipherKey().toByteArray(),
+                    chunk.getIsCompressed()
+            ));
+        }
+    }
+
+    static class Point {
+        long x;
+        long ts;
+        FilerProto.FileChunk chunk;
+        boolean isStart;
+
+        public Point(long x, FilerProto.FileChunk chunk, boolean isStart) {
+            this.x = x;
+            this.ts = chunk.getModifiedTsNs();
+            this.chunk = chunk;
+            this.isStart = isStart;
+        }
+    }
+
+}

other/java/client/src/main/java/seaweedfs/client/RemoteUtil.java

@@ -0,0 +1,23 @@
+package seaweedfs.client;
+
+import java.io.IOException;
+
+public class RemoteUtil {
+    public static boolean isInRemoteOnly(FilerProto.Entry entry) {
+        if (entry.getChunksList() == null || entry.getChunksList().isEmpty()) {
+            return entry.getRemoteEntry() != null && entry.getRemoteEntry().getRemoteSize() > 0;
+        }
+        return false;
+    }
+
+    public static FilerProto.Entry downloadRemoteEntry(FilerClient filerClient, String fullpath, FilerProto.Entry entry) throws IOException {
+        String dir = SeaweedOutputStream.getParentDirectory(fullpath);
+        String name = SeaweedOutputStream.getFileName(fullpath);
+
+        final FilerProto.CacheRemoteObjectToLocalClusterResponse response = filerClient.getBlockingStub()
+                .cacheRemoteObjectToLocalCluster(FilerProto.CacheRemoteObjectToLocalClusterRequest.newBuilder()
+                .setDirectory(dir).setName(name).build());
+
+        return response.getEntry();
+    }
+}

other/java/client/src/main/java/seaweedfs/client/SeaweedCipher.java

@@ -0,0 +1,55 @@
+package seaweedfs.client;
+
+import javax.crypto.Cipher;
+import javax.crypto.spec.GCMParameterSpec;
+import javax.crypto.spec.SecretKeySpec;
+import java.security.SecureRandom;
+
+public class SeaweedCipher {
+    // AES-GCM parameters
+    public static final int AES_KEY_SIZE = 256; // in bits
+    public static final int GCM_NONCE_LENGTH = 12; // in bytes
+    public static final int GCM_TAG_LENGTH = 16; // in bytes
+
+    private static SecureRandom random = new SecureRandom();
+
+    public static byte[] genCipherKey() throws Exception {
+        byte[] key = new byte[AES_KEY_SIZE / 8];
+        random.nextBytes(key);
+        return key;
+    }
+
+    public static byte[] encrypt(byte[] clearTextbytes, byte[] cipherKey) throws Exception {
+        return encrypt(clearTextbytes, 0, clearTextbytes.length, cipherKey);
+    }
+
+    public static byte[] encrypt(byte[] clearTextbytes, int offset, int length, byte[] cipherKey) throws Exception {
+
+        final byte[] nonce = new byte[GCM_NONCE_LENGTH];
+        random.nextBytes(nonce);
+        GCMParameterSpec spec = new GCMParameterSpec(GCM_TAG_LENGTH * 8, nonce);
+        SecretKeySpec keySpec = new SecretKeySpec(cipherKey, "AES");
+
+        Cipher AES_cipherInstance = Cipher.getInstance("AES/GCM/NoPadding");
+        AES_cipherInstance.init(Cipher.ENCRYPT_MODE, keySpec, spec);
+
+        byte[] encryptedText = AES_cipherInstance.doFinal(clearTextbytes, offset, length);
+
+        byte[] iv = AES_cipherInstance.getIV();
+        byte[] message = new byte[GCM_NONCE_LENGTH + length + GCM_TAG_LENGTH];
+        System.arraycopy(iv, 0, message, 0, GCM_NONCE_LENGTH);
+        System.arraycopy(encryptedText, 0, message, GCM_NONCE_LENGTH, encryptedText.length);
+
+        return message;
+    }
+
+    public static byte[] decrypt(byte[] encryptedText, byte[] cipherKey) throws Exception {
+        final Cipher AES_cipherInstance = Cipher.getInstance("AES/GCM/NoPadding");
+        GCMParameterSpec params = new GCMParameterSpec(GCM_TAG_LENGTH * 8, encryptedText, 0, GCM_NONCE_LENGTH);
+        SecretKeySpec keySpec = new SecretKeySpec(cipherKey, "AES");
+        AES_cipherInstance.init(Cipher.DECRYPT_MODE, keySpec, params);
+        byte[] decryptedText = AES_cipherInstance.doFinal(encryptedText, GCM_NONCE_LENGTH, encryptedText.length - GCM_NONCE_LENGTH);
+        return decryptedText;
+    }
+
+}

other/java/client/src/main/java/seaweedfs/client/SeaweedInputStream.java

@@ -0,0 +1,232 @@
+package seaweedfs.client;
+
+// based on org.apache.hadoop.fs.azurebfs.services.AbfsInputStream
+
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+
+import java.io.EOFException;
+import java.io.FileNotFoundException;
+import java.io.IOException;
+import java.io.InputStream;
+import java.nio.ByteBuffer;
+import java.util.List;
+
+public class SeaweedInputStream extends InputStream {
+
+    private static final Logger LOG = LoggerFactory.getLogger(SeaweedInputStream.class);
+    private static final IOException EXCEPTION_STREAM_IS_CLOSED = new IOException("Stream is closed!");
+
+    private final FilerClient filerClient;
+    private final String path;
+    private final List<SeaweedRead.VisibleInterval> visibleIntervalList;
+    private final long contentLength;
+    private FilerProto.Entry entry;
+
+    private long position = 0; // cursor of the file
+
+    private boolean closed = false;
+
+    public SeaweedInputStream(
+            final FilerClient filerClient,
+            final String fullpath) throws IOException {
+        this.path = fullpath;
+        this.filerClient = filerClient;
+        this.entry = filerClient.lookupEntry(
+                SeaweedOutputStream.getParentDirectory(fullpath),
+                SeaweedOutputStream.getFileName(fullpath));
+        if (entry == null) {
+            throw new FileNotFoundException();
+        }
+
+        if (RemoteUtil.isInRemoteOnly(entry)) {
+            entry = RemoteUtil.downloadRemoteEntry(filerClient, fullpath, entry);
+        }
+
+        this.contentLength = SeaweedRead.fileSize(entry);
+        this.visibleIntervalList = SeaweedRead.nonOverlappingVisibleIntervals(filerClient, entry.getChunksList());
+
+        LOG.debug("new path:{} entry:{} visibleIntervalList:{}", path, entry, visibleIntervalList);
+
+    }
+
+    public SeaweedInputStream(
+            final FilerClient filerClient,
+            final String path,
+            final FilerProto.Entry entry) throws IOException {
+        this.filerClient = filerClient;
+        this.path = path;
+        this.entry = entry;
+
+        if (RemoteUtil.isInRemoteOnly(entry)) {
+            this.entry = RemoteUtil.downloadRemoteEntry(filerClient, path, entry);
+        }
+
+        this.contentLength = SeaweedRead.fileSize(entry);
+        this.visibleIntervalList = SeaweedRead.nonOverlappingVisibleIntervals(filerClient, entry.getChunksList());
+
+        LOG.debug("new path:{} entry:{} visibleIntervalList:{}", path, entry, visibleIntervalList);
+
+    }
+
+    public String getPath() {
+        return path;
+    }
+
+    @Override
+    public int read() throws IOException {
+        byte[] b = new byte[1];
+        int numberOfBytesRead = read(b, 0, 1);
+        if (numberOfBytesRead < 0) {
+            return -1;
+        } else {
+            return (b[0] & 0xFF);
+        }
+    }
+
+    @Override
+    public int read(final byte[] b, final int off, final int len) throws IOException {
+
+        if (b == null) {
+            throw new IllegalArgumentException("null byte array passed in to read() method");
+        }
+        if (off >= b.length) {
+            throw new IllegalArgumentException("offset greater than length of array");
+        }
+        if (len < 0) {
+            throw new IllegalArgumentException("requested read length is less than zero");
+        }
+        if (len > (b.length - off)) {
+            throw new IllegalArgumentException(
+                    "requested read length is more than will fit after requested offset in buffer");
+        }
+
+        ByteBuffer buf = ByteBuffer.wrap(b, off, len);
+        return read(buf);
+
+    }
+
+    // implement ByteBufferReadable
+    public synchronized int read(ByteBuffer buf) throws IOException {
+
+        if (position < 0) {
+            throw new IllegalArgumentException("attempting to read from negative offset");
+        }
+        if (position >= contentLength) {
+            return -1; // Hadoop prefers -1 to EOFException
+        }
+
+        long bytesRead = 0;
+        int len = buf.remaining();
+        if (this.position < Integer.MAX_VALUE && (this.position + len) <= entry.getContent().size()) {
+            entry.getContent().substring((int) this.position, (int) (this.position + len)).copyTo(buf);
+            bytesRead = len; // FIX: Update bytesRead after inline copy
+        } else {
+            // Use the known contentLength instead of recomputing from the entry to avoid
+            // races
+            bytesRead = SeaweedRead.read(this.filerClient, this.visibleIntervalList, this.position, buf,
+                    this.contentLength);
+        }
+
+        if (bytesRead > Integer.MAX_VALUE) {
+            throw new IOException("Unexpected Content-Length");
+        }
+
+        // Clamp premature EOFs: do not return -1 unless position >= contentLength
+        if (bytesRead < 0 && position < contentLength) {
+            bytesRead = 0;
+        }
+
+        if (bytesRead > 0) {
+            this.position += bytesRead;
+        }
+
+        return (int) bytesRead;
+    }
+
+    public synchronized void seek(long n) throws IOException {
+        if (closed) {
+            throw EXCEPTION_STREAM_IS_CLOSED;
+        }
+        if (n < 0) {
+            throw new EOFException("Cannot seek to a negative offset");
+        }
+        if (n > contentLength) {
+            throw new EOFException("Attempted to seek or read past the end of the file");
+        }
+        this.position = n;
+    }
+
+    @Override
+    public synchronized long skip(long n) throws IOException {
+        if (closed) {
+            throw EXCEPTION_STREAM_IS_CLOSED;
+        }
+        if (this.position == contentLength) {
+            if (n > 0) {
+                throw new EOFException("Attempted to seek or read past the end of the file");
+            }
+        }
+        long newPos = this.position + n;
+        if (newPos < 0) {
+            newPos = 0;
+            n = newPos - this.position;
+        }
+        if (newPos > contentLength) {
+            newPos = contentLength;
+            n = newPos - this.position;
+        }
+        seek(newPos);
+        return n;
+    }
+
+    /**
+     * Return the size of the remaining available bytes
+     * if the size is less than or equal to {@link Integer#MAX_VALUE},
+     * otherwise, return {@link Integer#MAX_VALUE}.
+     * <p>
+     * This is to match the behavior of DFSInputStream.available(),
+     * which some clients may rely on (HBase write-ahead log reading in
+     * particular).
+     */
+    @Override
+    public synchronized int available() throws IOException {
+        if (closed) {
+            throw EXCEPTION_STREAM_IS_CLOSED;
+        }
+        final long remaining = this.contentLength - this.position;
+        return remaining <= Integer.MAX_VALUE
+                ? (int) remaining
+                : Integer.MAX_VALUE;
+    }
+
+    /**
+     * Returns the length of the file that this stream refers to. Note that the
+     * length returned is the length
+     * as of the time the Stream was opened. Specifically, if there have been
+     * subsequent appends to the file,
+     * they won't be reflected in the returned length.
+     *
+     * @return length of the file.
+     * @throws IOException if the stream is closed
+     */
+    public long length() throws IOException {
+        if (closed) {
+            throw EXCEPTION_STREAM_IS_CLOSED;
+        }
+        return contentLength;
+    }
+
+    public synchronized long getPos() throws IOException {
+        if (closed) {
+            throw EXCEPTION_STREAM_IS_CLOSED;
+        }
+        return position;
+    }
+
+    @Override
+    public synchronized void close() throws IOException {
+        closed = true;
+    }
+
+}

other/java/client/src/main/java/seaweedfs/client/SeaweedOutputStream.java

@@ -0,0 +1,360 @@
+package seaweedfs.client;
+
+// adapted from org.apache.hadoop.fs.azurebfs.services.AbfsOutputStream
+
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+
+import java.io.IOException;
+import java.io.InterruptedIOException;
+import java.io.OutputStream;
+import java.nio.Buffer;
+import java.nio.ByteBuffer;
+import java.util.concurrent.*;
+
+public class SeaweedOutputStream extends OutputStream {
+
+    private static final Logger LOG = LoggerFactory.getLogger(SeaweedOutputStream.class);
+    protected final boolean supportFlush = true;
+    private final FilerClient filerClient;
+    private final String path;
+    private final int bufferSize;
+    private final int maxConcurrentRequestCount;
+    private final ThreadPoolExecutor threadExecutor;
+    private final ExecutorCompletionService<Void> completionService;
+    private final ConcurrentLinkedDeque<WriteOperation> writeOperations;
+    private FilerProto.Entry.Builder entry;
+    private long position; // Flushed bytes (committed to service)
+    private boolean closed;
+    private volatile IOException lastError;
+    private long lastFlushOffset;
+    private long lastTotalAppendOffset = 0;
+    private ByteBuffer buffer;
+    private String replication = "";
+    private String collection = "";
+
+    public SeaweedOutputStream(FilerClient filerClient, final String fullpath) {
+        this(filerClient, fullpath, "");
+    }
+
+    public SeaweedOutputStream(FilerClient filerClient, final String fullpath, final String replication) {
+        this(filerClient, fullpath, null, 0, 8 * 1024 * 1024, replication);
+    }
+
+    public SeaweedOutputStream(FilerClient filerClient, final String path, FilerProto.Entry.Builder entry,
+            final long position, final int bufferSize, final String replication) {
+
+        this.filerClient = filerClient;
+        this.replication = replication;
+        this.path = path;
+        this.position = position;
+        this.closed = false;
+        this.lastError = null;
+        this.lastFlushOffset = 0;
+        this.bufferSize = bufferSize;
+        this.buffer = ByteBufferPool.request(bufferSize);
+        this.writeOperations = new ConcurrentLinkedDeque<>();
+
+        this.maxConcurrentRequestCount = Runtime.getRuntime().availableProcessors();
+
+        this.threadExecutor = new ThreadPoolExecutor(maxConcurrentRequestCount,
+                maxConcurrentRequestCount,
+                120L,
+                TimeUnit.SECONDS,
+                new LinkedBlockingQueue<Runnable>());
+        this.completionService = new ExecutorCompletionService<>(this.threadExecutor);
+
+        this.entry = entry;
+        if (this.entry == null) {
+            long now = System.currentTimeMillis() / 1000L;
+
+            this.entry = FilerProto.Entry.newBuilder()
+                    .setName(getFileName(path))
+                    .setIsDirectory(false)
+                    .setAttributes(FilerProto.FuseAttributes.newBuilder()
+                            .setFileMode(0755)
+                            .setCrtime(now)
+                            .setMtime(now)
+                            .clearGroupName());
+        }
+
+    }
+
+    public void setReplication(String replication) {
+        this.replication = replication;
+    }
+
+    public void setCollection(String collection) {
+        this.collection = collection;
+    }
+
+    /**
+     * Get the current position in the output stream.
+     * This returns the total position including both flushed and buffered data.
+     * 
+     * @return current position (flushed + buffered bytes)
+     */
+    public synchronized long getPos() throws IOException {
+        // Guard against NPE if called after close()
+        if (buffer == null) {
+            return position;
+        }
+
+        // Return current position (flushed + buffered)
+        return position + buffer.position();
+    }
+
+    public static String getParentDirectory(String path) {
+        int protoIndex = path.indexOf("://");
+        if (protoIndex >= 0) {
+            int pathStart = path.indexOf("/", protoIndex + 3);
+            if (pathStart < 0) {
+                // No path segment; treat as root (e.g., "seaweedfs://host")
+                return "/";
+            }
+            path = path.substring(pathStart);
+        }
+        if (path.equals("/")) {
+            return path;
+        }
+        int lastSlashIndex = path.lastIndexOf("/");
+        if (lastSlashIndex == 0) {
+            return "/";
+        }
+        return path.substring(0, lastSlashIndex);
+    }
+
+    public static String getFileName(String path) {
+        if (path.indexOf("/") < 0) {
+            return path;
+        }
+        int lastSlashIndex = path.lastIndexOf("/");
+        return path.substring(lastSlashIndex + 1);
+    }
+
+    private synchronized void flushWrittenBytesToServiceInternal(final long offset) throws IOException {
+        try {
+
+            // Set the file size in attributes based on our position
+            // This ensures Parquet footer metadata matches what we actually wrote
+            FilerProto.FuseAttributes.Builder attrBuilder = entry.getAttributes().toBuilder();
+            attrBuilder.setFileSize(offset);
+            entry.setAttributes(attrBuilder);
+
+            SeaweedWrite.writeMeta(filerClient, getParentDirectory(path), entry);
+        } catch (Exception ex) {
+            throw new IOException(ex);
+        }
+        this.lastFlushOffset = offset;
+    }
+
+    @Override
+    public void write(final int byteVal) throws IOException {
+        write(new byte[] { (byte) (byteVal & 0xFF) });
+    }
+
+    @Override
+    public synchronized void write(final byte[] data, final int off, final int length)
+            throws IOException {
+        maybeThrowLastError();
+
+        if (data == null) {
+            return;
+        }
+
+        if (off < 0 || length < 0 || length > data.length - off) {
+            throw new IndexOutOfBoundsException();
+        }
+
+        int currentOffset = off;
+        int writableBytes = bufferSize - buffer.position();
+        int numberOfBytesToWrite = length;
+
+        while (numberOfBytesToWrite > 0) {
+
+            if (numberOfBytesToWrite < writableBytes) {
+                buffer.put(data, currentOffset, numberOfBytesToWrite);
+                break;
+            }
+
+            // System.out.println(path + " [" + (outputIndex + currentOffset) + "," +
+            // ((outputIndex + currentOffset) + writableBytes) + ") " + buffer.capacity());
+            buffer.put(data, currentOffset, writableBytes);
+            currentOffset += writableBytes;
+
+            writeCurrentBufferToService();
+            numberOfBytesToWrite = numberOfBytesToWrite - writableBytes;
+            writableBytes = bufferSize - buffer.position();
+        }
+
+    }
+
+    /**
+     * Flushes this output stream and forces any buffered output bytes to be
+     * written out. If any data remains in the payload it is committed to the
+     * service. Data is queued for writing and forced out to the service
+     * before the call returns.
+     */
+    @Override
+    public void flush() throws IOException {
+        if (supportFlush) {
+            flushInternalAsync();
+        }
+    }
+
+    /**
+     * Force all data in the output stream to be written to Azure storage.
+     * Wait to return until this is complete. Close the access to the stream and
+     * shutdown the upload thread pool.
+     * If the blob was created, its lease will be released.
+     * Any error encountered caught in threads and stored will be rethrown here
+     * after cleanup.
+     */
+    @Override
+    public synchronized void close() throws IOException {
+        if (closed) {
+            return;
+        }
+
+        try {
+            flushInternal();
+            threadExecutor.shutdown();
+        } finally {
+            lastError = new IOException("Stream is closed!");
+            ByteBufferPool.release(buffer);
+            buffer = null;
+            closed = true;
+            writeOperations.clear();
+            if (!threadExecutor.isShutdown()) {
+                threadExecutor.shutdownNow();
+            }
+        }
+
+    }
+
+    private synchronized void writeCurrentBufferToService() throws IOException {
+        int bufferPos = buffer.position();
+
+        if (bufferPos == 0) {
+            return;
+        }
+
+        int written = submitWriteBufferToService(buffer, position);
+        position += written;
+
+        buffer = ByteBufferPool.request(bufferSize);
+
+    }
+
+    private synchronized int submitWriteBufferToService(final ByteBuffer bufferToWrite, final long writePosition)
+            throws IOException {
+
+        ((Buffer) bufferToWrite).flip();
+        int bytesLength = bufferToWrite.limit() - bufferToWrite.position();
+
+        if (threadExecutor.getQueue().size() >= maxConcurrentRequestCount) {
+            waitForTaskToComplete();
+        }
+        final Future<Void> job = completionService.submit(() -> {
+            // System.out.println(path + " is going to save [" + (writePosition) + "," +
+            // ((writePosition) + bytesLength) + ")");
+            SeaweedWrite.writeData(entry, replication, collection, filerClient, writePosition, bufferToWrite.array(),
+                    bufferToWrite.position(), bufferToWrite.limit(), path);
+            // System.out.println(path + " saved [" + (writePosition) + "," +
+            // ((writePosition) + bytesLength) + ")");
+            ByteBufferPool.release(bufferToWrite);
+            return null;
+        });
+
+        writeOperations.add(new WriteOperation(job, writePosition, bytesLength));
+
+        // Try to shrink the queue
+        shrinkWriteOperationQueue();
+
+        return bytesLength;
+
+    }
+
+    private void waitForTaskToComplete() throws IOException {
+        boolean completed;
+        for (completed = false; completionService.poll() != null; completed = true) {
+            // keep polling until there is no data
+        }
+
+        if (!completed) {
+            try {
+                completionService.take();
+            } catch (InterruptedException e) {
+                lastError = (IOException) new InterruptedIOException(e.toString()).initCause(e);
+                throw lastError;
+            }
+        }
+    }
+
+    private void maybeThrowLastError() throws IOException {
+        if (lastError != null) {
+            throw lastError;
+        }
+    }
+
+    /**
+     * Try to remove the completed write operations from the beginning of write
+     * operation FIFO queue.
+     */
+    private synchronized void shrinkWriteOperationQueue() throws IOException {
+        try {
+            while (writeOperations.peek() != null && writeOperations.peek().task.isDone()) {
+                writeOperations.peek().task.get();
+                lastTotalAppendOffset += writeOperations.peek().length;
+                writeOperations.remove();
+            }
+        } catch (Exception e) {
+            lastError = new IOException(e);
+            throw lastError;
+        }
+    }
+
+    protected synchronized void flushInternal() throws IOException {
+        maybeThrowLastError();
+        writeCurrentBufferToService();
+        flushWrittenBytesToService();
+    }
+
+    protected synchronized void flushInternalAsync() throws IOException {
+        maybeThrowLastError();
+        writeCurrentBufferToService();
+        flushWrittenBytesToServiceAsync();
+    }
+
+    private synchronized void flushWrittenBytesToService() throws IOException {
+        for (WriteOperation writeOperation : writeOperations) {
+            try {
+                writeOperation.task.get();
+            } catch (Exception ex) {
+                lastError = new IOException(ex);
+                throw lastError;
+            }
+        }
+        LOG.debug("flushWrittenBytesToService: {} position:{}", path, position);
+        flushWrittenBytesToServiceInternal(position);
+    }
+
+    private synchronized void flushWrittenBytesToServiceAsync() throws IOException {
+        shrinkWriteOperationQueue();
+
+        if (this.lastTotalAppendOffset > this.lastFlushOffset) {
+            this.flushWrittenBytesToServiceInternal(this.lastTotalAppendOffset);
+        }
+    }
+
+    private static class WriteOperation {
+        private final Future<Void> task;
+        private final long length;
+
+        WriteOperation(final Future<Void> task, final long startOffset, final long length) {
+            this.task = task;
+            this.length = length;
+        }
+    }
+
+}

other/java/client/src/main/java/seaweedfs/client/SeaweedRead.java

@@ -0,0 +1,358 @@
+package seaweedfs.client;
+
+import org.apache.http.Header;
+import org.apache.http.HeaderElement;
+import org.apache.http.HttpEntity;
+import org.apache.http.HttpHeaders;
+import org.apache.http.client.entity.GzipDecompressingEntity;
+import org.apache.http.client.methods.CloseableHttpResponse;
+import org.apache.http.client.methods.HttpGet;
+import org.apache.http.util.EntityUtils;
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+
+import java.io.IOException;
+import java.nio.ByteBuffer;
+import java.util.*;
+
+public class SeaweedRead {
+
+    private static final Logger LOG = LoggerFactory.getLogger(SeaweedRead.class);
+
+    static ChunkCache chunkCache = new ChunkCache(4);
+    static VolumeIdCache volumeIdCache = new VolumeIdCache(4 * 1024);
+
+    // returns bytesRead
+    public static long read(FilerClient filerClient, List<VisibleInterval> visibleIntervals,
+            final long position, final ByteBuffer buf, final long fileSize) throws IOException {
+
+        int originalRemaining = buf.remaining();
+        List<ChunkView> chunkViews = viewFromVisibles(visibleIntervals, position, originalRemaining);
+
+        Map<String, FilerProto.Locations> knownLocations = new HashMap<>();
+
+        FilerProto.LookupVolumeRequest.Builder lookupRequest = FilerProto.LookupVolumeRequest.newBuilder();
+        for (ChunkView chunkView : chunkViews) {
+            String vid = parseVolumeId(chunkView.fileId);
+            FilerProto.Locations locations = volumeIdCache.getLocations(vid);
+            if (locations == null) {
+                lookupRequest.addVolumeIds(vid);
+            } else {
+                knownLocations.put(vid, locations);
+            }
+        }
+
+        if (lookupRequest.getVolumeIdsCount() > 0) {
+            FilerProto.LookupVolumeResponse lookupResponse = filerClient
+                    .getBlockingStub().lookupVolume(lookupRequest.build());
+            Map<String, FilerProto.Locations> vid2Locations = lookupResponse.getLocationsMapMap();
+            for (Map.Entry<String, FilerProto.Locations> entry : vid2Locations.entrySet()) {
+                volumeIdCache.setLocations(entry.getKey(), entry.getValue());
+                knownLocations.put(entry.getKey(), entry.getValue());
+            }
+        }
+
+        // TODO parallel this
+        long readCount = 0;
+        long startOffset = position;
+        for (ChunkView chunkView : chunkViews) {
+
+            if (startOffset < chunkView.logicOffset) {
+                long gap = chunkView.logicOffset - startOffset;
+                LOG.debug("zero [{},{})", startOffset, startOffset + gap);
+                buf.position(buf.position() + (int) gap);
+                readCount += gap;
+                startOffset += gap;
+            }
+
+            String volumeId = parseVolumeId(chunkView.fileId);
+            FilerProto.Locations locations = knownLocations.get(volumeId);
+            if (locations == null || locations.getLocationsCount() == 0) {
+                LOG.error("failed to locate {}", chunkView.fileId);
+                volumeIdCache.clearLocations(volumeId);
+                throw new IOException("failed to locate fileId " + chunkView.fileId);
+            }
+
+            int len = readChunkView(filerClient, startOffset, buf, chunkView, locations);
+
+            LOG.debug("read [{},{}) {} size {}", startOffset, startOffset + len, chunkView.fileId, chunkView.size);
+
+            readCount += len;
+            startOffset += len;
+
+        }
+
+        // Fix: Calculate the correct limit based on the read position and requested
+        // size,
+        // not the buffer's absolute limit. This fixes the 78-byte EOF error when
+        // seeking
+        // near the end of the file.
+        long limit = Math.min(position + originalRemaining, fileSize);
+
+        if (startOffset < limit) {
+            long gap = limit - startOffset;
+            LOG.debug("zero2 [{},{})", startOffset, startOffset + gap);
+            buf.position(buf.position() + (int) gap);
+            readCount += gap;
+            startOffset += gap;
+        }
+
+        return readCount;
+    }
+
+    private static int readChunkView(FilerClient filerClient, long startOffset, ByteBuffer buf, ChunkView chunkView,
+            FilerProto.Locations locations) throws IOException {
+
+        byte[] chunkData = chunkCache.getChunk(chunkView.fileId);
+
+        if (chunkData == null) {
+            chunkData = doFetchFullChunkData(filerClient, chunkView, locations);
+            chunkCache.setChunk(chunkView.fileId, chunkData);
+        }
+
+        int len = (int) chunkView.size - (int) (startOffset - chunkView.logicOffset);
+        int srcOffset = (int) (startOffset - chunkView.logicOffset + chunkView.offset);
+        LOG.debug("readChunkView fid:{} chunkData.length:{} chunkView.offset:{} chunkView[{};{}) startOffset:{}",
+                chunkView.fileId, chunkData.length, chunkView.offset, chunkView.logicOffset,
+                chunkView.logicOffset + chunkView.size, startOffset);
+        // The fetched chunk can be shorter than the view claims when a read briefly
+        // returns an empty body (seen right after an append). Fail clearly instead of
+        // letting ByteBuffer.put throw an opaque IndexOutOfBoundsException.
+        if (srcOffset < 0 || len < 0 || srcOffset > chunkData.length - len) {
+            throw new IOException("chunk " + chunkView.fileId + " returned " + chunkData.length
+                    + " bytes, need [" + srcOffset + "," + ((long) srcOffset + len) + ")");
+        }
+        buf.put(chunkData, srcOffset, len);
+
+        return len;
+    }
+
+    public static byte[] doFetchFullChunkData(FilerClient filerClient, ChunkView chunkView,
+            FilerProto.Locations locations) throws IOException {
+
+        byte[] data = null;
+        IOException lastException = null;
+        for (long waitTime = 1000L; waitTime < 10 * 1000; waitTime += waitTime / 2) {
+            for (FilerProto.Location location : locations.getLocationsList()) {
+                String url = filerClient.getChunkUrl(chunkView.fileId, location.getUrl(), location.getPublicUrl());
+                try {
+                    byte[] fetched = doFetchOneFullChunkData(chunkView, url);
+                    // An empty (or null) body for a chunk we are reading from is never
+                    // valid; treat it as a transient failure so the retry loop tries
+                    // another location and backs off, rather than caching an empty chunk.
+                    if (fetched == null || fetched.length == 0) {
+                        lastException = new IOException("empty or null response for chunk " + chunkView.fileId + " from " + url);
+                        continue;
+                    }
+                    data = fetched;
+                    lastException = null;
+                    break;
+                } catch (IOException ioe) {
+                    LOG.debug("doFetchFullChunkData {} :{}", url, ioe);
+                    lastException = ioe;
+                }
+            }
+            if (data != null) {
+                break;
+            }
+            try {
+                Thread.sleep(waitTime);
+            } catch (InterruptedException e) {
+            }
+        }
+
+        if (lastException != null) {
+            throw lastException;
+        }
+
+        LOG.debug("doFetchFullChunkData fid:{} chunkData.length:{}", chunkView.fileId, data.length);
+
+        return data;
+
+    }
+
+    private static byte[] doFetchOneFullChunkData(ChunkView chunkView, String url) throws IOException {
+
+        HttpGet request = new HttpGet(url);
+
+        request.setHeader(HttpHeaders.ACCEPT_ENCODING, "gzip");
+
+        String basicAuthHeader = FilerSecurityContext.getBasicAuthHeaderValue();
+        if (basicAuthHeader != null) {
+            request.setHeader(HttpHeaders.AUTHORIZATION, basicAuthHeader);
+        }
+
+        byte[] data = null;
+
+        CloseableHttpResponse response = SeaweedUtil.getClosableHttpClient().execute(request);
+
+        try {
+            HttpEntity entity = response.getEntity();
+
+            Header contentEncodingHeader = entity.getContentEncoding();
+
+            if (contentEncodingHeader != null) {
+                HeaderElement[] encodings = contentEncodingHeader.getElements();
+                for (int i = 0; i < encodings.length; i++) {
+                    if (encodings[i].getName().equalsIgnoreCase("gzip")) {
+                        entity = new GzipDecompressingEntity(entity);
+                        break;
+                    }
+                }
+            }
+
+            data = EntityUtils.toByteArray(entity);
+
+            EntityUtils.consume(entity);
+
+        } finally {
+            response.close();
+            request.releaseConnection();
+        }
+
+        if (chunkView.cipherKey != null && chunkView.cipherKey.length != 0) {
+            try {
+                data = SeaweedCipher.decrypt(data, chunkView.cipherKey);
+            } catch (Exception e) {
+                throw new IOException("fail to decrypt", e);
+            }
+        }
+
+        if (chunkView.isCompressed) {
+            data = Gzip.decompress(data);
+        }
+
+        LOG.debug("doFetchOneFullChunkData url:{} chunkData.length:{}", url, data.length);
+
+        return data;
+
+    }
+
+    protected static List<ChunkView> viewFromVisibles(List<VisibleInterval> visibleIntervals, long offset, long size) {
+        List<ChunkView> views = new ArrayList<>();
+
+        long stop = offset + size;
+        for (VisibleInterval chunk : visibleIntervals) {
+            long chunkStart = Math.max(offset, chunk.start);
+            long chunkStop = Math.min(stop, chunk.stop);
+            if (chunkStart < chunkStop) {
+                boolean isFullChunk = chunk.isFullChunk && chunk.start == offset && chunk.stop <= stop;
+                views.add(new ChunkView(
+                        chunk.fileId,
+                        chunkStart - chunk.start + chunk.chunkOffset,
+                        chunkStop - chunkStart,
+                        chunkStart,
+                        isFullChunk,
+                        chunk.cipherKey,
+                        chunk.isCompressed));
+            }
+        }
+        return views;
+    }
+
+    public static List<VisibleInterval> nonOverlappingVisibleIntervals(
+            final FilerClient filerClient, List<FilerProto.FileChunk> chunkList) throws IOException {
+
+        chunkList = FileChunkManifest.resolveChunkManifest(filerClient, chunkList);
+
+        return ReadChunks.readResolvedChunks(chunkList);
+
+    }
+
+    public static String parseVolumeId(String fileId) {
+        int commaIndex = fileId.lastIndexOf(',');
+        if (commaIndex > 0) {
+            return fileId.substring(0, commaIndex);
+        }
+        return fileId;
+    }
+
+    public static long fileSize(FilerProto.Entry entry) {
+        long chunksSize = totalSize(entry.getChunksList());
+        long attrSize = entry.getAttributes().getFileSize();
+        long finalSize = Math.max(chunksSize, attrSize);
+        return finalSize;
+    }
+
+    public static long totalSize(List<FilerProto.FileChunk> chunksList) {
+        long size = 0;
+        for (FilerProto.FileChunk chunk : chunksList) {
+            long t = chunk.getOffset() + chunk.getSize();
+            if (size < t) {
+                size = t;
+            }
+        }
+        return size;
+    }
+
+    public static class VisibleInterval {
+        public final long start;
+        public final long stop;
+        public final long modifiedTime;
+        public final String fileId;
+        public final long chunkOffset;
+        public final boolean isFullChunk;
+        public final byte[] cipherKey;
+        public final boolean isCompressed;
+
+        public VisibleInterval(long start, long stop, String fileId, long modifiedTime, long chunkOffset,
+                boolean isFullChunk, byte[] cipherKey, boolean isCompressed) {
+            this.start = start;
+            this.stop = stop;
+            this.modifiedTime = modifiedTime;
+            this.fileId = fileId;
+            this.chunkOffset = chunkOffset;
+            this.isFullChunk = isFullChunk;
+            this.cipherKey = cipherKey;
+            this.isCompressed = isCompressed;
+        }
+
+        @Override
+        public String toString() {
+            return "VisibleInterval{" +
+                    "start=" + start +
+                    ", stop=" + stop +
+                    ", modifiedTime=" + modifiedTime +
+                    ", fileId='" + fileId + '\'' +
+                    ", isFullChunk=" + isFullChunk +
+                    ", cipherKey=" + Arrays.toString(cipherKey) +
+                    ", isCompressed=" + isCompressed +
+                    '}';
+        }
+    }
+
+    public static class ChunkView {
+        public final String fileId;
+        public final long offset;
+        public final long size;
+        public final long logicOffset;
+        public final boolean isFullChunk;
+        public final byte[] cipherKey;
+        public final boolean isCompressed;
+
+        public ChunkView(String fileId, long offset, long size, long logicOffset, boolean isFullChunk, byte[] cipherKey,
+                boolean isCompressed) {
+            this.fileId = fileId;
+            this.offset = offset;
+            this.size = size;
+            this.logicOffset = logicOffset;
+            this.isFullChunk = isFullChunk;
+            this.cipherKey = cipherKey;
+            this.isCompressed = isCompressed;
+        }
+
+        @Override
+        public String toString() {
+            return "ChunkView{" +
+                    "fileId='" + fileId + '\'' +
+                    ", offset=" + offset +
+                    ", size=" + size +
+                    ", logicOffset=" + logicOffset +
+                    ", isFullChunk=" + isFullChunk +
+                    ", cipherKey=" + Arrays.toString(cipherKey) +
+                    ", isCompressed=" + isCompressed +
+                    '}';
+        }
+    }
+
+}

other/java/client/src/main/java/seaweedfs/client/SeaweedUtil.java

@@ -0,0 +1,93 @@
+package seaweedfs.client;
+
+import org.apache.http.config.Registry;
+import org.apache.http.config.RegistryBuilder;
+import org.apache.http.conn.socket.ConnectionSocketFactory;
+import org.apache.http.conn.socket.PlainConnectionSocketFactory;
+import org.apache.http.conn.ssl.DefaultHostnameVerifier;
+import org.apache.http.conn.ssl.NoopHostnameVerifier;
+import org.apache.http.conn.ssl.SSLConnectionSocketFactory;
+import org.apache.http.impl.DefaultConnectionReuseStrategy;
+import org.apache.http.impl.client.CloseableHttpClient;
+import org.apache.http.impl.client.DefaultConnectionKeepAliveStrategy;
+import org.apache.http.impl.client.HttpClientBuilder;
+import org.apache.http.impl.conn.PoolingHttpClientConnectionManager;
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+
+import javax.net.ssl.HostnameVerifier;
+import javax.net.ssl.SSLContext;
+
+public class SeaweedUtil {
+
+    private static final Logger logger = LoggerFactory.getLogger(SeaweedUtil.class);
+    static PoolingHttpClientConnectionManager cm;
+    static CloseableHttpClient httpClient;
+
+    static {
+        //Apache HTTP client has a terrible API that makes you configure everything twice
+        //NoopHostnameVerifier is required because SeaweedFS doesn't verify hostnames
+        //and the servers are likely to have TLS certificates that do not match their hosts
+        if (FilerSecurityContext.isHttpSecurityEnabled()) {
+            SSLConnectionSocketFactory sslSocketFactory = new SSLConnectionSocketFactory(
+                    FilerSecurityContext.getHttpSslContext(),
+                    NoopHostnameVerifier.INSTANCE);
+
+            Registry<ConnectionSocketFactory> socketFactoryRegistry =
+                    RegistryBuilder.<ConnectionSocketFactory>create()
+                            .register("https", sslSocketFactory)
+                            .register("http", new PlainConnectionSocketFactory())
+                            .build();
+            cm = new PoolingHttpClientConnectionManager(socketFactoryRegistry);
+        } else {
+            cm = new PoolingHttpClientConnectionManager();
+        }
+
+        // Increase max total connection to 200
+        cm.setMaxTotal(200);
+        // Increase default max connection per route to 20
+        cm.setDefaultMaxPerRoute(20);
+
+        HttpClientBuilder builder = HttpClientBuilder.create()
+                .setConnectionManager(cm)
+                .setConnectionReuseStrategy(DefaultConnectionReuseStrategy.INSTANCE)
+                .setKeepAliveStrategy(DefaultConnectionKeepAliveStrategy.INSTANCE);
+
+        if (FilerSecurityContext.isHttpSecurityEnabled()) {
+            builder.setSSLContext(FilerSecurityContext.getHttpSslContext());
+            builder.setSSLHostnameVerifier(NoopHostnameVerifier.INSTANCE);
+        }
+
+        httpClient = builder.build();
+    }
+
+    public static CloseableHttpClient getClosableHttpClient() {
+        return httpClient;
+    }
+
+    public static String[] toDirAndName(String fullpath) {
+        if (fullpath == null) {
+            return new String[]{"/", ""};
+        }
+        if (fullpath.endsWith("/")) {
+            fullpath = fullpath.substring(0, fullpath.length() - 1);
+        }
+        if (fullpath.length() == 0) {
+            return new String[]{"/", ""};
+        }
+        int sep = fullpath.lastIndexOf("/");
+        String parent = sep == 0 ? "/" : fullpath.substring(0, sep);
+        String name = fullpath.substring(sep + 1);
+        return new String[]{parent, name};
+    }
+
+    public static String joinHostPort(String host, int port) {
+        if (host.startsWith("[") && host.endsWith("]")) {
+            return host + ":" + port;
+        }
+        if (host.indexOf(':')>=0) {
+            return "[" + host + "]:" + port;
+        }
+        return host + ":" + port;
+    }
+}

other/java/client/src/main/java/seaweedfs/client/SeaweedWrite.java

@@ -0,0 +1,232 @@
+package seaweedfs.client;
+
+import com.google.common.base.Strings;
+import com.google.protobuf.ByteString;
+import org.apache.http.HttpEntity;
+import org.apache.http.client.methods.CloseableHttpResponse;
+import org.apache.http.client.methods.HttpPost;
+import org.apache.http.entity.mime.HttpMultipartMode;
+import org.apache.http.entity.mime.MultipartEntityBuilder;
+import org.apache.http.util.EntityUtils;
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+
+import java.io.ByteArrayInputStream;
+import java.io.IOException;
+import java.io.InputStream;
+import java.security.SecureRandom;
+import java.security.MessageDigest;
+import java.util.List;
+import java.util.Base64;
+
+public class SeaweedWrite {
+
+    private static final Logger LOG = LoggerFactory.getLogger(SeaweedWrite.class);
+
+    private static final SecureRandom random = new SecureRandom();
+
+    public static void writeData(FilerProto.Entry.Builder entry,
+            final String replication,
+            String collection,
+            final FilerClient filerClient,
+            final long offset,
+            final byte[] bytes,
+            final long bytesOffset, final long bytesLength,
+            final String path) throws IOException {
+
+        IOException lastException = null;
+        for (long waitTime = 1000L; waitTime < 10 * 1000; waitTime += waitTime / 2) {
+            try {
+                FilerProto.FileChunk.Builder chunkBuilder = writeChunk(
+                        replication, collection, filerClient, offset, bytes, bytesOffset, bytesLength, path);
+                lastException = null;
+                synchronized (entry) {
+                    entry.addChunks(chunkBuilder);
+                }
+                break;
+            } catch (IOException ioe) {
+                LOG.debug("writeData:{}", ioe);
+                lastException = ioe;
+            }
+            try {
+                Thread.sleep(waitTime);
+            } catch (InterruptedException e) {
+            }
+        }
+
+        if (lastException != null) {
+            throw lastException;
+        }
+
+    }
+
+    public static FilerProto.FileChunk.Builder writeChunk(final String replication,
+            final String collection,
+            final FilerClient filerClient,
+            final long offset,
+            final byte[] bytes,
+            final long bytesOffset,
+            final long bytesLength,
+            final String path) throws IOException {
+
+        // Retry assignVolume call for transient network/server errors
+        FilerProto.AssignVolumeResponse response = null;
+        IOException lastException = null;
+        int maxRetries = 3;
+
+        for (int attempt = 0; attempt < maxRetries; attempt++) {
+            try {
+                response = filerClient.getBlockingStub().assignVolume(
+                        FilerProto.AssignVolumeRequest.newBuilder()
+                                .setCollection(
+                                        Strings.isNullOrEmpty(collection) ? filerClient.getCollection() : collection)
+                                .setReplication(
+                                        Strings.isNullOrEmpty(replication) ? filerClient.getReplication() : replication)
+                                .setDataCenter("")
+                                .setTtlSec(0)
+                                .setPath(path)
+                                .build());
+                break; // Success, exit retry loop
+            } catch (io.grpc.StatusRuntimeException e) {
+                lastException = new IOException(
+                        "assignVolume failed (attempt " + (attempt + 1) + "/" + maxRetries + "): " + e.getMessage(), e);
+                if (attempt < maxRetries - 1) {
+                    try {
+                        Thread.sleep(100 * (attempt + 1)); // Exponential backoff: 100ms, 200ms, 300ms
+                    } catch (InterruptedException ie) {
+                        Thread.currentThread().interrupt();
+                        throw new IOException("Interrupted during retry", ie);
+                    }
+                }
+            }
+        }
+
+        if (response == null) {
+            throw lastException != null ? lastException
+                    : new IOException("assignVolume failed after " + maxRetries + " attempts");
+        }
+
+        if (!Strings.isNullOrEmpty(response.getError())) {
+            throw new IOException(response.getError());
+        }
+
+        String fileId = response.getFileId();
+        String auth = response.getAuth();
+
+        String targetUrl = filerClient.getChunkUrl(fileId, response.getLocation().getUrl(),
+                response.getLocation().getPublicUrl());
+
+        ByteString cipherKeyString = com.google.protobuf.ByteString.EMPTY;
+        byte[] cipherKey = null;
+        if (filerClient.isCipher()) {
+            cipherKey = genCipherKey();
+            cipherKeyString = ByteString.copyFrom(cipherKey);
+        }
+
+        String etag = multipartUpload(targetUrl, auth, bytes, bytesOffset, bytesLength, cipherKey);
+
+        return FilerProto.FileChunk.newBuilder()
+                .setFileId(fileId)
+                .setOffset(offset)
+                .setSize(bytesLength)
+                .setModifiedTsNs(System.nanoTime())
+                .setETag(etag)
+                .setCipherKey(cipherKeyString);
+    }
+
+    public static void writeMeta(final FilerClient filerClient,
+            final String parentDirectory,
+            final FilerProto.Entry.Builder entry) throws IOException {
+
+        synchronized (entry) {
+            List<FilerProto.FileChunk> chunks = FileChunkManifest.maybeManifestize(filerClient, entry.getChunksList(),
+                    parentDirectory);
+
+            entry.clearChunks();
+            entry.addAllChunks(chunks);
+            filerClient.getBlockingStub().createEntry(
+                    FilerProto.CreateEntryRequest.newBuilder()
+                            .setDirectory(parentDirectory)
+                            .setEntry(entry)
+                            .build());
+        }
+    }
+
+    private static String multipartUpload(String targetUrl,
+            String auth,
+            final byte[] bytes,
+            final long bytesOffset, final long bytesLength,
+            byte[] cipherKey) throws IOException {
+        MessageDigest md = null;
+        try {
+            md = MessageDigest.getInstance("MD5");
+        } catch (java.security.NoSuchAlgorithmException e) {
+        }
+
+        InputStream inputStream = null;
+        if (cipherKey == null || cipherKey.length == 0) {
+            md.update(bytes, (int) bytesOffset, (int) bytesLength);
+            inputStream = new ByteArrayInputStream(bytes, (int) bytesOffset, (int) bytesLength);
+        } else {
+            try {
+                byte[] encryptedBytes = SeaweedCipher.encrypt(bytes, (int) bytesOffset, (int) bytesLength, cipherKey);
+                md.update(encryptedBytes);
+                inputStream = new ByteArrayInputStream(encryptedBytes, 0, encryptedBytes.length);
+            } catch (Exception e) {
+                throw new IOException("fail to encrypt data", e);
+            }
+        }
+
+        HttpPost post = new HttpPost(targetUrl);
+        if (auth != null && auth.length() != 0) {
+            // Volume JWT and Basic Auth both use the Authorization header; the JWT wins
+            // when present. Front the volume with a JWT-free path to use Basic Auth here.
+            post.addHeader("Authorization", "BEARER " + auth);
+        } else {
+            String basicAuthHeader = FilerSecurityContext.getBasicAuthHeaderValue();
+            if (basicAuthHeader != null) {
+                post.addHeader("Authorization", basicAuthHeader);
+            }
+        }
+        post.addHeader("Content-MD5", Base64.getEncoder().encodeToString(md.digest()));
+
+        post.setEntity(MultipartEntityBuilder.create()
+                .setMode(HttpMultipartMode.BROWSER_COMPATIBLE)
+                .addBinaryBody("upload", inputStream)
+                .build());
+
+        CloseableHttpResponse response = SeaweedUtil.getClosableHttpClient().execute(post);
+
+        try {
+            if (response.getStatusLine().getStatusCode() / 100 != 2) {
+                HttpEntity entity = response.getEntity();
+                if (entity != null && entity.getContentType() != null
+                        && entity.getContentType().getValue().equals("application/json")) {
+                    throw new IOException(EntityUtils.toString(entity, "UTF-8"));
+                } else {
+                    throw new IOException(response.getStatusLine().getReasonPhrase());
+                }
+            }
+
+            String etag = response.getLastHeader("ETag").getValue();
+
+            if (etag != null && etag.startsWith("\"") && etag.endsWith("\"")) {
+                etag = etag.substring(1, etag.length() - 1);
+            }
+
+            EntityUtils.consume(response.getEntity());
+
+            return etag;
+        } finally {
+            response.close();
+            post.releaseConnection();
+        }
+
+    }
+
+    private static byte[] genCipherKey() {
+        byte[] b = new byte[32];
+        random.nextBytes(b);
+        return b;
+    }
+}

other/java/client/src/main/java/seaweedfs/client/VolumeIdCache.java

@@ -0,0 +1,43 @@
+package seaweedfs.client;
+
+import com.google.common.cache.Cache;
+import com.google.common.cache.CacheBuilder;
+
+import java.util.concurrent.TimeUnit;
+
+public class VolumeIdCache {
+
+    private Cache<String, FilerProto.Locations> cache = null;
+
+    public VolumeIdCache(int maxEntries) {
+        if (maxEntries == 0) {
+            return;
+        }
+        this.cache = CacheBuilder.newBuilder()
+                .maximumSize(maxEntries)
+                .expireAfterWrite(5, TimeUnit.MINUTES)
+                .build();
+    }
+
+    public FilerProto.Locations getLocations(String volumeId) {
+        if (this.cache == null) {
+            return null;
+        }
+        return this.cache.getIfPresent(volumeId);
+    }
+
+    public void clearLocations(String volumeId) {
+        if (this.cache == null) {
+            return;
+        }
+        this.cache.invalidate(volumeId);
+    }
+
+    public void setLocations(String volumeId, FilerProto.Locations locations) {
+        if (this.cache == null) {
+            return;
+        }
+        this.cache.put(volumeId, locations);
+    }
+
+}

other/java/client/src/main/proto/filer.proto

@@ -0,0 +1,955 @@
+syntax = "proto3";
+
+package filer_pb;
+
+option go_package = "github.com/seaweedfs/seaweedfs/weed/pb/filer_pb";
+option java_package = "seaweedfs.client";
+option java_outer_classname = "FilerProto";
+
+//////////////////////////////////////////////////
+
+service SeaweedFiler {
+
+    rpc LookupDirectoryEntry (LookupDirectoryEntryRequest) returns (LookupDirectoryEntryResponse) {
+    }
+
+    rpc LookupDirectoryEntries (LookupDirectoryEntriesRequest) returns (LookupDirectoryEntriesResponse) {
+    }
+
+    rpc ListEntries (ListEntriesRequest) returns (stream ListEntriesResponse) {
+    }
+
+    rpc CreateEntry (CreateEntryRequest) returns (CreateEntryResponse) {
+    }
+
+    rpc UpdateEntry (UpdateEntryRequest) returns (UpdateEntryResponse) {
+    }
+
+    rpc TouchAccessTime (TouchAccessTimeRequest) returns (TouchAccessTimeResponse) {
+    }
+
+    rpc AppendToEntry (AppendToEntryRequest) returns (AppendToEntryResponse) {
+    }
+
+    rpc DeleteEntry (DeleteEntryRequest) returns (DeleteEntryResponse) {
+    }
+
+    rpc ObjectTransaction (ObjectTransactionRequest) returns (ObjectTransactionResponse) {
+    }
+
+    rpc ObjectTransactionBatch (ObjectTransactionBatchRequest) returns (ObjectTransactionBatchResponse) {
+    }
+
+    rpc PosixLock (PosixLockRequest) returns (PosixLockResponse) {
+    }
+
+    rpc AtomicRenameEntry (AtomicRenameEntryRequest) returns (AtomicRenameEntryResponse) {
+    }
+    rpc StreamRenameEntry (StreamRenameEntryRequest) returns (stream StreamRenameEntryResponse) {
+    }
+
+    rpc StreamMutateEntry (stream StreamMutateEntryRequest) returns (stream StreamMutateEntryResponse) {
+    }
+
+    rpc AssignVolume (AssignVolumeRequest) returns (AssignVolumeResponse) {
+    }
+
+    rpc LookupVolume (LookupVolumeRequest) returns (LookupVolumeResponse) {
+    }
+
+    rpc CollectionList (CollectionListRequest) returns (CollectionListResponse) {
+    }
+
+    rpc DeleteCollection (DeleteCollectionRequest) returns (DeleteCollectionResponse) {
+    }
+
+    rpc Statistics (StatisticsRequest) returns (StatisticsResponse) {
+    }
+
+    rpc Ping (PingRequest) returns (PingResponse) {
+    }
+
+    rpc GetFilerConfiguration (GetFilerConfigurationRequest) returns (GetFilerConfigurationResponse) {
+    }
+
+    rpc TraverseBfsMetadata (TraverseBfsMetadataRequest) returns (stream TraverseBfsMetadataResponse) {
+    }
+
+    rpc SubscribeMetadata (SubscribeMetadataRequest) returns (stream SubscribeMetadataResponse) {
+    }
+
+    rpc SubscribeLocalMetadata (SubscribeMetadataRequest) returns (stream SubscribeMetadataResponse) {
+    }
+
+    // List the metadata subscribers currently connected to this filer
+    // (FUSE mounts, S3, filer.sync, peer filers, ...).
+    rpc ListMetadataSubscribers (ListMetadataSubscribersRequest) returns (ListMetadataSubscribersResponse) {
+    }
+
+    rpc KvGet (KvGetRequest) returns (KvGetResponse) {
+    }
+
+    rpc KvPut (KvPutRequest) returns (KvPutResponse) {
+    }
+
+    rpc CacheRemoteObjectToLocalCluster (CacheRemoteObjectToLocalClusterRequest) returns (CacheRemoteObjectToLocalClusterResponse) {
+    }
+
+    rpc DistributedLock(LockRequest) returns (LockResponse) {
+    }
+    rpc DistributedUnlock(UnlockRequest) returns (UnlockResponse) {
+    }
+    rpc FindLockOwner(FindLockOwnerRequest) returns (FindLockOwnerResponse) {
+    }
+    // distributed lock management internal use only
+    rpc TransferLocks(TransferLocksRequest) returns (TransferLocksResponse) {
+    }
+    rpc ReplicateLock(ReplicateLockRequest) returns (ReplicateLockResponse) {
+    }
+
+    // Peer chunk sharing — tier 1: mount-server registry.
+    // See design-weed-mount-peer-chunk-sharing.md for details.
+    rpc MountRegister (MountRegisterRequest) returns (MountRegisterResponse) {
+    }
+    rpc MountList (MountListRequest) returns (MountListResponse) {
+    }
+}
+
+//////////////////////////////////////////////////
+
+message LookupDirectoryEntryRequest {
+    string directory = 1;
+    string name = 2;
+}
+
+message LookupDirectoryEntryResponse {
+    Entry entry = 1;
+    // filer log position stamped before the entry read: every event at or
+    // below it is reflected in the returned entry
+    int64 log_ts_ns = 2;
+    // signature of the filer whose clock stamped log_ts_ns; positions are
+    // only comparable with events that filer logged
+    int32 log_signature = 3;
+}
+
+message ListEntriesRequest {
+    string directory = 1;
+    string prefix = 2;
+    string startFromFileName = 3;
+    bool inclusiveStartFrom = 4;
+    uint32 limit = 5;
+    int64 snapshot_ts_ns = 6;
+    // Leave the chunk list out of every entry in the response. The attributes
+    // still carry the file size, so a listing that only reads attributes can
+    // ask for this and skip the largest part of the payload.
+    bool omit_chunks = 7;
+}
+
+message ListEntriesResponse {
+    Entry entry = 1;
+    int64 snapshot_ts_ns = 2;
+}
+
+message RemoteEntry {
+    string storage_name = 1;
+    int64 last_local_sync_ts_ns = 2;
+    string remote_e_tag = 3;
+    int64 remote_mtime = 4;
+    int64 remote_size = 5;
+    // unset when the remote listing does not report encodings (S3);
+    // empty when the remote object authoritatively has none
+    optional string remote_content_encoding = 6;
+}
+message Entry {
+    string name = 1;
+    bool is_directory = 2;
+    repeated FileChunk chunks = 3;
+    FuseAttributes attributes = 4;
+    map<string, bytes> extended = 5;
+    bytes hard_link_id = 7;
+    int32 hard_link_counter = 8; // only exists in hard link meta data
+    bytes content = 9; // if not empty, the file content
+
+    RemoteEntry remote_entry = 10;
+    int64 quota = 11; // for bucket only. Positive/Negative means enabled/disabled.
+    int64 worm_enforced_at_ts_ns = 12;
+}
+
+message FullEntry {
+    string dir = 1;
+    Entry entry = 2;
+}
+
+message EventNotification {
+    Entry old_entry = 1;
+    Entry new_entry = 2;
+    bool delete_chunks = 3;
+    string new_parent_path = 4;
+    bool is_from_other_cluster = 5;
+    repeated int32 signatures = 6;
+}
+
+enum SSEType {
+    NONE = 0;    // No server-side encryption
+    SSE_C = 1;   // Server-Side Encryption with Customer-Provided Keys  
+    SSE_KMS = 2; // Server-Side Encryption with KMS-Managed Keys
+    SSE_S3 = 3;  // Server-Side Encryption with S3-Managed Keys
+}
+
+message FileChunk {
+    string file_id = 1; // to be deprecated
+    int64 offset = 2;
+    uint64 size = 3;
+    int64 modified_ts_ns = 4;
+    string e_tag = 5;
+    string source_file_id = 6; // to be deprecated
+    FileId fid = 7;
+    FileId source_fid = 8;
+    bytes cipher_key = 9;
+    bool is_compressed = 10;
+    bool is_chunk_manifest = 11; // content is a list of FileChunks
+    SSEType sse_type = 12;           // Server-side encryption type
+    bytes sse_metadata = 13;         // Serialized SSE metadata for this chunk (SSE-C, SSE-KMS, or SSE-S3)
+}
+
+message FileChunkManifest {
+    repeated FileChunk chunks = 1;
+}
+
+message FileId {
+    uint32 volume_id = 1;
+    uint64 file_key = 2;
+    fixed32 cookie = 3;
+}
+
+message FuseAttributes {
+    uint64 file_size = 1;
+    int64 mtime = 2; // unix time in seconds
+    uint32 file_mode = 3;
+    uint32 uid = 4;
+    uint32 gid = 5;
+    int64 crtime = 6; // unix time in seconds
+    string mime = 7;
+    int32 ttl_sec = 10;
+    string user_name = 11; // for hdfs
+    repeated string group_name = 12; // for hdfs
+    string symlink_target = 13;
+    bytes md5 = 14;
+    uint32 rdev = 16;
+    uint64 inode = 17;
+    int64 ctime = 18; // unix time in seconds, inode change time
+    int32 mtime_ns = 19; // nanosecond component of mtime (0-999999999)
+    int32 ctime_ns = 20; // nanosecond component of ctime (0-999999999)
+    int32 crtime_ns = 21; // nanosecond component of crtime (0-999999999)
+    int64 atime = 22; // unix time in seconds, last access time
+    int32 atime_ns = 23; // nanosecond component of atime (0-999999999)
+}
+
+message CreateEntryRequest {
+    string directory = 1;
+    Entry entry = 2;
+    bool o_excl = 3;
+    bool is_from_other_cluster = 4;
+    repeated int32 signatures = 5;
+    bool skip_check_parent_directory = 6;
+    // Optional precondition evaluated against the current entry atomically with
+    // the write, under the filer's per-path lock.
+    WriteCondition condition = 7;
+    // Set on a create a filer forwarded to the entry's ring owner, so the owner
+    // applies it locally instead of forwarding again. Clients leave it unset.
+    bool is_moved = 8;
+}
+
+// WriteCondition is the precondition the filer evaluates against the existing
+// entry before writing, under the per-path lock. A failed condition returns
+// FilerError PRECONDITION_FAILED. The client maps request semantics (e.g. RFC
+// 7232) to clauses; the filer just compares.
+//
+// A condition is a list of clauses that ALL must hold (logical AND). One clause
+// is the common case; several express what a single comparison cannot: an ETag
+// set (If-Match / If-None-Match with multiple values), weak-ETag comparison, and
+// compound conditions (e.g. If-Match + If-Unmodified-Since together).
+message WriteCondition {
+    enum Kind {
+        NONE                  = 0; // unconditional
+        IF_NOT_EXISTS         = 1; // fail if the entry exists (If-None-Match: *)
+        IF_EXISTS             = 2; // fail if the entry is absent (If-Match: *)
+        IF_ETAG_MATCH         = 3; // fail if absent or etag matches none of the set (If-Match)
+        IF_ETAG_NOT_MATCH     = 4; // fail if present and etag matches any of the set (If-None-Match)
+        IF_UNMODIFIED_SINCE   = 5; // fail if present and mtime > unix_time
+        IF_MODIFIED_SINCE     = 6; // fail if present and mtime <= unix_time
+        IF_EXTENDED_NOT_EQUAL = 7; // fail if present and extended[ext_key] == ext_value
+        IF_EXTENDED_TIME_ELAPSED = 8; // fail if present and extended[ext_key] (unix seconds) is in the future
+        IF_CHUNKS_EQUAL       = 9; // fail unless the stored chunk fid multiset equals fids (absent entry = no chunks)
+    }
+    // Clause is one primitive comparison. IF_ETAG_MATCH holds when the current
+    // entry's ETag equals any value in etags; IF_ETAG_NOT_MATCH holds when it
+    // equals none. allow_weak permits weak-comparison (ignoring the W/ prefix).
+    //
+    // The IF_EXTENDED_* kinds are generic guards on an extended attribute, used
+    // to enforce object-lock without teaching the filer S3 semantics:
+    // IF_EXTENDED_NOT_EQUAL expresses a legal hold (block while a key equals a
+    // value), and IF_EXTENDED_TIME_ELAPSED expresses retention (block while a
+    // stored unix-second deadline is in the future, compared to the filer's
+    // clock). The caller composes these and, for governance-bypass, simply omits
+    // the retention clause when the bypass is authorized — the filer makes no
+    // authorization decision.
+    //
+    // IF_CHUNKS_EQUAL guards a chunk-preserving read-modify-write: the stored
+    // chunk fid set must still equal what the caller read, so a stale write
+    // cannot resurrect needles that a concurrent update already diffed away
+    // and queued for deletion. An empty fids list expects no chunks.
+    message Clause {
+        Kind kind = 1;
+        repeated string etags = 2; // ETag set for IF_ETAG_* kinds
+        int64 unix_time = 3;       // bound (unix seconds) for IF_*_SINCE kinds
+        bool allow_weak = 4;       // compare ETags ignoring the weak (W/) marker
+        string ext_key = 5;        // extended attribute name for IF_EXTENDED_* kinds
+        string ext_value = 6;      // blocking value for IF_EXTENDED_NOT_EQUAL
+        string gate_key = 7;       // IF_EXTENDED_TIME_ELAPSED: only enforce when extended[gate_key] == gate_value
+        string gate_value = 8;     // gate value (e.g. retention mode COMPLIANCE for governance bypass)
+        repeated string fids = 9;  // chunk fid strings for IF_CHUNKS_EQUAL
+    }
+    repeated Clause clauses = 1;   // all must hold (logical AND)
+}
+
+// Structured error codes for filer entry operations.
+// Values are stable — do not reorder or reuse numbers.
+enum FilerError {
+    OK                    = 0;
+    ENTRY_NAME_TOO_LONG   = 1; // name exceeds max_file_name_length
+    PARENT_IS_FILE        = 2; // parent path component is a file, not a directory
+    EXISTING_IS_DIRECTORY = 3; // cannot overwrite directory with file
+    EXISTING_IS_FILE      = 4; // cannot overwrite file with directory
+    ENTRY_ALREADY_EXISTS  = 5; // O_EXCL and entry already exists
+    PRECONDITION_FAILED   = 6; // WriteCondition not satisfied
+}
+
+// ObjectMutation is one entry-level change applied by ObjectTransaction. All
+// mutations of a transaction run under a single per-path lock (the request's
+// lock_key) and in order, so the gateway can describe a multi-entry object
+// operation as one request instead of holding a distributed lock across
+// several RPCs. Data-bearing writes (entries with chunks) should be written
+// before the transaction; mutations here are metadata-scoped.
+message ObjectMutation {
+    enum Type {
+        PUT              = 0; // create or replace the entry (entry field)
+        DELETE           = 1; // delete the entry at directory/name (no error if absent)
+        PATCH_EXTENDED   = 2; // merge set_extended / remove delete_extended on the entry
+        RECOMPUTE_LATEST = 3; // scan a directory and re-point a parent entry (recompute)
+    }
+    Type type = 1;
+    string directory = 2;
+    string name = 3;                       // entry name for DELETE / PATCH_EXTENDED / RECOMPUTE_LATEST (the pointer entry)
+    Entry entry = 4;                        // full entry for PUT
+    map<string, bytes> set_extended = 5;   // PATCH_EXTENDED: keys to set
+    repeated string delete_extended = 6;   // PATCH_EXTENDED: keys to remove
+    bool is_delete_data = 7;               // DELETE: also delete chunk data
+    bool is_recursive = 8;                 // DELETE: recurse into a directory
+    Recompute recompute = 9;               // RECOMPUTE_LATEST parameters
+    bool set_content = 10;                 // PATCH_EXTENDED: replace Entry.content with content
+    bytes content = 11;                    // PATCH_EXTENDED: new Entry.content when set_content
+    bool touch_mtime = 12;                 // PATCH_EXTENDED: set the entry's Mtime to now (e.g. a metadata-replace copy)
+    bool remove_empty_parent = 13;         // DELETE: also remove the parent directory when the delete leaves it empty (best-effort)
+}
+
+// Recompute re-derives a pointer entry (directory/name on the mutation) from the
+// current contents of a scanned directory, atomically under the transaction's
+// lock. It is mechanical: the filer picks the child that sorts first or last by
+// name and copies the requested fields into the pointer; it has no knowledge of
+// what the entries mean. The caller (which does know the versioning scheme)
+// supplies the sort direction and the key mappings. This covers re-pointing the
+// latest version after a specific version is deleted, where the scan must run
+// under the lock.
+message Recompute {
+    string scan_dir = 1;                   // directory whose direct children are scanned
+    bool descending = 2;                   // pick the child that sorts last by name (else first)
+    map<string, string> copy_extended = 3; // pointer extended key -> source extended key on the chosen child
+    string name_to_key = 4;                // if set, store the chosen child's name under this pointer key
+    string size_to_key = 5;                // if set, store the chosen child's FileSize (decimal) under this pointer key
+    string mtime_to_key = 6;               // if set, store the chosen child's Mtime (decimal) under this pointer key
+    string demote_key = 7;                 // if set, stamp demote_value on the prior name_to_key target when it changes
+    bytes demote_value = 8;                // value for demote_key
+    string exclude_name = 9;               // if set, skip this child when scanning (e.g. a version about to be deleted)
+}
+
+// ObjectTransactionRequest applies an ordered list of mutations atomically with
+// respect to other writers of the same object, by holding the filer's per-path
+// lock on lock_key for the whole transaction. The optional condition is checked
+// first, against condition_key when set, else lock_key. Callers set route_key to
+// the object's stable owner ring key; a filer that is not the owner forwards the
+// transaction one hop to the owner, so a stale ring view is tolerated.
+message ObjectTransactionRequest {
+    string lock_key = 1;               // object path to lock and to evaluate the condition against
+    WriteCondition condition = 2;      // optional precondition, checked under the lock
+    repeated ObjectMutation mutations = 3;
+    bool is_from_other_cluster = 4;
+    repeated int32 signatures = 5;
+    string condition_key = 6;          // if set, evaluate the condition against this entry instead of lock_key (still locking lock_key)
+    string route_key = 7;              // ring key identifying the owner filer; a non-owner forwards the whole transaction to it
+    bool is_moved = 8;                 // set on a forwarded transaction so the receiver applies it locally instead of forwarding again
+}
+
+message ObjectTransactionResponse {
+    string error = 1;
+    FilerError error_code = 2;
+}
+
+// PosixLockRange is one advisory byte-range lock. Owner identity is (sid, owner):
+// sid is the mount session, owner the FUSE lock owner within it, so owners from
+// different mounts never alias. end is inclusive (max uint64 = to EOF); is_flock
+// separates the flock and fcntl namespaces, which never conflict.
+message PosixLockRange {
+    uint64 start = 1;
+    uint64 end = 2;
+    uint32 type = 3;       // 1=read, 2=write, 3=unlock
+    uint64 sid = 4;
+    uint64 owner = 5;
+    uint32 pid = 6;        // holder pid, for get_lk reporting only
+    bool is_flock = 7;
+}
+
+// PosixLock routes an advisory lock operation to the inode's owner filer, which
+// holds the authoritative in-memory lock table. key is the inode identity ring
+// key (the file path, or hl:<HardLinkId> for a hardlink) used both to resolve the
+// owner and to index the table. A non-owner filer forwards the request one hop;
+// is_moved bounds it so a stale ring view cannot loop.
+message PosixLockRequest {
+    string key = 1;
+    bool is_moved = 2;
+    PosixLockOp op = 3;
+    PosixLockRange lock = 4;
+    // locks carries the full set a mount holds on key for a KEEP_ALIVE
+    // re-assertion, so the current owner filer can rebuild its in-memory state
+    // after an ownership change or restart. lock.sid identifies the session.
+    repeated PosixLockRange locks = 5;
+    // cooling_probe marks a dual-read a new owner sends to the previous owner
+    // during a ring change, so the previous owner answers from local state
+    // without itself cooling-off (no recursion).
+    bool cooling_probe = 6;
+}
+
+enum PosixLockOp {
+    TRY_LOCK = 0;             // grant lock or report conflict (non-blocking)
+    UNLOCK = 1;              // release lock's owner's locks over its range
+    GET_LK = 2;             // report a conflicting lock, if any
+    RELEASE_POSIX_OWNER = 3; // drop the owner's fcntl locks (flush-time)
+    RELEASE_FLOCK_OWNER = 4; // drop the owner's flock locks (release-time)
+    KEEP_ALIVE = 5;         // renew the session's lease on this owner (lock.sid)
+}
+
+message PosixLockResponse {
+    bool granted = 1;            // for TRY_LOCK: whether the lock was granted
+    bool has_conflict = 2;       // whether conflict is populated
+    PosixLockRange conflict = 3; // the blocking lock (TRY_LOCK conflict / GET_LK result)
+}
+
+// ObjectTransactionBatch applies several object transactions in one round trip,
+// each under its own per-path lock and independent of the others (no cross-key
+// atomicity). A caller groups keys that route to the same owner filer and sends
+// one batch per owner, e.g. for a multi-object delete. Each response is parallel
+// to its request.
+message ObjectTransactionBatchRequest {
+    repeated ObjectTransactionRequest transactions = 1;
+}
+
+message ObjectTransactionBatchResponse {
+    repeated ObjectTransactionResponse responses = 1;
+}
+
+message CreateEntryResponse {
+    string error = 1;                          // kept for human readability + backward compat
+    SubscribeMetadataResponse metadata_event = 2;
+    FilerError error_code = 3;                 // machine-readable error code
+    // filer log position stamped under the path lock before the write:
+    // every event at or below it is reflected in the acknowledged state
+    int64 log_ts_ns = 4;
+    int32 log_signature = 5; // filer whose clock stamped log_ts_ns
+}
+
+message UpdateEntryRequest {
+    string directory = 1;
+    Entry entry = 2;
+    bool is_from_other_cluster = 3;
+    repeated int32 signatures = 4;
+    map<string, bytes> expected_extended = 5;
+    // Optional precondition evaluated against the current entry atomically with
+    // the write, under the filer's per-path lock. The caller must route the
+    // key's writes to this entry's owner filer for the check to be authoritative.
+    WriteCondition condition = 6;
+}
+message UpdateEntryResponse {
+    SubscribeMetadataResponse metadata_event = 1;
+    // filer log position stamped under the path lock before the write:
+    // every event at or below it is reflected in the acknowledged state
+    int64 log_ts_ns = 2;
+    int32 log_signature = 3; // filer whose clock stamped log_ts_ns
+}
+
+message TouchAccessTimeRequest {
+    string directory = 1;
+    string name = 2;
+    int64 client_atime_ns = 3; // nanoseconds since epoch; filer may override with relatime
+}
+message TouchAccessTimeResponse {
+    int64 persisted_atime_ns = 1; // nanoseconds since epoch; 0 if no update was performed
+    bool updated = 2;
+}
+
+message AppendToEntryRequest {
+    string directory = 1;
+    string entry_name = 2;
+    repeated FileChunk chunks = 3;
+}
+message AppendToEntryResponse {
+}
+
+message DeleteEntryRequest {
+    string directory = 1;
+    string name = 2;
+    // bool is_directory = 3;
+    bool is_delete_data = 4;
+    bool is_recursive = 5;
+    bool ignore_recursive_error = 6;
+    bool is_from_other_cluster = 7;
+    repeated int32 signatures = 8;
+    int64 if_not_modified_after = 9;
+}
+
+message DeleteEntryResponse {
+    string error = 1;
+    SubscribeMetadataResponse metadata_event = 2;
+}
+
+message AtomicRenameEntryRequest {
+    string old_directory = 1;
+    string old_name = 2;
+    string new_directory = 3;
+    string new_name = 4;
+    repeated int32 signatures = 5;
+}
+
+message AtomicRenameEntryResponse {
+}
+
+message StreamRenameEntryRequest {
+    string old_directory = 1;
+    string old_name = 2;
+    string new_directory = 3;
+    string new_name = 4;
+    repeated int32 signatures = 5;
+}
+message StreamRenameEntryResponse {
+    string directory = 1;
+    EventNotification event_notification = 2;
+    int64 ts_ns = 3;
+}
+message AssignVolumeRequest {
+    int32 count = 1;
+    string collection = 2;
+    string replication = 3;
+    int32 ttl_sec = 4;
+    string data_center = 5;
+    string path = 6;
+    string rack = 7;
+    string data_node = 9;
+    string disk_type = 8;
+    uint64 expected_data_size = 10; // hint for size-aware volume selection
+}
+
+message AssignVolumeResponse {
+    string file_id = 1;
+    int32 count = 4;
+    string auth = 5;
+    string collection = 6;
+    string replication = 7;
+    string error = 8;
+    Location location = 9;
+    repeated Location replicas = 10;
+    // fsync is the storage rule's fsync decision for the assigned path, so the
+    // client can carry it onto the volume server upload request.
+    bool fsync = 11;
+}
+
+message LookupVolumeRequest {
+    repeated string volume_ids = 1;
+}
+
+message Locations {
+    repeated Location locations = 1;
+}
+
+message Location {
+    string url = 1;
+    string public_url = 2;
+    uint32 grpc_port = 3;
+    string data_center = 4;
+    bool data_in_remote = 5;
+}
+message LookupVolumeResponse {
+    map<string, Locations> locations_map = 1;
+}
+
+message Collection {
+    string name = 1;
+}
+message CollectionListRequest {
+    bool include_normal_volumes = 1;
+    bool include_ec_volumes = 2;
+}
+message CollectionListResponse {
+    repeated Collection collections = 1;
+}
+message DeleteCollectionRequest {
+    string collection = 1;
+}
+
+message DeleteCollectionResponse {
+}
+
+message StatisticsRequest {
+    string replication = 1;
+    string collection = 2;
+    string ttl = 3;
+    string disk_type = 4;
+}
+message StatisticsResponse {
+    uint64 total_size = 4;
+    uint64 used_size = 5;
+    uint64 file_count = 6;
+    // sizes counting one copy of the data, as reported by the master
+    uint64 logical_total_size = 7;
+    uint64 logical_used_size = 8;
+}
+
+message PingRequest {
+    string target = 1; // default to ping itself
+    string target_type = 2;
+}
+message PingResponse {
+    int64 start_time_ns = 1;
+    int64 remote_time_ns = 2;
+    int64 stop_time_ns = 3;
+}
+
+message GetFilerConfigurationRequest {
+}
+message GetFilerConfigurationResponse {
+    repeated string masters = 1;
+    string replication = 2;
+    string collection = 3;
+    uint32 max_mb = 4;
+    string dir_buckets = 5;
+    bool cipher = 7;
+    int32 signature = 8;
+    string metrics_address = 9;
+    int32 metrics_interval_sec = 10;
+    string version = 11;
+    string cluster_id = 12;
+    string filer_group = 13;
+    int32 major_version = 14;
+    int32 minor_version = 15;
+}
+
+message SubscribeMetadataRequest {
+    string client_name = 1;
+    string path_prefix = 2;
+    int64 since_ns = 3;
+    int32 signature = 4;
+    repeated string path_prefixes = 6;
+    int32 client_id = 7;
+    int64 until_ns = 8;
+    int32 client_epoch = 9;
+    repeated string directories = 10;  // exact directory to watch
+    bool client_supports_batching = 11; // client can unpack SubscribeMetadataResponse.events
+    bool client_supports_metadata_chunks = 12; // client can read log file chunks from volume servers
+    bool client_supports_idle_heartbeat = 13; // server may send empty responses carrying the current time while the client is caught up
+}
+message SubscribeMetadataResponse {
+    string directory = 1;
+    EventNotification event_notification = 2;
+    int64 ts_ns = 3;
+    repeated SubscribeMetadataResponse events = 4; // batch of additional events (backlog catch-up)
+    repeated LogFileChunkRef log_file_refs = 5;    // log file chunk refs for client direct-read
+    int64 flushed_ts_ns = 6; // local log-buffer flush watermark: everything at or below it is on disk
+}
+message ListMetadataSubscribersRequest {
+    repeated string client_types = 1; // optional filter by client type, e.g. "mount"; empty = all
+}
+message ListMetadataSubscribersResponse {
+    repeated MetadataSubscriber subscribers = 1;
+}
+message MetadataSubscriber {
+    string client_name = 1;     // "<type>@<address>"
+    string client_type = 2;     // e.g. "mount", "sw-vfs", "s3", "filer:<addr>"
+    string address = 3;         // client peer address
+    string path_prefix = 4;     // subscribed path prefix
+    int32 client_id = 5;
+    int32 client_epoch = 6;
+    int64 connected_at_ns = 7;
+    string filer_address = 8;   // the filer this subscriber is connected to
+}
+// A persisted log file that the client can read directly from volume servers.
+// The file format is: [4-byte size | protobuf LogEntry] repeated.
+// Each LogEntry.Data contains a marshaled SubscribeMetadataResponse.
+message LogFileChunkRef {
+    repeated FileChunk chunks = 1; // chunk references (fids) to read from volume servers
+    int64 file_ts_ns = 2;         // minute-level timestamp of the log file
+    string filer_id = 3;          // filer signature suffix from log filename
+}
+
+message TraverseBfsMetadataRequest {
+    string directory = 1;
+    repeated string excluded_prefixes = 2;
+}
+message TraverseBfsMetadataResponse {
+    string directory = 1;
+    Entry entry = 2;
+}
+
+message LogEntry {
+    int64 ts_ns = 1;
+    int32 partition_key_hash = 2;
+    bytes data = 3;
+    bytes key = 4;
+    int64 offset = 5;  // Sequential offset within partition
+}
+
+message KeepConnectedRequest {
+    string name = 1;
+    uint32 grpc_port = 2;
+    repeated string resources = 3;
+}
+message KeepConnectedResponse {
+}
+
+message LocateBrokerRequest {
+    string resource = 1;
+}
+
+message LocateBrokerResponse {
+    bool found = 1;
+    // if found, send the exact address
+    // if not found, send the full list of existing brokers
+    message Resource {
+        string grpc_addresses = 1;
+        int32 resource_count = 2;
+    }
+    repeated Resource resources = 2;
+}
+
+/////////////////////////
+// Key-Value operations
+/////////////////////////
+message KvGetRequest {
+    bytes key = 1;
+}
+message KvGetResponse {
+    bytes value = 1;
+    string error = 2;
+}
+message KvPutRequest {
+    bytes key = 1;
+    bytes value = 2;
+}
+message KvPutResponse {
+    string error = 1;
+}
+
+/////////////////////////
+// path-based configurations
+/////////////////////////
+message FilerConf {
+    int32 version = 1;
+    message PathConf {
+        string location_prefix = 1;
+        string collection = 2;
+        string replication = 3;
+        string ttl = 4;
+        string disk_type = 5;
+        bool fsync = 6;
+        uint32 volume_growth_count = 7;
+        bool read_only = 8;
+        string data_center = 9;
+        string rack = 10;
+        string data_node = 11;
+        uint32 max_file_name_length = 12;
+        bool disable_chunk_deletion = 13;
+        // unset inherits from the enclosing path rule, set overrides it
+        optional bool worm = 14;
+        uint64 worm_grace_period_seconds = 15;
+        uint64 worm_retention_time_seconds = 16;
+    }
+    repeated PathConf locations = 2;
+}
+
+/////////////////////////
+// Remote Storage related
+/////////////////////////
+message CacheRemoteObjectToLocalClusterRequest {
+    string directory = 1;
+    string name = 2;
+    int32 chunk_concurrency = 3; // parallel chunk downloads per file, 0 = default (8)
+    int32 download_concurrency = 4; // multipart download concurrency per chunk (if supported by remote storage), 0 = default (5 for S3)
+}
+message CacheRemoteObjectToLocalClusterResponse {
+    Entry entry = 1;
+    SubscribeMetadataResponse metadata_event = 2;
+    // filer log position stamped before the entry read: every event at or
+    // below it is reflected in the returned entry
+    int64 log_ts_ns = 3;
+    int32 log_signature = 4; // filer whose clock stamped log_ts_ns
+}
+
+/////////////////////////
+// distributed lock management
+/////////////////////////
+message LockRequest {
+    string name = 1;
+    int64 seconds_to_lock = 2;
+    string renew_token = 3;
+    bool is_moved = 4;
+    string owner = 5;
+}
+message LockResponse {
+    string renew_token = 1;
+    string lock_owner = 2;
+    string lock_host_moved_to = 3;
+    string error = 4;
+    int64 generation = 5;
+}
+message UnlockRequest {
+    string name = 1;
+    string renew_token = 2;
+    bool is_moved = 3;
+}
+message UnlockResponse {
+    string error = 1;
+    string moved_to = 2;
+}
+message FindLockOwnerRequest {
+    string name = 1;
+    bool is_moved = 2;
+}
+message FindLockOwnerResponse {
+    string owner = 1;
+}
+message Lock {
+    string name = 1;
+    string renew_token = 2;
+    int64 expired_at_ns = 3;
+    string owner = 4;
+    int64 generation = 5;
+    bool is_backup = 6;
+    int64 seq = 7;
+}
+message TransferLocksRequest {
+    repeated Lock locks = 1;
+}
+message TransferLocksResponse {
+}
+message ReplicateLockRequest {
+    string name = 1;
+    string renew_token = 2;
+    int64 expired_at_ns = 3;
+    string owner = 4;
+    int64 generation = 5;
+    bool is_unlock = 6;
+    int64 seq = 7;
+}
+message ReplicateLockResponse {
+}
+
+//////////////////////////////////////////////////
+// StreamMutateEntry: ordered bidirectional streaming for all filer mutations.
+// All create/update/delete/rename operations from a single mount go through
+// one stream, preserving mutation ordering and eliminating per-request
+// connection overhead.
+
+message StreamMutateEntryRequest {
+    uint64 request_id = 1;
+    oneof request {
+        CreateEntryRequest create_request = 2;
+        UpdateEntryRequest update_request = 3;
+        DeleteEntryRequest delete_request = 4;
+        StreamRenameEntryRequest rename_request = 5;
+    }
+}
+
+message StreamMutateEntryResponse {
+    uint64 request_id = 1;
+    bool is_last = 2; // always true except for rename, which sends multiple events
+    oneof response {
+        CreateEntryResponse create_response = 3;
+        UpdateEntryResponse update_response = 4;
+        DeleteEntryResponse delete_response = 5;
+        StreamRenameEntryResponse rename_response = 6;
+    }
+    string error = 7; // human-readable error message when the operation failed
+    int32 errno = 8;  // POSIX errno (e.g. ENOENT=2, ENOTEMPTY=66) for direct FUSE status mapping
+}
+
+//////////////////////////////////////////////////
+// Peer chunk sharing — mount-server registry
+//////////////////////////////////////////////////
+
+message MountRegisterRequest {
+    string peer_addr = 1;    // host:port where this mount serves peer chunk requests
+    string rack = 2;         // locality label (rack); used for peer ranking
+    int32 ttl_seconds = 3;   // how long the filer should keep this entry without a heartbeat
+    string data_center = 4;  // locality label (data center); coarser than rack
+}
+
+message MountRegisterResponse {
+}
+
+message MountListRequest {
+}
+
+message MountListResponse {
+    repeated MountInfo mounts = 1;
+}
+
+message MountInfo {
+    string peer_addr = 1;
+    string rack = 2;
+    int64 last_seen_ns = 3;
+    string data_center = 4;
+}
+
+// LookupDirectoryEntriesRequest batches independent exact-path lookups into
+// one bounded RPC. Results preserve this order. Empty batches and batches over
+// 4096 requests are rejected. Declared last to keep generated message indices
+// stable.
+message LookupDirectoryEntriesRequest {
+    repeated LookupDirectoryEntryRequest requests = 1;
+    // Cache callers may treat an Entry whose Volume the master no longer
+    // reports as a miss. A lookup the filer could not complete still marks the
+    // Entry with an error. Ordinary filesystem callers keep the fail-closed
+    // error in both cases.
+    bool unavailable_volume_is_miss = 2;
+}
+
+message LookupDirectoryEntryResult {
+    // found reports metadata presence. An error makes this item unusable even
+    // when entry is present, for example when a chunk volume cannot be located.
+    bool found = 1;
+    Entry entry = 2;
+    string error = 3;
+    // Per-entry read fence. Every filer event at or below this position is
+    // reflected in found/entry/error for this item.
+    int64 log_ts_ns = 4;
+    int32 log_signature = 5;
+}
+
+message LookupDirectoryEntriesResponse {
+    repeated LookupDirectoryEntryResult results = 1;
+    // One deduplicated location set for every volume referenced by returned
+    // Entry.chunks. A missing/unavailable volume has an empty Locations value
+    // and marks each affected result with an error.
+    map<string, Locations> locations_map = 2;
+    // Short-lived, exact-FID read capabilities. Direct data-plane clients must
+    // present the matching token to a Volume instead of treating a shared
+    // service credential as authority to read arbitrary needles.
+    map<string, string> read_auth = 3;
+}

other/java/client/src/test/java/seaweedfs/client/BasicAuthTest.java

@@ -0,0 +1,95 @@
+package seaweedfs.client;
+
+import io.grpc.CallOptions;
+import io.grpc.Channel;
+import io.grpc.ClientCall;
+import io.grpc.Metadata;
+import io.grpc.MethodDescriptor;
+import org.junit.After;
+import org.junit.Test;
+
+import java.nio.charset.StandardCharsets;
+import java.util.Base64;
+
+import static org.junit.Assert.assertEquals;
+import static org.junit.Assert.assertFalse;
+import static org.junit.Assert.assertNotNull;
+import static org.junit.Assert.assertNull;
+import static org.junit.Assert.assertTrue;
+
+public class BasicAuthTest {
+
+    @After
+    public void clearCredentials() {
+        FilerSecurityContext.setBasicAuth(null, null);
+    }
+
+    @Test
+    public void noCredentialsMeansNoHeader() {
+        FilerSecurityContext.setBasicAuth(null, null);
+        assertNull(FilerSecurityContext.getBasicAuthHeaderValue());
+        assertFalse(FilerSecurityContext.isBasicAuthEnabled());
+
+        FilerSecurityContext.setBasicAuth("", "ignored");
+        assertNull(FilerSecurityContext.getBasicAuthHeaderValue());
+        assertFalse(FilerSecurityContext.isBasicAuthEnabled());
+    }
+
+    @Test
+    public void encodesUserAndPassword() {
+        FilerSecurityContext.setBasicAuth("alice", "s3cret");
+        String expected = "Basic " + Base64.getEncoder()
+                .encodeToString("alice:s3cret".getBytes(StandardCharsets.UTF_8));
+        assertEquals(expected, FilerSecurityContext.getBasicAuthHeaderValue());
+        assertTrue(FilerSecurityContext.isBasicAuthEnabled());
+    }
+
+    @Test
+    public void interceptorAddsAuthorizationHeader() {
+        String headerValue = "Basic dGVzdDp0ZXN0";
+        final Metadata[] captured = new Metadata[1];
+
+        Channel channel = new Channel() {
+            @Override
+            public <ReqT, RespT> ClientCall<ReqT, RespT> newCall(
+                    MethodDescriptor<ReqT, RespT> method, CallOptions callOptions) {
+                return new ClientCall<ReqT, RespT>() {
+                    @Override
+                    public void start(Listener<RespT> responseListener, Metadata headers) {
+                        captured[0] = headers;
+                    }
+
+                    @Override
+                    public void request(int numMessages) {
+                    }
+
+                    @Override
+                    public void cancel(String message, Throwable cause) {
+                    }
+
+                    @Override
+                    public void halfClose() {
+                    }
+
+                    @Override
+                    public void sendMessage(ReqT message) {
+                    }
+                };
+            }
+
+            @Override
+            public String authority() {
+                return "test";
+            }
+        };
+
+        BasicAuthInterceptor interceptor = new BasicAuthInterceptor(headerValue);
+        ClientCall<Object, Object> call =
+                interceptor.interceptCall(null, CallOptions.DEFAULT, channel);
+        call.start(null, new Metadata());
+
+        Metadata.Key<String> key = Metadata.Key.of("authorization", Metadata.ASCII_STRING_MARSHALLER);
+        assertNotNull(captured[0]);
+        assertEquals(headerValue, captured[0].get(key));
+    }
+}

other/java/client/src/test/java/seaweedfs/client/FilerClientIntegrationTest.java

@@ -0,0 +1,323 @@
+package seaweedfs.client;
+
+import org.junit.After;
+import org.junit.Before;
+import org.junit.Test;
+
+import java.io.IOException;
+import java.nio.charset.StandardCharsets;
+import java.util.List;
+
+import static org.junit.Assert.*;
+
+/**
+ * Integration tests for FilerClient.
+ * 
+ * These tests verify FilerClient operations against a running SeaweedFS filer
+ * instance.
+ * 
+ * Prerequisites:
+ * - SeaweedFS master, volume server, and filer must be running
+ * - Default ports: filer HTTP 8888, filer gRPC 18888
+ * 
+ * To run tests:
+ * export SEAWEEDFS_TEST_ENABLED=true
+ * mvn test -Dtest=FilerClientIntegrationTest
+ */
+public class FilerClientIntegrationTest {
+
+    private FilerClient filerClient;
+    private static final String TEST_ROOT = "/test-client-integration";
+    private static final boolean TESTS_ENABLED = "true".equalsIgnoreCase(System.getenv("SEAWEEDFS_TEST_ENABLED"));
+
+    @Before
+    public void setUp() throws Exception {
+        if (!TESTS_ENABLED) {
+            return;
+        }
+
+        filerClient = new FilerClient("localhost", 18888);
+
+        // Clean up any existing test directory
+        if (filerClient.exists(TEST_ROOT)) {
+            filerClient.rm(TEST_ROOT, true, true);
+        }
+
+        // Create test root directory
+        filerClient.mkdirs(TEST_ROOT, 0755);
+    }
+
+    @After
+    public void tearDown() throws Exception {
+        if (!TESTS_ENABLED || filerClient == null) {
+            return;
+        }
+
+        try {
+            // Clean up test directory
+            if (filerClient.exists(TEST_ROOT)) {
+                filerClient.rm(TEST_ROOT, true, true);
+            }
+        } finally {
+            filerClient.shutdown();
+        }
+    }
+
+    @Test
+    public void testMkdirs() {
+        if (!TESTS_ENABLED) {
+            System.out.println("Skipping test - SEAWEEDFS_TEST_ENABLED not set");
+            return;
+        }
+
+        String testDir = TEST_ROOT + "/testdir";
+        boolean success = filerClient.mkdirs(testDir, 0755);
+
+        assertTrue("Directory creation should succeed", success);
+        assertTrue("Directory should exist", filerClient.exists(testDir));
+    }
+
+    @Test
+    public void testTouch() {
+        if (!TESTS_ENABLED) {
+            System.out.println("Skipping test - SEAWEEDFS_TEST_ENABLED not set");
+            return;
+        }
+
+        String testFile = TEST_ROOT + "/testfile.txt";
+        boolean success = filerClient.touch(testFile, 0644);
+
+        assertTrue("Touch should succeed", success);
+        assertTrue("File should exist", filerClient.exists(testFile));
+    }
+
+    @Test
+    public void testExists() {
+        if (!TESTS_ENABLED) {
+            System.out.println("Skipping test - SEAWEEDFS_TEST_ENABLED not set");
+            return;
+        }
+
+        assertTrue("Root should exist", filerClient.exists("/"));
+        assertTrue("Test root should exist", filerClient.exists(TEST_ROOT));
+        assertFalse("Non-existent path should not exist",
+                filerClient.exists(TEST_ROOT + "/nonexistent"));
+    }
+
+    @Test
+    public void testListEntries() {
+        if (!TESTS_ENABLED) {
+            System.out.println("Skipping test - SEAWEEDFS_TEST_ENABLED not set");
+            return;
+        }
+
+        // Create some test files and directories
+        filerClient.touch(TEST_ROOT + "/file1.txt", 0644);
+        filerClient.touch(TEST_ROOT + "/file2.txt", 0644);
+        filerClient.mkdirs(TEST_ROOT + "/subdir", 0755);
+
+        List<FilerProto.Entry> entries = filerClient.listEntries(TEST_ROOT);
+
+        assertNotNull("Entries should not be null", entries);
+        assertEquals("Should have 3 entries", 3, entries.size());
+    }
+
+    @Test
+    public void testListEntriesWithPrefix() {
+        if (!TESTS_ENABLED) {
+            System.out.println("Skipping test - SEAWEEDFS_TEST_ENABLED not set");
+            return;
+        }
+
+        // Create test files
+        filerClient.touch(TEST_ROOT + "/test1.txt", 0644);
+        filerClient.touch(TEST_ROOT + "/test2.txt", 0644);
+        filerClient.touch(TEST_ROOT + "/other.txt", 0644);
+
+        List<FilerProto.Entry> entries = filerClient.listEntries(TEST_ROOT, "test", "", 100, false);
+
+        assertNotNull("Entries should not be null", entries);
+        assertEquals("Should have 2 entries starting with 'test'", 2, entries.size());
+    }
+
+    @Test
+    public void testDeleteFile() {
+        if (!TESTS_ENABLED) {
+            System.out.println("Skipping test - SEAWEEDFS_TEST_ENABLED not set");
+            return;
+        }
+
+        String testFile = TEST_ROOT + "/deleteme.txt";
+        filerClient.touch(testFile, 0644);
+
+        assertTrue("File should exist before delete", filerClient.exists(testFile));
+
+        boolean success = filerClient.rm(testFile, false, true);
+
+        assertTrue("Delete should succeed", success);
+        assertFalse("File should not exist after delete", filerClient.exists(testFile));
+    }
+
+    @Test
+    public void testDeleteDirectoryRecursive() {
+        if (!TESTS_ENABLED) {
+            System.out.println("Skipping test - SEAWEEDFS_TEST_ENABLED not set");
+            return;
+        }
+
+        String testDir = TEST_ROOT + "/deletedir";
+        filerClient.mkdirs(testDir, 0755);
+        filerClient.touch(testDir + "/file.txt", 0644);
+
+        assertTrue("Directory should exist", filerClient.exists(testDir));
+        assertTrue("File should exist", filerClient.exists(testDir + "/file.txt"));
+
+        boolean success = filerClient.rm(testDir, true, true);
+
+        assertTrue("Delete should succeed", success);
+        assertFalse("Directory should not exist after delete", filerClient.exists(testDir));
+    }
+
+    @Test
+    public void testRename() {
+        if (!TESTS_ENABLED) {
+            System.out.println("Skipping test - SEAWEEDFS_TEST_ENABLED not set");
+            return;
+        }
+
+        String srcFile = TEST_ROOT + "/source.txt";
+        String dstFile = TEST_ROOT + "/destination.txt";
+
+        filerClient.touch(srcFile, 0644);
+        assertTrue("Source file should exist", filerClient.exists(srcFile));
+
+        boolean success = filerClient.mv(srcFile, dstFile);
+
+        assertTrue("Rename should succeed", success);
+        assertFalse("Source file should not exist after rename", filerClient.exists(srcFile));
+        assertTrue("Destination file should exist after rename", filerClient.exists(dstFile));
+    }
+
+    @Test
+    public void testGetEntry() {
+        if (!TESTS_ENABLED) {
+            System.out.println("Skipping test - SEAWEEDFS_TEST_ENABLED not set");
+            return;
+        }
+
+        String testFile = TEST_ROOT + "/getentry.txt";
+        filerClient.touch(testFile, 0644);
+
+        FilerProto.Entry entry = filerClient.lookupEntry(TEST_ROOT, "getentry.txt");
+
+        assertNotNull("Entry should not be null", entry);
+        assertEquals("Entry name should match", "getentry.txt", entry.getName());
+        assertFalse("Entry should not be a directory", entry.getIsDirectory());
+    }
+
+    @Test
+    public void testGetEntryForDirectory() {
+        if (!TESTS_ENABLED) {
+            System.out.println("Skipping test - SEAWEEDFS_TEST_ENABLED not set");
+            return;
+        }
+
+        String testDir = TEST_ROOT + "/testsubdir";
+        filerClient.mkdirs(testDir, 0755);
+
+        FilerProto.Entry entry = filerClient.lookupEntry(TEST_ROOT, "testsubdir");
+
+        assertNotNull("Entry should not be null", entry);
+        assertEquals("Entry name should match", "testsubdir", entry.getName());
+        assertTrue("Entry should be a directory", entry.getIsDirectory());
+    }
+
+    @Test
+    public void testCreateAndListNestedDirectories() {
+        if (!TESTS_ENABLED) {
+            System.out.println("Skipping test - SEAWEEDFS_TEST_ENABLED not set");
+            return;
+        }
+
+        String nestedPath = TEST_ROOT + "/level1/level2/level3";
+        boolean success = filerClient.mkdirs(nestedPath, 0755);
+
+        assertTrue("Nested directory creation should succeed", success);
+        assertTrue("Nested directory should exist", filerClient.exists(nestedPath));
+
+        // Verify each level exists
+        assertTrue("Level 1 should exist", filerClient.exists(TEST_ROOT + "/level1"));
+        assertTrue("Level 2 should exist", filerClient.exists(TEST_ROOT + "/level1/level2"));
+        assertTrue("Level 3 should exist", filerClient.exists(nestedPath));
+    }
+
+    @Test
+    public void testMultipleFilesInDirectory() {
+        if (!TESTS_ENABLED) {
+            System.out.println("Skipping test - SEAWEEDFS_TEST_ENABLED not set");
+            return;
+        }
+
+        String testDir = TEST_ROOT + "/multifiles";
+        filerClient.mkdirs(testDir, 0755);
+
+        // Create 10 files
+        for (int i = 0; i < 10; i++) {
+            filerClient.touch(testDir + "/file" + i + ".txt", 0644);
+        }
+
+        List<FilerProto.Entry> entries = filerClient.listEntries(testDir);
+
+        assertNotNull("Entries should not be null", entries);
+        assertEquals("Should have 10 files", 10, entries.size());
+    }
+
+    @Test
+    public void testRenameDirectory() {
+        if (!TESTS_ENABLED) {
+            System.out.println("Skipping test - SEAWEEDFS_TEST_ENABLED not set");
+            return;
+        }
+
+        String srcDir = TEST_ROOT + "/sourcedir";
+        String dstDir = TEST_ROOT + "/destdir";
+
+        filerClient.mkdirs(srcDir, 0755);
+        filerClient.touch(srcDir + "/file.txt", 0644);
+
+        boolean success = filerClient.mv(srcDir, dstDir);
+
+        assertTrue("Directory rename should succeed", success);
+        assertFalse("Source directory should not exist", filerClient.exists(srcDir));
+        assertTrue("Destination directory should exist", filerClient.exists(dstDir));
+        assertTrue("File should exist in destination", filerClient.exists(dstDir + "/file.txt"));
+    }
+
+    @Test
+    public void testLookupNonExistentEntry() {
+        if (!TESTS_ENABLED) {
+            System.out.println("Skipping test - SEAWEEDFS_TEST_ENABLED not set");
+            return;
+        }
+
+        FilerProto.Entry entry = filerClient.lookupEntry(TEST_ROOT, "nonexistent.txt");
+
+        assertNull("Entry for non-existent file should be null", entry);
+    }
+
+    @Test
+    public void testEmptyDirectory() {
+        if (!TESTS_ENABLED) {
+            System.out.println("Skipping test - SEAWEEDFS_TEST_ENABLED not set");
+            return;
+        }
+
+        String emptyDir = TEST_ROOT + "/emptydir";
+        filerClient.mkdirs(emptyDir, 0755);
+
+        List<FilerProto.Entry> entries = filerClient.listEntries(emptyDir);
+
+        assertNotNull("Entries should not be null", entries);
+        assertTrue("Empty directory should have no entries", entries.isEmpty());
+    }
+}

other/java/client/src/test/java/seaweedfs/client/GetPosBufferTest.java

@@ -0,0 +1,303 @@
+package seaweedfs.client;
+
+import org.junit.After;
+import org.junit.Before;
+import org.junit.Test;
+
+import java.io.IOException;
+import java.nio.charset.StandardCharsets;
+
+import static org.junit.Assert.*;
+
+/**
+ * Unit test to reproduce the Parquet EOF issue.
+ * 
+ * The issue: When Parquet writes column chunks, it calls getPos() to record
+ * offsets.
+ * If getPos() returns a position that doesn't include buffered (unflushed)
+ * data,
+ * the footer metadata will have incorrect offsets.
+ * 
+ * This test simulates Parquet's behavior:
+ * 1. Write some data (column chunk 1)
+ * 2. Call getPos() - Parquet records this as the END of chunk 1
+ * 3. Write more data (column chunk 2)
+ * 4. Call getPos() - Parquet records this as the END of chunk 2
+ * 5. Close the file
+ * 6. Verify that the recorded positions match the actual file content
+ * 
+ * Prerequisites:
+ * - SeaweedFS master, volume server, and filer must be running
+ * - Default ports: filer HTTP 8888, filer gRPC 18888
+ * 
+ * To run:
+ * export SEAWEEDFS_TEST_ENABLED=true
+ * cd other/java/client
+ * mvn test -Dtest=GetPosBufferTest
+ */
+public class GetPosBufferTest {
+
+    private FilerClient filerClient;
+    private static final String TEST_ROOT = "/test-getpos-buffer";
+    private static final boolean TESTS_ENABLED = "true".equalsIgnoreCase(System.getenv("SEAWEEDFS_TEST_ENABLED"));
+
+    @Before
+    public void setUp() throws Exception {
+        if (!TESTS_ENABLED) {
+            return;
+        }
+
+        String filerHost = System.getenv().getOrDefault("SEAWEEDFS_FILER_HOST", "localhost");
+        String filerGrpcPort = System.getenv().getOrDefault("SEAWEEDFS_FILER_GRPC_PORT", "18888");
+
+        filerClient = new FilerClient(filerHost, Integer.parseInt(filerGrpcPort));
+
+        // Clean up any existing test directory
+        if (filerClient.exists(TEST_ROOT)) {
+            filerClient.rm(TEST_ROOT, true, true);
+        }
+
+        // Create test root directory
+        filerClient.mkdirs(TEST_ROOT, 0755);
+    }
+
+    @After
+    public void tearDown() throws Exception {
+        if (!TESTS_ENABLED) {
+            return;
+        }
+        if (filerClient != null) {
+            filerClient.rm(TEST_ROOT, true, true);
+            filerClient.shutdown();
+        }
+    }
+
+    @Test
+    public void testGetPosWithBufferedData() throws IOException {
+        if (!TESTS_ENABLED) {
+            System.out.println("Skipping test - SEAWEEDFS_TEST_ENABLED not set");
+            return;
+        }
+
+        System.out.println("\n=== Testing getPos() with buffered data ===");
+
+        String testPath = TEST_ROOT + "/getpos-test.bin";
+
+        // Simulate what Parquet does when writing column chunks
+        SeaweedOutputStream outputStream = new SeaweedOutputStream(filerClient, testPath);
+
+        // Write "column chunk 1" - 100 bytes
+        byte[] chunk1 = new byte[100];
+        for (int i = 0; i < 100; i++) {
+            chunk1[i] = (byte) i;
+        }
+        outputStream.write(chunk1);
+
+        // Parquet calls getPos() here to record end of chunk 1
+        long posAfterChunk1 = outputStream.getPos();
+        System.out.println("Position after chunk 1 (100 bytes): " + posAfterChunk1);
+        assertEquals("getPos() should return 100 after writing 100 bytes", 100, posAfterChunk1);
+
+        // Write "column chunk 2" - 200 bytes
+        byte[] chunk2 = new byte[200];
+        for (int i = 0; i < 200; i++) {
+            chunk2[i] = (byte) (i + 100);
+        }
+        outputStream.write(chunk2);
+
+        // Parquet calls getPos() here to record end of chunk 2
+        long posAfterChunk2 = outputStream.getPos();
+        System.out.println("Position after chunk 2 (200 more bytes): " + posAfterChunk2);
+        assertEquals("getPos() should return 300 after writing 300 bytes total", 300, posAfterChunk2);
+
+        // Write "column chunk 3" - small chunk of 78 bytes (the problematic size!)
+        byte[] chunk3 = new byte[78];
+        for (int i = 0; i < 78; i++) {
+            chunk3[i] = (byte) (i + 50);
+        }
+        outputStream.write(chunk3);
+
+        // Parquet calls getPos() here to record end of chunk 3
+        long posAfterChunk3 = outputStream.getPos();
+        System.out.println("Position after chunk 3 (78 more bytes): " + posAfterChunk3);
+        assertEquals("getPos() should return 378 after writing 378 bytes total", 378, posAfterChunk3);
+
+        // Close to flush everything
+        outputStream.close();
+        System.out.println("File closed successfully");
+
+        // Now read the file and verify its actual size matches what getPos() reported
+        FilerProto.Entry entry = filerClient.lookupEntry(
+                SeaweedOutputStream.getParentDirectory(testPath),
+                SeaweedOutputStream.getFileName(testPath));
+
+        long actualFileSize = SeaweedRead.fileSize(entry);
+        System.out.println("Actual file size on disk: " + actualFileSize);
+
+        assertEquals("File size should match the last getPos() value", 378, actualFileSize);
+
+        // Now read the file and verify we can read all the data
+        SeaweedInputStream inputStream = new SeaweedInputStream(filerClient, testPath, entry);
+
+        byte[] readBuffer = new byte[500]; // Larger buffer to read everything
+        int totalRead = 0;
+        int bytesRead;
+        while ((bytesRead = inputStream.read(readBuffer, totalRead, readBuffer.length - totalRead)) > 0) {
+            totalRead += bytesRead;
+        }
+        inputStream.close();
+
+        System.out.println("Total bytes read: " + totalRead);
+        assertEquals("Should read exactly 378 bytes", 378, totalRead);
+
+        // Verify the data is correct
+        for (int i = 0; i < 100; i++) {
+            assertEquals("Chunk 1 data mismatch at byte " + i, (byte) i, readBuffer[i]);
+        }
+        for (int i = 0; i < 200; i++) {
+            assertEquals("Chunk 2 data mismatch at byte " + (100 + i), (byte) (i + 100), readBuffer[100 + i]);
+        }
+        for (int i = 0; i < 78; i++) {
+            assertEquals("Chunk 3 data mismatch at byte " + (300 + i), (byte) (i + 50), readBuffer[300 + i]);
+        }
+
+        System.out.println("SUCCESS: All data verified correctly!\n");
+    }
+
+    @Test
+    public void testGetPosWithSmallWrites() throws IOException {
+        if (!TESTS_ENABLED) {
+            System.out.println("Skipping test - SEAWEEDFS_TEST_ENABLED not set");
+            return;
+        }
+
+        System.out.println("\n=== Testing getPos() with many small writes (Parquet pattern) ===");
+
+        String testPath = TEST_ROOT + "/small-writes-test.bin";
+
+        SeaweedOutputStream outputStream = new SeaweedOutputStream(filerClient, testPath);
+
+        // Parquet writes column data in small chunks and frequently calls getPos()
+        String[] columnData = { "Alice", "Bob", "Charlie", "David" };
+        long[] recordedPositions = new long[columnData.length];
+
+        for (int i = 0; i < columnData.length; i++) {
+            byte[] data = columnData[i].getBytes(StandardCharsets.UTF_8);
+            outputStream.write(data);
+
+            // Parquet calls getPos() after each value to track offsets
+            recordedPositions[i] = outputStream.getPos();
+            System.out.println("After writing '" + columnData[i] + "': pos=" + recordedPositions[i]);
+        }
+
+        long finalPos = outputStream.getPos();
+        System.out.println("Final position before close: " + finalPos);
+
+        outputStream.close();
+
+        // Verify file size
+        FilerProto.Entry entry = filerClient.lookupEntry(
+                SeaweedOutputStream.getParentDirectory(testPath),
+                SeaweedOutputStream.getFileName(testPath));
+        long actualFileSize = SeaweedRead.fileSize(entry);
+
+        System.out.println("Actual file size: " + actualFileSize);
+        assertEquals("File size should match final getPos()", finalPos, actualFileSize);
+
+        // Verify we can read using the recorded positions
+        SeaweedInputStream inputStream = new SeaweedInputStream(filerClient, testPath, entry);
+
+        long currentPos = 0;
+        for (int i = 0; i < columnData.length; i++) {
+            long nextPos = recordedPositions[i];
+            int length = (int) (nextPos - currentPos);
+
+            byte[] buffer = new byte[length];
+            int bytesRead = inputStream.read(buffer, 0, length);
+
+            assertEquals("Should read " + length + " bytes for '" + columnData[i] + "'", length, bytesRead);
+
+            String readData = new String(buffer, 0, bytesRead, StandardCharsets.UTF_8);
+            System.out.println("Read at offset " + currentPos + ": '" + readData + "'");
+            assertEquals("Data mismatch", columnData[i], readData);
+
+            currentPos = nextPos;
+        }
+
+        inputStream.close();
+
+        System.out.println("SUCCESS: Small writes with getPos() tracking work correctly!\n");
+    }
+
+    @Test
+    public void testGetPosWithExactly78BytesBuffered() throws IOException {
+        if (!TESTS_ENABLED) {
+            System.out.println("Skipping test - SEAWEEDFS_TEST_ENABLED not set");
+            return;
+        }
+
+        System.out.println("\n=== Testing getPos() with EXACTLY 78 bytes buffered (the bug size!) ===");
+
+        String testPath = TEST_ROOT + "/78-bytes-test.bin";
+
+        SeaweedOutputStream outputStream = new SeaweedOutputStream(filerClient, testPath);
+
+        // Write some initial data
+        byte[] initial = new byte[1000];
+        for (int i = 0; i < 1000; i++) {
+            initial[i] = (byte) i;
+        }
+        outputStream.write(initial);
+        outputStream.flush(); // Ensure this is flushed
+
+        long posAfterFlush = outputStream.getPos();
+        System.out.println("Position after 1000 bytes + flush: " + posAfterFlush);
+        assertEquals("Should be at position 1000 after flush", 1000, posAfterFlush);
+
+        // Now write EXACTLY 78 bytes (the problematic buffer size in our bug)
+        byte[] problematicChunk = new byte[78];
+        for (int i = 0; i < 78; i++) {
+            problematicChunk[i] = (byte) (i + 50);
+        }
+        outputStream.write(problematicChunk);
+
+        // DO NOT FLUSH - this is the bug scenario!
+        // Parquet calls getPos() here while the 78 bytes are still buffered
+        long posWithBufferedData = outputStream.getPos();
+        System.out.println("Position with 78 bytes BUFFERED (not flushed): " + posWithBufferedData);
+
+        // This MUST return 1078, not 1000!
+        assertEquals("getPos() MUST include buffered data", 1078, posWithBufferedData);
+
+        // Now close (which will flush)
+        outputStream.close();
+
+        // Verify actual file size
+        FilerProto.Entry entry = filerClient.lookupEntry(
+                SeaweedOutputStream.getParentDirectory(testPath),
+                SeaweedOutputStream.getFileName(testPath));
+        long actualFileSize = SeaweedRead.fileSize(entry);
+
+        System.out.println("Actual file size: " + actualFileSize);
+        assertEquals("File size must be 1078", 1078, actualFileSize);
+
+        // Try to read at position 1000 for 78 bytes (what Parquet would try)
+        SeaweedInputStream inputStream = new SeaweedInputStream(filerClient, testPath, entry);
+        inputStream.seek(1000);
+
+        byte[] readBuffer = new byte[78];
+        int bytesRead = inputStream.read(readBuffer, 0, 78);
+
+        System.out.println("Bytes read at position 1000: " + bytesRead);
+        assertEquals("Should successfully read 78 bytes at position 1000", 78, bytesRead);
+
+        // Verify the data matches
+        for (int i = 0; i < 78; i++) {
+            assertEquals("Data mismatch at byte " + i, problematicChunk[i], readBuffer[i]);
+        }
+
+        inputStream.close();
+
+        System.out.println("SUCCESS: getPos() correctly includes buffered data!\n");
+    }
+}

other/java/client/src/test/java/seaweedfs/client/SeaweedCipherTest.java

@@ -0,0 +1,42 @@
+package seaweedfs.client;
+
+import org.junit.Test;
+
+import java.util.Base64;
+
+import static seaweedfs.client.SeaweedCipher.decrypt;
+import static seaweedfs.client.SeaweedCipher.encrypt;
+
+public class SeaweedCipherTest {
+
+    @Test
+    public void testSameAsGoImplemnetation() throws Exception {
+        byte[] secretKey = "256-bit key for AES 256 GCM encr".getBytes();
+
+        String plainText = "Now we need to generate a 256-bit key for AES 256 GCM";
+
+        System.out.println("Original Text : " + plainText);
+
+        byte[] cipherText = encrypt(plainText.getBytes(), secretKey);
+        System.out.println("Encrypted Text : " + Base64.getEncoder().encodeToString(cipherText));
+
+        byte[] decryptedText = decrypt(cipherText, secretKey);
+        System.out.println("DeCrypted Text : " + new String(decryptedText));
+    }
+
+    @Test
+    public void testEncryptDecrypt() throws Exception {
+        byte[] secretKey = SeaweedCipher.genCipherKey();
+
+        String plainText = "Now we need to generate a 256-bit key for AES 256 GCM";
+
+        System.out.println("Original Text : " + plainText);
+
+        byte[] cipherText = encrypt(plainText.getBytes(), secretKey);
+        System.out.println("Encrypted Text : " + Base64.getEncoder().encodeToString(cipherText));
+
+        byte[] decryptedText = decrypt(cipherText, secretKey);
+        System.out.println("DeCrypted Text : " + new String(decryptedText));
+    }
+
+}

other/java/client/src/test/java/seaweedfs/client/SeaweedFilerTest.java

@@ -0,0 +1,32 @@
+package seaweedfs.client;
+
+import java.util.List;
+
+public class SeaweedFilerTest {
+    public static void main(String[] args){
+
+        FilerClient filerClient = new FilerClient("localhost", 18888);
+
+        List<FilerProto.Entry> entries = filerClient.listEntries("/");
+
+        for (FilerProto.Entry entry : entries) {
+            System.out.println(entry.toString());
+        }
+
+        filerClient.mkdirs("/new_folder", 0755);
+        filerClient.touch("/new_folder/new_empty_file", 0755);
+        filerClient.touch("/new_folder/new_empty_file2", 0755);
+        if(!filerClient.exists("/new_folder/new_empty_file")){
+            System.out.println("/new_folder/new_empty_file should exists");
+        }
+
+        filerClient.rm("/new_folder/new_empty_file", false, true);
+        filerClient.rm("/new_folder", true, true);
+        if(filerClient.exists("/new_folder/new_empty_file")){
+            System.out.println("/new_folder/new_empty_file should not exists");
+        }
+        if(!filerClient.exists("/")){
+            System.out.println("/ should exists");
+        }
+    }
+}

other/java/client/src/test/java/seaweedfs/client/SeaweedReadTest.java

@@ -0,0 +1,193 @@
+package seaweedfs.client;
+
+import org.junit.Assert;
+import org.junit.Test;
+
+import java.io.IOException;
+import java.nio.ByteBuffer;
+import java.util.ArrayList;
+import java.util.List;
+import java.util.Random;
+
+public class SeaweedReadTest {
+
+    // A chunk fetch that briefly returns an empty body (observed right after an
+    // append) must not overrun the buffer with an opaque IndexOutOfBoundsException.
+    @Test
+    public void testReadChunkShorterThanViewFailsCleanly() throws IOException {
+        String fileId = "7,readchunkshort01";
+        SeaweedRead.volumeIdCache.setLocations("7",
+                FilerProto.Locations.newBuilder()
+                        .addLocations(FilerProto.Location.newBuilder().setUrl("localhost:0").build())
+                        .build());
+        // seed the chunk cache with an empty body so the fetch is skipped
+        SeaweedRead.chunkCache.setChunk(fileId, new byte[0]);
+
+        List<SeaweedRead.VisibleInterval> visibles = new ArrayList<>();
+        visibles.add(new SeaweedRead.VisibleInterval(0, 175, fileId, 1L, 0, true, null, false));
+
+        ByteBuffer buf = ByteBuffer.allocate(175);
+        try {
+            SeaweedRead.read(null, visibles, 0, buf, 175);
+            Assert.fail("expected IOException for a chunk shorter than its view");
+        } catch (IOException e) {
+            Assert.assertTrue(e.getMessage(), e.getMessage().contains(fileId));
+            Assert.assertTrue(e.getMessage(), e.getMessage().contains("[0,175)"));
+        }
+    }
+
+    @Test
+    public void testNonOverlappingVisibleIntervals() throws IOException {
+        List<FilerProto.FileChunk> chunks = new ArrayList<>();
+        chunks.add(FilerProto.FileChunk.newBuilder()
+                .setFileId("aaa")
+                .setOffset(0)
+                .setSize(100)
+                .setModifiedTsNs(1000)
+                .build());
+        chunks.add(FilerProto.FileChunk.newBuilder()
+                .setFileId("bbb")
+                .setOffset(100)
+                .setSize(133)
+                .setModifiedTsNs(2000)
+                .build());
+
+        List<SeaweedRead.VisibleInterval> visibleIntervals = SeaweedRead.nonOverlappingVisibleIntervals(null, chunks);
+        for (SeaweedRead.VisibleInterval visibleInterval : visibleIntervals) {
+            System.out.println("visible:" + visibleInterval);
+        }
+
+        Assert.assertEquals(visibleIntervals.size(), 2);
+
+        SeaweedRead.VisibleInterval visibleInterval = visibleIntervals.get(0);
+        Assert.assertEquals(visibleInterval.start, 0);
+        Assert.assertEquals(visibleInterval.stop, 100);
+        Assert.assertEquals(visibleInterval.modifiedTime, 1000);
+        Assert.assertEquals(visibleInterval.fileId, "aaa");
+
+        visibleInterval = visibleIntervals.get(1);
+        Assert.assertEquals(visibleInterval.start, 100);
+        Assert.assertEquals(visibleInterval.stop, 233);
+        Assert.assertEquals(visibleInterval.modifiedTime, 2000);
+        Assert.assertEquals(visibleInterval.fileId, "bbb");
+
+        List<SeaweedRead.ChunkView> chunkViews = SeaweedRead.viewFromVisibles(visibleIntervals, 0, 233);
+
+        SeaweedRead.ChunkView chunkView = chunkViews.get(0);
+        Assert.assertEquals(chunkView.offset, 0);
+        Assert.assertEquals(chunkView.size, 100);
+        Assert.assertEquals(chunkView.logicOffset, 0);
+        Assert.assertEquals(chunkView.fileId, "aaa");
+
+        chunkView = chunkViews.get(1);
+        Assert.assertEquals(chunkView.offset, 0);
+        Assert.assertEquals(chunkView.size, 133);
+        Assert.assertEquals(chunkView.logicOffset, 100);
+        Assert.assertEquals(chunkView.fileId, "bbb");
+
+
+    }
+
+
+    @Test
+    public void testReadResolvedChunks() throws IOException {
+        List<FilerProto.FileChunk> chunks = new ArrayList<>();
+        chunks.add(FilerProto.FileChunk.newBuilder()
+                .setFileId("a")
+                .setOffset(0)
+                .setSize(100)
+                .setModifiedTsNs(1)
+                .build());
+        chunks.add(FilerProto.FileChunk.newBuilder()
+                .setFileId("b")
+                .setOffset(50)
+                .setSize(100)
+                .setModifiedTsNs(2)
+                .build());
+        chunks.add(FilerProto.FileChunk.newBuilder()
+                .setFileId("c")
+                .setOffset(200)
+                .setSize(50)
+                .setModifiedTsNs(3)
+                .build());
+        chunks.add(FilerProto.FileChunk.newBuilder()
+                .setFileId("d")
+                .setOffset(250)
+                .setSize(50)
+                .setModifiedTsNs(4)
+                .build());
+        chunks.add(FilerProto.FileChunk.newBuilder()
+                .setFileId("e")
+                .setOffset(175)
+                .setSize(100)
+                .setModifiedTsNs(5)
+                .build());
+
+        List<SeaweedRead.VisibleInterval> visibleIntervals = ReadChunks.readResolvedChunks(chunks);
+        for (SeaweedRead.VisibleInterval visibleInterval : visibleIntervals) {
+            System.out.println("visible:" + visibleInterval);
+        }
+
+        Assert.assertEquals(4, visibleIntervals.size());
+
+        SeaweedRead.VisibleInterval visibleInterval = visibleIntervals.get(0);
+        Assert.assertEquals(visibleInterval.start, 0);
+        Assert.assertEquals(visibleInterval.stop, 50);
+        Assert.assertEquals(visibleInterval.modifiedTime, 1);
+        Assert.assertEquals(visibleInterval.fileId, "a");
+
+        visibleInterval = visibleIntervals.get(1);
+        Assert.assertEquals(visibleInterval.start, 50);
+        Assert.assertEquals(visibleInterval.stop, 150);
+        Assert.assertEquals(visibleInterval.modifiedTime, 2);
+        Assert.assertEquals(visibleInterval.fileId, "b");
+
+        visibleInterval = visibleIntervals.get(2);
+        Assert.assertEquals(visibleInterval.start, 175);
+        Assert.assertEquals(visibleInterval.stop, 275);
+        Assert.assertEquals(visibleInterval.modifiedTime, 5);
+        Assert.assertEquals(visibleInterval.fileId, "e");
+
+        visibleInterval = visibleIntervals.get(3);
+        Assert.assertEquals(visibleInterval.start, 275);
+        Assert.assertEquals(visibleInterval.stop, 300);
+        Assert.assertEquals(visibleInterval.modifiedTime, 4);
+        Assert.assertEquals(visibleInterval.fileId, "d");
+
+    }
+
+
+    @Test
+    public void testRandomizedReadResolvedChunks() throws IOException {
+        Random random = new Random();
+        int limit = 1024*1024;
+        long[] array = new long[limit];
+        List<FilerProto.FileChunk> chunks = new ArrayList<>();
+        for (long ts=0;ts<1024;ts++){
+            int x = random.nextInt(limit);
+            int y = random.nextInt(limit);
+            int size = Math.min(Math.abs(x-y), 1024);
+            chunks.add(randomWrite(array, Math.min(x,y), size, ts));
+        }
+
+        List<SeaweedRead.VisibleInterval> visibleIntervals = ReadChunks.readResolvedChunks(chunks);
+        for (SeaweedRead.VisibleInterval visibleInterval : visibleIntervals) {
+            System.out.println("visible:" + visibleInterval);
+            for (int i = (int) visibleInterval.start; i<visibleInterval.stop; i++) {
+                Assert.assertEquals(array[i], visibleInterval.modifiedTime);
+            }
+        }
+
+    }
+    private FilerProto.FileChunk randomWrite(long[] array, int start, int size, long ts) {
+        for (int i=start;i<start+size;i++) {
+            array[i] = ts;
+        }
+        return FilerProto.FileChunk.newBuilder()
+                .setFileId("")
+                .setOffset(start)
+                .setSize(size)
+                .setModifiedTsNs(ts)
+                .build();
+    }
+}

other/java/client/src/test/java/seaweedfs/client/SeaweedStreamIntegrationTest.java

@@ -0,0 +1,507 @@
+package seaweedfs.client;
+
+import org.junit.After;
+import org.junit.Before;
+import org.junit.Test;
+
+import java.io.IOException;
+import java.nio.charset.StandardCharsets;
+import java.util.Arrays;
+import java.util.Random;
+
+import static org.junit.Assert.*;
+
+/**
+ * Integration tests for SeaweedInputStream and SeaweedOutputStream.
+ * 
+ * These tests verify stream operations against a running SeaweedFS instance.
+ * 
+ * Prerequisites:
+ * - SeaweedFS master, volume server, and filer must be running
+ * - Default ports: filer HTTP 8888, filer gRPC 18888
+ * 
+ * To run tests:
+ * export SEAWEEDFS_TEST_ENABLED=true
+ * mvn test -Dtest=SeaweedStreamIntegrationTest
+ */
+public class SeaweedStreamIntegrationTest {
+
+    private FilerClient filerClient;
+    private static final String TEST_ROOT = "/test-stream-integration";
+    private static final boolean TESTS_ENABLED = "true".equalsIgnoreCase(System.getenv("SEAWEEDFS_TEST_ENABLED"));
+
+    @Before
+    public void setUp() throws Exception {
+        if (!TESTS_ENABLED) {
+            return;
+        }
+
+        filerClient = new FilerClient("localhost", 18888);
+
+        // Clean up any existing test directory
+        if (filerClient.exists(TEST_ROOT)) {
+            filerClient.rm(TEST_ROOT, true, true);
+        }
+
+        // Create test root directory
+        filerClient.mkdirs(TEST_ROOT, 0755);
+    }
+
+    @After
+    public void tearDown() throws Exception {
+        if (!TESTS_ENABLED || filerClient == null) {
+            return;
+        }
+
+        try {
+            // Clean up test directory
+            if (filerClient.exists(TEST_ROOT)) {
+                filerClient.rm(TEST_ROOT, true, true);
+            }
+        } finally {
+            filerClient.shutdown();
+        }
+    }
+
+    @Test
+    public void testWriteAndReadSmallFile() throws IOException {
+        if (!TESTS_ENABLED) {
+            System.out.println("Skipping test - SEAWEEDFS_TEST_ENABLED not set");
+            return;
+        }
+
+        String testPath = TEST_ROOT + "/small.txt";
+        String testContent = "Hello, SeaweedFS!";
+
+        // Write file
+        SeaweedOutputStream outputStream = new SeaweedOutputStream(filerClient, testPath);
+        outputStream.write(testContent.getBytes(StandardCharsets.UTF_8));
+        outputStream.close();
+
+        // Verify file exists
+        assertTrue("File should exist", filerClient.exists(testPath));
+
+        // Read file
+        FilerProto.Entry entry = filerClient.lookupEntry(
+                SeaweedOutputStream.getParentDirectory(testPath),
+                SeaweedOutputStream.getFileName(testPath));
+        assertNotNull("Entry should not be null", entry);
+
+        SeaweedInputStream inputStream = new SeaweedInputStream(filerClient, testPath, entry);
+        byte[] buffer = new byte[testContent.length()];
+        int bytesRead = inputStream.read(buffer);
+        inputStream.close();
+
+        assertEquals("Should read all bytes", testContent.length(), bytesRead);
+        assertEquals("Content should match", testContent, new String(buffer, StandardCharsets.UTF_8));
+    }
+
+    @Test
+    public void testWriteAndReadLargeFile() throws IOException {
+        if (!TESTS_ENABLED) {
+            System.out.println("Skipping test - SEAWEEDFS_TEST_ENABLED not set");
+            return;
+        }
+
+        String testPath = TEST_ROOT + "/large.bin";
+        int fileSize = 10 * 1024 * 1024; // 10 MB
+
+        // Generate random data
+        byte[] originalData = new byte[fileSize];
+        new Random(42).nextBytes(originalData); // Use seed for reproducibility
+
+        // Write file
+        SeaweedOutputStream outputStream = new SeaweedOutputStream(filerClient, testPath);
+        outputStream.write(originalData);
+        outputStream.close();
+
+        // Verify file exists
+        assertTrue("File should exist", filerClient.exists(testPath));
+
+        // Read file
+        FilerProto.Entry entry = filerClient.lookupEntry(
+                SeaweedOutputStream.getParentDirectory(testPath),
+                SeaweedOutputStream.getFileName(testPath));
+        assertNotNull("Entry should not be null", entry);
+
+        SeaweedInputStream inputStream = new SeaweedInputStream(filerClient, testPath, entry);
+
+        // Read file in chunks to handle large files properly
+        byte[] readData = new byte[fileSize];
+        int totalRead = 0;
+        int bytesRead;
+        byte[] buffer = new byte[8192]; // Read in 8KB chunks
+
+        while ((bytesRead = inputStream.read(buffer)) > 0) {
+            System.arraycopy(buffer, 0, readData, totalRead, bytesRead);
+            totalRead += bytesRead;
+        }
+        inputStream.close();
+
+        assertEquals("Should read all bytes", fileSize, totalRead);
+        assertArrayEquals("Content should match", originalData, readData);
+    }
+
+    @Test
+    public void testWriteInChunks() throws IOException {
+        if (!TESTS_ENABLED) {
+            System.out.println("Skipping test - SEAWEEDFS_TEST_ENABLED not set");
+            return;
+        }
+
+        String testPath = TEST_ROOT + "/chunked.txt";
+        String[] chunks = { "First chunk. ", "Second chunk. ", "Third chunk." };
+
+        // Write file in chunks
+        SeaweedOutputStream outputStream = new SeaweedOutputStream(filerClient, testPath);
+        for (String chunk : chunks) {
+            outputStream.write(chunk.getBytes(StandardCharsets.UTF_8));
+        }
+        outputStream.close();
+
+        // Read and verify
+        FilerProto.Entry entry = filerClient.lookupEntry(
+                SeaweedOutputStream.getParentDirectory(testPath),
+                SeaweedOutputStream.getFileName(testPath));
+
+        SeaweedInputStream inputStream = new SeaweedInputStream(filerClient, testPath, entry);
+        byte[] buffer = new byte[1024];
+        int bytesRead = inputStream.read(buffer);
+        inputStream.close();
+
+        String expected = String.join("", chunks);
+        String actual = new String(buffer, 0, bytesRead, StandardCharsets.UTF_8);
+
+        assertEquals("Content should match", expected, actual);
+    }
+
+    @Test
+    public void testReadWithOffset() throws IOException {
+        if (!TESTS_ENABLED) {
+            System.out.println("Skipping test - SEAWEEDFS_TEST_ENABLED not set");
+            return;
+        }
+
+        String testPath = TEST_ROOT + "/offset.txt";
+        String testContent = "0123456789ABCDEFGHIJ";
+
+        // Write file
+        SeaweedOutputStream outputStream = new SeaweedOutputStream(filerClient, testPath);
+        outputStream.write(testContent.getBytes(StandardCharsets.UTF_8));
+        outputStream.close();
+
+        // Read with offset
+        FilerProto.Entry entry = filerClient.lookupEntry(
+                SeaweedOutputStream.getParentDirectory(testPath),
+                SeaweedOutputStream.getFileName(testPath));
+
+        SeaweedInputStream inputStream = new SeaweedInputStream(filerClient, testPath, entry);
+        inputStream.seek(10); // Skip first 10 bytes
+
+        byte[] buffer = new byte[10];
+        int bytesRead = inputStream.read(buffer);
+        inputStream.close();
+
+        assertEquals("Should read 10 bytes", 10, bytesRead);
+        assertEquals("Should read from offset", "ABCDEFGHIJ",
+                new String(buffer, StandardCharsets.UTF_8));
+    }
+
+    @Test
+    public void testReadPartial() throws IOException {
+        if (!TESTS_ENABLED) {
+            System.out.println("Skipping test - SEAWEEDFS_TEST_ENABLED not set");
+            return;
+        }
+
+        String testPath = TEST_ROOT + "/partial.txt";
+        String testContent = "The quick brown fox jumps over the lazy dog";
+
+        // Write file
+        SeaweedOutputStream outputStream = new SeaweedOutputStream(filerClient, testPath);
+        outputStream.write(testContent.getBytes(StandardCharsets.UTF_8));
+        outputStream.close();
+
+        // Read partial
+        FilerProto.Entry entry = filerClient.lookupEntry(
+                SeaweedOutputStream.getParentDirectory(testPath),
+                SeaweedOutputStream.getFileName(testPath));
+
+        SeaweedInputStream inputStream = new SeaweedInputStream(filerClient, testPath, entry);
+
+        // Read only "quick brown"
+        inputStream.seek(4);
+        byte[] buffer = new byte[11];
+        int bytesRead = inputStream.read(buffer);
+        inputStream.close();
+
+        assertEquals("Should read 11 bytes", 11, bytesRead);
+        assertEquals("Should read partial content", "quick brown",
+                new String(buffer, StandardCharsets.UTF_8));
+    }
+
+    @Test
+    public void testEmptyFile() throws IOException {
+        if (!TESTS_ENABLED) {
+            System.out.println("Skipping test - SEAWEEDFS_TEST_ENABLED not set");
+            return;
+        }
+
+        String testPath = TEST_ROOT + "/empty.txt";
+
+        // Write empty file
+        SeaweedOutputStream outputStream = new SeaweedOutputStream(filerClient, testPath);
+        outputStream.close();
+
+        // Verify file exists
+        assertTrue("File should exist", filerClient.exists(testPath));
+
+        // Read empty file
+        FilerProto.Entry entry = filerClient.lookupEntry(
+                SeaweedOutputStream.getParentDirectory(testPath),
+                SeaweedOutputStream.getFileName(testPath));
+        assertNotNull("Entry should not be null", entry);
+
+        SeaweedInputStream inputStream = new SeaweedInputStream(filerClient, testPath, entry);
+        byte[] buffer = new byte[100];
+        int bytesRead = inputStream.read(buffer);
+        inputStream.close();
+
+        assertEquals("Should read 0 bytes from empty file", -1, bytesRead);
+    }
+
+    @Test
+    public void testOverwriteFile() throws IOException {
+        if (!TESTS_ENABLED) {
+            System.out.println("Skipping test - SEAWEEDFS_TEST_ENABLED not set");
+            return;
+        }
+
+        String testPath = TEST_ROOT + "/overwrite.txt";
+        String originalContent = "Original content";
+        String newContent = "New content that overwrites the original";
+
+        // Write original file
+        SeaweedOutputStream outputStream = new SeaweedOutputStream(filerClient, testPath);
+        outputStream.write(originalContent.getBytes(StandardCharsets.UTF_8));
+        outputStream.close();
+
+        // Overwrite file
+        outputStream = new SeaweedOutputStream(filerClient, testPath);
+        outputStream.write(newContent.getBytes(StandardCharsets.UTF_8));
+        outputStream.close();
+
+        // Read and verify
+        FilerProto.Entry entry = filerClient.lookupEntry(
+                SeaweedOutputStream.getParentDirectory(testPath),
+                SeaweedOutputStream.getFileName(testPath));
+
+        SeaweedInputStream inputStream = new SeaweedInputStream(filerClient, testPath, entry);
+        byte[] buffer = new byte[1024];
+        int bytesRead = inputStream.read(buffer);
+        inputStream.close();
+
+        String actual = new String(buffer, 0, bytesRead, StandardCharsets.UTF_8);
+        assertEquals("Should have new content", newContent, actual);
+    }
+
+    @Test
+    public void testMultipleReads() throws IOException {
+        if (!TESTS_ENABLED) {
+            System.out.println("Skipping test - SEAWEEDFS_TEST_ENABLED not set");
+            return;
+        }
+
+        String testPath = TEST_ROOT + "/multireads.txt";
+        String testContent = "ABCDEFGHIJKLMNOPQRSTUVWXYZ";
+
+        // Write file
+        SeaweedOutputStream outputStream = new SeaweedOutputStream(filerClient, testPath);
+        outputStream.write(testContent.getBytes(StandardCharsets.UTF_8));
+        outputStream.close();
+
+        // Read in multiple small chunks
+        FilerProto.Entry entry = filerClient.lookupEntry(
+                SeaweedOutputStream.getParentDirectory(testPath),
+                SeaweedOutputStream.getFileName(testPath));
+
+        SeaweedInputStream inputStream = new SeaweedInputStream(filerClient, testPath, entry);
+
+        StringBuilder result = new StringBuilder();
+        byte[] buffer = new byte[5];
+        int bytesRead;
+        while ((bytesRead = inputStream.read(buffer)) > 0) {
+            result.append(new String(buffer, 0, bytesRead, StandardCharsets.UTF_8));
+        }
+        inputStream.close();
+
+        assertEquals("Should read entire content", testContent, result.toString());
+    }
+
+    @Test
+    public void testBinaryData() throws IOException {
+        if (!TESTS_ENABLED) {
+            System.out.println("Skipping test - SEAWEEDFS_TEST_ENABLED not set");
+            return;
+        }
+
+        String testPath = TEST_ROOT + "/binary.bin";
+        byte[] binaryData = new byte[256];
+        for (int i = 0; i < 256; i++) {
+            binaryData[i] = (byte) i;
+        }
+
+        // Write binary file
+        SeaweedOutputStream outputStream = new SeaweedOutputStream(filerClient, testPath);
+        outputStream.write(binaryData);
+        outputStream.close();
+
+        // Read and verify
+        FilerProto.Entry entry = filerClient.lookupEntry(
+                SeaweedOutputStream.getParentDirectory(testPath),
+                SeaweedOutputStream.getFileName(testPath));
+
+        SeaweedInputStream inputStream = new SeaweedInputStream(filerClient, testPath, entry);
+        byte[] readData = new byte[256];
+        int bytesRead = inputStream.read(readData);
+        inputStream.close();
+
+        assertEquals("Should read all bytes", 256, bytesRead);
+        assertArrayEquals("Binary data should match", binaryData, readData);
+    }
+
+    @Test
+    public void testFlush() throws IOException {
+        if (!TESTS_ENABLED) {
+            System.out.println("Skipping test - SEAWEEDFS_TEST_ENABLED not set");
+            return;
+        }
+
+        String testPath = TEST_ROOT + "/flush.txt";
+        String testContent = "Content to flush";
+
+        // Write file with flush
+        SeaweedOutputStream outputStream = new SeaweedOutputStream(filerClient, testPath);
+        outputStream.write(testContent.getBytes(StandardCharsets.UTF_8));
+        outputStream.flush(); // Explicitly flush
+        outputStream.close();
+
+        // Verify file was written
+        assertTrue("File should exist after flush", filerClient.exists(testPath));
+
+        // Read and verify
+        FilerProto.Entry entry = filerClient.lookupEntry(
+                SeaweedOutputStream.getParentDirectory(testPath),
+                SeaweedOutputStream.getFileName(testPath));
+
+        SeaweedInputStream inputStream = new SeaweedInputStream(filerClient, testPath, entry);
+        byte[] buffer = new byte[testContent.length()];
+        int bytesRead = inputStream.read(buffer);
+        inputStream.close();
+
+        assertEquals("Content should match", testContent,
+                new String(buffer, 0, bytesRead, StandardCharsets.UTF_8));
+    }
+
+    /**
+     * Tests range reads similar to how Parquet reads column chunks.
+     * This simulates:
+     * 1. Seeking to specific offsets
+     * 2. Reading specific byte ranges
+     * 3. Verifying each read() call returns the correct number of bytes
+     * 
+     * This test specifically addresses the bug where read() was returning 0
+     * for inline content or -1 prematurely for chunked reads.
+     */
+    @Test
+    public void testRangeReads() throws IOException {
+        if (!TESTS_ENABLED) {
+            System.out.println("Skipping test - SEAWEEDFS_TEST_ENABLED not set");
+            return;
+        }
+
+        String testPath = TEST_ROOT + "/rangereads.dat";
+
+        // Create a 1275-byte file (similar to the Parquet file size that was failing)
+        byte[] testData = new byte[1275];
+        Random random = new Random(42); // Fixed seed for reproducibility
+        random.nextBytes(testData);
+
+        // Write file
+        SeaweedOutputStream outputStream = new SeaweedOutputStream(filerClient, testPath);
+        outputStream.write(testData);
+        outputStream.close();
+
+        // Read file entry
+        FilerProto.Entry entry = filerClient.lookupEntry(
+                SeaweedOutputStream.getParentDirectory(testPath),
+                SeaweedOutputStream.getFileName(testPath));
+
+        // Test 1: Read last 8 bytes (like reading Parquet footer length)
+        SeaweedInputStream inputStream = new SeaweedInputStream(filerClient, testPath, entry);
+        inputStream.seek(1267);
+        byte[] buffer = new byte[8];
+        int bytesRead = inputStream.read(buffer, 0, 8);
+        assertEquals("Should read 8 bytes at offset 1267", 8, bytesRead);
+        assertArrayEquals("Content at offset 1267 should match",
+                Arrays.copyOfRange(testData, 1267, 1275), buffer);
+        inputStream.close();
+
+        // Test 2: Read large chunk in middle (like reading column data)
+        inputStream = new SeaweedInputStream(filerClient, testPath, entry);
+        inputStream.seek(383);
+        buffer = new byte[884]; // Read bytes 383-1267
+        bytesRead = inputStream.read(buffer, 0, 884);
+        assertEquals("Should read 884 bytes at offset 383", 884, bytesRead);
+        assertArrayEquals("Content at offset 383 should match",
+                Arrays.copyOfRange(testData, 383, 1267), buffer);
+        inputStream.close();
+
+        // Test 3: Read from beginning (like reading Parquet magic bytes)
+        inputStream = new SeaweedInputStream(filerClient, testPath, entry);
+        buffer = new byte[4];
+        bytesRead = inputStream.read(buffer, 0, 4);
+        assertEquals("Should read 4 bytes at offset 0", 4, bytesRead);
+        assertArrayEquals("Content at offset 0 should match",
+                Arrays.copyOfRange(testData, 0, 4), buffer);
+        inputStream.close();
+
+        // Test 4: Multiple sequential reads without seeking (like
+        // H2SeekableInputStream.readFully)
+        // This is the critical test case that was failing!
+        inputStream = new SeaweedInputStream(filerClient, testPath, entry);
+        inputStream.seek(1197); // Position where EOF was being returned prematurely
+
+        byte[] fullBuffer = new byte[78]; // Try to read the "missing" 78 bytes
+        int totalRead = 0;
+        int offset = 0;
+        int remaining = 78;
+
+        // Simulate Parquet's H2SeekableInputStream.readFully() loop
+        while (remaining > 0) {
+            int read = inputStream.read(fullBuffer, offset, remaining);
+            if (read == -1) {
+                fail(String.format(
+                        "Got EOF after reading %d bytes, but expected to read %d more bytes (total requested: 78)",
+                        totalRead, remaining));
+            }
+            assertTrue("Each read() should return positive bytes", read > 0);
+            totalRead += read;
+            offset += read;
+            remaining -= read;
+        }
+
+        assertEquals("Should read all 78 bytes in readFully loop", 78, totalRead);
+        assertArrayEquals("Content at offset 1197 should match",
+                Arrays.copyOfRange(testData, 1197, 1275), fullBuffer);
+        inputStream.close();
+
+        // Test 5: Read entire file in one go
+        inputStream = new SeaweedInputStream(filerClient, testPath, entry);
+        byte[] allData = new byte[1275];
+        bytesRead = inputStream.read(allData, 0, 1275);
+        assertEquals("Should read entire 1275 bytes", 1275, bytesRead);
+        assertArrayEquals("Entire content should match", testData, allData);
+        inputStream.close();
+    }
+}

other/java/examples/pom.xml

@@ -0,0 +1,32 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project xmlns="http://maven.apache.org/POM/4.0.0"
+         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
+    <modelVersion>4.0.0</modelVersion>
+
+    <groupId>org.example</groupId>
+    <artifactId>unzip</artifactId>
+    <version>1.0-SNAPSHOT</version>
+    <dependencies>
+        <dependency>
+            <groupId>com.seaweedfs</groupId>
+            <artifactId>seaweedfs-client</artifactId>
+            <version>3.80</version>
+            <scope>compile</scope>
+        </dependency>
+        <dependency>
+            <groupId>com.seaweedfs</groupId>
+            <artifactId>seaweedfs-hadoop3-client</artifactId>
+            <version>3.80</version>
+            <scope>compile</scope>
+        </dependency>
+        <dependency>
+            <groupId>org.apache.hadoop</groupId>
+            <artifactId>hadoop-common</artifactId>
+            <version>3.4.0</version>
+            <scope>compile</scope>
+        </dependency>
+    </dependencies>
+
+
+</project>

other/java/examples/src/main/java/com/seaweedfs/examples/ExampleReadFile.java

@@ -0,0 +1,48 @@
+package com.seaweedfs.examples;
+
+import seaweedfs.client.FilerClient;
+import seaweedfs.client.SeaweedInputStream;
+
+import java.io.FileInputStream;
+import java.io.IOException;
+import java.io.InputStream;
+import java.util.zip.ZipEntry;
+import java.util.zip.ZipInputStream;
+
+public class ExampleReadFile {
+
+    public static void main(String[] args) throws IOException {
+
+        FilerClient filerClient = new FilerClient("localhost", 18888);
+
+        long startTime = System.currentTimeMillis();
+        parseZip("/Users/chris/tmp/test.zip");
+
+        long startTime2 = System.currentTimeMillis();
+
+        long localProcessTime = startTime2 - startTime;
+
+        SeaweedInputStream seaweedInputStream = new SeaweedInputStream(
+                filerClient, "/test.zip");
+        parseZip(seaweedInputStream);
+
+        long swProcessTime = System.currentTimeMillis() - startTime2;
+
+        System.out.println("Local time: " + localProcessTime);
+        System.out.println("SeaweedFS time: " + swProcessTime);
+
+    }
+
+    public static void parseZip(String filename) throws IOException {
+        FileInputStream fileInputStream = new FileInputStream(filename);
+        parseZip(fileInputStream);
+    }
+
+    public static void parseZip(InputStream is) throws IOException {
+        ZipInputStream zin = new ZipInputStream(is);
+        ZipEntry ze;
+        while ((ze = zin.getNextEntry()) != null) {
+            System.out.println(ze.getName());
+        }
+    }
+}

other/java/examples/src/main/java/com/seaweedfs/examples/ExampleWatchFileChanges.java

@@ -0,0 +1,46 @@
+package com.seaweedfs.examples;
+
+import seaweedfs.client.FilerClient;
+import seaweedfs.client.FilerProto;
+
+import java.io.IOException;
+import java.util.Date;
+import java.util.Iterator;
+
+public class ExampleWatchFileChanges {
+
+    public static void main(String[] args) throws IOException {
+
+        FilerClient filerClient = new FilerClient("localhost", 18888);
+
+        long sinceNs = (System.currentTimeMillis() - 3600 * 1000) * 1000000L;
+
+        Iterator<FilerProto.SubscribeMetadataResponse> watch = filerClient.watch(
+                "/buckets",
+                "exampleClientName",
+                sinceNs
+        );
+
+        System.out.println("Connected to filer, subscribing from " + new Date());
+
+        while (watch.hasNext()) {
+            FilerProto.SubscribeMetadataResponse event = watch.next();
+            FilerProto.EventNotification notification = event.getEventNotification();
+            if (!event.getDirectory().equals(notification.getNewParentPath())) {
+                // move an entry to a new directory, possibly with a new name
+                if (notification.hasOldEntry() && notification.hasNewEntry()) {
+                    System.out.println("moved " + event.getDirectory() + "/" + notification.getOldEntry().getName() + " to " + notification.getNewParentPath() + "/" + notification.getNewEntry().getName());
+                } else {
+                    System.out.println("this should not happen.");
+                }
+            } else if (notification.hasNewEntry() && !notification.hasOldEntry()) {
+                System.out.println("created entry " + event.getDirectory() + "/" + notification.getNewEntry().getName());
+            } else if (!notification.hasNewEntry() && notification.hasOldEntry()) {
+                System.out.println("deleted entry " + event.getDirectory() + "/" + notification.getOldEntry().getName());
+            } else if (notification.hasNewEntry() && notification.hasOldEntry()) {
+                System.out.println("updated entry " + event.getDirectory() + "/" + notification.getNewEntry().getName());
+            }
+        }
+
+    }
+}

other/java/examples/src/main/java/com/seaweedfs/examples/ExampleWriteFile.java

@@ -0,0 +1,47 @@
+package com.seaweedfs.examples;
+
+import seaweedfs.client.FilerClient;
+import seaweedfs.client.SeaweedInputStream;
+import seaweedfs.client.SeaweedOutputStream;
+
+import java.io.IOException;
+import java.io.InputStream;
+import java.util.zip.ZipEntry;
+import java.util.zip.ZipInputStream;
+
+public class ExampleWriteFile {
+
+    public static void main(String[] args) throws IOException {
+
+        FilerClient filerClient = new FilerClient("localhost", 18888);
+
+        SeaweedInputStream seaweedInputStream = new SeaweedInputStream(filerClient, "/test.zip");
+        unZipFiles(filerClient, seaweedInputStream);
+
+    }
+
+    public static void unZipFiles(FilerClient filerClient, InputStream is) throws IOException {
+        ZipInputStream zin = new ZipInputStream(is);
+        ZipEntry ze;
+        while ((ze = zin.getNextEntry()) != null) {
+
+            String filename = ze.getName();
+            if (filename.indexOf("/") >= 0) {
+                filename = filename.substring(filename.lastIndexOf("/") + 1);
+            }
+            if (filename.length()==0) {
+                continue;
+            }
+
+            SeaweedOutputStream seaweedOutputStream = new SeaweedOutputStream(filerClient, "/test/"+filename);
+            byte[] bytesIn = new byte[16 * 1024];
+            int read = 0;
+            while ((read = zin.read(bytesIn))!=-1) {
+                seaweedOutputStream.write(bytesIn,0,read);
+            }
+            seaweedOutputStream.close();
+
+            System.out.println(ze.getName());
+        }
+    }
+}

other/java/examples/src/main/java/com/seaweedfs/examples/ExampleWriteFile2.java

@@ -0,0 +1,22 @@
+package com.seaweedfs.examples;
+
+import com.google.common.io.Files;
+import seaweedfs.client.FilerClient;
+import seaweedfs.client.SeaweedOutputStream;
+
+import java.io.File;
+import java.io.IOException;
+
+public class ExampleWriteFile2 {
+
+    public static void main(String[] args) throws IOException {
+
+        FilerClient filerClient = new FilerClient("localhost", 18888);
+
+        SeaweedOutputStream seaweedOutputStream = new SeaweedOutputStream(filerClient, "/test/1");
+        Files.copy(new File("/etc/resolv.conf"), seaweedOutputStream);
+        seaweedOutputStream.close();
+
+    }
+
+}

other/java/examples/src/main/java/com/seaweedfs/examples/HdfsCopyFile.java

@@ -0,0 +1,25 @@
+package com.seaweedfs.examples;
+
+import org.apache.hadoop.conf.Configuration;
+import org.apache.hadoop.fs.FileSystem;
+import org.apache.hadoop.fs.Path;
+import org.apache.hadoop.io.IOUtils;
+
+import java.io.*;
+
+public class HdfsCopyFile {
+    public static void main(String[] args) throws IOException {
+        Configuration configuration = new Configuration();
+
+        configuration.set("fs.defaultFS", "seaweedfs://localhost:8888");
+        configuration.set("fs.seaweedfs.impl", "seaweed.hdfs.SeaweedFileSystem");
+
+        FileSystem fs = FileSystem.get(configuration);
+        String source = "/Users/chris/tmp/test.zip";
+        String destination = "/buckets/spark/test01.zip";
+        InputStream in = new BufferedInputStream(new FileInputStream(source));
+
+        OutputStream out = fs.create(new Path(destination));
+        IOUtils.copyBytes(in, out, 4096, true);
+    }
+}

other/java/hdfs3/README.md

@@ -0,0 +1,199 @@
+# SeaweedFS Hadoop3 Client
+
+Hadoop FileSystem implementation for SeaweedFS, compatible with Hadoop 3.x.
+
+## Building
+
+```bash
+mvn clean install
+```
+
+## Testing
+
+This project includes two types of tests:
+
+### 1. Configuration Tests (No SeaweedFS Required)
+
+These tests verify configuration handling and initialization logic without requiring a running SeaweedFS instance:
+
+```bash
+mvn test -Dtest=SeaweedFileSystemConfigTest
+```
+
+### 2. Integration Tests (Requires SeaweedFS)
+
+These tests verify actual FileSystem operations against a running SeaweedFS instance.
+
+#### Prerequisites
+
+1. Start SeaweedFS with default ports:
+   ```bash
+   # Terminal 1: Start master
+   weed master
+   
+   # Terminal 2: Start volume server
+   weed volume -master=localhost:9333
+   
+   # Terminal 3: Start filer
+   weed filer -master=localhost:9333
+   ```
+
+2. Verify services are running:
+   - Master: http://localhost:9333
+   - Filer HTTP: http://localhost:8888
+   - Filer gRPC: localhost:18888
+
+#### Running Integration Tests
+
+```bash
+# Enable integration tests
+export SEAWEEDFS_TEST_ENABLED=true
+
+# Run all tests
+mvn test
+
+# Run specific test
+mvn test -Dtest=SeaweedFileSystemTest
+```
+
+### Test Configuration
+
+Integration tests can be configured via environment variables or system properties:
+
+- `SEAWEEDFS_TEST_ENABLED`: Set to `true` to enable integration tests (default: false)
+- Tests use these default connection settings:
+  - Filer Host: localhost
+  - Filer HTTP Port: 8888
+  - Filer gRPC Port: 18888
+
+### Running Tests with Custom Configuration
+
+To test against a different SeaweedFS instance, modify the test code or use Hadoop configuration:
+
+```java
+conf.set("fs.seaweed.filer.host", "your-host");
+conf.setInt("fs.seaweed.filer.port", 8888);
+conf.setInt("fs.seaweed.filer.port.grpc", 18888);
+```
+
+## Test Coverage
+
+The test suite covers:
+
+- **Configuration & Initialization**
+  - URI parsing and configuration
+  - Default values
+  - Configuration overrides
+  - Working directory management
+
+- **File Operations**
+  - Create files
+  - Read files
+  - Write files
+  - Append to files
+  - Delete files
+
+- **Directory Operations**
+  - Create directories
+  - List directory contents
+  - Delete directories (recursive and non-recursive)
+
+- **Metadata Operations**
+  - Get file status
+  - Set permissions
+  - Set owner/group
+  - Rename files and directories
+
+## Usage in Hadoop
+
+1. Copy the built JAR to your Hadoop classpath:
+   ```bash
+   cp target/seaweedfs-hadoop3-client-*.jar $HADOOP_HOME/share/hadoop/common/lib/
+   ```
+
+2. Configure `core-site.xml`:
+   ```xml
+   <configuration>
+     <property>
+       <name>fs.seaweedfs.impl</name>
+       <value>seaweed.hdfs.SeaweedFileSystem</value>
+     </property>
+     <property>
+       <name>fs.seaweed.filer.host</name>
+       <value>localhost</value>
+     </property>
+     <property>
+       <name>fs.seaweed.filer.port</name>
+       <value>8888</value>
+     </property>
+     <property>
+       <name>fs.seaweed.filer.port.grpc</name>
+       <value>18888</value>
+     </property>
+     <!-- Optional: Replication configuration with three priority levels:
+          1) If set to non-empty value (e.g. "001") - uses that value
+          2) If set to empty string "" - uses SeaweedFS filer's default replication
+          3) If not configured (property not present) - uses HDFS replication parameter
+     -->
+     <!-- <property>
+       <name>fs.seaweed.replication</name>
+       <value>001</value>
+     </property> -->
+   </configuration>
+   ```
+
+3. Use SeaweedFS with Hadoop commands:
+   ```bash
+   hadoop fs -ls seaweedfs://localhost:8888/
+   hadoop fs -mkdir seaweedfs://localhost:8888/test
+   hadoop fs -put local.txt seaweedfs://localhost:8888/test/
+   ```
+
+## Continuous Integration
+
+For CI environments, tests can be run in two modes:
+
+1. **Configuration Tests Only** (default, no SeaweedFS required):
+   ```bash
+   mvn test -Dtest=SeaweedFileSystemConfigTest
+   ```
+
+2. **Full Integration Tests** (requires SeaweedFS):
+   ```bash
+   # Start SeaweedFS in CI environment
+   # Then run:
+   export SEAWEEDFS_TEST_ENABLED=true
+   mvn test
+   ```
+
+## Troubleshooting
+
+### Tests are skipped
+
+If you see "Skipping test - SEAWEEDFS_TEST_ENABLED not set":
+```bash
+export SEAWEEDFS_TEST_ENABLED=true
+```
+
+### Connection refused errors
+
+Ensure SeaweedFS is running and accessible:
+```bash
+curl http://localhost:8888/
+```
+
+### gRPC errors
+
+Verify the gRPC port is accessible:
+```bash
+# Should show the port is listening
+netstat -an | grep 18888
+```
+
+## Contributing
+
+When adding new features, please include:
+1. Configuration tests (no SeaweedFS required)
+2. Integration tests (with SEAWEEDFS_TEST_ENABLED guard)
+3. Documentation updates
+

other/java/hdfs3/dependency-reduced-pom.xml

@@ -0,0 +1,578 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">
+  <modelVersion>4.0.0</modelVersion>
+  <groupId>com.seaweedfs</groupId>
+  <artifactId>seaweedfs-hadoop3-client</artifactId>
+  <name>SeaweedFS HDFS3 Client</name>
+  <version>${seaweedfs.client.version}</version>
+  <description>A java client for SeaweedFS.</description>
+  <url>https://github.com/seaweedfs/seaweedfs</url>
+  <developers>
+    <developer>
+      <name>Chris Lu</name>
+      <email>chris.lu@gmail.com</email>
+      <organization>SeaweedFS</organization>
+      <organizationUrl>https://seaweedfs.com</organizationUrl>
+    </developer>
+  </developers>
+  <licenses>
+    <license>
+      <name>The Apache License, Version 2.0</name>
+      <url>http://www.apache.org/licenses/LICENSE-2.0.txt</url>
+    </license>
+  </licenses>
+  <scm>
+    <connection>scm:git:git://github.com/seaweedfs/seaweedfs.git</connection>
+    <developerConnection>scm:git:ssh://github.com:seaweedfs/seaweedfs.git</developerConnection>
+    <url>https://github.com/seaweedfs/seaweedfs/tree/master</url>
+  </scm>
+  <build>
+    <plugins>
+      <plugin>
+        <artifactId>maven-compiler-plugin</artifactId>
+        <configuration>
+          <source>8</source>
+          <target>8</target>
+          <release>8</release>
+        </configuration>
+      </plugin>
+      <plugin>
+        <artifactId>maven-shade-plugin</artifactId>
+        <version>3.2.1</version>
+        <executions>
+          <execution>
+            <phase>package</phase>
+            <goals>
+              <goal>shade</goal>
+            </goals>
+            <configuration>
+              <filters>
+                <filter>
+                  <artifact>*:*</artifact>
+                  <excludes>
+                    <exclude>META-INF/*.SF</exclude>
+                    <exclude>META-INF/*.DSA</exclude>
+                    <exclude>META-INF/*.RSA</exclude>
+                    <exclude>org/slf4j/**</exclude>
+                    <exclude>META-INF/maven/org.slf4j/**</exclude>
+                  </excludes>
+                </filter>
+              </filters>
+              <transformers>
+                <transformer />
+              </transformers>
+              <relocations>
+                <relocation>
+                  <pattern>com.google</pattern>
+                  <shadedPattern>shaded.com.google</shadedPattern>
+                </relocation>
+                <relocation>
+                  <pattern>io.grpc.internal</pattern>
+                  <shadedPattern>shaded.io.grpc.internal</shadedPattern>
+                </relocation>
+                <relocation>
+                  <pattern>org.apache.commons</pattern>
+                  <shadedPattern>shaded.org.apache.commons</shadedPattern>
+                  <excludes>
+                    <exclude>org.apache.hadoop</exclude>
+                    <exclude>org.apache.log4j</exclude>
+                  </excludes>
+                </relocation>
+                <relocation>
+                  <pattern>org.apache.http</pattern>
+                  <shadedPattern>shaded.org.apache.http</shadedPattern>
+                </relocation>
+              </relocations>
+            </configuration>
+          </execution>
+        </executions>
+      </plugin>
+      <plugin>
+        <artifactId>maven-gpg-plugin</artifactId>
+        <version>1.5</version>
+        <executions>
+          <execution>
+            <id>sign-artifacts</id>
+            <phase>verify</phase>
+            <goals>
+              <goal>sign</goal>
+            </goals>
+          </execution>
+        </executions>
+      </plugin>
+      <plugin>
+        <groupId>org.sonatype.central</groupId>
+        <artifactId>central-publishing-maven-plugin</artifactId>
+        <version>0.5.0</version>
+        <extensions>true</extensions>
+        <configuration>
+          <publishingServerId>central</publishingServerId>
+          <autoPublish>true</autoPublish>
+        </configuration>
+      </plugin>
+      <plugin>
+        <artifactId>maven-source-plugin</artifactId>
+        <version>2.2.1</version>
+        <executions>
+          <execution>
+            <id>attach-sources</id>
+            <goals>
+              <goal>jar-no-fork</goal>
+            </goals>
+          </execution>
+        </executions>
+      </plugin>
+      <plugin>
+        <artifactId>maven-javadoc-plugin</artifactId>
+        <version>3.0.1</version>
+        <executions>
+          <execution>
+            <id>attach-javadocs</id>
+            <goals>
+              <goal>jar</goal>
+            </goals>
+          </execution>
+        </executions>
+      </plugin>
+    </plugins>
+  </build>
+  <dependencies>
+    <dependency>
+      <groupId>org.apache.hadoop</groupId>
+      <artifactId>hadoop-client</artifactId>
+      <version>3.4.0</version>
+      <scope>provided</scope>
+      <exclusions>
+        <exclusion>
+          <artifactId>hadoop-hdfs-client</artifactId>
+          <groupId>org.apache.hadoop</groupId>
+        </exclusion>
+        <exclusion>
+          <artifactId>hadoop-yarn-api</artifactId>
+          <groupId>org.apache.hadoop</groupId>
+        </exclusion>
+        <exclusion>
+          <artifactId>hadoop-yarn-client</artifactId>
+          <groupId>org.apache.hadoop</groupId>
+        </exclusion>
+        <exclusion>
+          <artifactId>hadoop-mapreduce-client-core</artifactId>
+          <groupId>org.apache.hadoop</groupId>
+        </exclusion>
+        <exclusion>
+          <artifactId>hadoop-mapreduce-client-jobclient</artifactId>
+          <groupId>org.apache.hadoop</groupId>
+        </exclusion>
+        <exclusion>
+          <artifactId>hadoop-annotations</artifactId>
+          <groupId>org.apache.hadoop</groupId>
+        </exclusion>
+      </exclusions>
+    </dependency>
+    <dependency>
+      <groupId>org.apache.hadoop</groupId>
+      <artifactId>hadoop-common</artifactId>
+      <version>3.4.0</version>
+      <scope>provided</scope>
+      <exclusions>
+        <exclusion>
+          <artifactId>hadoop-shaded-protobuf_3_21</artifactId>
+          <groupId>org.apache.hadoop.thirdparty</groupId>
+        </exclusion>
+        <exclusion>
+          <artifactId>hadoop-shaded-guava</artifactId>
+          <groupId>org.apache.hadoop.thirdparty</groupId>
+        </exclusion>
+        <exclusion>
+          <artifactId>commons-cli</artifactId>
+          <groupId>commons-cli</groupId>
+        </exclusion>
+        <exclusion>
+          <artifactId>commons-math3</artifactId>
+          <groupId>org.apache.commons</groupId>
+        </exclusion>
+        <exclusion>
+          <artifactId>commons-io</artifactId>
+          <groupId>commons-io</groupId>
+        </exclusion>
+        <exclusion>
+          <artifactId>commons-net</artifactId>
+          <groupId>commons-net</groupId>
+        </exclusion>
+        <exclusion>
+          <artifactId>commons-collections</artifactId>
+          <groupId>commons-collections</groupId>
+        </exclusion>
+        <exclusion>
+          <artifactId>javax.servlet-api</artifactId>
+          <groupId>javax.servlet</groupId>
+        </exclusion>
+        <exclusion>
+          <artifactId>jakarta.activation-api</artifactId>
+          <groupId>jakarta.activation</groupId>
+        </exclusion>
+        <exclusion>
+          <artifactId>jetty-server</artifactId>
+          <groupId>org.eclipse.jetty</groupId>
+        </exclusion>
+        <exclusion>
+          <artifactId>jetty-util</artifactId>
+          <groupId>org.eclipse.jetty</groupId>
+        </exclusion>
+        <exclusion>
+          <artifactId>jetty-servlet</artifactId>
+          <groupId>org.eclipse.jetty</groupId>
+        </exclusion>
+        <exclusion>
+          <artifactId>jetty-webapp</artifactId>
+          <groupId>org.eclipse.jetty</groupId>
+        </exclusion>
+        <exclusion>
+          <artifactId>jsp-api</artifactId>
+          <groupId>javax.servlet.jsp</groupId>
+        </exclusion>
+        <exclusion>
+          <artifactId>jersey-core</artifactId>
+          <groupId>com.sun.jersey</groupId>
+        </exclusion>
+        <exclusion>
+          <artifactId>jersey-servlet</artifactId>
+          <groupId>com.sun.jersey</groupId>
+        </exclusion>
+        <exclusion>
+          <artifactId>jersey-json</artifactId>
+          <groupId>com.github.pjfanning</groupId>
+        </exclusion>
+        <exclusion>
+          <artifactId>jettison</artifactId>
+          <groupId>org.codehaus.jettison</groupId>
+        </exclusion>
+        <exclusion>
+          <artifactId>jersey-server</artifactId>
+          <groupId>com.sun.jersey</groupId>
+        </exclusion>
+        <exclusion>
+          <artifactId>reload4j</artifactId>
+          <groupId>ch.qos.reload4j</groupId>
+        </exclusion>
+        <exclusion>
+          <artifactId>commons-beanutils</artifactId>
+          <groupId>commons-beanutils</groupId>
+        </exclusion>
+        <exclusion>
+          <artifactId>commons-configuration2</artifactId>
+          <groupId>org.apache.commons</groupId>
+        </exclusion>
+        <exclusion>
+          <artifactId>commons-lang3</artifactId>
+          <groupId>org.apache.commons</groupId>
+        </exclusion>
+        <exclusion>
+          <artifactId>commons-text</artifactId>
+          <groupId>org.apache.commons</groupId>
+        </exclusion>
+        <exclusion>
+          <artifactId>slf4j-reload4j</artifactId>
+          <groupId>org.slf4j</groupId>
+        </exclusion>
+        <exclusion>
+          <artifactId>avro</artifactId>
+          <groupId>org.apache.avro</groupId>
+        </exclusion>
+        <exclusion>
+          <artifactId>re2j</artifactId>
+          <groupId>com.google.re2j</groupId>
+        </exclusion>
+        <exclusion>
+          <artifactId>hadoop-auth</artifactId>
+          <groupId>org.apache.hadoop</groupId>
+        </exclusion>
+        <exclusion>
+          <artifactId>jsch</artifactId>
+          <groupId>com.jcraft</groupId>
+        </exclusion>
+        <exclusion>
+          <artifactId>curator-client</artifactId>
+          <groupId>org.apache.curator</groupId>
+        </exclusion>
+        <exclusion>
+          <artifactId>curator-recipes</artifactId>
+          <groupId>org.apache.curator</groupId>
+        </exclusion>
+        <exclusion>
+          <artifactId>zookeeper</artifactId>
+          <groupId>org.apache.zookeeper</groupId>
+        </exclusion>
+        <exclusion>
+          <artifactId>netty-handler</artifactId>
+          <groupId>io.netty</groupId>
+        </exclusion>
+        <exclusion>
+          <artifactId>netty-transport-native-epoll</artifactId>
+          <groupId>io.netty</groupId>
+        </exclusion>
+        <exclusion>
+          <artifactId>metrics-core</artifactId>
+          <groupId>io.dropwizard.metrics</groupId>
+        </exclusion>
+        <exclusion>
+          <artifactId>commons-compress</artifactId>
+          <groupId>org.apache.commons</groupId>
+        </exclusion>
+        <exclusion>
+          <artifactId>bcprov-jdk15on</artifactId>
+          <groupId>org.bouncycastle</groupId>
+        </exclusion>
+        <exclusion>
+          <artifactId>kerb-core</artifactId>
+          <groupId>org.apache.kerby</groupId>
+        </exclusion>
+        <exclusion>
+          <artifactId>jackson-databind</artifactId>
+          <groupId>com.fasterxml.jackson.core</groupId>
+        </exclusion>
+        <exclusion>
+          <artifactId>stax2-api</artifactId>
+          <groupId>org.codehaus.woodstox</groupId>
+        </exclusion>
+        <exclusion>
+          <artifactId>woodstox-core</artifactId>
+          <groupId>com.fasterxml.woodstox</groupId>
+        </exclusion>
+        <exclusion>
+          <artifactId>dnsjava</artifactId>
+          <groupId>dnsjava</groupId>
+        </exclusion>
+        <exclusion>
+          <artifactId>snappy-java</artifactId>
+          <groupId>org.xerial.snappy</groupId>
+        </exclusion>
+        <exclusion>
+          <artifactId>hadoop-annotations</artifactId>
+          <groupId>org.apache.hadoop</groupId>
+        </exclusion>
+      </exclusions>
+    </dependency>
+    <dependency>
+      <groupId>junit</groupId>
+      <artifactId>junit</artifactId>
+      <version>4.13.1</version>
+      <scope>test</scope>
+      <exclusions>
+        <exclusion>
+          <artifactId>hamcrest-core</artifactId>
+          <groupId>org.hamcrest</groupId>
+        </exclusion>
+      </exclusions>
+    </dependency>
+    <dependency>
+      <groupId>org.mockito</groupId>
+      <artifactId>mockito-core</artifactId>
+      <version>3.12.4</version>
+      <scope>test</scope>
+      <exclusions>
+        <exclusion>
+          <artifactId>byte-buddy</artifactId>
+          <groupId>net.bytebuddy</groupId>
+        </exclusion>
+        <exclusion>
+          <artifactId>byte-buddy-agent</artifactId>
+          <groupId>net.bytebuddy</groupId>
+        </exclusion>
+        <exclusion>
+          <artifactId>objenesis</artifactId>
+          <groupId>org.objenesis</groupId>
+        </exclusion>
+      </exclusions>
+    </dependency>
+    <dependency>
+      <groupId>org.apache.hadoop</groupId>
+      <artifactId>hadoop-common</artifactId>
+      <version>3.4.0</version>
+      <type>test-jar</type>
+      <scope>test</scope>
+      <exclusions>
+        <exclusion>
+          <artifactId>hadoop-shaded-protobuf_3_21</artifactId>
+          <groupId>org.apache.hadoop.thirdparty</groupId>
+        </exclusion>
+        <exclusion>
+          <artifactId>hadoop-shaded-guava</artifactId>
+          <groupId>org.apache.hadoop.thirdparty</groupId>
+        </exclusion>
+        <exclusion>
+          <artifactId>commons-cli</artifactId>
+          <groupId>commons-cli</groupId>
+        </exclusion>
+        <exclusion>
+          <artifactId>commons-math3</artifactId>
+          <groupId>org.apache.commons</groupId>
+        </exclusion>
+        <exclusion>
+          <artifactId>commons-io</artifactId>
+          <groupId>commons-io</groupId>
+        </exclusion>
+        <exclusion>
+          <artifactId>commons-net</artifactId>
+          <groupId>commons-net</groupId>
+        </exclusion>
+        <exclusion>
+          <artifactId>commons-collections</artifactId>
+          <groupId>commons-collections</groupId>
+        </exclusion>
+        <exclusion>
+          <artifactId>javax.servlet-api</artifactId>
+          <groupId>javax.servlet</groupId>
+        </exclusion>
+        <exclusion>
+          <artifactId>jakarta.activation-api</artifactId>
+          <groupId>jakarta.activation</groupId>
+        </exclusion>
+        <exclusion>
+          <artifactId>jetty-server</artifactId>
+          <groupId>org.eclipse.jetty</groupId>
+        </exclusion>
+        <exclusion>
+          <artifactId>jetty-util</artifactId>
+          <groupId>org.eclipse.jetty</groupId>
+        </exclusion>
+        <exclusion>
+          <artifactId>jetty-servlet</artifactId>
+          <groupId>org.eclipse.jetty</groupId>
+        </exclusion>
+        <exclusion>
+          <artifactId>jetty-webapp</artifactId>
+          <groupId>org.eclipse.jetty</groupId>
+        </exclusion>
+        <exclusion>
+          <artifactId>jsp-api</artifactId>
+          <groupId>javax.servlet.jsp</groupId>
+        </exclusion>
+        <exclusion>
+          <artifactId>jersey-core</artifactId>
+          <groupId>com.sun.jersey</groupId>
+        </exclusion>
+        <exclusion>
+          <artifactId>jersey-servlet</artifactId>
+          <groupId>com.sun.jersey</groupId>
+        </exclusion>
+        <exclusion>
+          <artifactId>jersey-json</artifactId>
+          <groupId>com.github.pjfanning</groupId>
+        </exclusion>
+        <exclusion>
+          <artifactId>jettison</artifactId>
+          <groupId>org.codehaus.jettison</groupId>
+        </exclusion>
+        <exclusion>
+          <artifactId>jersey-server</artifactId>
+          <groupId>com.sun.jersey</groupId>
+        </exclusion>
+        <exclusion>
+          <artifactId>reload4j</artifactId>
+          <groupId>ch.qos.reload4j</groupId>
+        </exclusion>
+        <exclusion>
+          <artifactId>commons-beanutils</artifactId>
+          <groupId>commons-beanutils</groupId>
+        </exclusion>
+        <exclusion>
+          <artifactId>commons-configuration2</artifactId>
+          <groupId>org.apache.commons</groupId>
+        </exclusion>
+        <exclusion>
+          <artifactId>commons-lang3</artifactId>
+          <groupId>org.apache.commons</groupId>
+        </exclusion>
+        <exclusion>
+          <artifactId>commons-text</artifactId>
+          <groupId>org.apache.commons</groupId>
+        </exclusion>
+        <exclusion>
+          <artifactId>slf4j-reload4j</artifactId>
+          <groupId>org.slf4j</groupId>
+        </exclusion>
+        <exclusion>
+          <artifactId>avro</artifactId>
+          <groupId>org.apache.avro</groupId>
+        </exclusion>
+        <exclusion>
+          <artifactId>re2j</artifactId>
+          <groupId>com.google.re2j</groupId>
+        </exclusion>
+        <exclusion>
+          <artifactId>hadoop-auth</artifactId>
+          <groupId>org.apache.hadoop</groupId>
+        </exclusion>
+        <exclusion>
+          <artifactId>jsch</artifactId>
+          <groupId>com.jcraft</groupId>
+        </exclusion>
+        <exclusion>
+          <artifactId>curator-client</artifactId>
+          <groupId>org.apache.curator</groupId>
+        </exclusion>
+        <exclusion>
+          <artifactId>curator-recipes</artifactId>
+          <groupId>org.apache.curator</groupId>
+        </exclusion>
+        <exclusion>
+          <artifactId>zookeeper</artifactId>
+          <groupId>org.apache.zookeeper</groupId>
+        </exclusion>
+        <exclusion>
+          <artifactId>netty-handler</artifactId>
+          <groupId>io.netty</groupId>
+        </exclusion>
+        <exclusion>
+          <artifactId>netty-transport-native-epoll</artifactId>
+          <groupId>io.netty</groupId>
+        </exclusion>
+        <exclusion>
+          <artifactId>metrics-core</artifactId>
+          <groupId>io.dropwizard.metrics</groupId>
+        </exclusion>
+        <exclusion>
+          <artifactId>commons-compress</artifactId>
+          <groupId>org.apache.commons</groupId>
+        </exclusion>
+        <exclusion>
+          <artifactId>bcprov-jdk15on</artifactId>
+          <groupId>org.bouncycastle</groupId>
+        </exclusion>
+        <exclusion>
+          <artifactId>kerb-core</artifactId>
+          <groupId>org.apache.kerby</groupId>
+        </exclusion>
+        <exclusion>
+          <artifactId>jackson-databind</artifactId>
+          <groupId>com.fasterxml.jackson.core</groupId>
+        </exclusion>
+        <exclusion>
+          <artifactId>stax2-api</artifactId>
+          <groupId>org.codehaus.woodstox</groupId>
+        </exclusion>
+        <exclusion>
+          <artifactId>woodstox-core</artifactId>
+          <groupId>com.fasterxml.woodstox</groupId>
+        </exclusion>
+        <exclusion>
+          <artifactId>dnsjava</artifactId>
+          <groupId>dnsjava</groupId>
+        </exclusion>
+        <exclusion>
+          <artifactId>snappy-java</artifactId>
+          <groupId>org.xerial.snappy</groupId>
+        </exclusion>
+        <exclusion>
+          <artifactId>hadoop-annotations</artifactId>
+          <groupId>org.apache.hadoop</groupId>
+        </exclusion>
+      </exclusions>
+    </dependency>
+  </dependencies>
+  <properties>
+    <seaweedfs.client.version>4.00</seaweedfs.client.version>
+    <hadoop.version>3.4.0</hadoop.version>
+  </properties>
+</project>

other/java/hdfs3/pom.xml

@@ -0,0 +1,195 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project xmlns="http://maven.apache.org/POM/4.0.0"
+         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
+    <modelVersion>4.0.0</modelVersion>
+
+    <properties>
+        <seaweedfs.client.version>4.38</seaweedfs.client.version>
+        <hadoop.version>3.4.0</hadoop.version>
+    </properties>
+
+    <groupId>com.seaweedfs</groupId>
+    <artifactId>seaweedfs-hadoop3-client</artifactId>
+    <version>${seaweedfs.client.version}</version>
+
+    <name>SeaweedFS HDFS3 Client</name>
+    <description>A java client for SeaweedFS.</description>
+    <url>https://github.com/seaweedfs/seaweedfs</url>
+    <licenses>
+        <license>
+            <name>The Apache License, Version 2.0</name>
+            <url>http://www.apache.org/licenses/LICENSE-2.0.txt</url>
+        </license>
+    </licenses>
+    <developers>
+        <developer>
+            <name>Chris Lu</name>
+            <email>chris.lu@gmail.com</email>
+            <organization>SeaweedFS</organization>
+            <organizationUrl>https://seaweedfs.com</organizationUrl>
+        </developer>
+    </developers>
+    <scm>
+        <connection>scm:git:git://github.com/seaweedfs/seaweedfs.git</connection>
+        <developerConnection>scm:git:ssh://github.com:seaweedfs/seaweedfs.git</developerConnection>
+        <url>https://github.com/seaweedfs/seaweedfs/tree/master</url>
+    </scm>
+
+    <build>
+        <plugins>
+            <plugin>
+                <groupId>org.apache.maven.plugins</groupId>
+                <artifactId>maven-compiler-plugin</artifactId>
+                <configuration>
+                    <source>8</source>
+                    <target>8</target>
+                    <release>8</release>
+                </configuration>
+            </plugin>
+            <plugin>
+                <groupId>org.apache.maven.plugins</groupId>
+                <artifactId>maven-shade-plugin</artifactId>
+                <version>3.2.1</version>
+                <executions>
+                    <execution>
+                        <phase>package</phase>
+                        <goals>
+                            <goal>shade</goal>
+                        </goals>
+                        <configuration>
+                            <filters>
+                                <filter>
+                                    <artifact>*:*</artifact>
+                                    <excludes>
+                                        <exclude>META-INF/*.SF</exclude>
+                                        <exclude>META-INF/*.DSA</exclude>
+                                        <exclude>META-INF/*.RSA</exclude>
+                                        <exclude>org/slf4j/**</exclude>
+                                        <exclude>META-INF/maven/org.slf4j/**</exclude>
+                                    </excludes>
+                                </filter>
+                            </filters>
+                            <transformers>
+                                <transformer
+                                        implementation="org.apache.maven.plugins.shade.resource.ServicesResourceTransformer"/>
+                            </transformers>
+                            <relocations>
+                                <relocation>
+                                    <pattern>com.google</pattern>
+                                    <shadedPattern>shaded.com.google</shadedPattern>
+                                </relocation>
+                                <relocation>
+                                    <pattern>io.grpc.internal</pattern>
+                                    <shadedPattern>shaded.io.grpc.internal</shadedPattern>
+                                </relocation>
+                                <relocation>
+                                    <pattern>org.apache.commons</pattern>
+                                    <shadedPattern>shaded.org.apache.commons</shadedPattern>
+                                    <excludes>
+                                        <exclude>org.apache.hadoop</exclude>
+                                        <exclude>org.apache.log4j</exclude>
+                                    </excludes>
+                                </relocation>
+                                <relocation>
+                                    <pattern>org.apache.http</pattern>
+                                    <shadedPattern>shaded.org.apache.http</shadedPattern>
+                                </relocation>
+                            </relocations>
+                        </configuration>
+                    </execution>
+                </executions>
+            </plugin>
+            <plugin>
+                <groupId>org.apache.maven.plugins</groupId>
+                <artifactId>maven-gpg-plugin</artifactId>
+                <version>3.2.4</version>
+                <executions>
+                    <execution>
+                        <id>sign-artifacts</id>
+                        <phase>verify</phase>
+                        <goals>
+                            <goal>sign</goal>
+                        </goals>
+                    </execution>
+                </executions>
+            </plugin>
+            <plugin>
+                <groupId>org.sonatype.central</groupId>
+                <artifactId>central-publishing-maven-plugin</artifactId>
+                <version>0.5.0</version>
+                <extensions>true</extensions>
+                <configuration>
+                    <publishingServerId>central</publishingServerId>
+                    <autoPublish>true</autoPublish>
+                </configuration>
+            </plugin>
+            <plugin>
+                <groupId>org.apache.maven.plugins</groupId>
+                <artifactId>maven-source-plugin</artifactId>
+                <version>2.2.1</version>
+                <executions>
+                    <execution>
+                        <id>attach-sources</id>
+                        <goals>
+                            <goal>jar-no-fork</goal>
+                        </goals>
+                    </execution>
+                </executions>
+            </plugin>
+            <plugin>
+                <groupId>org.apache.maven.plugins</groupId>
+                <artifactId>maven-javadoc-plugin</artifactId>
+                <version>3.0.1</version>
+                <executions>
+                    <execution>
+                        <id>attach-javadocs</id>
+                        <goals>
+                            <goal>jar</goal>
+                        </goals>
+                    </execution>
+                </executions>
+            </plugin>
+        </plugins>
+    </build>
+
+    <dependencies>
+        <dependency>
+            <groupId>org.apache.hadoop</groupId>
+            <artifactId>hadoop-client</artifactId>
+            <version>${hadoop.version}</version>
+            <scope>provided</scope>
+        </dependency>
+        <dependency>
+            <groupId>com.seaweedfs</groupId>
+            <artifactId>seaweedfs-client</artifactId>
+            <version>${seaweedfs.client.version}</version>
+        </dependency>
+        <dependency>
+            <groupId>org.apache.hadoop</groupId>
+            <artifactId>hadoop-common</artifactId>
+            <version>${hadoop.version}</version>
+            <scope>provided</scope>
+        </dependency>
+        <dependency>
+            <groupId>junit</groupId>
+            <artifactId>junit</artifactId>
+            <version>4.13.1</version>
+            <scope>test</scope>
+        </dependency>
+        <dependency>
+            <groupId>org.mockito</groupId>
+            <artifactId>mockito-core</artifactId>
+            <version>3.12.4</version>
+            <scope>test</scope>
+        </dependency>
+        <dependency>
+            <groupId>org.apache.hadoop</groupId>
+            <artifactId>hadoop-common</artifactId>
+            <version>${hadoop.version}</version>
+            <scope>test</scope>
+            <type>test-jar</type>
+        </dependency>
+    </dependencies>
+
+</project>

other/java/hdfs3/src/main/java/seaweed/hdfs/BufferedByteBufferReadableInputStream.java

@@ -0,0 +1,25 @@
+package seaweed.hdfs;
+
+import org.apache.hadoop.fs.*;
+
+import java.io.IOException;
+import java.nio.ByteBuffer;
+
+public class BufferedByteBufferReadableInputStream extends BufferedFSInputStream implements ByteBufferReadable {
+
+    public BufferedByteBufferReadableInputStream(FSInputStream in, int size) {
+        super(in, size);
+        if (!(in instanceof Seekable) || !(in instanceof PositionedReadable)) {
+            throw new IllegalArgumentException("In is not an instance of Seekable or PositionedReadable");
+        }
+    }
+
+    @Override
+    public int read(ByteBuffer buf) throws IOException {
+        if (this.in instanceof ByteBufferReadable) {
+            return ((ByteBufferReadable)this.in).read(buf);
+        } else {
+            throw new UnsupportedOperationException("Byte-buffer read unsupported by input stream");
+        }
+    }
+}

other/java/hdfs3/src/main/java/seaweed/hdfs/SeaweedAbstractFileSystem.java

@@ -0,0 +1,35 @@
+/**
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package seaweed.hdfs;
+
+import org.apache.hadoop.conf.Configuration;
+import org.apache.hadoop.fs.DelegateToFileSystem;
+
+import java.io.IOException;
+import java.net.URI;
+import java.net.URISyntaxException;
+
+public class SeaweedAbstractFileSystem extends DelegateToFileSystem {
+
+    SeaweedAbstractFileSystem(final URI uri, final Configuration conf)
+            throws IOException, URISyntaxException {
+        super(uri, new SeaweedFileSystem(), conf, "seaweedfs", false);
+    }
+
+}

other/java/hdfs3/src/main/java/seaweed/hdfs/SeaweedFileSystem.java

@@ -0,0 +1,651 @@
+package seaweed.hdfs;
+
+import org.apache.hadoop.conf.Configuration;
+import org.apache.hadoop.fs.*;
+import org.apache.hadoop.fs.permission.AclEntry;
+import org.apache.hadoop.fs.permission.AclStatus;
+import org.apache.hadoop.fs.permission.FsPermission;
+import org.apache.hadoop.security.UserGroupInformation;
+import org.apache.hadoop.util.Progressable;
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+import seaweedfs.client.FilerProto;
+
+import java.io.FileNotFoundException;
+import java.io.IOException;
+import java.io.OutputStream;
+import java.net.URI;
+import java.util.EnumSet;
+import java.util.List;
+import java.util.Map;
+
+public class SeaweedFileSystem extends FileSystem {
+
+    public static final String FS_SEAWEED_FILER_HOST = "fs.seaweed.filer.host";
+    public static final String FS_SEAWEED_FILER_PORT = "fs.seaweed.filer.port";
+    public static final String FS_SEAWEED_FILER_PORT_GRPC = "fs.seaweed.filer.port.grpc";
+    public static final int FS_SEAWEED_DEFAULT_PORT = 8888;
+    public static final String FS_SEAWEED_BUFFER_SIZE = "fs.seaweed.buffer.size";
+    public static final String FS_SEAWEED_REPLICATION = "fs.seaweed.replication";
+    public static final String FS_SEAWEED_VOLUME_SERVER_ACCESS = "fs.seaweed.volume.server.access";
+    public static final int FS_SEAWEED_DEFAULT_BUFFER_SIZE = 4 * 1024 * 1024;
+    public static final String FS_SEAWEED_FILER_CN = "fs.seaweed.filer.cn";
+
+    private static final Logger LOG = LoggerFactory.getLogger(SeaweedFileSystem.class);
+
+    private URI uri;
+    private Path workingDirectory = new Path("/");
+    private SeaweedFileSystemStore seaweedFileSystemStore;
+
+    public URI getUri() {
+        return uri;
+    }
+
+    public String getScheme() {
+        return "seaweedfs";
+    }
+
+    @Override
+    public void initialize(URI uri, Configuration conf) throws IOException { // get
+        super.initialize(uri, conf);
+
+        // get host information from uri (overrides info in conf)
+        String host = uri.getHost();
+        host = (host == null) ? conf.get(FS_SEAWEED_FILER_HOST, "localhost") : host;
+        conf.set(FS_SEAWEED_FILER_HOST, host);
+
+        // get port information from uri, (overrides info in conf)
+        int port = uri.getPort();
+        port = (port == -1) ? FS_SEAWEED_DEFAULT_PORT : port;
+        conf.setInt(FS_SEAWEED_FILER_PORT, port);
+
+        int grpcPort = conf.getInt(FS_SEAWEED_FILER_PORT_GRPC, port + 10000);
+
+        setConf(conf);
+        this.uri = uri;
+
+        String cn = conf.get(FS_SEAWEED_FILER_CN, "");
+
+        seaweedFileSystemStore = new SeaweedFileSystemStore(host, port, grpcPort, cn, conf);
+    }
+
+    @Override
+    public void close() throws IOException {
+        super.close();
+        this.seaweedFileSystemStore.close();
+    }
+
+    @Override
+    public FSDataInputStream open(Path path, int bufferSize) throws IOException {
+
+        LOG.debug("open path: {} bufferSize:{}", path, bufferSize);
+
+        path = qualify(path);
+
+        try {
+            int seaweedBufferSize = this.getConf().getInt(FS_SEAWEED_BUFFER_SIZE, FS_SEAWEED_DEFAULT_BUFFER_SIZE);
+            FSInputStream inputStream = seaweedFileSystemStore.openFileForRead(path, statistics);
+
+            // Use BufferedFSInputStream for all streams (like RawLocalFileSystem)
+            // This ensures proper position tracking for positioned reads (critical for
+            // Parquet)
+            return new FSDataInputStream(new BufferedFSInputStream(inputStream, 4 * seaweedBufferSize));
+        } catch (Exception ex) {
+            LOG.error("Failed to open file: {} bufferSize:{}", path, bufferSize, ex);
+            throw new IOException("Failed to open file: " + path, ex);
+        }
+    }
+
+    @Override
+    public FSDataOutputStream create(Path path, FsPermission permission, final boolean overwrite, final int bufferSize,
+            final short replication, final long blockSize, final Progressable progress) throws IOException {
+
+        LOG.debug("create path: {} bufferSize:{} blockSize:{}", path, bufferSize, blockSize);
+
+        path = qualify(path);
+        final Path finalPath = path; // For use in anonymous inner class
+
+        try {
+            // Priority: 1) non-empty FS_SEAWEED_REPLICATION, 2) empty string -> filer
+            // default, 3) null -> HDFS replication
+            String replicaPlacement = this.getConf().get(FS_SEAWEED_REPLICATION);
+            if (replicaPlacement == null) {
+                // Not configured, use HDFS replication parameter. This creates a "00N"
+                // replication string,
+                // placing N (replication-1) extra replicas on different servers in the same
+                // rack.
+                replicaPlacement = String.format("%03d", replication - 1);
+            }
+            int seaweedBufferSize = this.getConf().getInt(FS_SEAWEED_BUFFER_SIZE, FS_SEAWEED_DEFAULT_BUFFER_SIZE);
+            OutputStream outputStream = seaweedFileSystemStore.createFile(path,
+                    overwrite, permission,
+                    seaweedBufferSize, replicaPlacement);
+            return new FSDataOutputStream(outputStream, statistics);
+        } catch (Exception ex) {
+            LOG.error("Failed to create file: {} bufferSize:{} blockSize:{}", path, bufferSize, blockSize, ex);
+            throw new IOException("Failed to create file: " + path, ex);
+        }
+    }
+
+    /**
+     * {@inheritDoc}
+     *
+     * @throws FileNotFoundException if the parent directory is not present -or
+     *                               is not a directory.
+     */
+    @Override
+    public FSDataOutputStream createNonRecursive(Path path,
+            FsPermission permission,
+            EnumSet<CreateFlag> flags,
+            int bufferSize,
+            short replication,
+            long blockSize,
+            Progressable progress) throws IOException {
+        Path parent = path.getParent();
+        if (parent != null) {
+            // expect this to raise an exception if there is no parent
+            if (!getFileStatus(parent).isDirectory()) {
+                throw new FileAlreadyExistsException("Not a directory: " + parent);
+            }
+        }
+        int seaweedBufferSize = this.getConf().getInt(FS_SEAWEED_BUFFER_SIZE, FS_SEAWEED_DEFAULT_BUFFER_SIZE);
+        return create(path, permission,
+                flags.contains(CreateFlag.OVERWRITE), bufferSize,
+                replication, seaweedBufferSize, progress);
+    }
+
+    @Override
+    public FSDataOutputStream append(Path path, int bufferSize, Progressable progressable) throws IOException {
+
+        LOG.debug("append path: {} bufferSize:{}", path, bufferSize);
+
+        path = qualify(path);
+        final Path finalPath = path; // For use in anonymous inner class
+        try {
+            int seaweedBufferSize = this.getConf().getInt(FS_SEAWEED_BUFFER_SIZE, FS_SEAWEED_DEFAULT_BUFFER_SIZE);
+            SeaweedHadoopOutputStream outputStream = (SeaweedHadoopOutputStream) seaweedFileSystemStore.createFile(path,
+                    false, null, seaweedBufferSize, "");
+            return new FSDataOutputStream(outputStream, statistics);
+        } catch (Exception ex) {
+            LOG.error("Failed to append to file: {} bufferSize:{}", path, bufferSize, ex);
+            throw new IOException("Failed to append to file: " + path, ex);
+        }
+    }
+
+    @Override
+    public boolean rename(Path src, Path dst) throws IOException {
+
+        LOG.debug("rename path: {} => {}", src, dst);
+
+        if (src.isRoot()) {
+            return false;
+        }
+
+        if (src.equals(dst)) {
+            return true;
+        }
+        FilerProto.Entry entry = seaweedFileSystemStore.lookupEntry(dst);
+
+        Path adjustedDst = dst;
+
+        if (entry != null) {
+            FileStatus dstFileStatus = getFileStatus(dst);
+            String sourceFileName = src.getName();
+            if (!dstFileStatus.isDirectory()) {
+                return false;
+            }
+            adjustedDst = new Path(dst, sourceFileName);
+        }
+
+        Path qualifiedSrcPath = qualify(src);
+        Path qualifiedDstPath = qualify(adjustedDst);
+
+        seaweedFileSystemStore.rename(qualifiedSrcPath, qualifiedDstPath);
+        return true;
+    }
+
+    @Override
+    public boolean delete(Path path, boolean recursive) throws IOException {
+
+        LOG.debug("delete path: {} recursive:{}", path, recursive);
+
+        path = qualify(path);
+
+        FilerProto.Entry entry = seaweedFileSystemStore.lookupEntry(path);
+
+        if (entry == null) {
+            return true;
+        }
+
+        FileStatus fileStatus = getFileStatus(path);
+
+        return seaweedFileSystemStore.deleteEntries(path, fileStatus.isDirectory(), recursive);
+
+    }
+
+    @Override
+    public FileStatus[] listStatus(Path path) throws IOException {
+
+        LOG.debug("listStatus path: {}", path);
+
+        path = qualify(path);
+
+        return seaweedFileSystemStore.listEntries(path);
+    }
+
+    @Override
+    public Path getWorkingDirectory() {
+        return workingDirectory;
+    }
+
+    @Override
+    public void setWorkingDirectory(Path path) {
+        if (path.isAbsolute()) {
+            workingDirectory = path;
+        } else {
+            workingDirectory = new Path(workingDirectory, path);
+        }
+    }
+
+    @Override
+    public boolean mkdirs(Path path, FsPermission fsPermission) throws IOException {
+
+        LOG.debug("mkdirs path: {}", path);
+
+        path = qualify(path);
+
+        FilerProto.Entry entry = seaweedFileSystemStore.lookupEntry(path);
+
+        if (entry == null) {
+
+            UserGroupInformation currentUser = UserGroupInformation.getCurrentUser();
+            return seaweedFileSystemStore.createDirectory(path, currentUser,
+                    fsPermission == null ? FsPermission.getDirDefault() : fsPermission,
+                    FsPermission.getUMask(getConf()));
+
+        }
+
+        FileStatus fileStatus = getFileStatus(path);
+
+        if (fileStatus.isDirectory()) {
+            return true;
+        } else {
+            throw new FileAlreadyExistsException("Path is a file: " + path);
+        }
+    }
+
+    @Override
+    public FileStatus getFileStatus(Path path) throws IOException {
+
+        LOG.debug("getFileStatus path: {}", path);
+
+        path = qualify(path);
+
+        return seaweedFileSystemStore.getFileStatus(path);
+    }
+
+    /**
+     * Set owner of a path (i.e. a file or a directory).
+     * The parameters owner and group cannot both be null.
+     *
+     * @param path  The path
+     * @param owner If it is null, the original username remains unchanged.
+     * @param group If it is null, the original groupname remains unchanged.
+     */
+    @Override
+    public void setOwner(Path path, final String owner, final String group)
+            throws IOException {
+        LOG.debug("setOwner path: {}", path);
+        path = qualify(path);
+
+        seaweedFileSystemStore.setOwner(path, owner, group);
+    }
+
+    /**
+     * Set permission of a path.
+     *
+     * @param path       The path
+     * @param permission Access permission
+     */
+    @Override
+    public void setPermission(Path path, final FsPermission permission) throws IOException {
+        LOG.debug("setPermission path: {}", path);
+
+        if (permission == null) {
+            throw new IllegalArgumentException("The permission can't be null");
+        }
+
+        path = qualify(path);
+
+        seaweedFileSystemStore.setPermission(path, permission);
+    }
+
+    Path qualify(Path path) {
+        return path.makeQualified(uri, workingDirectory);
+    }
+
+    /**
+     * Concat existing files together.
+     *
+     * @param trg   the path to the target destination.
+     * @param psrcs the paths to the sources to use for the concatenation.
+     * @throws IOException                   IO failure
+     * @throws UnsupportedOperationException if the operation is unsupported
+     *                                       (default).
+     */
+    @Override
+    public void concat(final Path trg, final Path[] psrcs) throws IOException {
+        throw new UnsupportedOperationException("Not implemented by the " +
+                getClass().getSimpleName() + " FileSystem implementation");
+    }
+
+    /**
+     * Truncate the file in the indicated path to the indicated size.
+     * <ul>
+     * <li>Fails if path is a directory.</li>
+     * <li>Fails if path does not exist.</li>
+     * <li>Fails if path is not closed.</li>
+     * <li>Fails if new size is greater than current size.</li>
+     * </ul>
+     *
+     * @param f         The path to the file to be truncated
+     * @param newLength The size the file is to be truncated to
+     * @return <code>true</code> if the file has been truncated to the desired
+     *         <code>newLength</code> and is immediately available to be reused for
+     *         write operations such as <code>append</code>, or
+     *         <code>false</code> if a background process of adjusting the length of
+     *         the last block has been started, and clients should wait for it to
+     *         complete before proceeding with further file updates.
+     * @throws IOException                   IO failure
+     * @throws UnsupportedOperationException if the operation is unsupported
+     *                                       (default).
+     */
+    @Override
+    public boolean truncate(Path f, long newLength) throws IOException {
+        throw new UnsupportedOperationException("Not implemented by the " +
+                getClass().getSimpleName() + " FileSystem implementation");
+    }
+
+    @Override
+    public void createSymlink(final Path target, final Path link,
+            final boolean createParent) throws IOException {
+        // Supporting filesystems should override this method
+        throw new UnsupportedOperationException(
+                "Filesystem does not support symlinks!");
+    }
+
+    public boolean supportsSymlinks() {
+        return false;
+    }
+
+    /**
+     * Create a snapshot.
+     *
+     * @param path         The directory where snapshots will be taken.
+     * @param snapshotName The name of the snapshot
+     * @return the snapshot path.
+     * @throws IOException                   IO failure
+     * @throws UnsupportedOperationException if the operation is unsupported
+     */
+    @Override
+    public Path createSnapshot(Path path, String snapshotName)
+            throws IOException {
+        throw new UnsupportedOperationException(getClass().getSimpleName()
+                + " doesn't support createSnapshot");
+    }
+
+    /**
+     * Rename a snapshot.
+     *
+     * @param path            The directory path where the snapshot was taken
+     * @param snapshotOldName Old name of the snapshot
+     * @param snapshotNewName New name of the snapshot
+     * @throws IOException                   IO failure
+     * @throws UnsupportedOperationException if the operation is unsupported
+     *                                       (default outcome).
+     */
+    @Override
+    public void renameSnapshot(Path path, String snapshotOldName,
+            String snapshotNewName) throws IOException {
+        throw new UnsupportedOperationException(getClass().getSimpleName()
+                + " doesn't support renameSnapshot");
+    }
+
+    /**
+     * Delete a snapshot of a directory.
+     *
+     * @param path         The directory that the to-be-deleted snapshot belongs to
+     * @param snapshotName The name of the snapshot
+     * @throws IOException                   IO failure
+     * @throws UnsupportedOperationException if the operation is unsupported
+     *                                       (default outcome).
+     */
+    @Override
+    public void deleteSnapshot(Path path, String snapshotName)
+            throws IOException {
+        throw new UnsupportedOperationException(getClass().getSimpleName()
+                + " doesn't support deleteSnapshot");
+    }
+
+    /**
+     * Modifies ACL entries of files and directories. This method can add new ACL
+     * entries or modify the permissions on existing ACL entries. All existing
+     * ACL entries that are not specified in this call are retained without
+     * changes. (Modifications are merged into the current ACL.)
+     *
+     * @param path    Path to modify
+     * @param aclSpec List&lt;AclEntry&gt; describing modifications
+     * @throws IOException                   if an ACL could not be modified
+     * @throws UnsupportedOperationException if the operation is unsupported
+     *                                       (default outcome).
+     */
+    @Override
+    public void modifyAclEntries(Path path, List<AclEntry> aclSpec)
+            throws IOException {
+        throw new UnsupportedOperationException(getClass().getSimpleName()
+                + " doesn't support modifyAclEntries");
+    }
+
+    /**
+     * Removes ACL entries from files and directories. Other ACL entries are
+     * retained.
+     *
+     * @param path    Path to modify
+     * @param aclSpec List describing entries to remove
+     * @throws IOException                   if an ACL could not be modified
+     * @throws UnsupportedOperationException if the operation is unsupported
+     *                                       (default outcome).
+     */
+    @Override
+    public void removeAclEntries(Path path, List<AclEntry> aclSpec)
+            throws IOException {
+        throw new UnsupportedOperationException(getClass().getSimpleName()
+                + " doesn't support removeAclEntries");
+    }
+
+    /**
+     * Removes all default ACL entries from files and directories.
+     *
+     * @param path Path to modify
+     * @throws IOException                   if an ACL could not be modified
+     * @throws UnsupportedOperationException if the operation is unsupported
+     *                                       (default outcome).
+     */
+    @Override
+    public void removeDefaultAcl(Path path)
+            throws IOException {
+        throw new UnsupportedOperationException(getClass().getSimpleName()
+                + " doesn't support removeDefaultAcl");
+    }
+
+    /**
+     * Removes all but the base ACL entries of files and directories. The entries
+     * for user, group, and others are retained for compatibility with permission
+     * bits.
+     *
+     * @param path Path to modify
+     * @throws IOException                   if an ACL could not be removed
+     * @throws UnsupportedOperationException if the operation is unsupported
+     *                                       (default outcome).
+     */
+    @Override
+    public void removeAcl(Path path)
+            throws IOException {
+        throw new UnsupportedOperationException(getClass().getSimpleName()
+                + " doesn't support removeAcl");
+    }
+
+    /**
+     * Fully replaces ACL of files and directories, discarding all existing
+     * entries.
+     *
+     * @param path    Path to modify
+     * @param aclSpec List describing modifications, which must include entries
+     *                for user, group, and others for compatibility with permission
+     *                bits.
+     * @throws IOException                   if an ACL could not be modified
+     * @throws UnsupportedOperationException if the operation is unsupported
+     *                                       (default outcome).
+     */
+    @Override
+    public void setAcl(Path path, List<AclEntry> aclSpec) throws IOException {
+        throw new UnsupportedOperationException(getClass().getSimpleName()
+                + " doesn't support setAcl");
+    }
+
+    /**
+     * Gets the ACL of a file or directory.
+     *
+     * @param path Path to get
+     * @return AclStatus describing the ACL of the file or directory
+     * @throws IOException                   if an ACL could not be read
+     * @throws UnsupportedOperationException if the operation is unsupported
+     *                                       (default outcome).
+     */
+    @Override
+    public AclStatus getAclStatus(Path path) throws IOException {
+        throw new UnsupportedOperationException(getClass().getSimpleName()
+                + " doesn't support getAclStatus");
+    }
+
+    /**
+     * Set an xattr of a file or directory.
+     * The name must be prefixed with the namespace followed by ".". For example,
+     * "user.attr".
+     * <p>
+     * Refer to the HDFS extended attributes user documentation for details.
+     *
+     * @param path  Path to modify
+     * @param name  xattr name.
+     * @param value xattr value.
+     * @param flag  xattr set flag
+     * @throws IOException                   IO failure
+     * @throws UnsupportedOperationException if the operation is unsupported
+     *                                       (default outcome).
+     */
+    @Override
+    public void setXAttr(Path path, String name, byte[] value,
+            EnumSet<XAttrSetFlag> flag) throws IOException {
+        throw new UnsupportedOperationException(getClass().getSimpleName()
+                + " doesn't support setXAttr");
+    }
+
+    /**
+     * Get an xattr name and value for a file or directory.
+     * The name must be prefixed with the namespace followed by ".". For example,
+     * "user.attr".
+     * <p>
+     * Refer to the HDFS extended attributes user documentation for details.
+     *
+     * @param path Path to get extended attribute
+     * @param name xattr name.
+     * @return byte[] xattr value.
+     * @throws IOException                   IO failure
+     * @throws UnsupportedOperationException if the operation is unsupported
+     *                                       (default outcome).
+     */
+    @Override
+    public byte[] getXAttr(Path path, String name) throws IOException {
+        throw new UnsupportedOperationException(getClass().getSimpleName()
+                + " doesn't support getXAttr");
+    }
+
+    /**
+     * Get all of the xattr name/value pairs for a file or directory.
+     * Only those xattrs which the logged-in user has permissions to view
+     * are returned.
+     * <p>
+     * Refer to the HDFS extended attributes user documentation for details.
+     *
+     * @param path Path to get extended attributes
+     * @return Map describing the XAttrs of the file or directory
+     * @throws IOException                   IO failure
+     * @throws UnsupportedOperationException if the operation is unsupported
+     *                                       (default outcome).
+     */
+    @Override
+    public Map<String, byte[]> getXAttrs(Path path) throws IOException {
+        throw new UnsupportedOperationException(getClass().getSimpleName()
+                + " doesn't support getXAttrs");
+    }
+
+    /**
+     * Get all of the xattrs name/value pairs for a file or directory.
+     * Only those xattrs which the logged-in user has permissions to view
+     * are returned.
+     * <p>
+     * Refer to the HDFS extended attributes user documentation for details.
+     *
+     * @param path  Path to get extended attributes
+     * @param names XAttr names.
+     * @return Map describing the XAttrs of the file or directory
+     * @throws IOException                   IO failure
+     * @throws UnsupportedOperationException if the operation is unsupported
+     *                                       (default outcome).
+     */
+    @Override
+    public Map<String, byte[]> getXAttrs(Path path, List<String> names)
+            throws IOException {
+        throw new UnsupportedOperationException(getClass().getSimpleName()
+                + " doesn't support getXAttrs");
+    }
+
+    /**
+     * Get all of the xattr names for a file or directory.
+     * Only those xattr names which the logged-in user has permissions to view
+     * are returned.
+     * <p>
+     * Refer to the HDFS extended attributes user documentation for details.
+     *
+     * @param path Path to get extended attributes
+     * @return List{@literal <String>} of the XAttr names of the file or directory
+     * @throws IOException                   IO failure
+     * @throws UnsupportedOperationException if the operation is unsupported
+     *                                       (default outcome).
+     */
+    @Override
+    public List<String> listXAttrs(Path path) throws IOException {
+        throw new UnsupportedOperationException(getClass().getSimpleName()
+                + " doesn't support listXAttrs");
+    }
+
+    /**
+     * Remove an xattr of a file or directory.
+     * The name must be prefixed with the namespace followed by ".". For example,
+     * "user.attr".
+     * <p>
+     * Refer to the HDFS extended attributes user documentation for details.
+     *
+     * @param path Path to remove extended attribute
+     * @param name xattr name
+     * @throws IOException                   IO failure
+     * @throws UnsupportedOperationException if the operation is unsupported
+     *                                       (default outcome).
+     */
+    @Override
+    public void removeXAttr(Path path, String name) throws IOException {
+        throw new UnsupportedOperationException(getClass().getSimpleName()
+                + " doesn't support removeXAttr");
+    }
+
+}

other/java/hdfs3/src/main/java/seaweed/hdfs/SeaweedFileSystemStore.java

@@ -0,0 +1,293 @@
+package seaweed.hdfs;
+
+import org.apache.hadoop.conf.Configuration;
+import org.apache.hadoop.fs.FSInputStream;
+import org.apache.hadoop.fs.FileStatus;
+import org.apache.hadoop.fs.FileSystem;
+import org.apache.hadoop.fs.Path;
+import org.apache.hadoop.fs.permission.FsPermission;
+import org.apache.hadoop.security.UserGroupInformation;
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+import seaweedfs.client.*;
+
+import java.io.FileNotFoundException;
+import java.io.IOException;
+import java.io.OutputStream;
+import java.util.ArrayList;
+import java.util.Arrays;
+import java.util.List;
+
+import static seaweed.hdfs.SeaweedFileSystem.*;
+
+public class SeaweedFileSystemStore {
+
+    private static final Logger LOG = LoggerFactory.getLogger(SeaweedFileSystemStore.class);
+
+    private FilerClient filerClient;
+    private Configuration conf;
+
+    public SeaweedFileSystemStore(String host, int port, int grpcPort, String cn, Configuration conf) {
+        filerClient = new FilerClient(host, port, grpcPort, cn);
+        this.conf = conf;
+        String volumeServerAccessMode = this.conf.get(FS_SEAWEED_VOLUME_SERVER_ACCESS, "direct");
+        if (volumeServerAccessMode.equals("publicUrl")) {
+            filerClient.setAccessVolumeServerByPublicUrl();
+        } else if (volumeServerAccessMode.equals("filerProxy")) {
+            filerClient.setAccessVolumeServerByFilerProxy();
+        }
+    }
+
+    public void close() {
+        try {
+            this.filerClient.shutdown();
+        } catch (InterruptedException e) {
+            e.printStackTrace();
+        }
+    }
+
+    public static String getParentDirectory(Path path) {
+        return path.isRoot() ? "/" : path.getParent().toUri().getPath();
+    }
+
+    static int permissionToMode(FsPermission permission, boolean isDirectory) {
+        int p = permission.toShort();
+        if (isDirectory) {
+            p = p | 1 << 31;
+        }
+        return p;
+    }
+
+    public boolean createDirectory(final Path path, UserGroupInformation currentUser,
+            final FsPermission permission, final FsPermission umask) {
+
+        LOG.debug("createDirectory path: {} permission: {} umask: {}",
+                path,
+                permission,
+                umask);
+
+        return filerClient.mkdirs(
+                path.toUri().getPath(),
+                permissionToMode(permission, true),
+                currentUser.getUserName(),
+                currentUser.getGroupNames());
+    }
+
+    public FileStatus[] listEntries(final Path path) throws IOException {
+        LOG.debug("listEntries path: {}", path);
+
+        FileStatus pathStatus = getFileStatus(path);
+
+        if (pathStatus == null) {
+            return new FileStatus[0];
+        }
+
+        if (!pathStatus.isDirectory()) {
+            return new FileStatus[] { pathStatus };
+        }
+
+        List<FileStatus> fileStatuses = new ArrayList<FileStatus>();
+
+        List<FilerProto.Entry> entries = filerClient.listEntries(path.toUri().getPath());
+
+        for (FilerProto.Entry entry : entries) {
+
+            FileStatus fileStatus = doGetFileStatus(new Path(path, entry.getName()), entry);
+
+            fileStatuses.add(fileStatus);
+        }
+        LOG.debug("listEntries path: {} size {}", fileStatuses, fileStatuses.size());
+        return fileStatuses.toArray(new FileStatus[0]);
+
+    }
+
+    public FileStatus getFileStatus(final Path path) throws IOException {
+
+        FilerProto.Entry entry = lookupEntry(path);
+        if (entry == null) {
+            throw new FileNotFoundException("File does not exist: " + path);
+        }
+        LOG.debug("doGetFileStatus path:{} entry:{}", path, entry);
+
+        FileStatus fileStatus = doGetFileStatus(path, entry);
+        return fileStatus;
+    }
+
+    public boolean deleteEntries(final Path path, boolean isDirectory, boolean recursive) {
+        LOG.debug("deleteEntries path: {} isDirectory {} recursive: {}",
+                path,
+                String.valueOf(isDirectory),
+                String.valueOf(recursive));
+
+        if (path.isRoot()) {
+            return true;
+        }
+
+        if (recursive && isDirectory) {
+            List<FilerProto.Entry> entries = filerClient.listEntries(path.toUri().getPath());
+            for (FilerProto.Entry entry : entries) {
+                deleteEntries(new Path(path, entry.getName()), entry.getIsDirectory(), true);
+            }
+        }
+
+        return filerClient.deleteEntry(getParentDirectory(path), path.getName(), true, recursive, true);
+    }
+
+    private FileStatus doGetFileStatus(Path path, FilerProto.Entry entry) {
+        FilerProto.FuseAttributes attributes = entry.getAttributes();
+        long length = SeaweedRead.fileSize(entry);
+        boolean isDir = entry.getIsDirectory();
+        int block_replication = 1;
+        int blocksize = this.conf.getInt(FS_SEAWEED_BUFFER_SIZE, FS_SEAWEED_DEFAULT_BUFFER_SIZE);
+        long modification_time = attributes.getMtime() * 1000; // milliseconds
+        long access_time = 0;
+        FsPermission permission = FsPermission.createImmutable((short) attributes.getFileMode());
+        String owner = attributes.getUserName();
+        String group = attributes.getGroupNameCount() > 0 ? attributes.getGroupName(0) : "";
+        return new FileStatus(length, isDir, block_replication, blocksize,
+                modification_time, access_time, permission, owner, group, null, path);
+    }
+
+    public FilerProto.Entry lookupEntry(Path path) {
+
+        return filerClient.lookupEntry(getParentDirectory(path), path.getName());
+
+    }
+
+    public void rename(Path source, Path destination) {
+
+        LOG.debug("rename source: {} destination:{}", source, destination);
+
+        if (source.isRoot()) {
+            return;
+        }
+
+        FilerProto.Entry entry = lookupEntry(source);
+        if (entry == null) {
+            LOG.warn("rename non-existing source: {}", source);
+            return;
+        }
+
+        filerClient.mv(source.toUri().getPath(), destination.toUri().getPath());
+    }
+
+    public OutputStream createFile(final Path path,
+            final boolean overwrite,
+            FsPermission permission,
+            int bufferSize,
+            String replication) throws IOException {
+
+        permission = permission == null ? FsPermission.getFileDefault() : permission;
+
+        
+        LOG.debug("createFile path: {} overwrite: {} permission: {}",
+                path,
+                overwrite,
+                permission.toString());
+
+        UserGroupInformation userGroupInformation = UserGroupInformation.getCurrentUser();
+        long now = System.currentTimeMillis() / 1000L;
+
+        FilerProto.Entry.Builder entry = null;
+        long writePosition = 0;
+        if (!overwrite) {
+            FilerProto.Entry existingEntry = lookupEntry(path);
+            LOG.debug("createFile merged entry path:{} existingEntry:{}", path, existingEntry);
+            if (existingEntry != null) {
+                entry = FilerProto.Entry.newBuilder();
+                entry.mergeFrom(existingEntry);
+                entry.clearContent();
+                entry.getAttributesBuilder().setMtime(now);
+                LOG.debug("createFile merged entry path:{} entry:{} from:{}", path, entry, existingEntry);
+                writePosition = SeaweedRead.fileSize(existingEntry);
+            }
+        }
+        if (entry == null) {
+            entry = FilerProto.Entry.newBuilder()
+                    .setName(path.getName())
+                    .setIsDirectory(false)
+                    .setAttributes(FilerProto.FuseAttributes.newBuilder()
+                            .setFileMode(permissionToMode(permission, false))
+                            .setCrtime(now)
+                            .setMtime(now)
+                            .setUserName(userGroupInformation.getUserName())
+                            .clearGroupName()
+                            .addAllGroupName(Arrays.asList(userGroupInformation.getGroupNames())));
+            SeaweedWrite.writeMeta(filerClient, getParentDirectory(path), entry);
+        }
+
+        
+        return new SeaweedHadoopOutputStream(filerClient, path.toString(), entry, writePosition, bufferSize,
+                replication);
+
+    }
+
+    public FSInputStream openFileForRead(final Path path, FileSystem.Statistics statistics) throws IOException {
+
+        LOG.debug("openFileForRead path:{}", path);
+
+        FilerProto.Entry entry = lookupEntry(path);
+
+        if (entry == null) {
+            throw new FileNotFoundException("read non-exist file " + path);
+        }
+
+        return new SeaweedHadoopInputStream(filerClient,
+                statistics,
+                path.toUri().getPath(),
+                entry);
+    }
+
+    public void setOwner(Path path, String owner, String group) {
+
+        LOG.debug("setOwner path:{} owner:{} group:{}", path, owner, group);
+
+        FilerProto.Entry entry = lookupEntry(path);
+        if (entry == null) {
+            LOG.debug("setOwner path:{} entry:{}", path, entry);
+            return;
+        }
+
+        FilerProto.Entry.Builder entryBuilder = entry.toBuilder();
+        FilerProto.FuseAttributes.Builder attributesBuilder = entry.getAttributes().toBuilder();
+
+        if (owner != null) {
+            attributesBuilder.setUserName(owner);
+        }
+        if (group != null) {
+            attributesBuilder.clearGroupName();
+            attributesBuilder.addGroupName(group);
+        }
+
+        entryBuilder.setAttributes(attributesBuilder);
+
+        LOG.debug("setOwner path:{} entry:{}", path, entryBuilder);
+
+        filerClient.updateEntry(getParentDirectory(path), entryBuilder.build());
+
+    }
+
+    public void setPermission(Path path, FsPermission permission) {
+
+        LOG.debug("setPermission path:{} permission:{}", path, permission);
+
+        FilerProto.Entry entry = lookupEntry(path);
+        if (entry == null) {
+            LOG.debug("setPermission path:{} entry:{}", path, entry);
+            return;
+        }
+
+        FilerProto.Entry.Builder entryBuilder = entry.toBuilder();
+        FilerProto.FuseAttributes.Builder attributesBuilder = entry.getAttributes().toBuilder();
+
+        attributesBuilder.setFileMode(permissionToMode(permission, entry.getIsDirectory()));
+
+        entryBuilder.setAttributes(attributesBuilder);
+
+        LOG.debug("setPermission path:{} entry:{}", path, entryBuilder);
+
+        filerClient.updateEntry(getParentDirectory(path), entryBuilder.build());
+
+    }
+
+}

other/java/hdfs3/src/main/java/seaweed/hdfs/SeaweedHadoopInputStream.java

@@ -0,0 +1,153 @@
+package seaweed.hdfs;
+
+// based on org.apache.hadoop.fs.azurebfs.services.AbfsInputStream
+
+import org.apache.hadoop.fs.FSInputStream;
+import org.apache.hadoop.fs.FileSystem.Statistics;
+import seaweedfs.client.FilerClient;
+import seaweedfs.client.FilerProto;
+import seaweedfs.client.SeaweedInputStream;
+
+import java.io.EOFException;
+import java.io.IOException;
+
+/**
+ * SeaweedFS Hadoop InputStream.
+ * 
+ * NOTE: Does NOT implement ByteBufferReadable to match RawLocalFileSystem
+ * behavior.
+ * This ensures BufferedFSInputStream is used, which properly handles position
+ * tracking
+ * for positioned reads (critical for Parquet and other formats).
+ */
+public class SeaweedHadoopInputStream extends FSInputStream {
+
+    private final SeaweedInputStream seaweedInputStream;
+    private final Statistics statistics;
+    private final String path;
+
+    public SeaweedHadoopInputStream(
+            final FilerClient filerClient,
+            final Statistics statistics,
+            final String path,
+            final FilerProto.Entry entry) throws IOException {
+        this.seaweedInputStream = new SeaweedInputStream(filerClient, path, entry);
+        this.statistics = statistics;
+        this.path = path;
+    }
+
+    @Override
+    public int read() throws IOException {
+        return seaweedInputStream.read();
+    }
+
+    @Override
+    public int read(final byte[] b, final int off, final int len) throws IOException {
+        return seaweedInputStream.read(b, off, len);
+    }
+
+    /**
+     * Seek to given position in stream.
+     *
+     * @param n position to seek to
+     * @throws IOException  if there is an error
+     * @throws EOFException if attempting to seek past end of file
+     */
+    @Override
+    public synchronized void seek(long n) throws IOException {
+        seaweedInputStream.seek(n);
+    }
+
+    @Override
+    public synchronized long skip(long n) throws IOException {
+        return seaweedInputStream.skip(n);
+    }
+
+    /**
+     * Return the size of the remaining available bytes
+     * if the size is less than or equal to {@link Integer#MAX_VALUE},
+     * otherwise, return {@link Integer#MAX_VALUE}.
+     * <p>
+     * This is to match the behavior of DFSInputStream.available(),
+     * which some clients may rely on (HBase write-ahead log reading in
+     * particular).
+     */
+    @Override
+    public synchronized int available() throws IOException {
+        return seaweedInputStream.available();
+    }
+
+    /**
+     * Returns the length of the file that this stream refers to. Note that the
+     * length returned is the length
+     * as of the time the Stream was opened. Specifically, if there have been
+     * subsequent appends to the file,
+     * they won't be reflected in the returned length.
+     *
+     * @return length of the file.
+     * @throws IOException if the stream is closed
+     */
+    public long length() throws IOException {
+        return seaweedInputStream.length();
+    }
+
+    /**
+     * Return the current offset from the start of the file
+     *
+     * @throws IOException throws {@link IOException} if there is an error
+     */
+    @Override
+    public synchronized long getPos() throws IOException {
+        return seaweedInputStream.getPos();
+    }
+
+    public String getPath() {
+        return path;
+    }
+
+    /**
+     * Seeks a different copy of the data. Returns true if
+     * found a new source, false otherwise.
+     *
+     * @throws IOException throws {@link IOException} if there is an error
+     */
+    @Override
+    public boolean seekToNewSource(long l) throws IOException {
+        return false;
+    }
+
+    @Override
+    public synchronized void close() throws IOException {
+        seaweedInputStream.close();
+    }
+
+    /**
+     * Not supported by this stream. Throws {@link UnsupportedOperationException}
+     *
+     * @param readlimit ignored
+     */
+    @Override
+    public synchronized void mark(int readlimit) {
+        throw new UnsupportedOperationException("mark()/reset() not supported on this stream");
+    }
+
+    /**
+     * Not supported by this stream. Throws {@link UnsupportedOperationException}
+     */
+    @Override
+    public synchronized void reset() throws IOException {
+        throw new UnsupportedOperationException("mark()/reset() not supported on this stream");
+    }
+
+    /**
+     * gets whether mark and reset are supported by
+     * {@code SeaweedHadoopInputStream}.
+     * Always returns false.
+     *
+     * @return always {@code false}
+     */
+    @Override
+    public boolean markSupported() {
+        return false;
+    }
+}

other/java/hdfs3/src/main/java/seaweed/hdfs/SeaweedHadoopOutputStream.java

@@ -0,0 +1,71 @@
+package seaweed.hdfs;
+
+// adapted from org.apache.hadoop.fs.azurebfs.services.AbfsOutputStream
+
+import org.apache.hadoop.fs.StreamCapabilities;
+import org.apache.hadoop.fs.Syncable;
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+import seaweedfs.client.FilerClient;
+import seaweedfs.client.FilerProto;
+import seaweedfs.client.SeaweedOutputStream;
+
+import java.io.IOException;
+import java.util.Locale;
+
+public class SeaweedHadoopOutputStream extends SeaweedOutputStream implements Syncable, StreamCapabilities {
+
+    private static final Logger LOG = LoggerFactory.getLogger(SeaweedHadoopOutputStream.class);
+
+    public SeaweedHadoopOutputStream(FilerClient filerClient, final String path, FilerProto.Entry.Builder entry,
+            final long position, final int bufferSize, final String replication) {
+        super(filerClient, path, entry, position, bufferSize, replication);
+
+    }
+
+    /**
+     * Similar to posix fsync, flush out the data in client's user buffer
+     * all the way to the disk device (but the disk may have it in its cache).
+     *
+     * @throws IOException if error occurs
+     */
+    @Override
+    public void hsync() throws IOException {
+
+        if (supportFlush) {
+            flushInternal();
+        }
+    }
+
+    /**
+     * Flush out the data in client's user buffer. After the return of
+     * this call, new readers will see the data.
+     *
+     * @throws IOException if any error occurs
+     */
+    @Override
+    public void hflush() throws IOException {
+
+        if (supportFlush) {
+            flushInternal();
+        }
+    }
+
+    /**
+     * Query the stream for a specific capability.
+     *
+     * @param capability string to query the stream support for.
+     * @return true for hsync and hflush.
+     */
+    @Override
+    public boolean hasCapability(String capability) {
+        switch (capability.toLowerCase(Locale.ENGLISH)) {
+            case StreamCapabilities.HSYNC:
+            case StreamCapabilities.HFLUSH:
+                return supportFlush;
+            default:
+                return false;
+        }
+    }
+
+}

other/java/hdfs3/src/test/java/seaweed/hdfs/SeaweedFileSystemConfigTest.java

@@ -0,0 +1,90 @@
+package seaweed.hdfs;
+
+import org.apache.hadoop.conf.Configuration;
+import org.apache.hadoop.fs.Path;
+import org.junit.Before;
+import org.junit.Test;
+
+import static org.junit.Assert.*;
+
+/**
+ * Unit tests for SeaweedFileSystem configuration that don't require a running SeaweedFS instance.
+ * 
+ * These tests verify basic properties and constants.
+ */
+public class SeaweedFileSystemConfigTest {
+
+    private SeaweedFileSystem fs;
+    private Configuration conf;
+
+    @Before
+    public void setUp() {
+        fs = new SeaweedFileSystem();
+        conf = new Configuration();
+    }
+
+    @Test
+    public void testScheme() {
+        assertEquals("seaweedfs", fs.getScheme());
+    }
+
+    @Test
+    public void testConstants() {
+        // Test that constants are defined correctly
+        assertEquals("fs.seaweed.filer.host", SeaweedFileSystem.FS_SEAWEED_FILER_HOST);
+        assertEquals("fs.seaweed.filer.port", SeaweedFileSystem.FS_SEAWEED_FILER_PORT);
+        assertEquals("fs.seaweed.filer.port.grpc", SeaweedFileSystem.FS_SEAWEED_FILER_PORT_GRPC);
+        assertEquals(8888, SeaweedFileSystem.FS_SEAWEED_DEFAULT_PORT);
+        assertEquals("fs.seaweed.buffer.size", SeaweedFileSystem.FS_SEAWEED_BUFFER_SIZE);
+        assertEquals(4 * 1024 * 1024, SeaweedFileSystem.FS_SEAWEED_DEFAULT_BUFFER_SIZE);
+        assertEquals("fs.seaweed.replication", SeaweedFileSystem.FS_SEAWEED_REPLICATION);
+        assertEquals("fs.seaweed.volume.server.access", SeaweedFileSystem.FS_SEAWEED_VOLUME_SERVER_ACCESS);
+        assertEquals("fs.seaweed.filer.cn", SeaweedFileSystem.FS_SEAWEED_FILER_CN);
+    }
+
+    @Test
+    public void testWorkingDirectoryPathOperations() {
+        // Test path operations that don't require initialization
+        Path testPath = new Path("/test/path");
+        assertTrue("Path should be absolute", testPath.isAbsolute());
+        assertEquals("/test/path", testPath.toUri().getPath());
+        
+        Path childPath = new Path(testPath, "child");
+        assertEquals("/test/path/child", childPath.toUri().getPath());
+    }
+
+    @Test
+    public void testConfigurationProperties() {
+        // Test that configuration can be set and read
+        conf.set(SeaweedFileSystem.FS_SEAWEED_FILER_HOST, "testhost");
+        assertEquals("testhost", conf.get(SeaweedFileSystem.FS_SEAWEED_FILER_HOST));
+        
+        conf.setInt(SeaweedFileSystem.FS_SEAWEED_FILER_PORT, 9999);
+        assertEquals(9999, conf.getInt(SeaweedFileSystem.FS_SEAWEED_FILER_PORT, 0));
+        
+        conf.setInt(SeaweedFileSystem.FS_SEAWEED_BUFFER_SIZE, 8 * 1024 * 1024);
+        assertEquals(8 * 1024 * 1024, conf.getInt(SeaweedFileSystem.FS_SEAWEED_BUFFER_SIZE, 0));
+        
+        conf.set(SeaweedFileSystem.FS_SEAWEED_REPLICATION, "001");
+        assertEquals("001", conf.get(SeaweedFileSystem.FS_SEAWEED_REPLICATION));
+        
+        conf.set(SeaweedFileSystem.FS_SEAWEED_VOLUME_SERVER_ACCESS, "publicUrl");
+        assertEquals("publicUrl", conf.get(SeaweedFileSystem.FS_SEAWEED_VOLUME_SERVER_ACCESS));
+        
+        conf.set(SeaweedFileSystem.FS_SEAWEED_FILER_CN, "test-cn");
+        assertEquals("test-cn", conf.get(SeaweedFileSystem.FS_SEAWEED_FILER_CN));
+    }
+
+    @Test
+    public void testDefaultBufferSize() {
+        // Test default buffer size constant
+        int expected = 4 * 1024 * 1024; // 4MB
+        assertEquals(expected, SeaweedFileSystem.FS_SEAWEED_DEFAULT_BUFFER_SIZE);
+    }
+
+    @Test
+    public void testDefaultPort() {
+        // Test default port constant
+        assertEquals(8888, SeaweedFileSystem.FS_SEAWEED_DEFAULT_PORT);
+    }
+}

other/java/hdfs3/src/test/java/seaweed/hdfs/SeaweedFileSystemTest.java

@@ -0,0 +1,379 @@
+package seaweed.hdfs;
+
+import org.apache.hadoop.conf.Configuration;
+import org.apache.hadoop.fs.FSDataInputStream;
+import org.apache.hadoop.fs.FSDataOutputStream;
+import org.apache.hadoop.fs.FileStatus;
+import org.apache.hadoop.fs.Path;
+import org.apache.hadoop.fs.permission.FsPermission;
+import org.junit.After;
+import org.junit.Before;
+import org.junit.Test;
+
+import java.io.IOException;
+import java.net.URI;
+
+import static org.junit.Assert.*;
+
+/**
+ * Unit tests for SeaweedFileSystem.
+ * 
+ * These tests verify basic FileSystem operations against a SeaweedFS backend.
+ * Note: These tests require a running SeaweedFS filer instance.
+ * 
+ * To run tests, ensure SeaweedFS is running with default ports:
+ * - Filer HTTP: 8888
+ * - Filer gRPC: 18888
+ * 
+ * Set environment variable SEAWEEDFS_TEST_ENABLED=true to enable these tests.
+ */
+public class SeaweedFileSystemTest {
+
+    private SeaweedFileSystem fs;
+    private Configuration conf;
+    private static final String TEST_ROOT = "/test-hdfs3";
+    private static final boolean TESTS_ENABLED = 
+        "true".equalsIgnoreCase(System.getenv("SEAWEEDFS_TEST_ENABLED"));
+
+    @Before
+    public void setUp() throws Exception {
+        if (!TESTS_ENABLED) {
+            return;
+        }
+        
+        conf = new Configuration();
+        conf.set("fs.seaweed.filer.host", "localhost");
+        conf.setInt("fs.seaweed.filer.port", 8888);
+        conf.setInt("fs.seaweed.filer.port.grpc", 18888);
+        
+        fs = new SeaweedFileSystem();
+        URI uri = new URI("seaweedfs://localhost:8888/");
+        fs.initialize(uri, conf);
+        
+        // Clean up any existing test directory
+        Path testPath = new Path(TEST_ROOT);
+        if (fs.exists(testPath)) {
+            fs.delete(testPath, true);
+        }
+    }
+
+    @After
+    public void tearDown() throws Exception {
+        if (!TESTS_ENABLED || fs == null) {
+            return;
+        }
+        
+        // Clean up test directory
+        Path testPath = new Path(TEST_ROOT);
+        if (fs.exists(testPath)) {
+            fs.delete(testPath, true);
+        }
+        
+        fs.close();
+    }
+
+    @Test
+    public void testInitialization() throws Exception {
+        if (!TESTS_ENABLED) {
+            System.out.println("Skipping test - SEAWEEDFS_TEST_ENABLED not set");
+            return;
+        }
+        
+        assertNotNull(fs);
+        assertEquals("seaweedfs", fs.getScheme());
+        assertNotNull(fs.getUri());
+        assertEquals("/", fs.getWorkingDirectory().toUri().getPath());
+    }
+
+    @Test
+    public void testMkdirs() throws Exception {
+        if (!TESTS_ENABLED) {
+            System.out.println("Skipping test - SEAWEEDFS_TEST_ENABLED not set");
+            return;
+        }
+        
+        Path testDir = new Path(TEST_ROOT + "/testdir");
+        assertTrue("Failed to create directory", fs.mkdirs(testDir));
+        assertTrue("Directory should exist", fs.exists(testDir));
+        
+        FileStatus status = fs.getFileStatus(testDir);
+        assertTrue("Path should be a directory", status.isDirectory());
+    }
+
+    @Test
+    public void testCreateAndReadFile() throws Exception {
+        if (!TESTS_ENABLED) {
+            System.out.println("Skipping test - SEAWEEDFS_TEST_ENABLED not set");
+            return;
+        }
+        
+        Path testFile = new Path(TEST_ROOT + "/testfile.txt");
+        String testContent = "Hello, SeaweedFS!";
+        
+        // Create and write to file
+        FSDataOutputStream out = fs.create(testFile, FsPermission.getDefault(), 
+            false, 4096, (short) 1, 4 * 1024 * 1024, null);
+        assertNotNull("Output stream should not be null", out);
+        out.write(testContent.getBytes());
+        out.close();
+        
+        // Verify file exists
+        assertTrue("File should exist", fs.exists(testFile));
+        
+        // Read and verify content
+        FSDataInputStream in = fs.open(testFile, 4096);
+        assertNotNull("Input stream should not be null", in);
+        byte[] buffer = new byte[testContent.length()];
+        int bytesRead = in.read(buffer);
+        in.close();
+        
+        assertEquals("Should read all bytes", testContent.length(), bytesRead);
+        assertEquals("Content should match", testContent, new String(buffer));
+    }
+
+    @Test
+    public void testFileStatus() throws Exception {
+        if (!TESTS_ENABLED) {
+            System.out.println("Skipping test - SEAWEEDFS_TEST_ENABLED not set");
+            return;
+        }
+        
+        Path testFile = new Path(TEST_ROOT + "/statustest.txt");
+        String content = "test content";
+        
+        FSDataOutputStream out = fs.create(testFile);
+        out.write(content.getBytes());
+        out.close();
+        
+        FileStatus status = fs.getFileStatus(testFile);
+        assertNotNull("FileStatus should not be null", status);
+        assertFalse("Should not be a directory", status.isDirectory());
+        assertTrue("Should be a file", status.isFile());
+        assertEquals("File length should match", content.length(), status.getLen());
+        assertNotNull("Path should not be null", status.getPath());
+    }
+
+    @Test
+    public void testListStatus() throws Exception {
+        if (!TESTS_ENABLED) {
+            System.out.println("Skipping test - SEAWEEDFS_TEST_ENABLED not set");
+            return;
+        }
+        
+        Path testDir = new Path(TEST_ROOT + "/listtest");
+        fs.mkdirs(testDir);
+        
+        // Create multiple files
+        for (int i = 0; i < 3; i++) {
+            Path file = new Path(testDir, "file" + i + ".txt");
+            FSDataOutputStream out = fs.create(file);
+            out.write(("content" + i).getBytes());
+            out.close();
+        }
+        
+        FileStatus[] statuses = fs.listStatus(testDir);
+        assertNotNull("List should not be null", statuses);
+        assertEquals("Should have 3 files", 3, statuses.length);
+    }
+
+    @Test
+    public void testRename() throws Exception {
+        if (!TESTS_ENABLED) {
+            System.out.println("Skipping test - SEAWEEDFS_TEST_ENABLED not set");
+            return;
+        }
+        
+        Path srcFile = new Path(TEST_ROOT + "/source.txt");
+        Path dstFile = new Path(TEST_ROOT + "/destination.txt");
+        String content = "rename test";
+        
+        // Create source file
+        FSDataOutputStream out = fs.create(srcFile);
+        out.write(content.getBytes());
+        out.close();
+        
+        assertTrue("Source file should exist", fs.exists(srcFile));
+        
+        // Rename
+        assertTrue("Rename should succeed", fs.rename(srcFile, dstFile));
+        
+        // Verify
+        assertFalse("Source file should not exist", fs.exists(srcFile));
+        assertTrue("Destination file should exist", fs.exists(dstFile));
+        
+        // Verify content preserved
+        FSDataInputStream in = fs.open(dstFile);
+        byte[] buffer = new byte[content.length()];
+        in.read(buffer);
+        in.close();
+        assertEquals("Content should be preserved", content, new String(buffer));
+    }
+
+    @Test
+    public void testDelete() throws Exception {
+        if (!TESTS_ENABLED) {
+            System.out.println("Skipping test - SEAWEEDFS_TEST_ENABLED not set");
+            return;
+        }
+        
+        Path testFile = new Path(TEST_ROOT + "/deletetest.txt");
+        
+        // Create file
+        FSDataOutputStream out = fs.create(testFile);
+        out.write("delete me".getBytes());
+        out.close();
+        
+        assertTrue("File should exist before delete", fs.exists(testFile));
+        
+        // Delete
+        assertTrue("Delete should succeed", fs.delete(testFile, false));
+        assertFalse("File should not exist after delete", fs.exists(testFile));
+    }
+
+    @Test
+    public void testDeleteDirectory() throws Exception {
+        if (!TESTS_ENABLED) {
+            System.out.println("Skipping test - SEAWEEDFS_TEST_ENABLED not set");
+            return;
+        }
+        
+        Path testDir = new Path(TEST_ROOT + "/deletedir");
+        Path testFile = new Path(testDir, "file.txt");
+        
+        // Create directory with file
+        fs.mkdirs(testDir);
+        FSDataOutputStream out = fs.create(testFile);
+        out.write("content".getBytes());
+        out.close();
+        
+        assertTrue("Directory should exist", fs.exists(testDir));
+        assertTrue("File should exist", fs.exists(testFile));
+        
+        // Recursive delete
+        assertTrue("Recursive delete should succeed", fs.delete(testDir, true));
+        assertFalse("Directory should not exist after delete", fs.exists(testDir));
+        assertFalse("File should not exist after delete", fs.exists(testFile));
+    }
+
+    @Test
+    public void testAppend() throws Exception {
+        if (!TESTS_ENABLED) {
+            System.out.println("Skipping test - SEAWEEDFS_TEST_ENABLED not set");
+            return;
+        }
+        
+        Path testFile = new Path(TEST_ROOT + "/appendtest.txt");
+        String initialContent = "initial";
+        String appendContent = " appended";
+        
+        // Create initial file
+        FSDataOutputStream out = fs.create(testFile);
+        out.write(initialContent.getBytes());
+        out.close();
+        
+        // Append
+        FSDataOutputStream appendOut = fs.append(testFile, 4096, null);
+        assertNotNull("Append stream should not be null", appendOut);
+        appendOut.write(appendContent.getBytes());
+        appendOut.close();
+        
+        // Verify combined content
+        FSDataInputStream in = fs.open(testFile);
+        byte[] buffer = new byte[initialContent.length() + appendContent.length()];
+        int bytesRead = in.read(buffer);
+        in.close();
+        
+        String expected = initialContent + appendContent;
+        assertEquals("Should read all bytes", expected.length(), bytesRead);
+        assertEquals("Content should match", expected, new String(buffer));
+    }
+
+    @Test
+    public void testSetWorkingDirectory() throws Exception {
+        if (!TESTS_ENABLED) {
+            System.out.println("Skipping test - SEAWEEDFS_TEST_ENABLED not set");
+            return;
+        }
+        
+        Path originalWd = fs.getWorkingDirectory();
+        assertEquals("Original working directory should be /", "/", originalWd.toUri().getPath());
+        
+        Path newWd = new Path(TEST_ROOT);
+        fs.mkdirs(newWd);
+        fs.setWorkingDirectory(newWd);
+        
+        Path currentWd = fs.getWorkingDirectory();
+        assertTrue("Working directory should be updated", 
+            currentWd.toUri().getPath().contains(TEST_ROOT));
+    }
+
+    @Test
+    public void testSetPermission() throws Exception {
+        if (!TESTS_ENABLED) {
+            System.out.println("Skipping test - SEAWEEDFS_TEST_ENABLED not set");
+            return;
+        }
+        
+        Path testFile = new Path(TEST_ROOT + "/permtest.txt");
+        
+        // Create file
+        FSDataOutputStream out = fs.create(testFile);
+        out.write("permission test".getBytes());
+        out.close();
+        
+        // Set permission
+        FsPermission newPerm = new FsPermission((short) 0644);
+        fs.setPermission(testFile, newPerm);
+        
+        FileStatus status = fs.getFileStatus(testFile);
+        assertNotNull("Permission should not be null", status.getPermission());
+    }
+
+    @Test
+    public void testSetOwner() throws Exception {
+        if (!TESTS_ENABLED) {
+            System.out.println("Skipping test - SEAWEEDFS_TEST_ENABLED not set");
+            return;
+        }
+        
+        Path testFile = new Path(TEST_ROOT + "/ownertest.txt");
+        
+        // Create file
+        FSDataOutputStream out = fs.create(testFile);
+        out.write("owner test".getBytes());
+        out.close();
+        
+        // Set owner - this may not fail even if not fully implemented
+        fs.setOwner(testFile, "testuser", "testgroup");
+        
+        // Just verify the call doesn't throw an exception
+        FileStatus status = fs.getFileStatus(testFile);
+        assertNotNull("FileStatus should not be null", status);
+    }
+
+    @Test
+    public void testRenameToExistingDirectory() throws Exception {
+        if (!TESTS_ENABLED) {
+            System.out.println("Skipping test - SEAWEEDFS_TEST_ENABLED not set");
+            return;
+        }
+        
+        Path srcFile = new Path(TEST_ROOT + "/movefile.txt");
+        Path dstDir = new Path(TEST_ROOT + "/movedir");
+        
+        // Create source file and destination directory
+        FSDataOutputStream out = fs.create(srcFile);
+        out.write("move test".getBytes());
+        out.close();
+        fs.mkdirs(dstDir);
+        
+        // Rename file to existing directory (should move file into directory)
+        assertTrue("Rename to directory should succeed", fs.rename(srcFile, dstDir));
+        
+        // File should be moved into the directory
+        Path expectedLocation = new Path(dstDir, srcFile.getName());
+        assertTrue("File should exist in destination directory", fs.exists(expectedLocation));
+        assertFalse("Source file should not exist", fs.exists(srcFile));
+    }
+}
+

other/java/s3copier/README.md

@@ -0,0 +1,110 @@
+# SeaweedFS S3 Java SDK Compatibility Tests
+
+This project contains Java-based integration tests for SeaweedFS S3 API compatibility.
+
+## Overview
+
+Tests are provided for both AWS SDK v1 and v2 to ensure compatibility with the various SDK versions commonly used in production.
+
+## SDK Versions
+
+| SDK | Version | Notes |
+|-----|---------|-------|
+| AWS SDK v1 for Java | 1.12.600 | Legacy SDK, less strict ETag validation |
+| AWS SDK v2 for Java | 2.20.127 | Modern SDK with strict checksum validation |
+
+## Running Tests
+
+### Prerequisites
+
+1. SeaweedFS running with S3 API enabled:
+   ```bash
+   weed server -s3
+   ```
+
+2. Java 18+ and Maven
+
+### Run All Tests
+
+```bash
+mvn test
+```
+
+### Run Specific Tests
+
+```bash
+# Run only ETag validation tests (AWS SDK v2)
+mvn test -Dtest=ETagValidationTest
+
+# Run with custom endpoint
+mvn test -Dtest=ETagValidationTest -DS3_ENDPOINT=http://localhost:8333
+```
+
+### Environment Variables
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `S3_ENDPOINT` | `http://127.0.0.1:8333` | S3 API endpoint URL |
+| `S3_ACCESS_KEY` | `some_access_key1` | Access key ID |
+| `S3_SECRET_KEY` | `some_secret_key1` | Secret access key |
+| `S3_REGION` | `us-east-1` | AWS region |
+
+## Test Coverage
+
+### ETagValidationTest (AWS SDK v2)
+
+Tests for [GitHub Issue #7768](https://github.com/seaweedfs/seaweedfs/issues/7768) - ETag format validation.
+
+| Test | Description |
+|------|-------------|
+| `testSmallFilePutObject` | Verify small files return pure MD5 ETag |
+| `testLargeFilePutObject_Issue7768` | **Critical**: Verify large files (>8MB) return pure MD5 ETag |
+| `testExtraLargeFilePutObject` | Verify very large files (>24MB) return pure MD5 ETag |
+| `testMultipartUploadETag` | Verify multipart uploads return composite ETag |
+| `testETagConsistency` | Verify ETag consistency across PUT/HEAD/GET |
+| `testMultipleLargeFileUploads` | Stress test multiple large uploads |
+
+### Background: Issue #7768
+
+AWS SDK v2 for Java includes checksum validation that decodes the ETag as hexadecimal. When SeaweedFS returned composite ETags (`<md5>-<count>`) for regular `PutObject` with internally auto-chunked files, the SDK failed with:
+
+```
+java.lang.IllegalArgumentException: Invalid base 16 character: '-'
+```
+
+**Per AWS S3 specification:**
+- `PutObject`: ETag is always a pure MD5 hex string (32 chars)
+- `CompleteMultipartUpload`: ETag is composite format (`<md5>-<partcount>`)
+
+The fix ensures SeaweedFS follows this specification.
+
+## Project Structure
+
+```
+src/
+├── main/java/com/seaweedfs/s3/
+│   ├── PutObject.java           # Example PutObject with SDK v1
+│   └── HighLevelMultipartUpload.java
+└── test/java/com/seaweedfs/s3/
+    ├── PutObjectTest.java       # Basic SDK v1 test
+    └── ETagValidationTest.java  # Comprehensive SDK v2 ETag tests
+```
+
+## Validated SDK Versions
+
+This Java test project validates:
+
+- ✅ AWS SDK v2 for Java 2.20.127+
+- ✅ AWS SDK v1 for Java 1.12.600+
+
+Go SDK validation is performed by separate test suites:
+- See [Go ETag Tests](/test/s3/etag/) for AWS SDK v2 for Go tests
+- See [test/s3/SDK_COMPATIBILITY.md](/test/s3/SDK_COMPATIBILITY.md) for full SDK compatibility matrix
+
+## Related
+
+- [GitHub Issue #7768](https://github.com/seaweedfs/seaweedfs/issues/7768)
+- [AWS S3 ETag Documentation](https://docs.aws.amazon.com/AmazonS3/latest/API/API_Object.html)
+- [Go ETag Tests](/test/s3/etag/)
+- [SDK Compatibility Matrix](/test/s3/SDK_COMPATIBILITY.md)
+

other/java/s3copier/pom.xml

@@ -0,0 +1,85 @@
+<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+  xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">
+  <modelVersion>4.0.0</modelVersion>
+  <groupId>com.seaweedfs.s3</groupId>
+  <artifactId>copier</artifactId>
+  <packaging>jar</packaging>
+  <version>1.0-SNAPSHOT</version>
+  <properties>
+    <maven.compiler.source>11</maven.compiler.source>
+    <maven.compiler.target>11</maven.compiler.target>
+    <aws.sdk.v1.version>1.12.600</aws.sdk.v1.version>
+    <aws.sdk.v2.version>2.20.127</aws.sdk.v2.version>
+  </properties>
+  <name>copier</name>
+  <url>http://maven.apache.org</url>
+
+  <dependencyManagement>
+    <dependencies>
+      <!-- AWS SDK v1 BOM -->
+      <dependency>
+        <groupId>com.amazonaws</groupId>
+        <artifactId>aws-java-sdk-bom</artifactId>
+        <version>${aws.sdk.v1.version}</version>
+        <type>pom</type>
+        <scope>import</scope>
+      </dependency>
+      <!-- AWS SDK v2 BOM -->
+      <dependency>
+        <groupId>software.amazon.awssdk</groupId>
+        <artifactId>bom</artifactId>
+        <version>${aws.sdk.v2.version}</version>
+        <type>pom</type>
+        <scope>import</scope>
+      </dependency>
+    </dependencies>
+  </dependencyManagement>
+
+  <dependencies>
+    <!-- AWS SDK v1 (for backward compatibility with existing code) -->
+    <dependency>
+      <groupId>com.amazonaws</groupId>
+      <artifactId>aws-java-sdk-s3</artifactId>
+    </dependency>
+    
+    <!-- AWS SDK v2 (for modern tests with checksum validation) -->
+    <dependency>
+      <groupId>software.amazon.awssdk</groupId>
+      <artifactId>s3</artifactId>
+    </dependency>
+    <dependency>
+      <groupId>software.amazon.awssdk</groupId>
+      <artifactId>s3-transfer-manager</artifactId>
+    </dependency>
+    
+    <!-- Test dependencies -->
+    <dependency>
+      <groupId>junit</groupId>
+      <artifactId>junit</artifactId>
+      <version>4.13.2</version>
+      <scope>test</scope>
+    </dependency>
+    <dependency>
+      <groupId>org.junit.jupiter</groupId>
+      <artifactId>junit-jupiter</artifactId>
+      <version>5.10.0</version>
+      <scope>test</scope>
+    </dependency>
+    <dependency>
+      <groupId>org.assertj</groupId>
+      <artifactId>assertj-core</artifactId>
+      <version>3.27.7</version>
+      <scope>test</scope>
+    </dependency>
+  </dependencies>
+
+  <build>
+    <plugins>
+      <plugin>
+        <groupId>org.apache.maven.plugins</groupId>
+        <artifactId>maven-surefire-plugin</artifactId>
+        <version>3.2.2</version>
+      </plugin>
+    </plugins>
+  </build>
+</project>

other/java/s3copier/src/main/java/com/seaweedfs/s3/HighLevelMultipartUpload.java

@@ -0,0 +1,78 @@
+package com.seaweedfs.s3;
+
+import com.amazonaws.AmazonServiceException;
+import com.amazonaws.ClientConfiguration;
+import com.amazonaws.SdkClientException;
+import com.amazonaws.auth.AWSCredentials;
+import com.amazonaws.auth.AWSStaticCredentialsProvider;
+import com.amazonaws.auth.BasicAWSCredentials;
+import com.amazonaws.client.builder.AwsClientBuilder;
+import com.amazonaws.regions.Regions;
+import com.amazonaws.services.s3.AmazonS3;
+import com.amazonaws.services.s3.AmazonS3ClientBuilder;
+import com.amazonaws.services.s3.model.CreateBucketRequest;
+import com.amazonaws.services.s3.model.GetBucketLocationRequest;
+import com.amazonaws.services.s3.transfer.TransferManager;
+import com.amazonaws.services.s3.transfer.TransferManagerBuilder;
+import com.amazonaws.services.s3.transfer.Upload;
+
+import java.io.File;
+
+public class HighLevelMultipartUpload {
+
+    public static void main(String[] args) throws Exception {
+        String bucketName = "javabucket";
+        String filePath = args[0];
+        File file = new File(filePath);
+        String keyName = "path/to/" + file.getName();
+
+        try {
+            AWSCredentials credentials = new BasicAWSCredentials("ANY-ACCESSKEYID", "ANY-SECRETACCESSKEY");
+            ClientConfiguration clientConfiguration = new ClientConfiguration();
+            clientConfiguration.setSignerOverride("AWSS3V4SignerType");
+
+            AmazonS3 s3Client = AmazonS3ClientBuilder
+                .standard()
+                .withEndpointConfiguration(new AwsClientBuilder.EndpointConfiguration(
+                    "http://localhost:8333", Regions.US_WEST_1.name()))
+                .withPathStyleAccessEnabled(true)
+                .withClientConfiguration(clientConfiguration)
+                .withCredentials(new AWSStaticCredentialsProvider(credentials))
+                .build();
+
+            TransferManager tm = TransferManagerBuilder.standard()
+                .withS3Client(s3Client)
+                .build();
+
+
+            if (!s3Client.doesBucketExistV2(bucketName)) {
+                // Because the CreateBucketRequest object doesn't specify a region, the
+                // bucket is created in the region specified in the client.
+                s3Client.createBucket(new CreateBucketRequest(bucketName));
+
+                // Verify that the bucket was created by retrieving it and checking its location.
+                String bucketLocation = s3Client.getBucketLocation(new GetBucketLocationRequest(bucketName));
+                System.out.println("Bucket location: " + bucketLocation);
+            } else {
+                System.out.println("Bucket already exists");
+            }
+
+            // TransferManager processes all transfers asynchronously,
+            // so this call returns immediately.
+            Upload upload = tm.upload(bucketName, keyName, file);
+            System.out.println("Object upload started");
+
+            // Optionally, wait for the upload to finish before continuing.
+            upload.waitForCompletion();
+            System.out.println("Object upload complete");
+        } catch (AmazonServiceException e) {
+            // The call was transmitted successfully, but Amazon S3 couldn't process
+            // it, so it returned an error response.
+            e.printStackTrace();
+        } catch (SdkClientException e) {
+            // Amazon S3 couldn't be contacted for a response, or the client
+            // couldn't parse the response from Amazon S3.
+            e.printStackTrace();
+        }
+    }
+}

other/java/s3copier/src/main/java/com/seaweedfs/s3/PutObject.java

@@ -0,0 +1,101 @@
+package com.seaweedfs.s3;
+
+import com.amazonaws.AmazonServiceException;
+import com.amazonaws.ClientConfiguration;
+import com.amazonaws.SdkClientException;
+import com.amazonaws.auth.AWSCredentials;
+import com.amazonaws.auth.AWSStaticCredentialsProvider;
+import com.amazonaws.auth.BasicAWSCredentials;
+import com.amazonaws.client.builder.AwsClientBuilder;
+import com.amazonaws.regions.Regions;
+import com.amazonaws.services.s3.AmazonS3;
+import com.amazonaws.services.s3.AmazonS3ClientBuilder;
+import com.amazonaws.services.s3.model.ObjectMetadata;
+import com.amazonaws.services.s3.model.PutObjectRequest;
+import com.amazonaws.services.s3.model.S3Object;
+import com.amazonaws.util.IOUtils;
+import org.apache.commons.logging.Log;
+import org.apache.commons.logging.LogFactory;
+
+import java.io.File;
+import java.io.IOException;
+
+/**
+ * Hello world!
+ */
+public class PutObject {
+
+    private static Log log = LogFactory.getLog(PutObject.class);
+
+    public static void main(String[] args) {
+
+        AWSCredentials credentials = new BasicAWSCredentials("ANY-ACCESSKEYID", "ANY-SECRETACCESSKEY");
+        ClientConfiguration clientConfiguration = new ClientConfiguration();
+        clientConfiguration.setSignerOverride("AWSS3V4SignerType");
+
+        AmazonS3 s3Client = AmazonS3ClientBuilder
+            .standard()
+            .withEndpointConfiguration(new AwsClientBuilder.EndpointConfiguration(
+                "http://localhost:8333", Regions.US_WEST_1.name()))
+            .withPathStyleAccessEnabled(true)
+            .withClientConfiguration(clientConfiguration)
+            .withCredentials(new AWSStaticCredentialsProvider(credentials))
+            .build();
+
+        String bucketName = "javabucket";
+        String stringObjKeyName = "strObject2";
+        String fileObjKeyName = "fileObject2";
+        String fileName = args[0];
+
+        String stringContent = "Uploaded String Object v3";
+        try {
+
+            // Upload a text string as a new object.
+            s3Client.putObject(bucketName, stringObjKeyName, stringContent);
+
+            // Upload a file as a new object with ContentType and title specified.
+            PutObjectRequest request = new PutObjectRequest(bucketName, fileObjKeyName, new File(fileName));
+            ObjectMetadata metadata = new ObjectMetadata();
+            metadata.setContentType("plain/text");
+            metadata.addUserMetadata("x-amz-meta-title", "someTitle");
+            request.setMetadata(metadata);
+            s3Client.putObject(request);
+
+            // test reads
+            S3Object written = s3Client.getObject(bucketName, stringObjKeyName);
+            try {
+                String expected = IOUtils.toString(written.getObjectContent());
+
+                if (!stringContent.equals(expected)){
+                    System.out.println("Failed to put and get back the content!");
+                }
+
+            } catch (IOException e) {
+                throw new SdkClientException("Error streaming content from S3 during download");
+            } finally {
+                IOUtils.closeQuietly(written, log);
+            }
+
+            // test deletes
+            s3Client.deleteObject(bucketName, stringObjKeyName);
+
+
+            // delete bucket
+            String tmpBucket = "tmpbucket";
+            s3Client.createBucket(tmpBucket);
+            s3Client.putObject(tmpBucket, stringObjKeyName, stringContent);
+            s3Client.deleteBucket(tmpBucket);
+
+        } catch (AmazonServiceException e) {
+            // The call was transmitted successfully, but Amazon S3 couldn't process
+            // it, so it returned an error response.
+            e.printStackTrace();
+        } catch (SdkClientException e) {
+            // Amazon S3 couldn't be contacted for a response, or the client
+            // couldn't parse the response from Amazon S3.
+            e.printStackTrace();
+        }
+
+        System.out.println("Hello World!");
+    }
+}

other/java/s3copier/src/test/java/com/seaweedfs/s3/ETagValidationTest.java

@@ -0,0 +1,439 @@
+package com.seaweedfs.s3;
+
+import org.junit.jupiter.api.*;
+import org.junit.jupiter.api.condition.EnabledIfEnvironmentVariable;
+import software.amazon.awssdk.auth.credentials.AwsBasicCredentials;
+import software.amazon.awssdk.auth.credentials.StaticCredentialsProvider;
+import software.amazon.awssdk.core.sync.RequestBody;
+import software.amazon.awssdk.regions.Region;
+import software.amazon.awssdk.services.s3.S3Client;
+import software.amazon.awssdk.services.s3.model.*;
+
+import java.net.URI;
+import java.security.MessageDigest;
+import java.security.SecureRandom;
+import java.util.ArrayList;
+import java.util.List;
+import java.util.UUID;
+import java.util.regex.Pattern;
+
+import static org.assertj.core.api.Assertions.*;
+
+/**
+ * AWS SDK v2 Integration Tests for S3 ETag Format Validation.
+ * 
+ * These tests verify that SeaweedFS returns correct ETag formats that are
+ * compatible with AWS SDK v2's checksum validation.
+ * 
+ * Background (GitHub Issue #7768):
+ * AWS SDK v2 for Java validates ETags as hexadecimal MD5 hashes for PutObject
+ * responses. If the ETag contains non-hex characters (like '-' in composite
+ * format), the SDK fails with "Invalid base 16 character: '-'".
+ * 
+ * Per AWS S3 specification:
+ * - Regular PutObject: ETag is always a pure MD5 hex string (32 chars)
+ * - CompleteMultipartUpload: ETag is composite format "<md5>-<partcount>"
+ * 
+ * To run these tests:
+ *   mvn test -Dtest=ETagValidationTest -DS3_ENDPOINT=http://localhost:8333
+ * 
+ * Or set environment variable:
+ *   export S3_ENDPOINT=http://localhost:8333
+ *   mvn test -Dtest=ETagValidationTest
+ */
+@TestInstance(TestInstance.Lifecycle.PER_CLASS)
+@DisplayName("S3 ETag Format Validation Tests (AWS SDK v2)")
+class ETagValidationTest {
+
+    // Configuration - can be overridden via system properties or environment variables
+    private static final String DEFAULT_ENDPOINT = "http://127.0.0.1:8333";
+    private static final String DEFAULT_ACCESS_KEY = "some_access_key1";
+    private static final String DEFAULT_SECRET_KEY = "some_secret_key1";
+    private static final String DEFAULT_REGION = "us-east-1";
+    
+    // Auto-chunking threshold in SeaweedFS (must match s3api_object_handlers_put.go)
+    private static final int AUTO_CHUNK_SIZE = 8 * 1024 * 1024; // 8MB
+    
+    // Test sizes
+    private static final int SMALL_FILE_SIZE = 1024; // 1KB
+    private static final int LARGE_FILE_SIZE = 10 * 1024 * 1024; // 10MB (triggers auto-chunking)
+    private static final int XL_FILE_SIZE = 25 * 1024 * 1024; // 25MB (multiple chunks)
+    private static final int MULTIPART_PART_SIZE = 5 * 1024 * 1024; // 5MB per part
+    
+    // ETag format patterns
+    private static final Pattern PURE_MD5_PATTERN = Pattern.compile("^\"?[a-f0-9]{32}\"?$");
+    private static final Pattern COMPOSITE_PATTERN = Pattern.compile("^\"?[a-f0-9]{32}-\\d+\"?$");
+    
+    private S3Client s3Client;
+    private String testBucketName;
+    private final SecureRandom random = new SecureRandom();
+
+    @BeforeAll
+    void setUp() {
+        String endpoint = getConfig("S3_ENDPOINT", DEFAULT_ENDPOINT);
+        String accessKey = getConfig("S3_ACCESS_KEY", DEFAULT_ACCESS_KEY);
+        String secretKey = getConfig("S3_SECRET_KEY", DEFAULT_SECRET_KEY);
+        String region = getConfig("S3_REGION", DEFAULT_REGION);
+        
+        System.out.println("Connecting to S3 endpoint: " + endpoint);
+        
+        s3Client = S3Client.builder()
+                .endpointOverride(URI.create(endpoint))
+                .credentialsProvider(StaticCredentialsProvider.create(
+                        AwsBasicCredentials.create(accessKey, secretKey)))
+                .region(Region.of(region))
+                .forcePathStyle(true) // Required for SeaweedFS
+                .build();
+        
+        // Create test bucket
+        testBucketName = "test-etag-" + UUID.randomUUID().toString().substring(0, 8);
+        s3Client.createBucket(CreateBucketRequest.builder()
+                .bucket(testBucketName)
+                .build());
+        
+        System.out.println("Created test bucket: " + testBucketName);
+    }
+
+    @AfterAll
+    void tearDown() {
+        if (s3Client != null && testBucketName != null) {
+            try {
+                // Delete all objects with pagination
+                String continuationToken = null;
+                do {
+                    ListObjectsV2Response listResp = s3Client.listObjectsV2(
+                            ListObjectsV2Request.builder()
+                                    .bucket(testBucketName)
+                                    .continuationToken(continuationToken)
+                                    .build());
+                    for (S3Object obj : listResp.contents()) {
+                        s3Client.deleteObject(DeleteObjectRequest.builder()
+                                .bucket(testBucketName)
+                                .key(obj.key())
+                                .build());
+                    }
+                    continuationToken = listResp.nextContinuationToken();
+                } while (continuationToken != null);
+                
+                // Abort any multipart uploads
+                ListMultipartUploadsResponse mpResp = s3Client.listMultipartUploads(
+                        ListMultipartUploadsRequest.builder().bucket(testBucketName).build());
+                for (MultipartUpload upload : mpResp.uploads()) {
+                    s3Client.abortMultipartUpload(AbortMultipartUploadRequest.builder()
+                            .bucket(testBucketName)
+                            .key(upload.key())
+                            .uploadId(upload.uploadId())
+                            .build());
+                }
+                
+                // Delete bucket
+                s3Client.deleteBucket(DeleteBucketRequest.builder()
+                        .bucket(testBucketName)
+                        .build());
+                
+                System.out.println("Cleaned up test bucket: " + testBucketName);
+            } catch (Exception e) {
+                System.err.println("Warning: Failed to cleanup test bucket: " + e.getMessage());
+            }
+            s3Client.close();
+        }
+    }
+
+    @Test
+    @DisplayName("Small file PutObject should return pure MD5 ETag")
+    void testSmallFilePutObject() throws Exception {
+        byte[] testData = generateRandomData(SMALL_FILE_SIZE);
+        String expectedMD5 = calculateMD5Hex(testData);
+        String objectKey = "small-file-" + UUID.randomUUID() + ".bin";
+        
+        PutObjectResponse response = s3Client.putObject(
+                PutObjectRequest.builder()
+                        .bucket(testBucketName)
+                        .key(objectKey)
+                        .build(),
+                RequestBody.fromBytes(testData));
+        
+        String etag = response.eTag();
+        System.out.println("Small file ETag: " + etag + " (expected MD5: " + expectedMD5 + ")");
+        
+        assertThat(etag)
+                .describedAs("Small file ETag should be pure MD5")
+                .matches(PURE_MD5_PATTERN);
+        assertThat(cleanETag(etag))
+                .describedAs("ETag should match calculated MD5")
+                .isEqualTo(expectedMD5);
+        assertThat(etag)
+                .describedAs("ETag should not contain hyphen")
+                .doesNotContain("-");
+    }
+
+    /**
+     * Critical test for GitHub Issue #7768.
+     * 
+     * This test uploads a file larger than the auto-chunking threshold (8MB),
+     * which triggers SeaweedFS to split the file into multiple internal chunks.
+     * 
+     * Previously, this caused SeaweedFS to return a composite ETag like
+     * "d41d8cd98f00b204e9800998ecf8427e-2", which AWS SDK v2 rejected because
+     * it validates the ETag as hexadecimal and '-' is not a valid hex character.
+     * 
+     * The fix ensures that regular PutObject always returns a pure MD5 ETag,
+     * regardless of internal chunking.
+     */
+    @Test
+    @DisplayName("Large file PutObject (>8MB) should return pure MD5 ETag - Issue #7768")
+    void testLargeFilePutObject_Issue7768() throws Exception {
+        byte[] testData = generateRandomData(LARGE_FILE_SIZE);
+        String expectedMD5 = calculateMD5Hex(testData);
+        String objectKey = "large-file-" + UUID.randomUUID() + ".bin";
+        
+        System.out.println("Uploading large file (" + LARGE_FILE_SIZE + " bytes, " +
+                "> " + AUTO_CHUNK_SIZE + " byte auto-chunk threshold)...");
+        
+        // This is where Issue #7768 would manifest - SDK v2 validates ETag
+        PutObjectResponse response = s3Client.putObject(
+                PutObjectRequest.builder()
+                        .bucket(testBucketName)
+                        .key(objectKey)
+                        .build(),
+                RequestBody.fromBytes(testData));
+        
+        String etag = response.eTag();
+        int expectedChunks = (LARGE_FILE_SIZE / AUTO_CHUNK_SIZE) + 1;
+        System.out.println("Large file ETag: " + etag + 
+                " (expected MD5: " + expectedMD5 + ", internal chunks: ~" + expectedChunks + ")");
+        
+        // These assertions would fail before the fix
+        assertThat(etag)
+                .describedAs("Large file PutObject ETag MUST be pure MD5 (not composite)")
+                .matches(PURE_MD5_PATTERN);
+        assertThat(etag)
+                .describedAs("Large file ETag should NOT be composite format")
+                .doesNotMatch(COMPOSITE_PATTERN);
+        assertThat(etag)
+                .describedAs("ETag should not contain hyphen for regular PutObject")
+                .doesNotContain("-");
+        assertThat(cleanETag(etag))
+                .describedAs("ETag should match calculated MD5")
+                .isEqualTo(expectedMD5);
+        
+        // Verify hex decoding works (this is what fails in Issue #7768)
+        assertThatCode(() -> hexToBytes(cleanETag(etag)))
+                .describedAs("ETag should be valid hexadecimal (AWS SDK v2 validation)")
+                .doesNotThrowAnyException();
+    }
+
+    @Test
+    @DisplayName("Extra large file PutObject (>24MB) should return pure MD5 ETag")
+    void testExtraLargeFilePutObject() throws Exception {
+        byte[] testData = generateRandomData(XL_FILE_SIZE);
+        String expectedMD5 = calculateMD5Hex(testData);
+        String objectKey = "xl-file-" + UUID.randomUUID() + ".bin";
+        
+        int expectedChunks = (XL_FILE_SIZE / AUTO_CHUNK_SIZE) + 1;
+        System.out.println("Uploading XL file (" + XL_FILE_SIZE + " bytes, ~" + 
+                expectedChunks + " internal chunks)...");
+        
+        PutObjectResponse response = s3Client.putObject(
+                PutObjectRequest.builder()
+                        .bucket(testBucketName)
+                        .key(objectKey)
+                        .build(),
+                RequestBody.fromBytes(testData));
+        
+        String etag = response.eTag();
+        System.out.println("XL file ETag: " + etag);
+        
+        assertThat(etag)
+                .describedAs("XL file PutObject ETag MUST be pure MD5")
+                .matches(PURE_MD5_PATTERN);
+        assertThat(cleanETag(etag))
+                .describedAs("ETag should match calculated MD5")
+                .isEqualTo(expectedMD5);
+    }
+
+    @Test
+    @DisplayName("Multipart upload should return composite ETag")
+    void testMultipartUploadETag() throws Exception {
+        int totalSize = 15 * 1024 * 1024; // 15MB = 3 parts
+        byte[] testData = generateRandomData(totalSize);
+        String objectKey = "multipart-file-" + UUID.randomUUID() + ".bin";
+        
+        System.out.println("Performing multipart upload (" + totalSize + " bytes)...");
+        
+        // Initiate multipart upload
+        CreateMultipartUploadResponse createResp = s3Client.createMultipartUpload(
+                CreateMultipartUploadRequest.builder()
+                        .bucket(testBucketName)
+                        .key(objectKey)
+                        .build());
+        String uploadId = createResp.uploadId();
+        
+        List<CompletedPart> completedParts = new ArrayList<>();
+        int partNumber = 1;
+        
+        // Upload parts
+        for (int offset = 0; offset < totalSize; offset += MULTIPART_PART_SIZE) {
+            int end = Math.min(offset + MULTIPART_PART_SIZE, totalSize);
+            byte[] partData = new byte[end - offset];
+            System.arraycopy(testData, offset, partData, 0, partData.length);
+            
+            UploadPartResponse uploadResp = s3Client.uploadPart(
+                    UploadPartRequest.builder()
+                            .bucket(testBucketName)
+                            .key(objectKey)
+                            .uploadId(uploadId)
+                            .partNumber(partNumber)
+                            .build(),
+                    RequestBody.fromBytes(partData));
+            
+            completedParts.add(CompletedPart.builder()
+                    .partNumber(partNumber)
+                    .eTag(uploadResp.eTag())
+                    .build());
+            partNumber++;
+        }
+        
+        // Complete multipart upload
+        CompleteMultipartUploadResponse completeResp = s3Client.completeMultipartUpload(
+                CompleteMultipartUploadRequest.builder()
+                        .bucket(testBucketName)
+                        .key(objectKey)
+                        .uploadId(uploadId)
+                        .multipartUpload(CompletedMultipartUpload.builder()
+                                .parts(completedParts)
+                                .build())
+                        .build());
+        
+        String etag = completeResp.eTag();
+        System.out.println("Multipart upload ETag: " + etag + " (" + completedParts.size() + " parts)");
+        
+        // Multipart uploads SHOULD have composite ETag
+        assertThat(etag)
+                .describedAs("Multipart upload ETag SHOULD be composite format")
+                .matches(COMPOSITE_PATTERN);
+        assertThat(etag)
+                .describedAs("Multipart ETag should contain hyphen")
+                .contains("-");
+        
+        // Verify part count in ETag
+        String[] parts = cleanETag(etag).split("-");
+        assertThat(parts).hasSize(2);
+        assertThat(parts[1])
+                .describedAs("Part count in ETag should match uploaded parts")
+                .isEqualTo(String.valueOf(completedParts.size()));
+    }
+
+    @Test
+    @DisplayName("ETag should be consistent across PUT, HEAD, and GET")
+    void testETagConsistency() throws Exception {
+        byte[] testData = generateRandomData(LARGE_FILE_SIZE);
+        String objectKey = "consistency-test-" + UUID.randomUUID() + ".bin";
+        
+        // PUT
+        PutObjectResponse putResp = s3Client.putObject(
+                PutObjectRequest.builder()
+                        .bucket(testBucketName)
+                        .key(objectKey)
+                        .build(),
+                RequestBody.fromBytes(testData));
+        String putETag = putResp.eTag();
+        
+        // HEAD
+        HeadObjectResponse headResp = s3Client.headObject(
+                HeadObjectRequest.builder()
+                        .bucket(testBucketName)
+                        .key(objectKey)
+                        .build());
+        String headETag = headResp.eTag();
+        
+        // GET
+        GetObjectResponse getResp = s3Client.getObject(
+                GetObjectRequest.builder()
+                        .bucket(testBucketName)
+                        .key(objectKey)
+                        .build())
+                .response();
+        String getETag = getResp.eTag();
+        
+        System.out.println("PUT ETag: " + putETag + ", HEAD ETag: " + headETag + ", GET ETag: " + getETag);
+        
+        assertThat(putETag).isEqualTo(headETag);
+        assertThat(putETag).isEqualTo(getETag);
+    }
+
+    @Test
+    @DisplayName("Multiple large file uploads should all return pure MD5 ETags")
+    void testMultipleLargeFileUploads() throws Exception {
+        int numFiles = 3;
+        
+        for (int i = 0; i < numFiles; i++) {
+            byte[] testData = generateRandomData(LARGE_FILE_SIZE);
+            String expectedMD5 = calculateMD5Hex(testData);
+            String objectKey = "multi-large-" + i + "-" + UUID.randomUUID() + ".bin";
+            
+            PutObjectResponse response = s3Client.putObject(
+                    PutObjectRequest.builder()
+                            .bucket(testBucketName)
+                            .key(objectKey)
+                            .build(),
+                    RequestBody.fromBytes(testData));
+            
+            String etag = response.eTag();
+            System.out.println("File " + i + " ETag: " + etag);
+            
+            assertThat(etag)
+                    .describedAs("File " + i + " ETag should be pure MD5")
+                    .matches(PURE_MD5_PATTERN);
+            assertThat(cleanETag(etag))
+                    .describedAs("File " + i + " ETag should match MD5")
+                    .isEqualTo(expectedMD5);
+            
+            // Validate hex decoding
+            assertThatCode(() -> hexToBytes(cleanETag(etag)))
+                    .doesNotThrowAnyException();
+        }
+    }
+
+    // Helper methods
+    
+    private String getConfig(String key, String defaultValue) {
+        String value = System.getProperty(key);
+        if (value == null) {
+            value = System.getenv(key);
+        }
+        return value != null ? value : defaultValue;
+    }
+    
+    private byte[] generateRandomData(int size) {
+        byte[] data = new byte[size];
+        random.nextBytes(data);
+        return data;
+    }
+    
+    private String calculateMD5Hex(byte[] data) throws Exception {
+        MessageDigest md = MessageDigest.getInstance("MD5");
+        byte[] digest = md.digest(data);
+        StringBuilder sb = new StringBuilder();
+        for (byte b : digest) {
+            sb.append(String.format("%02x", b));
+        }
+        return sb.toString();
+    }
+    
+    private String cleanETag(String etag) {
+        if (etag == null) return null;
+        return etag.replace("\"", "");
+    }
+    
+    private byte[] hexToBytes(String hex) {
+        int len = hex.length();
+        byte[] data = new byte[len / 2];
+        for (int i = 0; i < len; i += 2) {
+            data[i / 2] = (byte) ((Character.digit(hex.charAt(i), 16) << 4)
+                    + Character.digit(hex.charAt(i + 1), 16));
+        }
+        return data;
+    }
+}
+

other/java/s3copier/src/test/java/com/seaweedfs/s3/PutObjectTest.java

@@ -0,0 +1,38 @@
+package com.seaweedfs.s3;
+
+import junit.framework.Test;
+import junit.framework.TestCase;
+import junit.framework.TestSuite;
+
+/**
+ * Unit test for simple App.
+ */
+public class PutObjectTest
+    extends TestCase
+{
+    /**
+     * Create the test case
+     *
+     * @param testName name of the test case
+     */
+    public PutObjectTest(String testName )
+    {
+        super( testName );
+    }
+
+    /**
+     * @return the suite of tests being tested
+     */
+    public static Test suite()
+    {
+        return new TestSuite( PutObjectTest.class );
+    }
+
+    /**
+     * Rigorous Test :-)
+     */
+    public void testApp()
+    {
+        assertTrue( true );
+    }
+}