Merge pull request #770 from tdnguyenND/feature/toindefarray-v2

feat: add toindefarray struct tag option for CBOR indefinite-length arrays.  This can be useful for Cardano Plutus Data interoperability.

Author: fxamacker

cache.go

@@ -111,9 +111,16 @@ func getDecodingStructType(t reflect.Type) (*decodingStructType, error) {
 
 	flds, structOptions := getFields(t)
 
-	toArray := hasToArrayOption(structOptions)
-
-	if toArray {
+	hasToArray, hasToIndefArray, err := arrayStructOptions(t, structOptions)
+	if err != nil {
+		structType := &decodingStructType{err: err}
+		decodingStructTypeCache.Store(t, structType)
+		return nil, err
+	}
+	// Both options describe a struct laid out as a CBOR array. The decoder
+	// accepts definite- and indefinite-length arrays interchangeably, so
+	// the same code path serves both options.
+	if hasToArray || hasToIndefArray {
 		return getDecodingStructToArrayType(t, flds)
 	}
 
@@ -205,11 +212,12 @@ func getDecodingStructToArrayType(t reflect.Type, flds fields) (*decodingStructT
 
 type encodingStructType struct {
 	fields             encodingFields
-	bytewiseFields     encodingFields // Only populated if toArray is false
-	lengthFirstFields  encodingFields // Only populated if toArray is false
-	omitEmptyFieldsIdx []int          // Only populated if toArray is false
+	bytewiseFields     encodingFields // Only populated if struct is not array-shaped
+	lengthFirstFields  encodingFields // Only populated if struct is not array-shaped
+	omitEmptyFieldsIdx []int          // Only populated if struct is not array-shaped
 	err                error
-	toArray            bool
+	toArray            bool // True iff the struct declares the `toarray` option
+	toIndefArray       bool // True iff the struct declares the `toindefarray` option
 }
 
 func (st *encodingStructType) getFields(em *encMode) encodingFields {
@@ -245,8 +253,14 @@ func getEncodingStructType(t reflect.Type) (*encodingStructType, error) {
 
 	flds, structOptions := getFields(t)
 
-	if hasToArrayOption(structOptions) {
-		return getEncodingStructToArrayType(t, flds)
+	hasToArray, hasToIndefArray, err := arrayStructOptions(t, structOptions)
+	if err != nil {
+		structType := &encodingStructType{err: err}
+		encodingStructTypeCache.Store(t, structType)
+		return nil, err
+	}
+	if hasToArray || hasToIndefArray {
+		return getEncodingStructToArrayType(t, flds, hasToArray, hasToIndefArray)
 	}
 
 	var hasKeyAsInt bool
@@ -344,7 +358,7 @@ func getEncodingStructType(t reflect.Type) (*encodingStructType, error) {
 	return structType, nil
 }
 
-func getEncodingStructToArrayType(t reflect.Type, flds fields) (*encodingStructType, error) {
+func getEncodingStructToArrayType(t reflect.Type, flds fields, toArray, toIndefArray bool) (*encodingStructType, error) {
 	encFlds := make(encodingFields, len(flds))
 	for i, f := range flds {
 		encFlds[i] = &encodingField{field: *f}
@@ -357,8 +371,9 @@ func getEncodingStructToArrayType(t reflect.Type, flds fields) (*encodingStructT
 	}
 
 	structType := &encodingStructType{
-		fields:  encFlds,
-		toArray: true,
+		fields:       encFlds,
+		toArray:      toArray,
+		toIndefArray: toIndefArray,
 	}
 	encodingStructTypeCache.Store(t, structType)
 	return structType, nil
@@ -388,3 +403,21 @@ func hasToArrayOption(tag string) bool {
 	idx := strings.Index(tag, s)
 	return idx >= 0 && (len(tag) == idx+len(s) || tag[idx+len(s)] == ',')
 }
+
+func hasToIndefArrayOption(tag string) bool {
+	s := ",toindefarray"
+	idx := strings.Index(tag, s)
+	return idx >= 0 && (len(tag) == idx+len(s) || tag[idx+len(s)] == ',')
+}
+
+// arrayStructOptions reports whether the struct options request encoding as
+// a CBOR array (definite- or indefinite-length), and returns an error if the
+// two options are specified together (they are mutually exclusive).
+func arrayStructOptions(t reflect.Type, structOptions string) (hasToArray, hasToIndefArray bool, err error) {
+	hasToArray = hasToArrayOption(structOptions)
+	hasToIndefArray = hasToIndefArrayOption(structOptions)
+	if hasToArray && hasToIndefArray {
+		return false, false, fmt.Errorf("cbor: struct %v cannot have both \"toarray\" and \"toindefarray\" options", t)
+	}
+	return hasToArray, hasToIndefArray, nil
+}

encode.go

@@ -546,6 +546,25 @@ func (tmm TextMarshalerMode) valid() bool {
 	return tmm >= 0 && tmm < maxTextMarshalerMode
 }
 
+// ToIndefArrayStructTagMode specifies whether to honor the `toindefarray`
+// struct tag option. Indefinite-length encoding via the streaming API is
+// governed separately by IndefLength.
+type ToIndefArrayStructTagMode int
+
+const (
+	// ToIndefArrayStructTagForbidden rejects encoding of structs tagged with `toindefarray`.
+	ToIndefArrayStructTagForbidden ToIndefArrayStructTagMode = iota
+
+	// ToIndefArrayStructTagAllowed encodes structs tagged with `toindefarray` as indefinite-length arrays.
+	ToIndefArrayStructTagAllowed
+
+	maxToIndefArrayStructTagMode
+)
+
+func (m ToIndefArrayStructTagMode) valid() bool {
+	return m >= 0 && m < maxToIndefArrayStructTagMode
+}
+
 // EncOptions specifies encoding options.
 type EncOptions struct {
 	// Sort specifies sorting order.
@@ -611,6 +630,9 @@ type EncOptions struct {
 	// json.Marshaler but do not also implement cbor.Marshaler. If nil, encoding behavior is not
 	// influenced by whether or not a type implements json.Marshaler.
 	JSONMarshalerTranscoder Transcoder
+
+	// ToIndefArrayStructTag specifies whether the `toindefarray` struct tag option is honored.
+	ToIndefArrayStructTag ToIndefArrayStructTagMode
 }
 
 // CanonicalEncOptions returns EncOptions for "Canonical CBOR" encoding,
@@ -824,6 +846,12 @@ func (opts EncOptions) encMode() (*encMode, error) { //nolint:gocritic // ignore
 	if !opts.TextMarshaler.valid() {
 		return nil, errors.New("cbor: invalid TextMarshaler " + strconv.Itoa(int(opts.TextMarshaler)))
 	}
+	if !opts.ToIndefArrayStructTag.valid() {
+		return nil, errors.New("cbor: invalid ToIndefArrayStructTag " + strconv.Itoa(int(opts.ToIndefArrayStructTag)))
+	}
+	if opts.IndefLength == IndefLengthForbidden && opts.ToIndefArrayStructTag == ToIndefArrayStructTagAllowed {
+		return nil, errors.New("cbor: cannot set ToIndefArrayStructTag to ToIndefArrayStructTagAllowed when IndefLength is IndefLengthForbidden")
+	}
 	em := encMode{
 		sort:                      opts.Sort,
 		shortestFloat:             opts.ShortestFloat,
@@ -845,6 +873,7 @@ func (opts EncOptions) encMode() (*encMode, error) { //nolint:gocritic // ignore
 		binaryMarshaler:           opts.BinaryMarshaler,
 		textMarshaler:             opts.TextMarshaler,
 		jsonMarshalerTranscoder:   opts.JSONMarshalerTranscoder,
+		toIndefArrayStructTag:     opts.ToIndefArrayStructTag,
 	}
 	return &em, nil
 }
@@ -892,6 +921,7 @@ type encMode struct {
 	binaryMarshaler           BinaryMarshalerMode
 	textMarshaler             TextMarshalerMode
 	jsonMarshalerTranscoder   Transcoder
+	toIndefArrayStructTag     ToIndefArrayStructTagMode
 }
 
 var defaultEncMode, _ = EncOptions{}.encMode()
@@ -986,6 +1016,7 @@ func (em *encMode) EncOptions() EncOptions {
 		BinaryMarshaler:         em.binaryMarshaler,
 		TextMarshaler:           em.textMarshaler,
 		JSONMarshalerTranscoder: em.jsonMarshalerTranscoder,
+		ToIndefArrayStructTag:   em.toIndefArrayStructTag,
 	}
 }
 
@@ -1457,13 +1488,22 @@ func encodeStructToArray(e *bytes.Buffer, em *encMode, v reflect.Value) (err err
 		return err
 	}
 
+	if structType.toIndefArray && em.toIndefArrayStructTag != ToIndefArrayStructTagAllowed {
+		return errors.New("cbor: cannot encode struct " + v.Type().String() +
+			" with `toindefarray` when ToIndefArrayStructTag is not ToIndefArrayStructTagAllowed")
+	}
+
 	if b := em.encTagBytes(v.Type()); b != nil {
 		e.Write(b)
 	}
 
 	flds := structType.fields
 
-	encodeHead(e, byte(cborTypeArray), uint64(len(flds)))
+	if structType.toIndefArray {
+		e.WriteByte(cborArrayWithIndefiniteLengthHead)
+	} else {
+		encodeHead(e, byte(cborTypeArray), uint64(len(flds)))
+	}
 	for i := range flds {
 		f := flds[i]
 
@@ -1486,6 +1526,9 @@ func encodeStructToArray(e *bytes.Buffer, em *encMode, v reflect.Value) (err err
 			return err
 		}
 	}
+	if structType.toIndefArray {
+		e.WriteByte(cborBreakFlag)
+	}
 	return nil
 }
 
@@ -2050,7 +2093,7 @@ func getEncodeFuncInternal(t reflect.Type) (ef encodeFunc, ief isEmptyFunc, izf
 		if f, ok := t.FieldByName("_"); ok {
 			tag := f.Tag.Get("cbor")
 			if tag != "-" {
-				if hasToArrayOption(tag) {
+				if hasToArrayOption(tag) || hasToIndefArrayOption(tag) {
 					return encodeStructToArray, isEmptyStruct, isZeroFieldStruct
 				}
 			}
@@ -2133,7 +2176,7 @@ func isEmptyStruct(em *encMode, v reflect.Value) (bool, error) {
 		return false, nil
 	}
 
-	if structType.toArray {
+	if structType.toArray || structType.toIndefArray {
 		return len(structType.fields) == 0, nil
 	}
 

encode_test.go

@@ -5633,6 +5633,13 @@ func TestEncOptions(t *testing.T) {
 				// non-zero value for other options (e.g. TimeTag).
 				continue
 			}
+			if fn == "ToIndefArrayStructTag" {
+				// Roundtripping non-zero values for ToIndefArrayStructTag is tested
+				// separately since the non-zero value (ToIndefArrayStructTagAllowed)
+				// is incompatible with IndefLengthForbidden, which is the non-zero
+				// value used by IndefLength above.
+				continue
+			}
 			t.Errorf("options field %q is unset or set to the zero value for its type", fn)
 		}
 	}