docs(fuse): clarify st_blocks/st_blksize rationale

Author: lidel

fuse/readonly/readonly_unix.go

@@ -181,9 +181,9 @@ type roFileHandle struct {
 // Used by both Getattr and Lookup (to fill EntryOut.Attr so the kernel
 // doesn't cache zero values for the entry timeout duration).
 //
-// Blksize is set on every entry: go-fuse's setBlocks otherwise
-// auto-fills both st_blocks and st_blksize with a 4 KiB page-based
-// fallback, which would clobber the values set below.
+// Blocks and Blksize are set on every entry because go-fuse's setBlocks
+// otherwise auto-fills them from Size with a 4 KiB page-based fallback,
+// which clobbers the UnixFS-derived values set below.
 func (n *Node) fillAttr(a *fuse.Attr) {
 	a.Blksize = fusemnt.DefaultBlksize
 
@@ -204,6 +204,9 @@ func (n *Node) fillAttr(a *fuse.Attr) {
 	switch n.cached.Type() {
 	case ft.TDirectory, ft.THAMTShard:
 		a.Mode = uint32(fusemnt.DefaultDirModeRO.Perm())
+		// Nominal 1 block: du sums child leaves, so the directory's
+		// own st_blocks is not arithmetically meaningful, but some
+		// tools treat 0 as "unsupported" and skip the entry.
 		a.Blocks = 1
 	case ft.TFile:
 		a.Mode = uint32(fusemnt.DefaultFileModeRO.Perm())

fuse/writable/writable.go

@@ -44,8 +44,9 @@ type Config struct {
 	// Blksize is the preferred I/O size advertised via st_blksize on
 	// every stat. Callers should derive it from Import.UnixFSChunker via
 	// fusemnt.BlksizeFromChunker so the hint matches the chunker MFS
-	// will use for writes. Zero is normalized to fusemnt.DefaultBlksize
-	// by NewDir.
+	// will use for writes. If zero, NewDir writes fusemnt.DefaultBlksize
+	// into this field in place, so fillAttr on every inode can read
+	// cfg.Blksize without a nil-check on each stat.
 	Blksize uint32
 }
 
@@ -58,10 +59,9 @@ func NewDir(d *mfs.Directory, cfg *Config) *Dir {
 	if cfg == nil || cfg.DAG == nil {
 		panic("fuse/writable: Config.DAG is required")
 	}
-	// Normalize Blksize once so fillAttr on every inode can read
-	// cfg.Blksize directly. Tests and callers that don't plumb
-	// Import.UnixFSChunker leave this zero; we fall back to the FUSE
-	// default so stat still advertises a usable st_blksize.
+	// Tests and callers that don't plumb Import.UnixFSChunker leave
+	// Blksize zero; fall back to the FUSE default so stat advertises a
+	// usable st_blksize. See Config.Blksize for why we mutate in place.
 	if cfg.Blksize == 0 {
 		cfg.Blksize = fusemnt.DefaultBlksize
 	}
@@ -75,11 +75,11 @@ type Dir struct {
 	Cfg    *Config
 }
 
-// fillAttr fills stat attributes for a directory. Blksize is set on
-// every entry: go-fuse's setBlocks otherwise auto-fills both st_blocks
-// and st_blksize with a 4 KiB page-based fallback. For directories that
-// fallback computes Blocks from Size=0 and yields st_blocks=0, which
-// some tools treat as "unsupported".
+// fillAttr fills stat attributes for a directory. Blocks and Blksize
+// are set explicitly because go-fuse's setBlocks otherwise auto-fills
+// them from Size with a 4 KiB page-based fallback. For directories
+// Size is 0, so the fallback yields st_blocks=0, which some tools
+// (dedup scanners, file managers) treat as "unsupported".
 func (d *Dir) fillAttr(a *fuse.Attr) {
 	a.Mode = uint32(fusemnt.DefaultDirModeRW.Perm())
 	a.Blocks = 1