[#170] version: Add docs, refactor

Signed-off-by: Alex Vanin <alexey@nspcc.ru>
This commit is contained in:
Alex Vanin 2022-03-23 18:35:44 +03:00 committed by LeL
parent 3e75660802
commit ade8822a2f
21 changed files with 142 additions and 144 deletions

View file

@ -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
}

View file

@ -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)

View file

@ -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()))
}

View file

@ -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 {

View file

@ -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())
})
}

View file

@ -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)

View file

@ -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(),
},

View file

@ -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
}

View file

@ -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())
})

View file

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

View file

@ -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
}

View file

@ -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)
})
}

View file

@ -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) {

View file

@ -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())

View file

@ -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)) {

View file

@ -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()

16
version/doc.go Normal file
View file

@ -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

6
version/test/doc.go Normal file
View file

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

View file

@ -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
}

View file

@ -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() &&

View file

@ -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())
})
}