From ade8822a2f6b082291cbcba3bf3611d4a7cf7e73 Mon Sep 17 00:00:00 2001 From: Alex Vanin Date: Wed, 23 Mar 2022 18:35:44 +0300 Subject: [PATCH] [#170] version: Add docs, refactor Signed-off-by: Alex Vanin --- audit/result.go | 5 ++- client/common.go | 5 ++- client/netmap.go | 6 ++- container/container.go | 14 +++++-- container/container_test.go | 12 ++++-- container/test/generate.go | 3 +- eacl/record_test.go | 2 +- eacl/table.go | 7 +++- eacl/table_test.go | 9 +++-- eacl/test/benchmark_test.go | 2 +- eacl/test/generate.go | 2 +- object/object.go | 15 +++++--- object/raw_test.go | 6 +-- object/test/generate.go | 3 +- reputation/trust.go | 14 +++++-- reputation/trust_test.go | 14 +++---- version/doc.go | 16 ++++++++ version/test/doc.go | 6 +++ version/test/generate.go | 11 ++---- version/version.go | 76 ++++++++++++++----------------------- version/version_test.go | 58 +++++----------------------- 21 files changed, 142 insertions(+), 144 deletions(-) create mode 100644 version/doc.go create mode 100644 version/test/doc.go diff --git a/audit/result.go b/audit/result.go index 3a3d73c9..744ed7a4 100644 --- a/audit/result.go +++ b/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 } diff --git a/client/common.go b/client/common.go index b1fd7d6f..7c82183e 100644 --- a/client/common.go +++ b/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) diff --git a/client/netmap.go b/client/netmap.go index 86384e53..aeb16b2a 100644 --- a/client/netmap.go +++ b/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())) } diff --git a/container/container.go b/container/container.go index b9bff7b6..d2b9bb6c 100644 --- a/container/container.go +++ b/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 { diff --git a/container/container_test.go b/container/container_test.go index ee87061b..2d00c674 100644 --- a/container/container_test.go +++ b/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()) }) } diff --git a/container/test/generate.go b/container/test/generate.go index f16f705e..b0bf5cda 100644 --- a/container/test/generate.go +++ b/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) diff --git a/eacl/record_test.go b/eacl/record_test.go index edc19456..1163bdfb 100644 --- a/eacl/record_test.go +++ b/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(), }, diff --git a/eacl/table.go b/eacl/table.go index 555a1d89..75c07552 100644 --- a/eacl/table.go +++ b/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 } diff --git a/eacl/table_test.go b/eacl/table_test.go index 18331b0b..a9737cb6 100644 --- a/eacl/table_test.go +++ b/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()) }) diff --git a/eacl/test/benchmark_test.go b/eacl/test/benchmark_test.go index d1bd7c6f..2f40446c 100644 --- a/eacl/test/benchmark_test.go +++ b/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 } diff --git a/eacl/test/generate.go b/eacl/test/generate.go index 895d11ee..f316024c 100644 --- a/eacl/test/generate.go +++ b/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 } diff --git a/object/object.go b/object/object.go index ac394372..37140ee1 100644 --- a/object/object.go +++ b/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( - (*object.Object)(o). - GetHeader(). - GetVersion(), - ) + var ver version.Version + if verV2 := (*object.Object)(o).GetHeader().GetVersion(); verV2 != nil { + ver.ReadFromV2(*verV2) + } + 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) }) } diff --git a/object/raw_test.go b/object/raw_test.go index 4c6b9abd..930afc77 100644 --- a/object/raw_test.go +++ b/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) { diff --git a/object/test/generate.go b/object/test/generate.go index 7af9347d..3df931ed 100644 --- a/object/test/generate.go +++ b/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()) diff --git a/reputation/trust.go b/reputation/trust.go index ec7eea7d..b55b7b04 100644 --- a/reputation/trust.go +++ b/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( - (*reputation.GlobalTrust)(x).GetVersion()) + var ver version.Version + if verV2 := (*reputation.GlobalTrust)(x).GetVersion(); verV2 != nil { + ver.ReadFromV2(*verV2) + } + return &ver } func (x *GlobalTrust) setBodyField(setter func(*reputation.GlobalTrustBody)) { diff --git a/reputation/trust_test.go b/reputation/trust_test.go index 74616708..5c81ee56 100644 --- a/reputation/trust_test.go +++ b/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() - version.SetMajor(13) - version.SetMinor(31) - gt.SetVersion(version) - require.Equal(t, version, gt.Version()) + var ver version.Version + ver.SetMajor(13) + ver.SetMinor(31) + gt.SetVersion(&ver) + 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() diff --git a/version/doc.go b/version/doc.go new file mode 100644 index 00000000..bd1ca8e2 --- /dev/null +++ b/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 diff --git a/version/test/doc.go b/version/test/doc.go new file mode 100644 index 00000000..04266e99 --- /dev/null +++ b/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 diff --git a/version/test/generate.go b/version/test/generate.go index 39b1b11f..b4ea64f1 100644 --- a/version/test/generate.go +++ b/version/test/generate.go @@ -7,11 +7,8 @@ import ( ) // Version returns random version.Version. -func Version() *version.Version { - x := version.New() - - x.SetMajor(rand.Uint32()) - x.SetMinor(rand.Uint32()) - - return x +func Version() (v version.Version) { + v.SetMajor(rand.Uint32()) + v.SetMinor(rand.Uint32()) + return v } diff --git a/version/version.go b/version/version.go index a1f30ac3..76cad82e 100644 --- a/version/version.go +++ b/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. -// -// Nil refs.Version converts to nil. -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() +// Current returns Version instance that initialized to the +// latest supported NeoFS API revision number in SDK. +func Current() (v Version) { 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. -func (v *Version) ToV2() *refs.Version { - return (*refs.Version)(v) +// See also ReadFromV2. +func (v Version) WriteToV2(m *refs.Version) { + *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() && diff --git a/version/version_test.go b/version/version_test.go index d823c028..0d1aa0ab 100644 --- a/version/version_test.go +++ b/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.Empty(t, vV2.GetMinor()) + require.Zero(t, vV2.GetMajor()) + 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()) - }) -}