README
¶
neofs-sdk-go
Go implementation of NeoFS SDK. It contains high-level version-independent wrappers for structures from neofs-api-go as well as helper functions for simplifying node/dApp implementations.
Repository structure
accounting
Contains fixed-point Decimal type for performing balance calculations.
eacl
Contains Extended ACL types for fine-grained access control. There is also a reference implementation of checking algorithm which is used in NeoFS node.
checksum
Contains Checksum type encapsulating checksum as well as it's kind.
Currently Sha256 and Tillich-Zemor hashsum are in use.
owner
owner.ID type represents single account interacting with NeoFS. In v2 version of protocol
it is just raw bytes behing base58-encoded address
in Neo blockchain. Note that for historical reasons it contains
version prefix and checksum in addition to script-hash.
token
Contains Bearer token type with several NeoFS-specific methods.
ns
In NeoFS there are 2 types of name resolution: DNS and NNS. NNS stands for Neo Name Service is just a contract deployed on a Neo blockchain. Basically, NNS is just a DNS-on-chain which can be used for resolving container nice-names as well as any other name in dApps. See our CoreDNS plugin for the example of how NNS can be integrated in DNS.
session
To help lightweight clients interact with NeoFS without sacrificing trust, NeoFS has a concept of session token. It is signed by client and allows any node with which a session is established to perform certain actions on behalf of the user.
client
Contains client for working with NeoFS.
var prmInit client.PrmInit
prmInit.SetDefaultPrivateKey(key) // private key for request signing
c, err := client.New(prmInit)
if err != nil {
return
}
var prmDial client.PrmDial
prmDial.SetServerURI("grpcs://localhost:40005") // endpoint address
err := c.Dial(prmDial)
if err != nil {
return
}
ctx, cancel := context.WithTimeout(context.Background(), 5 * time.Second)
defer cancel()
var prm client.PrmBalanceGet
prm.SetAccount(acc)
res, err := c.BalanceGet(ctx, prm)
if err != nil {
return
}
fmt.Printf("Balance for %s: %v\n", acc, res.Amount())
Response status
In NeoFS every operation can fail on multiple levels, so a single error doesn't suffice,
e.g. consider a case when object was put on 4 out of 5 replicas. Thus, all request execution
details are contained in Status returned from every RPC call. dApp can inspect them
if needed and perform any desired action. In the case above we may want to report
these details to the user as well as retry an operation, possibly with different parameters.
Status wire-format is extendable and each node can report any set of details it wants.
The set of reserved status codes can be found in
NeoFS API.
policy
Contains helpers allowing conversion of placing policy from/to JSON representation and SQL-like human-readable language.
p, _ := policy.Parse(`
REP 2
SELECT 6 FROM F
FILTER StorageType EQ SSD AS F`)
// Convert parsed policy back to human-readable text and print.
println(strings.Join(policy.Encode(p), "\n"))
netmap
Contains CRUSH-like implementation of container node selection algorithm. Relevant details are described in this paper http://ceur-ws.org/Vol-2344/short10.pdf . Note that it can be outdated in some details.
netmap/json_tests subfolder contains language-agnostic tests for selection algorithm.
import (
"github.com/nspcc-dev/neofs-sdk-go/netmap"
"github.com/nspcc-dev/neofs-sdk-go/object"
)
func placementNodes(addr *object.Address, p *netmap.PlacementPolicy, neofsNodes []netmap.NodeInfo) {
// Convert list of nodes in NeoFS API format to the intermediate representation.
nodes := netmap.NodesFromInfo(nodes)
// Create new netmap (errors are skipped for the sake of clarity).
nm, _ := NewNetmap(nodes)
// Calculate nodes of container.
cn, _ := nm.GetContainerNodes(p, addr.ContainerID().ToV2().GetValue())
// Return list of nodes for each replica to place object on in the order of priority.
return nm.GetPlacementVectors(cn, addr.ObjectID().ToV2().GetValue())
}
pool
Simple pool for managing connections to NeoFS nodes.
acl, checksum, version, signature
Contain simple API wrappers.
logger
Wrapper over zap.Logger which is used across NeoFS codebase.
util
Utilities for working with signature-related code.
Directories
¶
| Path | Synopsis |
|---|---|
|
Package accounting provides primitives to perform accounting operations in NeoFS.
|
Package accounting provides primitives to perform accounting operations in NeoFS. |
|
test
Package accountingtest provides functions for convenient testing of accounting package API.
|
Package accountingtest provides functions for convenient testing of accounting package API. |
|
Package audit provides features to process data audit in NeoFS system.
|
Package audit provides features to process data audit in NeoFS system. |
|
test
Package audittest provides functions for convenient testing of audit package API.
|
Package audittest provides functions for convenient testing of audit package API. |
|
Package bearer provides bearer token definition.
|
Package bearer provides bearer token definition. |
|
test
Package bearertest provides functions for testing bearer package.
|
Package bearertest provides functions for testing bearer package. |
|
Package checksum provides primitives to work with checksums.
|
Package checksum provides primitives to work with checksums. |
|
test
Package checksumtest provides functions for convenient testing of checksum package API.
|
Package checksumtest provides functions for convenient testing of checksum package API. |
|
Package client provides NeoFS API client implementation.
|
Package client provides NeoFS API client implementation. |
|
Package container provides functionality related to the NeoFS containers.
|
Package container provides functionality related to the NeoFS containers. |
|
acl
Package acl provides functionality to control access to data and operations on them in NeoFS containers.
|
Package acl provides functionality to control access to data and operations on them in NeoFS containers. |
|
id
Package cid provides primitives to work with container identification in NeoFS.
|
Package cid provides primitives to work with container identification in NeoFS. |
|
id/test
Package cidtest provides functions for convenient testing of cid package API.
|
Package cidtest provides functions for convenient testing of cid package API. |
|
Package neofscrypto collects NeoFS cryptographic primitives.
|
Package neofscrypto collects NeoFS cryptographic primitives. |
|
ecdsa
Package neofsecdsa collects ECDSA primitives for NeoFS cryptography.
|
Package neofsecdsa collects ECDSA primitives for NeoFS cryptography. |
|
test
Package tests provides special help functions for testing NeoFS API and its environment.
|
Package tests provides special help functions for testing NeoFS API and its environment. |
|
Package netmap provides functionality for working with information about the NeoFS network, primarily a layer of storage nodes.
|
Package netmap provides functionality for working with information about the NeoFS network, primarily a layer of storage nodes. |
|
id
Package oid provides primitives to work with object identification in NeoFS.
|
Package oid provides primitives to work with object identification in NeoFS. |
|
id/test
Package oidtest provides functions for convenient testing of oid package API.
|
Package oidtest provides functions for convenient testing of oid package API. |
|
relations
Package relations provides feature to process inner object structure.
|
Package relations provides feature to process inner object structure. |
|
slicer
Package slicer provides raw data slicing into NeoFS objects.
|
Package slicer provides raw data slicing into NeoFS objects. |
|
Package pool provides a wrapper for several NeoFS API clients.
|
Package pool provides a wrapper for several NeoFS API clients. |
|
Package reputation collects functionality related to the NeoFS reputation system.
|
Package reputation collects functionality related to the NeoFS reputation system. |
|
Package session collects functionality of the NeoFS sessions.
|
Package session collects functionality of the NeoFS sessions. |
|
test
Package sessiontest provides functions for convenient testing of session package API.
|
Package sessiontest provides functions for convenient testing of session package API. |
|
Package storagegroup provides features to work with information that is used for proof of storage in NeoFS system.
|
Package storagegroup provides features to work with information that is used for proof of storage in NeoFS system. |
|
test
Package storagegrouptest provides functions for convenient testing of storagegroup package API.
|
Package storagegrouptest provides functions for convenient testing of storagegroup package API. |
|
Package user provides functionality related to NeoFS users.
|
Package user provides functionality related to NeoFS users. |
|
test
Package usertest provides functions for convenient testing of user package API.
|
Package usertest provides functions for convenient testing of user package API. |
|
Package version provides functionality for NeoFS versioning.
|
Package version provides functionality for NeoFS versioning. |
|
test
Package versiontest provides functions for testing version package.
|
Package versiontest provides functions for testing version package. |
|
Package waiter provides synchronous implementation of asynchronous commands of [client.Client] and [pool.Pool].
|
Package waiter provides synchronous implementation of asynchronous commands of [client.Client] and [pool.Pool]. |