[#170] version: Add docs, refactor

Signed-off-by: Alex Vanin <alexey@nspcc.ru>

audit/result.go

@@ -2,6 +2,7 @@ package audit
 
 import (
 	"github.com/nspcc-dev/neofs-api-go/v2/audit"
+	"github.com/nspcc-dev/neofs-api-go/v2/refs"
 	cid "github.com/nspcc-dev/neofs-sdk-go/container/id"
 	oid "github.com/nspcc-dev/neofs-sdk-go/object/id"
 	"github.com/nspcc-dev/neofs-sdk-go/version"
@@ -28,7 +29,9 @@ type Result struct {
 // See also Unmarshal.
 func (r *Result) Marshal() []byte {
 	if !r.versionEncoded {
-		r.v2.SetVersion(version.Current().ToV2())
+		var verV2 refs.Version
+		version.Current().WriteToV2(&verV2)
+		r.v2.SetVersion(&verV2)
 		r.versionEncoded = true
 	}
 

client/common.go

@@ -4,6 +4,7 @@ import (
 	"crypto/ecdsa"
 	"fmt"
 
+	"github.com/nspcc-dev/neofs-api-go/v2/refs"
 	"github.com/nspcc-dev/neofs-api-go/v2/rpc/client"
 	v2session "github.com/nspcc-dev/neofs-api-go/v2/session"
 	"github.com/nspcc-dev/neofs-api-go/v2/signature"
@@ -159,7 +160,9 @@ func (x contextCall) prepareRequest() {
 	}
 
 	if meta.GetVersion() == nil {
-		meta.SetVersion(version.Current().ToV2())
+		var verV2 refs.Version
+		version.Current().WriteToV2(&verV2)
+		meta.SetVersion(&verV2)
 	}
 
 	meta.SetNetworkMagic(x.netMagic)

client/netmap.go

@@ -91,7 +91,11 @@ func (c *Client) EndpointInfo(ctx context.Context, prm PrmEndpointInfo) (*ResEnd
 
 		body := resp.GetBody()
 
-		res.setLatestVersion(version.NewFromV2(body.GetVersion()))
+		var ver version.Version
+		if v2ver := body.GetVersion(); v2ver != nil {
+			ver.ReadFromV2(*v2ver)
+		}
+		res.setLatestVersion(&ver)
 		res.setNodeInfo(netmap.NewNodeInfoFromV2(body.GetNodeInfo()))
 	}
 

container/container.go

@@ -5,6 +5,7 @@ import (
 
 	"github.com/google/uuid"
 	"github.com/nspcc-dev/neofs-api-go/v2/container"
+	"github.com/nspcc-dev/neofs-api-go/v2/refs"
 	"github.com/nspcc-dev/neofs-sdk-go/acl"
 	cid "github.com/nspcc-dev/neofs-sdk-go/container/id"
 	"github.com/nspcc-dev/neofs-sdk-go/netmap"
@@ -53,7 +54,8 @@ func New(opts ...Option) *Container {
 	}
 
 	cnr.SetAttributes(cnrOptions.attributes)
-	cnr.SetVersion(version.Current())
+	ver := version.Current()
+	cnr.SetVersion(&ver)
 
 	return cnr
 }
@@ -98,11 +100,17 @@ func CalculateID(c *Container) *cid.ID {
 }
 
 func (c *Container) Version() *version.Version {
-	return version.NewFromV2(c.v2.GetVersion())
+	var ver version.Version
+	if v2ver := c.v2.GetVersion(); v2ver != nil {
+		ver.ReadFromV2(*c.v2.GetVersion())
+	}
+	return &ver
 }
 
 func (c *Container) SetVersion(v *version.Version) {
-	c.v2.SetVersion(v.ToV2())
+	var verV2 refs.Version
+	v.WriteToV2(&verV2)
+	c.v2.SetVersion(&verV2)
 }
 
 func (c *Container) OwnerID() *owner.ID {

container/container_test.go

@@ -4,6 +4,7 @@ import (
 	"testing"
 
 	"github.com/google/uuid"
+	"github.com/nspcc-dev/neofs-api-go/v2/refs"
 	"github.com/nspcc-dev/neofs-sdk-go/acl"
 	"github.com/nspcc-dev/neofs-sdk-go/container"
 	containertest "github.com/nspcc-dev/neofs-sdk-go/container/test"
@@ -34,7 +35,7 @@ func TestNewContainer(t *testing.T) {
 	c.SetOwnerID(ownerID)
 
 	ver := versiontest.Version()
-	c.SetVersion(ver)
+	c.SetVersion(&ver)
 
 	v2 := c.ToV2()
 	newContainer := container.NewContainerFromV2(v2)
@@ -48,7 +49,7 @@ func TestNewContainer(t *testing.T) {
 
 	require.EqualValues(t, newNonce, nonce)
 	require.EqualValues(t, newContainer.OwnerID(), ownerID)
-	require.EqualValues(t, newContainer.Version(), ver)
+	require.EqualValues(t, *newContainer.Version(), ver)
 }
 
 func TestContainerEncoding(t *testing.T) {
@@ -112,7 +113,7 @@ func TestContainer_ToV2(t *testing.T) {
 		require.Nil(t, cnt.OwnerID())
 
 		require.EqualValues(t, acl.PrivateBasicRule, cnt.BasicACL())
-		require.Equal(t, version.Current(), cnt.Version())
+		require.Equal(t, version.Current(), *cnt.Version())
 
 		nonce, err := cnt.NonceUUID()
 		require.NoError(t, err)
@@ -131,6 +132,9 @@ func TestContainer_ToV2(t *testing.T) {
 		require.Nil(t, cntV2.GetOwnerID())
 
 		require.Equal(t, uint32(acl.PrivateBasicRule), cntV2.GetBasicACL())
-		require.Equal(t, version.Current().ToV2(), cntV2.GetVersion())
+
+		var verV2 refs.Version
+		version.Current().WriteToV2(&verV2)
+		require.Equal(t, verV2, *cntV2.GetVersion())
 	})
 }

container/test/generate.go

@@ -26,8 +26,9 @@ func Attributes() container.Attributes {
 // Container returns random container.Container.
 func Container() *container.Container {
 	x := container.New()
+	ver := versiontest.Version()
 
-	x.SetVersion(versiontest.Version())
+	x.SetVersion(&ver)
 	x.SetAttributes(Attributes())
 	x.SetOwnerID(ownertest.ID())
 	x.SetBasicACL(123)

eacl/record_test.go

@@ -170,7 +170,7 @@ func TestReservedRecords(t *testing.T) {
 			value: "bar",
 		},
 		{
-			f:     func(r *Record) { r.AddObjectVersionFilter(MatchStringEqual, v) },
+			f:     func(r *Record) { r.AddObjectVersionFilter(MatchStringEqual, &v) },
 			key:   v2acl.FilterObjectVersion,
 			value: v.String(),
 		},

eacl/table.go

@@ -4,6 +4,7 @@ import (
 	"crypto/sha256"
 
 	v2acl "github.com/nspcc-dev/neofs-api-go/v2/acl"
+	"github.com/nspcc-dev/neofs-api-go/v2/refs"
 	cid "github.com/nspcc-dev/neofs-sdk-go/container/id"
 	"github.com/nspcc-dev/neofs-sdk-go/session"
 	"github.com/nspcc-dev/neofs-sdk-go/signature"
@@ -98,7 +99,9 @@ func (t *Table) ToV2() *v2acl.Table {
 		v2.SetRecords(records)
 	}
 
-	v2.SetVersion(t.version.ToV2())
+	var verV2 refs.Version
+	t.version.WriteToV2(&verV2)
+	v2.SetVersion(&verV2)
 
 	return v2
 }
@@ -113,7 +116,7 @@ func (t *Table) ToV2() *v2acl.Table {
 //  - signature: nil.
 func NewTable() *Table {
 	t := new(Table)
-	t.SetVersion(*version.Current())
+	t.SetVersion(version.Current())
 
 	return t
 }

eacl/table_test.go

@@ -4,6 +4,7 @@ import (
 	"crypto/sha256"
 	"testing"
 
+	"github.com/nspcc-dev/neofs-api-go/v2/refs"
 	cidtest "github.com/nspcc-dev/neofs-sdk-go/container/id/test"
 	"github.com/nspcc-dev/neofs-sdk-go/eacl"
 	eacltest "github.com/nspcc-dev/neofs-sdk-go/eacl/test"
@@ -46,7 +47,7 @@ func TestTable(t *testing.T) {
 
 		table := eacl.CreateTable(*id)
 		require.Equal(t, id, table.CID())
-		require.Equal(t, *version.Current(), table.Version())
+		require.Equal(t, version.Current(), table.Version())
 	})
 }
 
@@ -121,7 +122,7 @@ func TestTable_ToV2(t *testing.T) {
 		table := eacl.NewTable()
 
 		// check initial values
-		require.Equal(t, *version.Current(), table.Version())
+		require.Equal(t, version.Current(), table.Version())
 		require.Nil(t, table.Records())
 		require.Nil(t, table.CID())
 		require.Nil(t, table.SessionToken())
@@ -130,7 +131,9 @@ func TestTable_ToV2(t *testing.T) {
 		// convert to v2 message
 		tableV2 := table.ToV2()
 
-		require.Equal(t, version.Current().ToV2(), tableV2.GetVersion())
+		var verV2 refs.Version
+		version.Current().WriteToV2(&verV2)
+		require.Equal(t, verV2, *tableV2.GetVersion())
 		require.Nil(t, tableV2.GetRecords())
 		require.Nil(t, tableV2.GetContainerID())
 	})

eacl/test/benchmark_test.go

@@ -110,7 +110,7 @@ func TableN(n int) *eacl.Table {
 		x.AddRecord(RecordN(n))
 	}
 
-	x.SetVersion(*versiontest.Version())
+	x.SetVersion(versiontest.Version())
 
 	return x
 }

eacl/test/generate.go

@@ -39,7 +39,7 @@ func Table() *eacl.Table {
 	x.SetCID(cidtest.ID())
 	x.AddRecord(Record())
 	x.AddRecord(Record())
-	x.SetVersion(*versiontest.Version())
+	x.SetVersion(versiontest.Version())
 
 	return x
 }

object/object.go

@@ -122,17 +122,20 @@ func (o *Object) SetPayload(v []byte) {
 
 // Version returns version of the object.
 func (o *Object) Version() *version.Version {
-	return version.NewFromV2(
+	var ver version.Version
-		(*object.Object)(o).
+	if verV2 := (*object.Object)(o).GetHeader().GetVersion(); verV2 != nil {
-			GetHeader().
+		ver.ReadFromV2(*verV2)
-			GetVersion(),
+	}
-	)
+	return &ver
 }
 
 // SetVersion sets version of the object.
 func (o *Object) SetVersion(v *version.Version) {
+	var verV2 refs.Version
+	v.WriteToV2(&verV2)
+
 	o.setHeaderField(func(h *object.Header) {
-		h.SetVersion(v.ToV2())
+		h.SetVersion(&verV2)
 	})
 }
 

object/raw_test.go

@@ -73,13 +73,13 @@ func TestObject_SetPayload(t *testing.T) {
 func TestObject_SetVersion(t *testing.T) {
 	obj := New()
 
-	ver := version.New()
+	var ver version.Version
 	ver.SetMajor(1)
 	ver.SetMinor(2)
 
-	obj.SetVersion(ver)
+	obj.SetVersion(&ver)
 
-	require.Equal(t, ver, obj.Version())
+	require.Equal(t, ver, *obj.Version())
 }
 
 func TestObject_SetPayloadSize(t *testing.T) {

object/test/generate.go

@@ -44,6 +44,7 @@ func SplitID() *object.SplitID {
 
 func generate(withParent bool) *object.Object {
 	x := object.New()
+	ver := version.Current()
 
 	x.SetID(oidtest.ID())
 	x.SetSessionToken(sessiontest.Token())
@@ -51,7 +52,7 @@ func generate(withParent bool) *object.Object {
 	x.SetOwnerID(ownertest.ID())
 	x.SetContainerID(cidtest.ID())
 	x.SetType(object.TypeTombstone)
-	x.SetVersion(version.Current())
+	x.SetVersion(&ver)
 	x.SetPayloadSize(111)
 	x.SetCreationEpoch(222)
 	x.SetPreviousID(oidtest.ID())

reputation/trust.go

@@ -178,7 +178,8 @@ type GlobalTrust reputation.GlobalTrust
 //  - trust: nil.
 func NewGlobalTrust() *GlobalTrust {
 	gt := GlobalTrustFromV2(new(reputation.GlobalTrust))
-	gt.SetVersion(version.Current())
+	ver := version.Current()
+	gt.SetVersion(&ver)
 
 	return gt
 }
@@ -201,13 +202,18 @@ func (x *GlobalTrust) ToV2() *reputation.GlobalTrust {
 
 // SetVersion sets GlobalTrust's protocol version.
 func (x *GlobalTrust) SetVersion(version *version.Version) {
-	(*reputation.GlobalTrust)(x).SetVersion(version.ToV2())
+	var verV2 refs.Version
+	version.WriteToV2(&verV2)
+	(*reputation.GlobalTrust)(x).SetVersion(&verV2)
 }
 
 // Version returns GlobalTrust's protocol version.
 func (x *GlobalTrust) Version() *version.Version {
-	return version.NewFromV2(
+	var ver version.Version
-		(*reputation.GlobalTrust)(x).GetVersion())
+	if verV2 := (*reputation.GlobalTrust)(x).GetVersion(); verV2 != nil {
+		ver.ReadFromV2(*verV2)
+	}
+	return &ver
 }
 
 func (x *GlobalTrust) setBodyField(setter func(*reputation.GlobalTrustBody)) {

reputation/trust_test.go

@@ -102,15 +102,15 @@ func TestGlobalTrust(t *testing.T) {
 	t.Run("getters+setters", func(t *testing.T) {
 		gt := reputation.NewGlobalTrust()
 
-		require.Equal(t, version.Current(), gt.Version())
+		require.Equal(t, version.Current(), *gt.Version())
 		require.Nil(t, gt.Manager())
 		require.Nil(t, gt.Trust())
 
-		version := version.New()
+		var ver version.Version
-		version.SetMajor(13)
+		ver.SetMajor(13)
-		version.SetMinor(31)
+		ver.SetMinor(31)
-		gt.SetVersion(version)
+		gt.SetVersion(&ver)
-		require.Equal(t, version, gt.Version())
+		require.Equal(t, ver, *gt.Version())
 
 		mngr := reputationtest.PeerID()
 		gt.SetManager(mngr)
@@ -240,7 +240,7 @@ func TestNewGlobalTrust(t *testing.T) {
 		require.Nil(t, trust.Manager())
 		require.Nil(t, trust.Trust())
 
-		require.Equal(t, version.Current().String(), trust.Version().String())
+		require.Equal(t, version.Current(), *trust.Version())
 
 		// convert to v2 message
 		trustV2 := trust.ToV2()

version/doc.go

@@ -0,0 +1,16 @@
+/*
+Package version provides functionality for NeoFS versioning.
+
+NeoFS uses NeoFS API versioning scheme. It uses major and minor version of
+the API.
+
+In most of the cases it will be enough to use the latest supported NeoFS API
+version in SDK:
+	ver := version.Current()
+
+It is possible to specify arbitrary version by setting major and minor numbers:
+	var ver version.Version
+	ver.SetMajor(2)
+	ver.SetMinor(5)
+*/
+package version

version/test/doc.go

@@ -0,0 +1,6 @@
+/*
+Package versiontest provides functions for testing version package.
+
+Note that this package intended only for tests.
+*/
+package versiontest

version/test/generate.go

@@ -7,11 +7,8 @@ import (
 )
 
 // Version returns random version.Version.
-func Version() *version.Version {
+func Version() (v version.Version) {
-	x := version.New()
+	v.SetMajor(rand.Uint32())
-
+	v.SetMinor(rand.Uint32())
-	x.SetMajor(rand.Uint32())
+	return v
-	x.SetMinor(rand.Uint32())
-
-	return x
 }

version/version.go

@@ -6,34 +6,24 @@ import (
 	"github.com/nspcc-dev/neofs-api-go/v2/refs"
 )
 
-// Version represents v2-compatible version.
+// Version represents revision number in SemVer scheme.
+//
+// Version is mutually compatible with github.com/nspcc-dev/neofs-api-go/v2/refs.Version
+// message. See ReadFromV2 / WriteToV2 methods.
+//
+// Instances can be created using built-in var declaration.
+//
+// Note that direct typecast is not safe and may result in loss of compatibility:
+// 	_ = Version(refs.Version{}) // not recommended
 type Version refs.Version
 
-const sdkMjr, sdkMnr = 2, 11
+const sdkMjr, sdkMnr = 2, 12
 
-// NewFromV2 wraps v2 Version message to Version.
+// Current returns Version instance that initialized to the
-//
+// latest supported NeoFS API revision number in SDK.
-// Nil refs.Version converts to nil.
+func Current() (v Version) {
-func NewFromV2(v *refs.Version) *Version {
-	return (*Version)(v)
-}
-
-// New creates and initializes blank Version.
-//
-// Defaults:
-//  - major: 0;
-//  - minor: 0.
-func New() *Version {
-	return NewFromV2(new(refs.Version))
-}
-
-// Current returns Version instance that
-// initialized to current SDK revision number.
-func Current() *Version {
-	v := New()
 	v.SetMajor(sdkMjr)
 	v.SetMinor(sdkMnr)
-
 	return v
 }
 
@@ -57,37 +47,27 @@ func (v *Version) SetMinor(val uint32) {
 	(*refs.Version)(v).SetMinor(val)
 }
 
-// ToV2 converts Version to v2 Version message.
+// WriteToV2 writes Version to the refs.Version message.
+// The message must not be nil.
 //
-// Nil Version converts to nil.
+// See also ReadFromV2.
-func (v *Version) ToV2() *refs.Version {
+func (v Version) WriteToV2(m *refs.Version) {
-	return (*refs.Version)(v)
+	*m = (refs.Version)(v)
 }
 
-func (v *Version) String() string {
+// ReadFromV2 reads Version from the refs.Version message.
+//
+// See also WriteToV2.
+func (v *Version) ReadFromV2(m refs.Version) {
+	*v = Version(m)
+}
+
+// String returns semver formatted value without patch and with v prefix,
+// e.g. 'v2.1'.
+func (v Version) String() string {
 	return fmt.Sprintf("v%d.%d", v.Major(), v.Minor())
 }
 
-// Marshal marshals Version into a protobuf binary form.
-func (v *Version) Marshal() ([]byte, error) {
-	return (*refs.Version)(v).StableMarshal(nil)
-}
-
-// Unmarshal unmarshals protobuf binary representation of Version.
-func (v *Version) Unmarshal(data []byte) error {
-	return (*refs.Version)(v).Unmarshal(data)
-}
-
-// MarshalJSON encodes Version to protobuf JSON format.
-func (v *Version) MarshalJSON() ([]byte, error) {
-	return (*refs.Version)(v).MarshalJSON()
-}
-
-// UnmarshalJSON decodes Version from protobuf JSON format.
-func (v *Version) UnmarshalJSON(data []byte) error {
-	return (*refs.Version)(v).UnmarshalJSON(data)
-}
-
 // Equal returns true if versions are identical.
 func (v Version) Equal(v2 Version) bool {
 	return v.Major() == v2.Major() &&

version/version_test.go

@@ -9,31 +9,33 @@ import (
 
 func TestNewVersion(t *testing.T) {
 	t.Run("default values", func(t *testing.T) {
-		v := New()
+		var v Version
 
 		// check initial values
 		require.Zero(t, v.Major())
 		require.Zero(t, v.Minor())
 
 		// convert to v2 message
-		vV2 := v.ToV2()
+		var vV2 refs.Version
+		v.WriteToV2(&vV2)
 
-		require.Empty(t, vV2.GetMajor())
+		require.Zero(t, vV2.GetMajor())
-		require.Empty(t, vV2.GetMinor())
+		require.Zero(t, vV2.GetMinor())
 	})
 
 	t.Run("setting values", func(t *testing.T) {
-		v := New()
+		var v Version
 
 		var mjr, mnr uint32 = 1, 2
 
 		v.SetMajor(mjr)
 		v.SetMinor(mnr)
-
 		require.Equal(t, mjr, v.Major())
 		require.Equal(t, mnr, v.Minor())
 
-		ver := v.ToV2()
+		// convert to v2 message
+		var ver refs.Version
+		v.WriteToV2(&ver)
 
 		require.Equal(t, mjr, ver.GetMajor())
 		require.Equal(t, mnr, ver.GetMinor())
@@ -46,45 +48,3 @@ func TestSDKVersion(t *testing.T) {
 	require.Equal(t, uint32(sdkMjr), v.Major())
 	require.Equal(t, uint32(sdkMnr), v.Minor())
 }
-
-func TestVersionEncoding(t *testing.T) {
-	v := New()
-	v.SetMajor(1)
-	v.SetMinor(2)
-
-	t.Run("binary", func(t *testing.T) {
-		data, err := v.Marshal()
-		require.NoError(t, err)
-
-		v2 := New()
-		require.NoError(t, v2.Unmarshal(data))
-
-		require.Equal(t, v, v2)
-	})
-
-	t.Run("json", func(t *testing.T) {
-		data, err := v.MarshalJSON()
-		require.NoError(t, err)
-
-		v2 := New()
-		require.NoError(t, v2.UnmarshalJSON(data))
-
-		require.Equal(t, v, v2)
-	})
-}
-
-func TestNewVersionFromV2(t *testing.T) {
-	t.Run("from nil", func(t *testing.T) {
-		var x *refs.Version
-
-		require.Nil(t, NewFromV2(x))
-	})
-}
-
-func TestVersion_ToV2(t *testing.T) {
-	t.Run("nil", func(t *testing.T) {
-		var x *Version
-
-		require.Nil(t, x.ToV2())
-	})
-}