Merge develop into release/v0.13.0 (add v4 write support)

Author: kolkov

CHANGELOG.md

@@ -45,18 +45,22 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### ✨ Added
 
 #### HDF5 Format v4 Superblock Support (TASK-024)
-- **Superblock Version 4** parsing (52-byte structure)
+- **Superblock Version 4** read and write support (52-byte structure)
+- **Read Support**: Parse v4 superblocks with checksum validation
+- **Write Support**: Create v4 superblocks with CRC32/Fletcher32 checksums
 - **Checksum Validation** - CRC32, Fletcher32, none
 - **Mandatory Extension Validation** - Format v4 compliance
 - **Backward Compatibility** - Full support for v0, v2, v3 formats
 
 **Implementation**:
 - Extended Superblock struct with v4 fields
-- `validateSuperblockChecksum()` with 3 algorithms
+- `validateSuperblockChecksum()` with 3 algorithms (read)
+- `writeV4()` with checksum generation (write)
 - `computeFletcher32()` per HDF5 specification
+- Round-trip validation tests (write → read → compare)
 - Mock-based testing (real v4 files when HDF5 2.0.0 becomes available)
 
-**Files**: `superblock.go` (+103 lines), `superblock_test.go` (+285 lines)
+**Files**: `superblock.go` (+203 lines), `superblock_test.go` (+435 lines), `superblock_write_test.go` (+157 lines)
 
 #### 64-bit Chunk Dimensions Support (TASK-025)
 - **BREAKING CHANGE**: `DataLayoutMessage.ChunkSize` changed from `[]uint32` to `[]uint64`

internal/core/superblock.go

