diff --git a/accounting/doc.go b/accounting/doc.go index f1a30373..df72ff60 100644 --- a/accounting/doc.go +++ b/accounting/doc.go @@ -1,33 +1,7 @@ /* Package accounting provides primitives to perform accounting operations in NeoFS. -Decimal type provides functionality to process user balances. For example, when -working with Fixed8 balance precision: - - var dec accounting.Decimal - dec.SetValue(val) - dec.SetPrecision(8) - -Instances can be also used to process NeoFS API V2 protocol messages -(see neo.fs.v2.accounting package in https://github.com/nspcc-dev/neofs-api). - -On client side: - - import "github.com/nspcc-dev/neofs-api-go/v2/accounting" - - var msg accounting.Decimal - dec.WriteToV2(&msg) - - // send msg - -On server side: - - // recv msg - - var dec accounting.Decimal - dec.ReadFromV2(msg) - - // process dec +Decimal type provides functionality to process user balances. Using package types in an application is recommended to potentially work with different protocol versions with which these types are compatible. diff --git a/accounting/example_test.go b/accounting/example_test.go new file mode 100644 index 00000000..1cedc39d --- /dev/null +++ b/accounting/example_test.go @@ -0,0 +1,41 @@ +package accounting_test + +import ( + apiGoAccounting "github.com/nspcc-dev/neofs-api-go/v2/accounting" + "github.com/nspcc-dev/neofs-sdk-go/accounting" +) + +// Decimal type provides functionality to process user balances. For example, when +// working with Fixed8 balance precision. +func ExampleDecimal_SetValue() { + var val int64 + + var dec accounting.Decimal + dec.SetValue(val) + dec.SetPrecision(8) +} + +// Instances can be also used to process NeoFS API V2 protocol messages +// (see neo.fs.v2.accounting package in https://github.com/nspcc-dev/neofs-api) on client side. +func ExampleDecimal_WriteToV2() { + // import apiGoAccounting "github.com/nspcc-dev/neofs-api-go/v2/accounting" + + var dec accounting.Decimal + var msg apiGoAccounting.Decimal + dec.WriteToV2(&msg) + + // send msg +} + +// Instances can be also used to process NeoFS API V2 protocol messages +// (see neo.fs.v2.accounting package in https://github.com/nspcc-dev/neofs-api) on server side. +func ExampleDecimal_ReadFromV2() { + // import apiGoAccounting "github.com/nspcc-dev/neofs-api-go/v2/accounting" + + var dec accounting.Decimal + var msg apiGoAccounting.Decimal + + _ = dec.ReadFromV2(msg) + + // send msg +} diff --git a/audit/doc.go b/audit/doc.go index a41f88d8..507dc595 100644 --- a/audit/doc.go +++ b/audit/doc.go @@ -1,25 +1,6 @@ /* Package audit provides features to process data audit in NeoFS system. -Result type groups values which can be gathered during data audit process: - - var res audit.Result - res.ForEpoch(32) - res.ForContainer(cnr) - // ... - res.Complete() - -Result instances can be stored in a binary format. On reporter side: - - data := res.Marshal() - // send data - -On receiver side: - - var res audit.Result - err := res.Unmarshal(data) - // ... - Using package types in an application is recommended to potentially work with different protocol versions with which these types are compatible. */ diff --git a/audit/example_test.go b/audit/example_test.go new file mode 100644 index 00000000..d2a84766 --- /dev/null +++ b/audit/example_test.go @@ -0,0 +1,36 @@ +package audit_test + +import ( + "github.com/nspcc-dev/neofs-sdk-go/audit" + cid "github.com/nspcc-dev/neofs-sdk-go/container/id" +) + +// Result type groups values which can be gathered during data audit process. +func Example() { + var res audit.Result + var cnr cid.ID + + res.ForEpoch(32) + res.ForContainer(cnr) + // ... + res.Complete() +} + +// Result instances can be stored in a binary format on reporter side. +func ExampleResult_Marshal() { + var res audit.Result + data := res.Marshal() + _ = data + + // send data +} + +// Result instances can be restored from a binary format on receiver side. +func ExampleResult_Unmarshal() { + var data []byte + + var res audit.Result + _ = res.Unmarshal(data) + + // process result +} diff --git a/bearer/doc.go b/bearer/doc.go index 52436eb1..86cd3381 100644 --- a/bearer/doc.go +++ b/bearer/doc.go @@ -4,28 +4,5 @@ Package bearer provides bearer token definition. Bearer token is attached to the object service requests, and it overwrites extended ACL of the container. Mainly it is used to provide access of private data for specific user. Therefore, it must be signed by owner of the container. - -Define bearer token by setting correct lifetime, extended ACL and owner ID of -the user that will attach token to its requests. - - var bearerToken bearer.Token - bearerToken.SetExpiration(500) - bearerToken.SetIssuedAt(10) - bearerToken.SetNotBefore(10) - bearerToken.SetEACL(eaclTable) - bearerToken.SetOwner(ownerID) - -Bearer token must be signed by owner of the container. - - err := bearerToken.Sign(privateKey) - -Provide signed token in JSON or binary format to the request sender. Request -sender can attach this bearer token to the object service requests: - - import sdkClient "github.com/nspcc-dev/neofs-sdk-go/client" - - var headParams sdkClient.PrmObjectHead - headParams.WithBearerToken(bearerToken) - response, err := client.ObjectHead(ctx, headParams) */ package bearer diff --git a/bearer/example_test.go b/bearer/example_test.go new file mode 100644 index 00000000..ed30e18e --- /dev/null +++ b/bearer/example_test.go @@ -0,0 +1,68 @@ +package bearer_test + +import ( + "context" + + "github.com/nspcc-dev/neofs-sdk-go/bearer" + "github.com/nspcc-dev/neofs-sdk-go/client" + cid "github.com/nspcc-dev/neofs-sdk-go/container/id" + neofscrypto "github.com/nspcc-dev/neofs-sdk-go/crypto" + "github.com/nspcc-dev/neofs-sdk-go/eacl" + oid "github.com/nspcc-dev/neofs-sdk-go/object/id" + "github.com/nspcc-dev/neofs-sdk-go/user" +) + +// Define bearer token by setting correct lifetime, extended ACL and owner ID of +// the user that will attach token to its requests. +func Example() { + // import "github.com/nspcc-dev/neofs-sdk-go/eacl" + // import "github.com/nspcc-dev/neofs-sdk-go/user" + + var bearerToken bearer.Token + var ownerID user.ID + var eaclTable eacl.Table + + bearerToken.SetExp(500) + bearerToken.SetIat(10) + bearerToken.SetNbf(10) + bearerToken.SetEACLTable(eaclTable) + bearerToken.ForUser(ownerID) +} + +// Bearer token must be signed by owner of the container. +func ExampleToken_Sign() { + // import neofscrypto "github.com/nspcc-dev/neofs-sdk-go/crypto" + + var bearerToken bearer.Token + var signer neofscrypto.Signer + + // signer initialization, bearerToken initialization, other steps ... + + _ = bearerToken.Sign(signer) + + // ... +} + +// Provide signed token in JSON or binary format to the request sender. Request +// sender can attach this bearer token to the object service requests. +func ExampleToken_attachToRequest() { + // import "github.com/nspcc-dev/neofs-sdk-go/client" + // import "github.com/nspcc-dev/neofs-sdk-go/user" + // import oid "github.com/nspcc-dev/neofs-sdk-go/object/id" + // import cid "github.com/nspcc-dev/neofs-sdk-go/container/id" + + var bearerToken bearer.Token + var sdkClient *client.Client + var signer user.Signer + + // init bearerToken, sdkClient, signer, other steps ... + + var headParams client.PrmObjectHead + headParams.WithBearerToken(bearerToken) + // ... + + response, err := sdkClient.ObjectHead(context.Background(), cid.ID{}, oid.ID{}, signer, headParams) + + _ = response + _ = err +} diff --git a/checksum/doc.go b/checksum/doc.go index 859d67f3..94f30399 100644 --- a/checksum/doc.go +++ b/checksum/doc.go @@ -2,15 +2,6 @@ Package checksum provides primitives to work with checksums. Checksum is a basic type of data checksums. -For example, calculating checksums: - - // retrieving any payload for hashing - - var sha256Sum Checksum - Calculate(&sha256Sum, SHA256, payload) // sha256Sum contains SHA256 hash of the payload - - var tzSum Checksum - Calculate(&tzSum, TZ, payload) // tzSum contains TZ hash of the payload Using package types in an application is recommended to potentially work with different protocol versions with which these types are compatible. diff --git a/checksum/example_test.go b/checksum/example_test.go index 42239f21..458f231a 100644 --- a/checksum/example_test.go +++ b/checksum/example_test.go @@ -13,7 +13,10 @@ func ExampleCalculate() { payload := []byte{0, 1, 2, 3, 4, 5, 6} var cs Checksum + // sha256Sum contains SHA256 hash of the payload Calculate(&cs, SHA256, payload) + + // tzSum contains TZ hash of the payload Calculate(&cs, TZ, payload) } diff --git a/client/doc.go b/client/doc.go index 4ae629b8..21dc30cb 100644 --- a/client/doc.go +++ b/client/doc.go @@ -3,84 +3,5 @@ Package client provides NeoFS API client implementation. The main component is Client type. It is a virtual connection to the network and provides methods for executing operations on the server. - -Create client instance: - - var prm client.PrmInit - prm.SetDefaultSigner(signer) - // ... - - c, err := client.New(prm) - -Connect to the NeoFS server: - - var prm client.PrmDial - prm.SetServerURI("localhost:8080") - prm.SetDefaultSigner(signer) - // ... - - err := c.Dial(prm) - // ... - -Execute NeoFS operation on the server: - - var prm client.PrmContainerPut - // ... - - res, err := c.ContainerPut(context.Background(), cnr, prm) - err := c.Dial(dialPrm) - if err == nil { - err = apistatus.ErrFromStatus(res.Status()) - } - // ... - -Consume custom service of the server: - - syntax = "proto3"; - - service CustomService { - rpc CustomRPC(CustomRPCRequest) returns (CustomRPCResponse); - } - - import "github.com/nspcc-dev/neofs-api-go/v2/rpc/client" - import "github.com/nspcc-dev/neofs-api-go/v2/rpc/common" - - req := new(CustomRPCRequest) - // ... - resp := new(CustomRPCResponse) - - err := c.ExecRaw(func(c *client.Client) error { - return client.SendUnary(c, common.CallMethodInfo{ - Service: "CustomService", - Name: "CustomRPC", - }, req, resp) - }) - // ... - -Close the connection: - - err := c.Close() - // ... - -Note that it's not allowed to override Client behaviour directly: the parameters -for the all operations are write-only and the results of the all operations are -read-only. To be able to override client behavior (e.g. for tests), abstract it -with an interface: - - import "github.com/nspcc-dev/neofs-sdk-go/client" - - type NeoFSClient interface { - // Operations according to the application needs - CreateContainer(context.Context, container.Container) error - // ... - } - - type client struct { - c *client.Client - } - - func (x *client) CreateContainer(context.Context, container.Container) error { - // ... - } */ package client diff --git a/client/example_container_put_test.go b/client/example_container_put_test.go deleted file mode 100644 index 3f8f6a39..00000000 --- a/client/example_container_put_test.go +++ /dev/null @@ -1,104 +0,0 @@ -package client_test - -import ( - "context" - "fmt" - "time" - - "github.com/nspcc-dev/neo-go/pkg/crypto/keys" - netmapv2 "github.com/nspcc-dev/neofs-api-go/v2/netmap" - "github.com/nspcc-dev/neofs-sdk-go/client" - "github.com/nspcc-dev/neofs-sdk-go/container" - "github.com/nspcc-dev/neofs-sdk-go/container/acl" - cid "github.com/nspcc-dev/neofs-sdk-go/container/id" - "github.com/nspcc-dev/neofs-sdk-go/netmap" - "github.com/nspcc-dev/neofs-sdk-go/user" -) - -func ExampleClient_ContainerPut() { - ctx := context.Background() - var accountID user.ID - - // The account was taken from https://github.com/nspcc-dev/neofs-aio - key, err := keys.NEP2Decrypt("6PYM8VdX2BSm7BSXKzV4Fz6S3R9cDLLWNrD9nMjxW352jEv3fsC8N3wNLY", "one", keys.NEP2ScryptParams()) - if err != nil { - panic(err) - } - - signer := user.NewAutoIDSignerRFC6979(key.PrivateKey) - // take account from user's signer - accountID = signer.UserID() - - // prepare client - var prmInit client.PrmInit - - c, err := client.New(prmInit) - if err != nil { - panic(fmt.Errorf("New: %w", err)) - } - - // connect to NeoFS gateway - var prmDial client.PrmDial - prmDial.SetServerURI("grpc://localhost:8080") // endpoint address - prmDial.SetTimeout(15 * time.Second) - prmDial.SetStreamTimeout(15 * time.Second) - - if err = c.Dial(prmDial); err != nil { - panic(fmt.Errorf("dial %v", err)) - } - - // describe new container - cont := container.Container{} - // set version and nonce - cont.Init() - cont.SetOwner(accountID) - cont.SetBasicACL(acl.PublicRW) - - // set reserved attributes - cont.SetName("name-1") - cont.SetCreationTime(time.Now().UTC()) - - // init placement policy - var containerID cid.ID - var placementPolicyV2 netmapv2.PlacementPolicy - var replicas []netmapv2.Replica - - replica := netmapv2.Replica{} - replica.SetCount(1) - replicas = append(replicas, replica) - placementPolicyV2.SetReplicas(replicas) - - var placementPolicy netmap.PlacementPolicy - if err = placementPolicy.ReadFromV2(placementPolicyV2); err != nil { - panic(fmt.Errorf("ReadFromV2 %w", err)) - } - - placementPolicy.SetContainerBackupFactor(1) - cont.SetPlacementPolicy(placementPolicy) - - containerID, err = c.ContainerPut(ctx, cont, signer, client.PrmContainerPut{}) - if err != nil { - panic(fmt.Errorf("ContainerPut %w", err)) - } - - // containerID already exists - fmt.Println(containerID) - // example output: 76wa5UNiT8gk8Q5rdCVCV4pKuZSmYsifh6g84BcL6Hqs - - // but container creation is async operation. We should wait some time or make polling to ensure container created - // for simplifying we just wait - <-time.After(2 * time.Second) - - contRes, err := c.ContainerGet(ctx, containerID, client.PrmContainerGet{}) - if err != nil { - panic(fmt.Errorf("ContainerGet %w", err)) - } - - jsonData, err := contRes.MarshalJSON() - if err != nil { - panic(fmt.Errorf("MarshalJSON %w", err)) - } - - fmt.Println(string(jsonData)) - // example output: {"version":{"major":2,"minor":13},"ownerID":{"value":"Ne6eoiwn40vQFI/EEI4I906PUEiy8ZXKcw=="},"nonce":"rPVd/iw2RW6Q6d66FVnIqg==","basicACL":532660223,"attributes":[{"key":"Name","value":"name-1"},{"key":"Timestamp","value":"1681738627"}],"placementPolicy":{"replicas":[{"count":1,"selector":""}],"containerBackupFactor":1,"selectors":[],"filters":[],"subnetId":{"value":0}}} -} diff --git a/client/example_test.go b/client/example_test.go new file mode 100644 index 00000000..0d503556 --- /dev/null +++ b/client/example_test.go @@ -0,0 +1,237 @@ +package client_test + +import ( + "context" + "fmt" + "time" + + "github.com/nspcc-dev/neo-go/pkg/crypto/keys" + netmapv2 "github.com/nspcc-dev/neofs-api-go/v2/netmap" + rpcClient "github.com/nspcc-dev/neofs-api-go/v2/rpc/client" + "github.com/nspcc-dev/neofs-api-go/v2/rpc/common" + "github.com/nspcc-dev/neofs-api-go/v2/rpc/grpc" + "github.com/nspcc-dev/neofs-sdk-go/client" + "github.com/nspcc-dev/neofs-sdk-go/container" + "github.com/nspcc-dev/neofs-sdk-go/container/acl" + cid "github.com/nspcc-dev/neofs-sdk-go/container/id" + "github.com/nspcc-dev/neofs-sdk-go/netmap" + "github.com/nspcc-dev/neofs-sdk-go/user" + "github.com/nspcc-dev/neofs-sdk-go/waiter" +) + +func ExampleClient_createInstance() { + // Create client instance + var prm client.PrmInit + c, err := client.New(prm) + _ = err + + // Connect to the NeoFS server + var prmDial client.PrmDial + prmDial.SetServerURI("grpc://localhost:8080") // endpoint address + prmDial.SetTimeout(15 * time.Second) + prmDial.SetStreamTimeout(15 * time.Second) + + _ = c.Dial(prmDial) +} + +// Put a new container into NeoFS. +func ExampleClient_ContainerPut() { + ctx := context.Background() + var accountID user.ID + + // The account was taken from https://github.com/nspcc-dev/neofs-aio + key, err := keys.NEP2Decrypt("6PYM8VdX2BSm7BSXKzV4Fz6S3R9cDLLWNrD9nMjxW352jEv3fsC8N3wNLY", "one", keys.NEP2ScryptParams()) + if err != nil { + panic(err) + } + + signer := user.NewAutoIDSignerRFC6979(key.PrivateKey) + // take account from user's signer + accountID = signer.UserID() + + // prepare client + var prmInit client.PrmInit + + c, err := client.New(prmInit) + if err != nil { + panic(fmt.Errorf("New: %w", err)) + } + + // connect to NeoFS gateway + var prmDial client.PrmDial + prmDial.SetServerURI("grpc://localhost:8080") // endpoint address + prmDial.SetTimeout(15 * time.Second) + prmDial.SetStreamTimeout(15 * time.Second) + + if err = c.Dial(prmDial); err != nil { + panic(fmt.Errorf("dial %v", err)) + } + + // describe new container + cont := container.Container{} + // set version and nonce + cont.Init() + cont.SetOwner(accountID) + cont.SetBasicACL(acl.PublicRW) + + // set reserved attributes + cont.SetName("name-1") + cont.SetCreationTime(time.Now().UTC()) + + // init placement policy + var containerID cid.ID + var placementPolicyV2 netmapv2.PlacementPolicy + var replicas []netmapv2.Replica + + replica := netmapv2.Replica{} + replica.SetCount(1) + replicas = append(replicas, replica) + placementPolicyV2.SetReplicas(replicas) + + var placementPolicy netmap.PlacementPolicy + if err = placementPolicy.ReadFromV2(placementPolicyV2); err != nil { + panic(fmt.Errorf("ReadFromV2 %w", err)) + } + + placementPolicy.SetContainerBackupFactor(1) + cont.SetPlacementPolicy(placementPolicy) + + w := waiter.NewContainerPutWaiter(c, waiter.DefaultPollInterval) + + // waiter creates the container and waits until it will be created or context canceled. + containerID, err = w.ContainerPut(ctx, cont, signer, client.PrmContainerPut{}) + if err != nil { + panic(fmt.Errorf("ContainerPut %w", err)) + } + + // containerID already exists + fmt.Println(containerID) + // example output: 76wa5UNiT8gk8Q5rdCVCV4pKuZSmYsifh6g84BcL6Hqs + + contRes, err := c.ContainerGet(ctx, containerID, client.PrmContainerGet{}) + if err != nil { + panic(fmt.Errorf("ContainerGet %w", err)) + } + + jsonData, err := contRes.MarshalJSON() + if err != nil { + panic(fmt.Errorf("MarshalJSON %w", err)) + } + + fmt.Println(string(jsonData)) + // example output: + /* + { + "version": { + "major": 2, + "minor": 13 + }, + "ownerID": { + "value": "Ne6eoiwn40vQFI/EEI4I906PUEiy8ZXKcw==" + }, + "nonce": "rPVd/iw2RW6Q6d66FVnIqg==", + "basicACL": 532660223, + "attributes": [ + { + "key": "Name", + "value": "name-1" + }, + { + "key": "Timestamp", + "value": "1681738627" + } + ], + "placementPolicy": { + "replicas": [ + { + "count": 1, + "selector": "" + } + ], + "containerBackupFactor": 1, + "selectors": [], + "filters": [], + "subnetId": { + "value": 0 + } + } + } + */ +} + +type CustomRPCRequest struct { +} + +type CustomRPCResponse struct { +} + +func (a *CustomRPCRequest) ToGRPCMessage() grpc.Message { + return nil +} + +func (a *CustomRPCRequest) FromGRPCMessage(grpc.Message) error { + return nil +} + +func (a *CustomRPCResponse) ToGRPCMessage() grpc.Message { + return nil +} + +func (a *CustomRPCResponse) FromGRPCMessage(grpc.Message) error { + return nil +} + +// Consume custom service of the server. +func Example_customService() { + // syntax = "proto3"; + // + // service CustomService { + // rpc CustomRPC(CustomRPCRequest) returns (CustomRPCResponse); + // } + + // import "github.com/nspcc-dev/neofs-api-go/v2/rpc/client" + // import "github.com/nspcc-dev/neofs-api-go/v2/rpc/common" + + var prmInit client.PrmInit + // ... + + c, _ := client.New(prmInit) + + req := &CustomRPCRequest{} + resp := &CustomRPCResponse{} + + err := c.ExecRaw(func(c *rpcClient.Client) error { + return rpcClient.SendUnary(c, common.CallMethodInfo{ + Service: "CustomService", + Name: "CustomRPC", + }, req, resp) + }) + + _ = err + + // ... + + // Close the connection + _ = c.Close() + + // Note that it's not allowed to override Client behaviour directly: the parameters + // for the all operations are write-only and the results of the all operations are + // read-only. To be able to override client behavior (e.g. for tests), abstract it + // with an interface: + // + // import "github.com/nspcc-dev/neofs-sdk-go/client" + // + // type NeoFSClient interface { + // // Operations according to the application needs + // CreateContainer(context.Context, container.Container) error + // // ... + // } + // + // type client struct { + // c *client.Client + // } + // + // func (x *client) CreateContainer(context.Context, container.Container) error { + // // ... + // } +} diff --git a/container/doc.go b/container/doc.go index e333d48c..5b0e4c05 100644 --- a/container/doc.go +++ b/container/doc.go @@ -1,47 +1,7 @@ /* Package container provides functionality related to the NeoFS containers. -The base type is Container. To create new container in the NeoFS network -Container instance should be initialized - - var cnr Container - cnr.Init() - // fill all the fields - - // encode cnr and send - -After the container is persisted in the NeoFS network, applications can process -it using the instance of Container types - - // recv binary container - - var cnr Container - - err := cnr.Unmarshal(bin) - // ... - - // process the container data - -Instances can be also used to process NeoFS API V2 protocol messages -(see neo.fs.v2.container package in https://github.com/nspcc-dev/neofs-api). - -On client side: - - import "github.com/nspcc-dev/neofs-api-go/v2/container" - - var msg container.Container - cnr.WriteToV2(&msg) - - // send msg - -On server side: - - // recv msg - - var cnr Container - cnr.ReadFromV2(msg) - - // process cnr +The base type is Container. Using package types in an application is recommended to potentially work with different protocol versions with which these types are compatible. diff --git a/container/example_test.go b/container/example_test.go new file mode 100644 index 00000000..c7916070 --- /dev/null +++ b/container/example_test.go @@ -0,0 +1,79 @@ +package container_test + +import ( + "time" + + apiGoContainer "github.com/nspcc-dev/neofs-api-go/v2/container" + "github.com/nspcc-dev/neofs-sdk-go/container" + "github.com/nspcc-dev/neofs-sdk-go/container/acl" + "github.com/nspcc-dev/neofs-sdk-go/netmap" + "github.com/nspcc-dev/neofs-sdk-go/user" +) + +// To create new container in the NeoFS network Container instance should be initialized. +func ExampleContainer_Init() { + // import "github.com/nspcc-dev/neofs-sdk-go/container/acl" + // import "github.com/nspcc-dev/neofs-sdk-go/user" + // import "github.com/nspcc-dev/neofs-sdk-go/netmap" + + var account user.ID + + var cnr container.Container + cnr.Init() + + // required fields + cnr.SetOwner(account) + cnr.SetBasicACL(acl.PublicRWExtended) + + // optional + cnr.SetName("awesome container name") + cnr.SetCreationTime(time.Now()) + // ... + + // placement policy and replicas definition is required + var pp netmap.PlacementPolicy + pp.SetContainerBackupFactor(1) + + var rd netmap.ReplicaDescriptor + rd.SetNumberOfObjects(1) + pp.AddReplicas(rd) + + cnr.SetPlacementPolicy(pp) +} + +// After the container is persisted in the NeoFS network, applications can process +// it using the instance of Container types. +func ExampleContainer_Unmarshal() { + // recv binary container + + var bin []byte + var cnr container.Container + + _ = cnr.Unmarshal(bin) + + // process the container data +} + +// Instances can be also used to process NeoFS API V2 protocol messages +// (see neo.fs.v2.container package in https://github.com/nspcc-dev/neofs-api) on client side. +func ExampleContainer_WriteToV2() { + // import apiGoContainer "github.com/nspcc-dev/neofs-api-go/v2/container" + + var cnr container.Container + var msg apiGoContainer.Container + + cnr.WriteToV2(&msg) +} + +// Instances can be also used to process NeoFS API V2 protocol messages +// (see neo.fs.v2.container package in https://github.com/nspcc-dev/neofs-api) on server side. +func ExampleContainer_ReadFromV2() { + // import apiGoContainer "github.com/nspcc-dev/neofs-api-go/v2/container" + + var cnr container.Container + var msg apiGoContainer.Container + + _ = cnr.ReadFromV2(msg) + + // ... +} diff --git a/crypto/doc.go b/crypto/doc.go index fe97a31b..dae6fea1 100644 --- a/crypto/doc.go +++ b/crypto/doc.go @@ -3,48 +3,11 @@ Package neofscrypto collects NeoFS cryptographic primitives. Signer type unifies entities for signing NeoFS data. - // instantiate Signer - // select data to be signed - - var sig Signature - - err := sig.Calculate(signer, data) - // ... - - // attach signature to the request - SDK natively supports several signature schemes that are implemented in nested packages. PublicKey allows to verify signatures. - // get signature to be verified - // compose signed data - - isValid := sig.Verify(data) - // ... - -Signature can be also used to process NeoFS API V2 protocol messages -(see neo.fs.v2.refs package in https://github.com/nspcc-dev/neofs-api). - -On client side: - - import "github.com/nspcc-dev/neofs-api-go/v2/refs" - - var msg refs.Signature - sig.WriteToV2(&msg) - - // send msg - -On server side: - - // recv msg - - var sig neofscrypto.Signature - sig.ReadFromV2(msg) - - // process sig - Using package types in an application is recommended to potentially work with different protocol versions with which these types are compatible. */ diff --git a/crypto/example_test.go b/crypto/example_test.go new file mode 100644 index 00000000..a75c2e2a --- /dev/null +++ b/crypto/example_test.go @@ -0,0 +1,57 @@ +package neofscrypto_test + +import ( + "github.com/nspcc-dev/neofs-api-go/v2/refs" + neofscrypto "github.com/nspcc-dev/neofs-sdk-go/crypto" +) + +func ExampleSignature_Calculate() { + var signer neofscrypto.Signer + var data []byte + + // instantiate Signer + // select data to be signed + + var sig neofscrypto.Signature + _ = sig.Calculate(signer, data) + + // attach signature to the request +} + +// PublicKey allows to verify signatures. +func ExampleSignature_Verify() { + var sig neofscrypto.Signature + + var data []byte + sig.Verify(data) + + // ... +} + +// Signature can be also used to process NeoFS API V2 protocol messages +// (see neo.fs.v2.refs package in https://github.com/nspcc-dev/neofs-api) on client side. +func ExampleSignature_WriteToV2() { + // import "github.com/nspcc-dev/neofs-api-go/v2/refs" + + var sig neofscrypto.Signature + var msg refs.Signature + + sig.WriteToV2(&msg) + + // send msg +} + +// Signature can be also used to process NeoFS API V2 protocol messages +// (see neo.fs.v2.refs package in https://github.com/nspcc-dev/neofs-api) on server side. +func ExampleSignature_ReadFromV2() { + // import "github.com/nspcc-dev/neofs-api-go/v2/refs" + + // recv msg + + var msg refs.Signature + var sig neofscrypto.Signature + + _ = sig.ReadFromV2(msg) + + // process sig +} diff --git a/netmap/doc.go b/netmap/doc.go index 931e874e..4b2120ba 100644 --- a/netmap/doc.go +++ b/netmap/doc.go @@ -14,29 +14,6 @@ container creator. NetworkInfo type is dedicated to descriptive characterization of network state and settings. -Instances can be also used to process NeoFS API V2 protocol messages -(see neo.fs.v2.netmap package in https://github.com/nspcc-dev/neofs-api). - -On client side: - - import "github.com/nspcc-dev/neofs-api-go/v2/netmap" - - var msg netmap.NodeInfo - info.WriteToV2(&msg) - - // send msg - -On server side: - - // recv msg - - var info NodeInfo - - err := info.ReadFromV2(msg) - // ... - - // process info - Using package types in an application is recommended to potentially work with different protocol versions with which these types are compatible. */ diff --git a/netmap/example_test.go b/netmap/example_test.go new file mode 100644 index 00000000..be9fffef --- /dev/null +++ b/netmap/example_test.go @@ -0,0 +1,34 @@ +package netmap_test + +import ( + apiGoNetmap "github.com/nspcc-dev/neofs-api-go/v2/netmap" + "github.com/nspcc-dev/neofs-sdk-go/netmap" +) + +// Instances can be also used to process NeoFS API V2 protocol messages +// (see neo.fs.v2.netmap package in https://github.com/nspcc-dev/neofs-api) on client side. +func ExampleNodeInfo_WriteToV2() { + // import apiGoNetmap "github.com/nspcc-dev/neofs-api-go/v2/netmap" + + var info netmap.NodeInfo + var msg apiGoNetmap.NodeInfo + + info.WriteToV2(&msg) + + // send msg +} + +// Instances can be also used to process NeoFS API V2 protocol messages +// (see neo.fs.v2.netmap package in https://github.com/nspcc-dev/neofs-api) on server side. +func ExampleNodeInfo_ReadFromV2() { + // import apiGoNetmap "github.com/nspcc-dev/neofs-api-go/v2/netmap" + + // recv msg + + var info netmap.NodeInfo + var msg apiGoNetmap.NodeInfo + + _ = info.ReadFromV2(msg) + + // process info +} diff --git a/pool/doc.go b/pool/doc.go index a9abeb8d..caa6ac09 100644 --- a/pool/doc.go +++ b/pool/doc.go @@ -10,50 +10,5 @@ The mechanism allows to manipulate objects like upload, download, delete, etc, w This behavior may be disabled per request by calling IgnoreSession() on the appropriate Prm* argument. Note that if auto-session is disabled, the user MUST provide the appropriate session manually for PUT and DELETE object operations. The user may provide session, for another object operations. - -Create pool instance with 3 nodes connection. -This InitParameters will make pool use 192.168.130.71 node while it is healthy. Otherwise, it will make the pool use -192.168.130.72 for 90% of requests and 192.168.130.73 for remaining 10%. -: - - var prm pool.InitParameters - prm.SetSigner(signer) - prm.AddNode(NewNodeParam(1, "192.168.130.71", 1)) - prm.AddNode(NewNodeParam(2, "192.168.130.72", 9)) - prm.AddNode(NewNodeParam(2, "192.168.130.73", 1)) - // ... - - p, err := pool.NewPool(prm) - // ... - -Connect to the NeoFS server: - - err := p.Dial(ctx) - // ... - -Execute NeoFS operation on the server: - - var prm pool.PrmContainerPut - prm.SetContainer(cnr) - // ... - - res, err := p.PutContainer(context.Background(), prm) - // ... - -Execute NeoFS operation on the server and check error: - - var prm pool.PrmObjectHead - prm.SetAddress(addr) - // ... - - res, err := p.HeadObject(context.Background(), prm) - if client.IsErrObjectNotFound(err) { - // ... - } - // ... - -Close the connection: - - p.Close() */ package pool diff --git a/pool/example_pool_test.go b/pool/example_pool_test.go deleted file mode 100644 index 22246ca8..00000000 --- a/pool/example_pool_test.go +++ /dev/null @@ -1,54 +0,0 @@ -package pool - -import ( - "crypto/ecdsa" - "crypto/elliptic" - "crypto/rand" - - "github.com/nspcc-dev/neofs-sdk-go/client" - "github.com/nspcc-dev/neofs-sdk-go/session" - "github.com/nspcc-dev/neofs-sdk-go/user" -) - -func ExampleNew_easiestWay() { - // Signer generation, like example. - pk, _ := ecdsa.GenerateKey(elliptic.P256(), rand.Reader) - signer := user.NewAutoIDSignerRFC6979(*pk) - - pool, _ := New(NewFlatNodeParams([]string{"grpc://localhost:8080", "grpcs://localhost:8081"}), signer, DefaultOptions()) - _ = pool - - // ... -} - -func ExampleNew_adjustingParameters() { - // Signer generation, like example. - pk, _ := ecdsa.GenerateKey(elliptic.P256(), rand.Reader) - signer := user.NewAutoIDSignerRFC6979(*pk) - - opts := DefaultOptions() - opts.SetErrorThreshold(10) - - pool, _ := New(NewFlatNodeParams([]string{"grpc://localhost:8080", "grpcs://localhost:8081"}), signer, opts) - _ = pool - - // ... -} - -func ExamplePool_ObjectPutInit_explicitAutoSessionDisabling() { - var prm client.PrmObjectPutInit - - // If you don't provide the session manually with prm.WithinSession, the request will be executed without session. - prm.IgnoreSession() - // ... -} - -func ExamplePool_ObjectPutInit_autoSessionDisabling() { - var sess session.Object - var prm client.PrmObjectPutInit - - // Auto-session disabled, because you provided session already. - prm.WithinSession(sess) - - // ... -} diff --git a/pool/example_test.go b/pool/example_test.go new file mode 100644 index 00000000..26466e15 --- /dev/null +++ b/pool/example_test.go @@ -0,0 +1,160 @@ +package pool_test + +import ( + "context" + "crypto/ecdsa" + "crypto/elliptic" + "crypto/rand" + "errors" + + "github.com/nspcc-dev/neofs-sdk-go/client" + apistatus "github.com/nspcc-dev/neofs-sdk-go/client/status" + "github.com/nspcc-dev/neofs-sdk-go/container" + cid "github.com/nspcc-dev/neofs-sdk-go/container/id" + neofscrypto "github.com/nspcc-dev/neofs-sdk-go/crypto" + oid "github.com/nspcc-dev/neofs-sdk-go/object/id" + "github.com/nspcc-dev/neofs-sdk-go/pool" + "github.com/nspcc-dev/neofs-sdk-go/session" + "github.com/nspcc-dev/neofs-sdk-go/user" + "github.com/nspcc-dev/neofs-sdk-go/waiter" +) + +// Create pool instance with 3 nodes connection. +// This InitParameters will make pool use 192.168.130.71 node while it is healthy. +// Otherwise, it will make the pool use 192.168.130.72 for 90% of requests and 192.168.130.73 for remaining 10%. +func ExampleNewPool() { + // import "github.com/nspcc-dev/neofs-sdk-go/user" + + var signer user.Signer + var prm pool.InitParameters + prm.SetSigner(signer) + prm.AddNode(pool.NewNodeParam(1, "192.168.130.71", 1)) + prm.AddNode(pool.NewNodeParam(2, "192.168.130.72", 9)) + prm.AddNode(pool.NewNodeParam(2, "192.168.130.73", 1)) + // ... + + p, err := pool.NewPool(prm) + + _ = p + _ = err + // ... +} + +func ExampleNew_easiestWay() { + // Signer generation, like example. + pk, _ := ecdsa.GenerateKey(elliptic.P256(), rand.Reader) + signer := user.NewAutoIDSignerRFC6979(*pk) + + p, _ := pool.New( + pool.NewFlatNodeParams([]string{"grpc://localhost:8080", "grpcs://localhost:8081"}), + signer, + pool.DefaultOptions(), + ) + _ = p + + // ... +} + +func ExampleNew_adjustingParameters() { + // Signer generation, like example. + pk, _ := ecdsa.GenerateKey(elliptic.P256(), rand.Reader) + signer := user.NewAutoIDSignerRFC6979(*pk) + + opts := pool.DefaultOptions() + opts.SetErrorThreshold(10) + + p, _ := pool.New( + pool.NewFlatNodeParams([]string{"grpc://localhost:8080", "grpcs://localhost:8081"}), + signer, + opts, + ) + _ = p + + // ... +} + +func ExamplePool_ObjectPutInit_explicitAutoSessionDisabling() { + var prm client.PrmObjectPutInit + + // If you don't provide the session manually with prm.WithinSession, the request will be executed without session. + prm.IgnoreSession() + // ... +} + +func ExamplePool_ObjectPutInit_autoSessionDisabling() { + var sess session.Object + var prm client.PrmObjectPutInit + + // Auto-session disabled, because you provided session already. + prm.WithinSession(sess) + + // ... +} + +// Connect to the NeoFS server. +func ExamplePool_Dial() { + var p pool.Pool + + // Connect to the NeoFS server + _ = p.Dial(context.Background()) +} + +func ExamplePool_ContainerPut() { + // import "github.com/nspcc-dev/neofs-sdk-go/waiter" + // import "github.com/nspcc-dev/neofs-sdk-go/container" + // import neofscrypto "github.com/nspcc-dev/neofs-sdk-go/crypto" + + var p pool.Pool + // ... init pool + + // Connect to the NeoFS server + _ = p.Dial(context.Background()) + + var cont container.Container + // ... fill container + + var signer neofscrypto.Signer + // ... create signer + + var prmPut client.PrmContainerPut + // ... fill params, if required + + // waits until container created or context canceled. + w := waiter.NewContainerPutWaiter(&p, waiter.DefaultPollInterval) + + containerID, err := w.ContainerPut(context.Background(), cont, signer, prmPut) + + _ = containerID + _ = err +} + +func ExamplePool_ObjectHead() { + // import "github.com/nspcc-dev/neofs-sdk-go/waiter" + // import "github.com/nspcc-dev/neofs-sdk-go/container" + // import "github.com/nspcc-dev/neofs-sdk-go/user" + + var p pool.Pool + // ... init pool + + // Connect to the NeoFS server + _ = p.Dial(context.Background()) + + var signer user.Signer + // ... create signer + + var prmHead client.PrmObjectHead + // ... fill params, if required + + hdr, err := p.ObjectHead(context.Background(), cid.ID{}, oid.ID{}, signer, prmHead) + if err != nil { + if errors.Is(err, apistatus.ErrObjectNotFound) { + return + } + + // ... + } + + _ = hdr + + p.Close() +} diff --git a/reputation/doc.go b/reputation/doc.go index 7e59ace7..00cbdea3 100644 --- a/reputation/doc.go +++ b/reputation/doc.go @@ -8,27 +8,6 @@ Trust to support the direction of trust, i.e. from whom to whom. GlobalTrust is designed as a global measure of trust in a network member. See the docs for each type for details. -Instances can be also used to process NeoFS API V2 protocol messages -(see neo.fs.v2.reputation package in https://github.com/nspcc-dev/neofs-api). - -On client side: - - import "github.com/nspcc-dev/neofs-api-go/v2/reputation" - - var msg reputation.GlobalTrust - trust.WriteToV2(&msg) - - // send trust - -On server side: - - // recv msg - - var trust reputation.GlobalTrust - trust.ReadFromV2(msg) - - // process trust - Using package types in an application is recommended to potentially work with different protocol versions with which these types are compatible. */ diff --git a/reputation/example_test.go b/reputation/example_test.go new file mode 100644 index 00000000..4c3fe5e9 --- /dev/null +++ b/reputation/example_test.go @@ -0,0 +1,33 @@ +package reputation_test + +import ( + apiGoReputation "github.com/nspcc-dev/neofs-api-go/v2/reputation" + "github.com/nspcc-dev/neofs-sdk-go/reputation" +) + +// Instances can be also used to process NeoFS API V2 protocol messages +// (see neo.fs.v2.reputation package in https://github.com/nspcc-dev/neofs-api) on client side. +func ExampleGlobalTrust_WriteToV2() { + // import apiGoReputation "github.com/nspcc-dev/neofs-api-go/v2/reputation" + + var trust reputation.GlobalTrust + var msg apiGoReputation.GlobalTrust + trust.WriteToV2(&msg) + + // send trust +} + +// Instances can be also used to process NeoFS API V2 protocol messages +// (see neo.fs.v2.reputation package in https://github.com/nspcc-dev/neofs-api) on server side. +func ExampleGlobalTrust_ReadFromV2() { + // import apiGoReputation "github.com/nspcc-dev/neofs-api-go/v2/reputation" + + // recv msg + + var trust reputation.GlobalTrust + var msg apiGoReputation.GlobalTrust + + _ = trust.ReadFromV2(msg) + + // process trust +} diff --git a/session/doc.go b/session/doc.go index 29b84206..4312c77c 100644 --- a/session/doc.go +++ b/session/doc.go @@ -11,39 +11,8 @@ Both parties agree on a secret (private session key), the possession of which will be authenticated by a trusted person. The principal confirms his trust by signing the public part of the secret (public session key). - var tok Container - tok.ForVerb(VerbContainerDelete) - tok.SetAuthKey(trustedKey) - // ... - - err := tok.Sign(principalKey) - // ... - - // transfer the token to a trusted party - The trusted member can perform operations on behalf of the trustee. -Instances can be also used to process NeoFS API V2 protocol messages -(see neo.fs.v2.accounting package in https://github.com/nspcc-dev/neofs-api). - -On client side: - - import "github.com/nspcc-dev/neofs-api-go/v2/session" - - var msg session.Token - tok.WriteToV2(&msg) - - // send msg - -On server side: - - // recv msg - - var tok session.Container - tok.ReadFromV2(msg) - - // process cnr - Using package types in an application is recommended to potentially work with different protocol versions with which these types are compatible. */ diff --git a/session/example_test.go b/session/example_test.go new file mode 100644 index 00000000..f1c0823f --- /dev/null +++ b/session/example_test.go @@ -0,0 +1,62 @@ +package session_test + +import ( + apiGoSession "github.com/nspcc-dev/neofs-api-go/v2/session" + cid "github.com/nspcc-dev/neofs-sdk-go/container/id" + neofscrypto "github.com/nspcc-dev/neofs-sdk-go/crypto" + "github.com/nspcc-dev/neofs-sdk-go/session" + "github.com/nspcc-dev/neofs-sdk-go/user" +) + +// Both parties agree on a secret (private session key), the possession of which +// will be authenticated by a trusted person. The principal confirms his trust by +// signing the public part of the secret (public session key). +func ExampleContainer_Sign() { + // import neofscrypto "github.com/nspcc-dev/neofs-sdk-go/crypto" + // import "github.com/nspcc-dev/neofs-sdk-go/user" + // import cid "github.com/nspcc-dev/neofs-sdk-go/container/id" + + // you private key/signer, to prove you are you + var principalSigner user.Signer + // trusted party, who can do action on behalf of you + var trustedPubKey neofscrypto.PublicKey + var cnr cid.ID + + var tok session.Object + tok.ForVerb(session.VerbObjectPut) + tok.SetAuthKey(trustedPubKey) + tok.BindContainer(cnr) + // ... + + _ = tok.Sign(principalSigner) + + // transfer the token to a trusted party +} + +// Instances can be also used to process NeoFS API V2 protocol messages +// (see neo.fs.v2.accounting package in https://github.com/nspcc-dev/neofs-api) on client side. +func ExampleObject_WriteToV2() { + // import apiGoSession "github.com/nspcc-dev/neofs-api-go/v2/session" + + var tok session.Object + var msg apiGoSession.Token + + tok.WriteToV2(&msg) + + // send msg +} + +// Instances can be also used to process NeoFS API V2 protocol messages +// (see neo.fs.v2.accounting package in https://github.com/nspcc-dev/neofs-api) on server side. +func ExampleObject_ReadFromV2() { + // import apiGoSession "github.com/nspcc-dev/neofs-api-go/v2/session" + + // recv msg + + var tok session.Object + var msg apiGoSession.Token + + _ = tok.ReadFromV2(msg) + + // process cnr +} diff --git a/storagegroup/doc.go b/storagegroup/doc.go index cf478b8a..60c7e0d3 100644 --- a/storagegroup/doc.go +++ b/storagegroup/doc.go @@ -2,36 +2,6 @@ Package storagegroup provides features to work with information that is used for proof of storage in NeoFS system. -StorageGroup type groups verification values for Data Audit sessions: - - // receive sg info - - sg.ExpirationEpoch() // expiration of the storage group - sg.Members() // objects in the group - sg.ValidationDataHash() // hash for objects validation - sg.ValidationDataSize() // total objects' payload size - -Instances can be also used to process NeoFS API V2 protocol messages -(see neo.fs.v2.storagegroup package in https://github.com/nspcc-dev/neofs-api). - -On client side: - - import "github.com/nspcc-dev/neofs-api-go/v2/storagegroup" - - var msg storagegroup.StorageGroup - sg.WriteToV2(&msg) - - // send msg - -On server side: - - // recv msg - - var sg StorageGroupDecimal - sg.ReadFromV2(msg) - - // process sg - Using package types in an application is recommended to potentially work with different protocol versions with which these types are compatible. */ diff --git a/storagegroup/example_test.go b/storagegroup/example_test.go new file mode 100644 index 00000000..d4a0ea1f --- /dev/null +++ b/storagegroup/example_test.go @@ -0,0 +1,44 @@ +package storagegroup_test + +import ( + apiGoStoragegroup "github.com/nspcc-dev/neofs-api-go/v2/storagegroup" + "github.com/nspcc-dev/neofs-sdk-go/storagegroup" +) + +// StorageGroup type groups verification values for Data Audit sessions. +func ExampleStorageGroup_validation() { + // receive sg info + + var sg storagegroup.StorageGroup + + sg.ExpirationEpoch() // expiration of the storage group + sg.Members() // objects in the group + sg.ValidationDataHash() // hash for objects validation + sg.ValidationDataSize() // total objects' payload size +} + +// Instances can be also used to process NeoFS API V2 protocol messages +// (see neo.fs.v2.storagegroup package in https://github.com/nspcc-dev/neofs-api) on client side. +func ExampleStorageGroup_WriteToV2() { + // import apiGoStoragegroup "github.com/nspcc-dev/neofs-api-go/v2/storagegroup" + + var sg storagegroup.StorageGroup + var msg apiGoStoragegroup.StorageGroup + sg.WriteToV2(&msg) + + // send msg +} + +// Instances can be also used to process NeoFS API V2 protocol messages +// (see neo.fs.v2.storagegroup package in https://github.com/nspcc-dev/neofs-api) on server side. +func ExampleStorageGroup_ReadFromV2() { + // import apiGoStoragegroup "github.com/nspcc-dev/neofs-api-go/v2/storagegroup" + + // recv msg + + var sg storagegroup.StorageGroup + var msg apiGoStoragegroup.StorageGroup + _ = sg.ReadFromV2(msg) + + // process sg +} diff --git a/user/doc.go b/user/doc.go index 768edf8a..13eb8e7e 100644 --- a/user/doc.go +++ b/user/doc.go @@ -3,55 +3,5 @@ Package user provides functionality related to NeoFS users. User identity is reflected in ID type. Each user has its own unique identifier within the same network. - -NeoFS user identification is compatible with Neo accounts: - - import "github.com/nspcc-dev/neo-go/pkg/crypto/keys" - import "github.com/nspcc-dev/neo-go/pkg/crypto/hash" - - var id user.ID - - var scriptHash util.Uint160 // user account in NeoFS - id.SetScriptHash(scriptHash) - -ID is compatible with the NeoFS Smart Contract API: - - var id user.ID - // ... - - wallet := id.WalletBytes() - - // use wallet in call - -Encoding/decoding mechanisms are used to transfer identifiers: - - var id user.ID - // ... - - s := id.EncodeToString() // on transmitter - err = id.DecodeString(s) // on receiver - -Instances can be also used to process NeoFS API protocol messages -(see neo.fs.v2.refs package in https://github.com/nspcc-dev/neofs-api). - -On client side: - - import "github.com/nspcc-dev/neofs-api-go/v2/refs" - - var msg refs.OwnerID - id.WriteToV2(&msg) - - // send msg - -On server side: - - // recv msg - - var id user.ID - - err := id.ReadFromV2(msg) - // ... - - // process id */ package user diff --git a/user/example_test.go b/user/example_test.go new file mode 100644 index 00000000..6d885f7e --- /dev/null +++ b/user/example_test.go @@ -0,0 +1,67 @@ +package user_test + +import ( + "github.com/nspcc-dev/neo-go/pkg/util" + apiGoRefs "github.com/nspcc-dev/neofs-api-go/v2/refs" + "github.com/nspcc-dev/neofs-sdk-go/user" +) + +// NeoFS user identification is compatible with Neo accounts. +func ExampleID_SetScriptHash() { + // import "github.com/nspcc-dev/neo-go/pkg/util" + var id user.ID + + var scriptHash util.Uint160 // user account in NeoFS + id.SetScriptHash(scriptHash) +} + +// ID is compatible with the NeoFS Smart Contract API. +func ExampleID_WalletBytes() { + var id user.ID + // ... + + wallet := id.WalletBytes() + _ = wallet + + // use wallet in call +} + +// Encoding mechanisms are used to transfer identifiers on transmitter. +func ExampleID_EncodeToString() { + var id user.ID + // ... + + _ = id.EncodeToString() // +} + +// Encoding mechanisms are used to transfer identifiers on receiver. +func ExampleID_DecodeString() { + var id user.ID + // ... + + var s string + _ = id.DecodeString(s) // on receiver +} + +// Instances can be also used to process NeoFS API protocol messages +// (see neo.fs.v2.refs package in https://github.com/nspcc-dev/neofs-api) on client side. +func ExampleID_WriteToV2() { + // import apiGoRefs "github.com/nspcc-dev/neofs-api-go/v2/refs" + + var id user.ID + var msg apiGoRefs.OwnerID + id.WriteToV2(&msg) + + // send msg +} + +// Instances can be also used to process NeoFS API protocol messages +// (see neo.fs.v2.refs package in https://github.com/nspcc-dev/neofs-api) on server side. +func ExampleID_ReadFromV2() { + // import apiGoRefs "github.com/nspcc-dev/neofs-api-go/v2/refs" + + var id user.ID + var msg apiGoRefs.OwnerID + _ = id.ReadFromV2(msg) + // send msg +} diff --git a/version/doc.go b/version/doc.go index e5e90f92..0e78da12 100644 --- a/version/doc.go +++ b/version/doc.go @@ -3,16 +3,5 @@ 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/example_test.go b/version/example_test.go new file mode 100644 index 00000000..cb6a1bd0 --- /dev/null +++ b/version/example_test.go @@ -0,0 +1,17 @@ +package version_test + +import ( + "github.com/nspcc-dev/neofs-sdk-go/version" +) + +// In most of the cases it will be enough to use the latest supported NeoFS API version in SDK. +func ExampleCurrent() { + _ = version.Current() +} + +// It is possible to specify arbitrary version by setting major and minor numbers. +func ExampleVersion_SetMajor() { + var ver version.Version + ver.SetMajor(2) + ver.SetMinor(5) +}