diff --git a/README.md b/README.md index 95b3485..bf5549f 100644 --- a/README.md +++ b/README.md @@ -13,8 +13,8 @@ NeoFS-API repository is the basis for language-specific libraries, e.g.: -- [neofs-api-go](https://github.com/nspcc-dev/neofs-api-go) -- [neofs-api-csharp](https://github.com/nspcc-dev/neofs-api-csharp) +- [neofs-sdk-go](https://github.com/nspcc-dev/neofs-sdk-go) (see `proto` package there for vanilla API) +- [neofs-api-csharp](https://github.com/neo-ngd/neofs-api-csharp) Those libraries contain compiled protocol buffers definitions, wrapped with language-specific code. Use them to integrate applications with NeoFS. diff --git a/accounting/service.proto b/accounting/service.proto index 3b94884..80930c5 100644 --- a/accounting/service.proto +++ b/accounting/service.proto @@ -7,7 +7,7 @@ import "refs/types.proto"; import "session/types.proto"; option csharp_namespace = "Neo.FileStorage.API.Accounting"; -option go_package = "github.com/nspcc-dev/neofs-api-go/v2/accounting/grpc;accounting"; +option go_package = "github.com/nspcc-dev/neofs-sdk-go/proto/accounting"; // Accounting service provides methods for interaction with FS chain via // other NeoFS nodes to get information about the account balance. Deposit and diff --git a/accounting/types.proto b/accounting/types.proto index 0044e11..a1c0a76 100644 --- a/accounting/types.proto +++ b/accounting/types.proto @@ -3,7 +3,7 @@ syntax = "proto3"; package neo.fs.v2.accounting; option csharp_namespace = "Neo.FileStorage.API.Accounting"; -option go_package = "github.com/nspcc-dev/neofs-api-go/v2/accounting/grpc;accounting"; +option go_package = "github.com/nspcc-dev/neofs-sdk-go/proto/accounting"; // Standard floating point data type can't be used in NeoFS due to inexactness // of the result when doing lots of small number operations. To solve the lost diff --git a/acl/types.proto b/acl/types.proto index 2503f48..53f4c5a 100644 --- a/acl/types.proto +++ b/acl/types.proto @@ -5,7 +5,7 @@ package neo.fs.v2.acl; import "refs/types.proto"; option csharp_namespace = "Neo.FileStorage.API.Acl"; -option go_package = "github.com/nspcc-dev/neofs-api-go/v2/acl/grpc;acl"; +option go_package = "github.com/nspcc-dev/neofs-sdk-go/proto/acl"; // Target role of the access control rule in access control list. enum Role { @@ -226,10 +226,10 @@ message BearerToken { // Lifetime parameters of the token. Field names taken from // [rfc7519](https://tools.ietf.org/html/rfc7519). message TokenLifetime { - // Expiration Epoch + // Expiration epoch, the last epoch when token is valid. uint64 exp = 1 [json_name = "exp"]; - // Not valid before Epoch + // Not valid before epoch, the first epoch when token is valid. uint64 nbf = 2 [json_name = "nbf"]; // Issued at Epoch diff --git a/audit/types.proto b/audit/types.proto index 356568d..7d3cec1 100644 --- a/audit/types.proto +++ b/audit/types.proto @@ -5,7 +5,7 @@ package neo.fs.v2.audit; import "refs/types.proto"; option csharp_namespace = "Neo.FileStorage.API.Audit"; -option go_package = "github.com/nspcc-dev/neofs-api-go/v2/audit/grpc;audit"; +option go_package = "github.com/nspcc-dev/neofs-sdk-go/proto/audit"; // DataAuditResult keeps record of conducted Data Audits. The detailed report is // generated separately. diff --git a/container/service.proto b/container/service.proto index 9063fa3..4f4fad6 100644 --- a/container/service.proto +++ b/container/service.proto @@ -8,7 +8,7 @@ import "refs/types.proto"; import "session/types.proto"; option csharp_namespace = "Neo.FileStorage.API.Container"; -option go_package = "github.com/nspcc-dev/neofs-api-go/v2/container/grpc;container"; +option go_package = "github.com/nspcc-dev/neofs-sdk-go/proto/container"; // `ContainerService` provides API to interact with `Container` smart contract // in FS chain via other NeoFS nodes. All of those actions can be done diff --git a/container/types.proto b/container/types.proto index 9c32b59..b341b1f 100644 --- a/container/types.proto +++ b/container/types.proto @@ -6,7 +6,7 @@ import "netmap/types.proto"; import "refs/types.proto"; option csharp_namespace = "Neo.FileStorage.API.Container"; -option go_package = "github.com/nspcc-dev/neofs-api-go/v2/container/grpc;container"; +option go_package = "github.com/nspcc-dev/neofs-sdk-go/proto/container"; // Container is a structure that defines object placement behaviour. Objects can // be stored only within containers. They define placement rule, attributes and diff --git a/link/types.proto b/link/types.proto index 62276c1..1092f77 100644 --- a/link/types.proto +++ b/link/types.proto @@ -5,7 +5,7 @@ package neo.fs.v2.link; import "refs/types.proto"; option csharp_namespace = "Neo.FileStorage.API.Link"; -option go_package = "github.com/nspcc-dev/neofs-api-go/v2/link/grpc;link"; +option go_package = "github.com/nspcc-dev/neofs-sdk-go/proto/link"; // Link is a payload of helper objects that contain the full list of the split // chain objects' IDs. It is created only after the whole split chain is known diff --git a/lock/types.proto b/lock/types.proto index 3e1e917..b0dc0a7 100644 --- a/lock/types.proto +++ b/lock/types.proto @@ -5,7 +5,7 @@ package neo.fs.v2.lock; import "refs/types.proto"; option csharp_namespace = "Neo.FileStorage.API.Lock"; -option go_package = "github.com/nspcc-dev/neofs-api-go/v2/lock/grpc;lock"; +option go_package = "github.com/nspcc-dev/neofs-sdk-go/proto/lock"; // Lock objects protects a list of objects from being deleted. The lifetime of a // lock object is limited similar to regular objects in diff --git a/netmap/service.proto b/netmap/service.proto index 184179f..a623056 100644 --- a/netmap/service.proto +++ b/netmap/service.proto @@ -7,7 +7,7 @@ import "refs/types.proto"; import "session/types.proto"; option csharp_namespace = "Neo.FileStorage.API.Netmap"; -option go_package = "github.com/nspcc-dev/neofs-api-go/v2/netmap/grpc;netmap"; +option go_package = "github.com/nspcc-dev/neofs-sdk-go/proto/netmap"; // `NetmapService` provides methods to work with `Network Map` and the information // required to build it. The resulting `Network Map` is stored in FS chain diff --git a/netmap/types.proto b/netmap/types.proto index bad932d..f411006 100644 --- a/netmap/types.proto +++ b/netmap/types.proto @@ -5,7 +5,7 @@ package neo.fs.v2.netmap; import "refs/types.proto"; option csharp_namespace = "Neo.FileStorage.API.Netmap"; -option go_package = "github.com/nspcc-dev/neofs-api-go/v2/netmap/grpc;netmap"; +option go_package = "github.com/nspcc-dev/neofs-sdk-go/proto/netmap"; // Operations on filters enum Operation { diff --git a/object/service.proto b/object/service.proto index 810793b..6d8e13a 100644 --- a/object/service.proto +++ b/object/service.proto @@ -8,7 +8,7 @@ import "session/types.proto"; import "status/types.proto"; option csharp_namespace = "Neo.FileStorage.API.Object"; -option go_package = "github.com/nspcc-dev/neofs-api-go/v2/object/grpc;object"; +option go_package = "github.com/nspcc-dev/neofs-sdk-go/proto/object"; // `ObjectService` provides API for manipulating objects. Object operations do // not affect FS chain and are only served by nodes in P2P style. @@ -84,6 +84,8 @@ service ObjectService { // Delete the object from a container. There is no immediate removal // guarantee. Object will be marked for removal and deleted eventually. + // Notice that some types of objects (see ObjectType) can not be removed, + // currently it's Tombstone and Lock. // // Extended headers can change `Delete` behaviour: // * __NEOFS__NETMAP_EPOCH \ diff --git a/object/types.proto b/object/types.proto index 1a4371c..e07a25a 100644 --- a/object/types.proto +++ b/object/types.proto @@ -6,7 +6,7 @@ import "refs/types.proto"; import "session/types.proto"; option csharp_namespace = "Neo.FileStorage.API.Object"; -option go_package = "github.com/nspcc-dev/neofs-api-go/v2/object/grpc;object"; +option go_package = "github.com/nspcc-dev/neofs-sdk-go/proto/object"; // Type of the object payload content. Only `REGULAR` type objects can be split, // hence `TOMBSTONE`, `STORAGE_GROUP` and `LOCK` payload is limited by the maximum @@ -154,10 +154,10 @@ message ShortHeader { // `0xFFFFFFFFFFFFFFFF` means `payload_length` is unknown uint64 payload_length = 5 [json_name = "payloadLength"]; - // Hash of payload bytes + // SHA256 hash of payload bytes. neo.fs.v2.refs.Checksum payload_hash = 6 [json_name = "payloadHash"]; - // Homomorphic hash of the object payload + // Homomorphic hash of the object payload (Tillich-Zemor). neo.fs.v2.refs.Checksum homomorphic_hash = 7 [json_name = "homomorphicHash"]; } @@ -180,13 +180,13 @@ message Header { // `0xFFFFFFFFFFFFFFFF` means `payload_length` is unknown. uint64 payload_length = 5 [json_name = "payloadLength"]; - // Hash of payload bytes + // SHA256 hash of payload bytes neo.fs.v2.refs.Checksum payload_hash = 6 [json_name = "payloadHash"]; // Type of the object payload content ObjectType object_type = 7 [json_name = "objectType"]; - // Homomorphic hash of the object payload + // Homomorphic hash of the object payload (Tillich-Zemor). neo.fs.v2.refs.Checksum homomorphic_hash = 8 [json_name = "homomorphicHash"]; // Session token, if it was used during Object creation. Need it to verify @@ -204,7 +204,8 @@ message Header { // that affect system behaviour: // // * __NEOFS__EXPIRATION_EPOCH \ - // Tells GC to delete object after that epoch + // Tells GC to delete object after that epoch (but object is available + // throughout the epoch specified in this attribute). // * __NEOFS__TICK_EPOCH \ // Decimal number that defines what epoch must produce // object notification with UTF-8 object address in a diff --git a/proto-docs/acl.md b/proto-docs/acl.md index d434801..d008565 100644 --- a/proto-docs/acl.md +++ b/proto-docs/acl.md @@ -72,8 +72,8 @@ Lifetime parameters of the token. Field names taken from | Field | Type | Label | Description | | ----- | ---- | ----- | ----------- | -| exp | [uint64](#uint64) | | Expiration Epoch | -| nbf | [uint64](#uint64) | | Not valid before Epoch | +| exp | [uint64](#uint64) | | Expiration epoch, the last epoch when token is valid. | +| nbf | [uint64](#uint64) | | Not valid before epoch, the first epoch when token is valid. | | iat | [uint64](#uint64) | | Issued at Epoch | diff --git a/proto-docs/object.md b/proto-docs/object.md index 080b546..895372b 100644 --- a/proto-docs/object.md +++ b/proto-docs/object.md @@ -173,6 +173,8 @@ been deleted; Delete the object from a container. There is no immediate removal guarantee. Object will be marked for removal and deleted eventually. +Notice that some types of objects (see ObjectType) can not be removed, +currently it's Tombstone and Lock. Extended headers can change `Delete` behaviour: * __NEOFS__NETMAP_EPOCH \ @@ -902,9 +904,9 @@ Object Header | owner_id | [neo.fs.v2.refs.OwnerID](#neo.fs.v2.refs.OwnerID) | | Object's owner | | creation_epoch | [uint64](#uint64) | | Object creation Epoch | | payload_length | [uint64](#uint64) | | Size of payload in bytes. `0xFFFFFFFFFFFFFFFF` means `payload_length` is unknown. | -| payload_hash | [neo.fs.v2.refs.Checksum](#neo.fs.v2.refs.Checksum) | | Hash of payload bytes | +| payload_hash | [neo.fs.v2.refs.Checksum](#neo.fs.v2.refs.Checksum) | | SHA256 hash of payload bytes | | object_type | [ObjectType](#neo.fs.v2.object.ObjectType) | | Type of the object payload content | -| homomorphic_hash | [neo.fs.v2.refs.Checksum](#neo.fs.v2.refs.Checksum) | | Homomorphic hash of the object payload | +| homomorphic_hash | [neo.fs.v2.refs.Checksum](#neo.fs.v2.refs.Checksum) | | Homomorphic hash of the object payload (Tillich-Zemor). | | session_token | [neo.fs.v2.session.SessionToken](#neo.fs.v2.session.SessionToken) | | Session token, if it was used during Object creation. Need it to verify integrity and authenticity out of Request scope. | | attributes | [Header.Attribute](#neo.fs.v2.object.Header.Attribute) | repeated | User-defined object attributes. Attributes vary in length from object to object, so keep an eye on the entire Header limit depending on the context. | | split | [Header.Split](#neo.fs.v2.object.Header.Split) | | Position of the object in the split hierarchy | @@ -924,7 +926,8 @@ There are some "well-known" attributes starting with `__NEOFS__` prefix that affect system behaviour: * __NEOFS__EXPIRATION_EPOCH \ - Tells GC to delete object after that epoch + Tells GC to delete object after that epoch (but object is available + throughout the epoch specified in this attribute). * __NEOFS__TICK_EPOCH \ Decimal number that defines what epoch must produce object notification with UTF-8 object address in a @@ -1086,8 +1089,8 @@ Short header fields | owner_id | [neo.fs.v2.refs.OwnerID](#neo.fs.v2.refs.OwnerID) | | Object's owner | | object_type | [ObjectType](#neo.fs.v2.object.ObjectType) | | Type of the object payload content | | payload_length | [uint64](#uint64) | | Size of payload in bytes. `0xFFFFFFFFFFFFFFFF` means `payload_length` is unknown | -| payload_hash | [neo.fs.v2.refs.Checksum](#neo.fs.v2.refs.Checksum) | | Hash of payload bytes | -| homomorphic_hash | [neo.fs.v2.refs.Checksum](#neo.fs.v2.refs.Checksum) | | Homomorphic hash of the object payload | +| payload_hash | [neo.fs.v2.refs.Checksum](#neo.fs.v2.refs.Checksum) | | SHA256 hash of payload bytes. | +| homomorphic_hash | [neo.fs.v2.refs.Checksum](#neo.fs.v2.refs.Checksum) | | Homomorphic hash of the object payload (Tillich-Zemor). | diff --git a/proto-docs/session.md b/proto-docs/session.md index 58605b0..50e5367 100644 --- a/proto-docs/session.md +++ b/proto-docs/session.md @@ -92,7 +92,7 @@ Session creation request body | Field | Type | Label | Description | | ----- | ---- | ----- | ----------- | | owner_id | [neo.fs.v2.refs.OwnerID](#neo.fs.v2.refs.OwnerID) | | Session initiating user's or node's key derived `OwnerID` | -| expiration | [uint64](#uint64) | | Session expiration `Epoch` | +| expiration | [uint64](#uint64) | | Session expiration epoch, the last epoch when session is valid. | @@ -270,8 +270,8 @@ Lifetime parameters of the token. Field names taken from rfc7519. | Field | Type | Label | Description | | ----- | ---- | ----- | ----------- | -| exp | [uint64](#uint64) | | Expiration Epoch | -| nbf | [uint64](#uint64) | | Not valid before Epoch | +| exp | [uint64](#uint64) | | Expiration epoch, the last epoch when token is valid. | +| nbf | [uint64](#uint64) | | Not valid before epoch, the first epoch when token is valid. | | iat | [uint64](#uint64) | | Issued at Epoch | diff --git a/proto-docs/tombstone.md b/proto-docs/tombstone.md index a855019..b5a5fad 100644 --- a/proto-docs/tombstone.md +++ b/proto-docs/tombstone.md @@ -26,7 +26,8 @@ ### Message Tombstone Tombstone keeps record of deleted objects for a few epochs until they are -purged from the NeoFS network. +purged from the NeoFS network. It is impossible to delete a tombstone object +via ObjectService.Delete RPC call. | Field | Type | Label | Description | diff --git a/refs/types.proto b/refs/types.proto index b3dce60..9be849b 100644 --- a/refs/types.proto +++ b/refs/types.proto @@ -3,7 +3,7 @@ syntax = "proto3"; package neo.fs.v2.refs; option csharp_namespace = "Neo.FileStorage.API.Refs"; -option go_package = "github.com/nspcc-dev/neofs-api-go/v2/refs/grpc;refs"; +option go_package = "github.com/nspcc-dev/neofs-sdk-go/proto/refs"; // Objects in NeoFS are addressed by their ContainerID and ObjectID. // diff --git a/reputation/service.proto b/reputation/service.proto index a799bb0..c1afa65 100644 --- a/reputation/service.proto +++ b/reputation/service.proto @@ -6,7 +6,7 @@ import "reputation/types.proto"; import "session/types.proto"; option csharp_namespace = "Neo.FileStorage.API.Reputation"; -option go_package = "github.com/nspcc-dev/neofs-api-go/v2/reputation/grpc;reputation"; +option go_package = "github.com/nspcc-dev/neofs-sdk-go/proto/reputation"; // `ReputationService` provides mechanisms for exchanging trust values with // other NeoFS nodes. Nodes rate each other's reputation based on how good they diff --git a/reputation/types.proto b/reputation/types.proto index 3c6b7ff..fc6afe7 100644 --- a/reputation/types.proto +++ b/reputation/types.proto @@ -5,7 +5,7 @@ package neo.fs.v2.reputation; import "refs/types.proto"; option csharp_namespace = "Neo.FileStorage.API.Reputation"; -option go_package = "github.com/nspcc-dev/neofs-api-go/v2/reputation/grpc;reputation"; +option go_package = "github.com/nspcc-dev/neofs-sdk-go/proto/reputation"; // NeoFS unique peer identifier is a 33 byte long compressed public key of the // node, the same as the one stored in the network map. diff --git a/session/service.proto b/session/service.proto index 4b04482..e51bd8c 100644 --- a/session/service.proto +++ b/session/service.proto @@ -6,7 +6,7 @@ import "refs/types.proto"; import "session/types.proto"; option csharp_namespace = "Neo.FileStorage.API.Session"; -option go_package = "github.com/nspcc-dev/neofs-api-go/v2/session/grpc;session"; +option go_package = "github.com/nspcc-dev/neofs-sdk-go/proto/session"; // `SessionService` allows to establish a temporary trust relationship between // two peer nodes and generate a `SessionToken` as the proof of trust to be @@ -28,7 +28,7 @@ message CreateRequest { message Body { // Session initiating user's or node's key derived `OwnerID` neo.fs.v2.refs.OwnerID owner_id = 1; - // Session expiration `Epoch` + // Session expiration epoch, the last epoch when session is valid. uint64 expiration = 2; } // Body of a create session token request message. diff --git a/session/types.proto b/session/types.proto index 9d72f9c..dcfef8c 100644 --- a/session/types.proto +++ b/session/types.proto @@ -7,7 +7,7 @@ import "refs/types.proto"; import "status/types.proto"; option csharp_namespace = "Neo.FileStorage.API.Session"; -option go_package = "github.com/nspcc-dev/neofs-api-go/v2/session/grpc;session"; +option go_package = "github.com/nspcc-dev/neofs-sdk-go/proto/session"; // Context information for Session Tokens related to ObjectService requests message ObjectSessionContext { @@ -97,10 +97,10 @@ message SessionToken { // Lifetime parameters of the token. Field names taken from rfc7519. message TokenLifetime { - // Expiration Epoch + // Expiration epoch, the last epoch when token is valid. uint64 exp = 1 [json_name = "exp"]; - // Not valid before Epoch + // Not valid before epoch, the first epoch when token is valid. uint64 nbf = 2 [json_name = "nbf"]; // Issued at Epoch diff --git a/status/types.proto b/status/types.proto index 367452a..0a8750f 100644 --- a/status/types.proto +++ b/status/types.proto @@ -3,7 +3,7 @@ syntax = "proto3"; package neo.fs.v2.status; option csharp_namespace = "Neo.FileStorage.API.Status"; -option go_package = "github.com/nspcc-dev/neofs-api-go/v2/status/grpc;status"; +option go_package = "github.com/nspcc-dev/neofs-sdk-go/proto/status"; // Declares the general format of the status returns of the NeoFS RPC protocol. // Status is present in all response messages. Each RPC of NeoFS protocol diff --git a/storagegroup/types.proto b/storagegroup/types.proto index 2a21142..dc1ace3 100644 --- a/storagegroup/types.proto +++ b/storagegroup/types.proto @@ -5,7 +5,7 @@ package neo.fs.v2.storagegroup; import "refs/types.proto"; option csharp_namespace = "Neo.FileStorage.API.StorageGroup"; -option go_package = "github.com/nspcc-dev/neofs-api-go/v2/storagegroup/grpc;storagegroup"; +option go_package = "github.com/nspcc-dev/neofs-sdk-go/proto/storagegroup"; // StorageGroup keeps verification information for Data Audit sessions. Objects // that require paid storage guarantees are gathered in `StorageGroups` with diff --git a/subnet/types.proto b/subnet/types.proto index e8bbd14..bdd2bed 100644 --- a/subnet/types.proto +++ b/subnet/types.proto @@ -5,7 +5,7 @@ package neo.fs.v2.subnet; import "refs/types.proto"; option csharp_namespace = "Neo.FileStorage.API.Subnet"; -option go_package = "github.com/nspcc-dev/neofs-api-go/v2/subnet/grpc;subnet"; +option go_package = "github.com/nspcc-dev/neofs-sdk-go/proto/subnet"; // NeoFS subnetwork description // diff --git a/tombstone/types.proto b/tombstone/types.proto index c7731a1..d406fa3 100644 --- a/tombstone/types.proto +++ b/tombstone/types.proto @@ -5,10 +5,11 @@ package neo.fs.v2.tombstone; import "refs/types.proto"; option csharp_namespace = "Neo.FileStorage.API.Tombstone"; -option go_package = "github.com/nspcc-dev/neofs-api-go/v2/tombstone/grpc;tombstone"; +option go_package = "github.com/nspcc-dev/neofs-sdk-go/proto/tombstone"; // Tombstone keeps record of deleted objects for a few epochs until they are -// purged from the NeoFS network. +// purged from the NeoFS network. It is impossible to delete a tombstone object +// via ObjectService.Delete RPC call. message Tombstone { // Last NeoFS epoch number of the tombstone lifetime. It's set by the tombstone // creator depending on the current NeoFS network settings.