@@ -329,9 +329,9 @@ func computeFletcher32(data []byte) uint32 {
 //
 // Returns error if write fails or if superblock version is not supported.
 func (sb *Superblock) WriteTo(w io.WriterAt, eofAddress uint64) error {
-	// Support v0 (legacy) and v2 (modern)
-	if sb.Version != Version0 && sb.Version != Version2 {
-		return fmt.Errorf("only superblock version 0 and 2 are supported for writing, got version %d", sb.Version)
+	// Support v0 (legacy), v2 (modern), and v4 (HDF5 2.0.0)
+	if sb.Version != Version0 && sb.Version != Version2 && sb.Version != Version4 {
+		return fmt.Errorf("only superblock version 0, 2, and 4 are supported for writing, got version %d", sb.Version)
 	}
 
 	// Dispatch to version-specific writer
@@ -340,6 +340,8 @@ func (sb *Superblock) WriteTo(w io.WriterAt, eofAddress uint64) error {
 		return sb.writeV0(w, eofAddress)
 	case Version2:
 		return sb.writeV2(w, eofAddress)
+	case Version4:
+		return sb.writeV4(w, eofAddress)
 	default:
 		return fmt.Errorf("unsupported superblock version: %d", sb.Version)
 	}
@@ -526,3 +528,102 @@ func (sb *Superblock) writeV0(w io.WriterAt, eofAddress uint64) error {
 
 	return nil
 }
+
+// writeV4 writes superblock version 4 (HDF5 2.0.0 format with enhanced checksums).
+//
+// Superblock v4 structure (52 bytes):
+//
+//	Bytes 0-7: Format Signature (\211HDF\r\n\032\n)
+//	Byte 8: Superblock Version (4)
+//	Byte 9: Size of Offsets (8)
+//	Byte 10: Size of Lengths (8)
+//	Byte 11: File Consistency Flags (0)
+//	Bytes 12-19: Base Address
+//	Bytes 20-27: Superblock Extension Address (REQUIRED for v4)
+//	Bytes 28-35: End of File Address
+//	Bytes 36-43: Root Group Object Header Address
+//	Byte 44: Checksum Algorithm (0=None, 1=CRC32, 2=Fletcher32)
+//	Bytes 45-47: Reserved (3 bytes, must be 0)
+//	Bytes 48-51: Checksum (covers bytes 8-47)
+func (sb *Superblock) writeV4(w io.WriterAt, eofAddress uint64) error {
+	// Validate required fields
+	if sb.OffsetSize != 8 || sb.LengthSize != 8 {
+		return fmt.Errorf("only 8-byte offsets and lengths are supported for writing v4, got offset=%d, length=%d",
+			sb.OffsetSize, sb.LengthSize)
+	}
+
+	// V4 requires superblock extension (cannot be UNDEFINED)
+	if sb.SuperExtension == 0 || sb.SuperExtension == 0xFFFFFFFFFFFFFFFF {
+		return errors.New("superblock v4 requires valid extension address")
+	}
+
+	// Default to CRC32 if not specified
+	checksumAlgo := sb.ChecksumAlgorithm
+	if checksumAlgo == 0 {
+		checksumAlgo = 1 // CRC32
+	}
+
+	// Allocate buffer for superblock v4 (52 bytes)
+	buf := make([]byte, 52)
+
+	// Bytes 0-7: Signature
+	copy(buf[0:8], Signature)
+
+	// Byte 8: Version 4
+	buf[8] = 4
+
+	// Byte 9: Size of offsets (8 bytes)
+	buf[9] = 8
+
+	// Byte 10: Size of lengths (8 bytes)
+	buf[10] = 8
+
+	// Byte 11: File consistency flags (0 for now)
+	buf[11] = 0
+
+	// Bytes 12-19: Base address (typically 0)
+	binary.LittleEndian.PutUint64(buf[12:20], sb.BaseAddress)
+
+	// Bytes 20-27: Superblock extension address (REQUIRED for v4)
+	binary.LittleEndian.PutUint64(buf[20:28], sb.SuperExtension)
+
+	// Bytes 28-35: End-of-file address
+	binary.LittleEndian.PutUint64(buf[28:36], eofAddress)
+
+	// Bytes 36-43: Root group object header address
+	binary.LittleEndian.PutUint64(buf[36:44], sb.RootGroup)
+
+	// Byte 44: Checksum algorithm
+	buf[44] = checksumAlgo
+
+	// Bytes 45-47: Reserved (already zero)
+
+	// Bytes 48-51: Checksum (covers bytes 8-47)
+	var checksum uint32
+	dataToChecksum := buf[8:48]
+
+	switch checksumAlgo {
+	case 0: // None
+		checksum = 0
+	case 1: // CRC32
+		checksum = crc32.ChecksumIEEE(dataToChecksum)
+	case 2: // Fletcher32
+		checksum = computeFletcher32(dataToChecksum)
+	default:
+		return fmt.Errorf("unsupported checksum algorithm: %d", checksumAlgo)
+	}
+
+	binary.LittleEndian.PutUint32(buf[48:52], checksum)
+
+	// Write superblock at offset 0
+	n, err := w.WriteAt(buf, 0)
+	if err != nil {
+		return fmt.Errorf("failed to write superblock v4: %w", err)
+	}
+
+	if n != 52 {
+		return fmt.Errorf("incomplete superblock v4 write: wrote %d bytes, expected 52", n)
+	}
+
+	return nil
+}

internal/core/superblock_test.go

@@ -241,14 +241,14 @@ func TestSuperblockWrite(t *testing.T) {
 		defer tmpFile.Close()
 
 		sb := &Superblock{
-			Version:    1, // v1 not supported (only v0 and v2 are supported).
+			Version:    1, // v1 not supported (only v0, v2, and v4 are supported).
 			OffsetSize: 8,
 			LengthSize: 8,
 		}
 
 		err = sb.WriteTo(tmpFile, 1024)
 		assert.Error(t, err)
-		assert.Contains(t, err.Error(), "only superblock version 0 and 2 are supported")
+		assert.Contains(t, err.Error(), "only superblock version 0, 2, and 4 are supported")
 	})
 
 	t.Run("rejects invalid sizes", func(t *testing.T) {

internal/core/superblock_write_test.go

@@ -25,6 +25,17 @@ func (m *memWriterAt) WriteAt(p []byte, off int64) (n int, err error) {
 	return len(p), nil
 }
 
+func (m *memWriterAt) ReadAt(p []byte, off int64) (n int, err error) {
+	if off < 0 {
+		return 0, nil
+	}
+	if off >= int64(len(m.data)) {
+		return 0, nil
+	}
+	n = copy(p, m.data[off:])
+	return n, nil
+}
+
 // TestSuperblock_WriteV0 tests v0 superblock writing.
 func TestSuperblock_WriteV0(t *testing.T) {
 	tests := []struct {
@@ -140,3 +151,155 @@ func TestSuperblock_WriteV0_SymbolTableEntry(t *testing.T) {
 	cacheType := binary.LittleEndian.Uint32(symEntry[16:20])
 	require.Equal(t, uint32(1), cacheType, "cache type should be 1 for group")
 }
+
+// TestSuperblock_WriteV4 tests v4 superblock writing.
+func TestSuperblock_WriteV4(t *testing.T) {
+	tests := []struct {
+		name        string
+		sb          *Superblock
+		eofAddr     uint64
+		wantErr     bool
+		errContains string
+	}{
+		{
+			name: "valid v4 superblock with CRC32",
+			sb: &Superblock{
+				Version:           4,
+				OffsetSize:        8,
+				LengthSize:        8,
+				BaseAddress:       0,
+				RootGroup:         0x1000,
+				SuperExtension:    0x800, // Required for v4
+				ChecksumAlgorithm: 1,     // CRC32
+			},
+			eofAddr: 0x2000,
+			wantErr: false,
+		},
+		{
+			name: "valid v4 with Fletcher32",
+			sb: &Superblock{
+				Version:           4,
+				OffsetSize:        8,
+				LengthSize:        8,
+				BaseAddress:       0,
+				RootGroup:         0x1000,
+				SuperExtension:    0x800,
+				ChecksumAlgorithm: 2, // Fletcher32
+			},
+			eofAddr: 0x2000,
+			wantErr: false,
+		},
+		{
+			name: "v4 missing superblock extension",
+			sb: &Superblock{
+				Version:        4,
+				OffsetSize:     8,
+				LengthSize:     8,
+				BaseAddress:    0,
+				RootGroup:      0x1000,
+				SuperExtension: 0, // Invalid for v4
+			},
+			eofAddr:     0x2000,
+			wantErr:     true,
+			errContains: "requires valid extension",
+		},
+		{
+			name: "v4 with UNDEF extension",
+			sb: &Superblock{
+				Version:        4,
+				OffsetSize:     8,
+				LengthSize:     8,
+				BaseAddress:    0,
+				RootGroup:      0x1000,
+				SuperExtension: 0xFFFFFFFFFFFFFFFF, // UNDEF
+			},
+			eofAddr:     0x2000,
+			wantErr:     true,
+			errContains: "requires valid extension",
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			buf := &memWriterAt{data: make([]byte, 0)}
+			err := tt.sb.writeV4(buf, tt.eofAddr)
+
+			if tt.wantErr {
+				require.Error(t, err)
+				if tt.errContains != "" {
+					require.Contains(t, err.Error(), tt.errContains)
+				}
+				return
+			}
+
+			require.NoError(t, err)
+
+			// Verify written data
+			data := buf.data
+			require.Equal(t, 52, len(data), "v4 superblock should be exactly 52 bytes")
+
+			// Check signature
+			for i := 0; i < 8; i++ {
+				require.Equal(t, Signature[i], data[i], "signature byte %d mismatch", i)
+			}
+
+			// Check version
+			require.Equal(t, uint8(4), data[8])
+
+			// Check sizes
+			require.Equal(t, uint8(8), data[9], "offset size")
+			require.Equal(t, uint8(8), data[10], "length size")
+
+			// Check addresses
+			gotBase := binary.LittleEndian.Uint64(data[12:20])
+			require.Equal(t, tt.sb.BaseAddress, gotBase)
+
+			gotSuperExt := binary.LittleEndian.Uint64(data[20:28])
+			require.Equal(t, tt.sb.SuperExtension, gotSuperExt)
+
+			gotEOF := binary.LittleEndian.Uint64(data[28:36])
+			require.Equal(t, tt.eofAddr, gotEOF)
+
+			gotRootGroup := binary.LittleEndian.Uint64(data[36:44])
+			require.Equal(t, tt.sb.RootGroup, gotRootGroup)
+
+			// Check checksum algorithm
+			require.Equal(t, tt.sb.ChecksumAlgorithm, data[44])
+
+			// Verify checksum is correct
+			checksum := binary.LittleEndian.Uint32(data[48:52])
+			require.NotZero(t, checksum, "checksum should be non-zero")
+		})
+	}
+}
+
+// TestSuperblock_WriteV4_RoundTrip tests write + read round-trip for v4.
+func TestSuperblock_WriteV4_RoundTrip(t *testing.T) {
+	original := &Superblock{
+		Version:           4,
+		OffsetSize:        8,
+		LengthSize:        8,
+		BaseAddress:       0,
+		RootGroup:         0xABCDEF,
+		SuperExtension:    0x12345,
+		ChecksumAlgorithm: 1, // CRC32
+	}
+
+	// Write
+	buf := &memWriterAt{data: make([]byte, 0)}
+	err := original.writeV4(buf, 0x20000)
+	require.NoError(t, err)
+
+	// Read back
+	readBack, err := ReadSuperblock(buf)
+	require.NoError(t, err)
+
+	// Compare
+	require.Equal(t, uint8(4), readBack.Version)
+	require.Equal(t, original.OffsetSize, readBack.OffsetSize)
+	require.Equal(t, original.LengthSize, readBack.LengthSize)
+	require.Equal(t, original.BaseAddress, readBack.BaseAddress)
+	require.Equal(t, original.RootGroup, readBack.RootGroup)
+	require.Equal(t, original.SuperExtension, readBack.SuperExtension)
+	require.Equal(t, original.ChecksumAlgorithm, readBack.ChecksumAlgorithm)
+}