feat: custom metadata support

Add OptMetadata, which allows supplying custom metadata when calling NewDescriptorInput. Add GetMetadata, which allows a user to parse custom metadata from a Descriptor.

Author: tri-adam

pkg/sif/descriptor.go

@@ -1,4 +1,4 @@
-// Copyright (c) 2018-2022, Sylabs Inc. All rights reserved.
+// Copyright (c) 2018-2023, Sylabs Inc. All rights reserved.
 // Copyright (c) 2017, SingularityWare, LLC. All rights reserved.
 // Copyright (c) 2017, Yannick Cote <yhcote@gmail.com> All rights reserved.
 // This software is licensed under a 3-clause BSD license. Please consult the
@@ -10,6 +10,7 @@ package sif
 import (
 "bytes"
 "crypto"
+"encoding"
 "encoding/binary"
 "errors"
 "fmt"
@@ -78,28 +79,49 @@ func (d *rawDescriptor) setName(name string) error {
 
 var errExtraTooLarge = errors.New("extra value too large")
 
-// setExtra encodes v into the extra field of d.
-func (d *rawDescriptor) setExtra(v interface{}) error {
+// setExtra encodes v into the extra field of d. If the encoding.BinaryMarshaler interface is
+// implemented by v, it is used for marshaling. Otherwise, binary.Write() is used.
+func (d *rawDescriptor) setExtra(v any) error {
 if v == nil {
 return nil
 }
 
-if binary.Size(v) > len(d.Extra) {
-return errExtraTooLarge
+var extra []byte
+
+if m, ok := v.(encoding.BinaryMarshaler); ok {
+b, err := m.MarshalBinary()
+if err != nil {
+return err
+}
+extra = b
+} else {
+b := new(bytes.Buffer)
+if err := binary.Write(b, binary.LittleEndian, v); err != nil {
+return err
+}
+extra = b.Bytes()
 }
 
-b := new(bytes.Buffer)
-if err := binary.Write(b, binary.LittleEndian, v); err != nil {
-return err
+if len(extra) > len(d.Extra) {
+return errExtraTooLarge
 }
 
-for i := copy(d.Extra[:], b.Bytes()); i < len(d.Extra); i++ {
+for i := copy(d.Extra[:], extra); i < len(d.Extra); i++ {
 d.Extra[i] = 0
 }
 
 return nil
 }
 
+// getExtra decodes the extra fields of d into v. If the encoding.BinaryUnmarshaler interface is
+// implemented by v, it is used for unmarshaling. Otherwise, binary.Read() is used.
+func (d *rawDescriptor) getExtra(v any) error {
+if u, ok := v.(encoding.BinaryUnmarshaler); ok {
+return u.UnmarshalBinary(d.Extra[:])
+}
+return binary.Read(bytes.NewReader(d.Extra[:]), binary.LittleEndian, v)
+}
+
 // getPartitionMetadata gets metadata for a partition data object.
 func (d rawDescriptor) getPartitionMetadata() (FSType, PartType, string, error) {
 if got, want := d.DataType, DataPartition; got != want {
@@ -108,9 +130,8 @@ func (d rawDescriptor) getPartitionMetadata() (FSType, PartType, string, error)
 
 var p partition
 
-b := bytes.NewReader(d.Extra[:])
-if err := binary.Read(b, binary.LittleEndian, &p); err != nil {
-return 0, 0, "", fmt.Errorf("%w", err)
+if err := d.getExtra(&p); err != nil {
+return 0, 0, "", err
 }
 
 return p.Fstype, p.Parttype, p.Arch.GoArch(), nil
@@ -168,11 +189,24 @@ func (d Descriptor) ModifiedAt() time.Time { return time.Unix(d.raw.ModifiedAt,
 // Name returns the name of the data object.
 func (d Descriptor) Name() string { return strings.TrimRight(string(d.raw.Name[:]), "\000") }
 
+// GetMetadata reads metadata from d into v. If the encoding.BinaryUnmarshaler interface is
+// implemented by v, it is used for unmarshaling. Otherwise, binary.Read() is used.
+func (d Descriptor) GetMetadata(v any) error {
+if err := d.raw.getExtra(v); err != nil {
+return fmt.Errorf("%w", err)
+}
+return nil
+}
+
 // PartitionMetadata gets metadata for a partition data object.
 //
 //nolint:nonamedreturns // Named returns effective as documentation.
 func (d Descriptor) PartitionMetadata() (fs FSType, pt PartType, arch string, err error) {
-return d.raw.getPartitionMetadata()
+fs, pt, arch, err = d.raw.getPartitionMetadata()
+if err != nil {
+return 0, 0, "", fmt.Errorf("%w", err)
+}
+return fs, pt, arch, err
 }
 
 var errHashUnsupported = errors.New("hash algorithm unsupported")
@@ -204,8 +238,7 @@ func (d Descriptor) SignatureMetadata() (ht crypto.Hash, fp []byte, err error) {
 
 var s signature
 
-b := bytes.NewReader(d.raw.Extra[:])
-if err := binary.Read(b, binary.LittleEndian, &s); err != nil {
+if err := d.raw.getExtra(&s); err != nil {
 return ht, fp, fmt.Errorf("%w", err)
 }
 
@@ -232,8 +265,7 @@ func (d Descriptor) CryptoMessageMetadata() (FormatType, MessageType, error) {
 
 var m cryptoMessage
 
-b := bytes.NewReader(d.raw.Extra[:])
-if err := binary.Read(b, binary.LittleEndian, &m); err != nil {
+if err := d.raw.getExtra(&m); err != nil {
 return 0, 0, fmt.Errorf("%w", err)
 }
 
@@ -248,8 +280,7 @@ func (d Descriptor) SBOMMetadata() (SBOMFormat, error) {
 
 var s sbom
 
-b := bytes.NewReader(d.raw.Extra[:])
-if err := binary.Read(b, binary.LittleEndian, &s); err != nil {
+if err := d.raw.getExtra(&s); err != nil {
 return 0, fmt.Errorf("%w", err)
 }
 

pkg/sif/descriptor_input.go

@@ -1,4 +1,4 @@
-// Copyright (c) 2021-2022, Sylabs Inc. All rights reserved.
+// Copyright (c) 2021-2023, Sylabs Inc. All rights reserved.
 // This software is licensed under a 3-clause BSD license. Please consult the
 // LICENSE file distributed with the sources of this project regarding your
 // rights to use or distribute this software.
@@ -19,7 +19,7 @@ type descriptorOpts struct {
 linkID uint32
 alignment int
 name string
-extra interface{}
+extra any
 t time.Time
 }
 
@@ -92,6 +92,15 @@ func OptObjectTime(t time.Time) DescriptorInputOpt {
 }
 }
 
+// OptMetadata sets v as the metadata for a data object. If the encoding.BinaryMarshaler interface
+// is implemented by v, it is used for marshaling. Otherwise, binary.Write() is used.
+func OptMetadata(v any) DescriptorInputOpt {
+return func(t DataType, opts *descriptorOpts) error {
+opts.extra = v
+return nil
+}
+}
+
 type unexpectedDataTypeError struct {
 got DataType
 want []DataType
@@ -259,7 +268,8 @@ const DefaultObjectGroup = 1
 //
 // It is possible (and often necessary) to store additional metadata related to certain types of
 // data objects. Consider supplying options such as OptCryptoMessageMetadata, OptPartitionMetadata,
-// OptSignatureMetadata, and OptSBOMMetadata for this purpose.
+// OptSignatureMetadata, and OptSBOMMetadata for this purpose. To set custom metadata, use
+// OptMetadata.
 //
 // By default, the data object will be placed in the default data object group (1). To override
 // this behavior, use OptNoGroup or OptGroupID. To link this data object, use OptLinkedID or

pkg/sif/descriptor_input_test.go

@@ -1,4 +1,4 @@
-// Copyright (c) 2021-2022, Sylabs Inc. All rights reserved.
+// Copyright (c) 2021-2023, Sylabs Inc. All rights reserved.
 // This software is licensed under a 3-clause BSD license. Please consult the
 // LICENSE file distributed with the sources of this project regarding your
 // rights to use or distribute this software.
@@ -118,6 +118,13 @@ func TestNewDescriptorInput(t *testing.T) {
 OptObjectTime(time.Unix(946702800, 0)),
 },
 },
+{
+name: "OptMetadata",
+t: DataGeneric,
+opts: []DescriptorInputOpt{
+OptMetadata(testMetadata{100}),
+},
+},
 {
 name: "OptCryptoMessageMetadataUnexpectedDataType",
 t: DataGeneric,

pkg/sif/descriptor_test.go

@@ -1,4 +1,4 @@
-// Copyright (c) 2018-2022, Sylabs Inc. All rights reserved.
+// Copyright (c) 2018-2023, Sylabs Inc. All rights reserved.
 // This software is licensed under a 3-clause BSD license. Please consult the
 // LICENSE file distributed with the sources of this project regarding your
 // rights to use or distribute this software.
@@ -8,10 +8,12 @@ package sif
 import (
 "bytes"
 "crypto"
+"encoding/json"
 "errors"
 "io"
 "os"
 "path/filepath"
+"reflect"
 "testing"
 
 "github.com/sebdah/goldie/v2"
@@ -102,6 +104,57 @@ func TestDescriptor_Name(t *testing.T) {
 }
 }
 
+type testMetadata struct {
+Value int
+}
+
+func (m testMetadata) MarshalBinary() ([]byte, error) {
+return json.Marshal(m)
+}
+
+func (m *testMetadata) UnmarshalBinary(b []byte) error {
+return json.Unmarshal(bytes.TrimRight(b, "\x00"), m)
+}
+
+func TestDescriptor_GetMetadata(t *testing.T) {
+md := testMetadata{100}
+
+rd := rawDescriptor{
+DataType: DataGeneric,
+}
+if err := rd.setExtra(md); err != nil {
+t.Fatal(err)
+}
+
+tests := []struct {
+name string
+rd rawDescriptor
+wantMD any
+wantErr error
+}{
+{
+name: "OK",
+rd: rd,
+wantMD: md,
+},
+}
+for _, tt := range tests {
+t.Run(tt.name, func(t *testing.T) {
+d := Descriptor{raw: tt.rd}
+
+var md testMetadata
+
+if got, want := d.GetMetadata(&md), tt.wantErr; !errors.Is(got, want) {
+t.Fatalf("got error %v, want %v", got, want)
+}
+
+if got, want := md, tt.wantMD; !reflect.DeepEqual(got, want) {
+t.Fatalf("got metadata %v, want %v", got, want)
+}
+})
+}
+}
+
 func TestDescriptor_PartitionMetadata(t *testing.T) {
 p := partition{
 Fstype: FsSquash,