Define CAR v2 fixed prefix and header

v2/car.go

@@ -0,0 +1,52 @@
+package car
+
+const (
+	// HeaderBytesSize is the fixed size of CAR v2 header in number of bytes.
+	HeaderBytesSize = 40
+	// CharacteristicsBytesSize is the fixed size of Characteristics bitfield within CAR v2 header in number of bytes.
+	CharacteristicsBytesSize = 16
+)
+
+var (
+	// The fixed prefix of a CAR v2, signalling the version number to previous versions for graceful fail over.
+	PrefixBytes = []byte{
+		0x0a,                                     // unit(10)
+		0xa1,                                     // map(1)
+		0x67,                                     // string(7)
+		0x76, 0x65, 0x72, 0x73, 0x69, 0x6f, 0x6e, // "version"
+		0x02, // uint(2)
+	}
+	// The size of the CAR v2 prefix in 11 bytes, (i.e. 11).
+	PrefixBytesSize = len(PrefixBytes)
+	// Reserved 128 bits space to capture future characteristics of CAR v2 such as order, duplication, etc.
+	EmptyCharacteristics = new(Characteristics)
+)
+
+type (
+	// Header represents the CAR v2 header/pragma.
+	Header struct {
+		// 128-bit characteristics of this CAR v2 file, such as order, deduplication, etc. Reserved for future use.
+		Characteristics Characteristics
+		// The offset from the beginning of the file at which the dump of CAR v1 starts.
+		CarV1Offset uint64
+		// The size of CAR v1 encapsulated in this CAR v2 as bytes.
+		CarV1Size uint64
+		// The offset from the beginning of the file at which the CAR v2 index begins.
+		IndexOffset uint64
+	}
+	// Characteristics is a bitfield placeholder for capturing the characteristics of a CAR v2 such as order and determinism.
+	Characteristics struct {
+		Hi uint64
+		Lo uint64
+	}
+)
+
+// Size gets the size of Header in number of bytes.
+func (h *Header) Size() int {
+	return HeaderBytesSize
+}
+
+// Size gets the size of Characteristics in number of bytes.
+func (c *Characteristics) Size() int {
+	return CharacteristicsBytesSize
+}

v2/car_test.go

@@ -0,0 +1,78 @@
+package car_test
+
+import (
+	cbor "github.com/ipfs/go-ipld-cbor"
+	car_v1 "github.com/ipld/go-car"
+	car_v2 "github.com/ipld/go-car/v2"
+	"github.com/stretchr/testify/assert"
+	"testing"
+)
+
+func TestCarV2PrefixLength(t *testing.T) {
+	tests := []struct {
+		name string
+		want interface{}
+		got  interface{}
+	}{
+		{
+			"cached size should be 11 bytes",
+			11,
+			car_v2.PrefixBytesSize,
+		},
+		{
+			"actual size should be 11 bytes",
+			11,
+			len(car_v2.PrefixBytes),
+		},
+		{
+			"should start with varint(10)",
+			car_v2.PrefixBytes[0],
+			10,
+		},
+	}
+	for _, tt := range tests {
+		tt := tt
+		t.Run(tt.name, func(t *testing.T) {
+			assert.EqualValues(t, tt.want, tt.got, "CarV2Prefix got = %v, want %v", tt.got, tt.want)
+		})
+	}
+}
+
+func TestCarV2PrefixIsValidCarV1Header(t *testing.T) {
+	var v1h car_v1.CarHeader
+	err := cbor.DecodeInto(car_v2.PrefixBytes[1:], &v1h)
+	assert.NoError(t, err, "cannot decode prefix as CBOR with CAR v1 header structure")
+	assert.Equal(t, car_v1.CarHeader{
+		Roots:   nil,
+		Version: 2,
+	}, v1h, "CAR v2 prefix must be a valid CAR v1 header")
+}
+
+func TestEmptyCharacteristics(t *testing.T) {
+	tests := []struct {
+		name string
+		want interface{}
+		got  interface{}
+	}{
+		{
+			"is of size 16 bytes",
+			16,
+			car_v2.EmptyCharacteristics.Size(),
+		},
+		{
+			"is a whole lot of nothin'",
+			&car_v2.Characteristics{},
+			car_v2.EmptyCharacteristics,
+		},
+	}
+	for _, tt := range tests {
+		tt := tt
+		t.Run(tt.name, func(t *testing.T) {
+			assert.EqualValues(t, tt.want, tt.got, "EmptyCharacteristics got = %v, want %v", tt.got, tt.want)
+		})
+	}
+}
+
+func TestHeader_SizeIs40Bytes(t *testing.T) {
+	assert.Equal(t, 40, new(car_v2.Header).Size())
+}

v2/go.mod

@@ -1,3 +1,11 @@
 module github.com/ipld/go-car/v2
 
 go 1.15
+
+require (
+	github.com/ipfs/go-ipld-cbor v0.0.5
+	github.com/ipld/go-car v0.3.1
+	github.com/stretchr/testify v1.7.0
+)
+
+replace github.com/ipld/go-car => ../