README
¶
frostfs-sdk-go
Go implementation of FrostFS SDK. It contains high-level version-independent wrappers for structures from frostfs-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 FrostFS 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 FrostFS. 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 FrostFS-specific methods.
ns
In FrostFS 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 FrostFS without sacrificing trust, FrostFS 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 FrostFS.
var prmInit client.PrmInit
prmInit.SetDefaultPrivateKey(key) // private key for request signing
prmInit.ResolveFrostFSFailures() // enable erroneous status parsing
var c client.Client
c.Init(prmInit)
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 FrostFS 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
FrostFS API. There is also
a client.PrmInit.ResolveFrostFSFailures() to seamlessly convert erroneous statuses into Go error type.
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/TrueCloudLab/frostfs-sdk-go/netmap"
"github.com/TrueCloudLab/frostfs-sdk-go/object"
)
func placementNodes(addr *object.Address, p *netmap.PlacementPolicy, frostfsNodes []netmap.NodeInfo) {
// Convert list of nodes in FrostFS 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 FrostFS nodes.
acl, checksum, version, signature
Contain simple API wrappers.
logger
Wrapper over zap.Logger which is used across FrostFS codebase.
util
Utilities for working with signature-related code.
Directories
¶
| Path | Synopsis |
|---|---|
|
Package accounting provides primitives to perform accounting operations in FrostFS.
|
Package accounting provides primitives to perform accounting operations in FrostFS. |
|
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 FrostFS system.
|
Package audit provides features to process data audit in FrostFS 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 FrostFS API client implementation.
|
Package client provides FrostFS API client implementation. |
|
Package container provides functionality related to the FrostFS containers.
|
Package container provides functionality related to the FrostFS containers. |
|
acl
Package acl provides functionality to control access to data and operations on them in FrostFS containers.
|
Package acl provides functionality to control access to data and operations on them in FrostFS containers. |
|
id
Package cid provides primitives to work with container identification in FrostFS.
|
Package cid provides primitives to work with container identification in FrostFS. |
|
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 frostfscrypto collects FrostFS cryptographic primitives.
|
Package frostfscrypto collects FrostFS cryptographic primitives. |
|
ecdsa
Package frostfsecdsa collects ECDSA primitives for FrostFS cryptography.
|
Package frostfsecdsa collects ECDSA primitives for FrostFS cryptography. |
|
Package netmap provides functionality for working with information about the FrostFS network, primarily a layer of storage nodes.
|
Package netmap provides functionality for working with information about the FrostFS network, primarily a layer of storage nodes. |
|
Package ns provides functionality of FrostFS name system.
|
Package ns provides functionality of FrostFS name system. |
|
id
Package oid provides primitives to work with object identification in FrostFS.
|
Package oid provides primitives to work with object identification in FrostFS. |
|
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. |
|
Package pool provides a wrapper for several FrostFS API clients.
|
Package pool provides a wrapper for several FrostFS API clients. |
|
Package reputation collects functionality related to the FrostFS reputation system.
|
Package reputation collects functionality related to the FrostFS reputation system. |
|
Package session collects functionality of the FrostFS sessions.
|
Package session collects functionality of the FrostFS 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 FrostFS system.
|
Package storagegroup provides features to work with information that is used for proof of storage in FrostFS 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 subnet collects functionality related to the FrostFS subnets.
|
Package subnet collects functionality related to the FrostFS subnets. |
|
id
Package subnetid provides primitives to work with subnet identification in FrostFS.
|
Package subnetid provides primitives to work with subnet identification in FrostFS. |
|
id/test
Package subnetidtest provides functions for convenient testing of subnetid package API.
|
Package subnetidtest provides functions for convenient testing of subnetid package API. |
|
test
Package subnettest provides functions for convenient testing of subnet package API.
|
Package subnettest provides functions for convenient testing of subnet package API. |
|
Package user provides functionality related to FrostFS users.
|
Package user provides functionality related to FrostFS 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 FrostFS versioning.
|
Package version provides functionality for FrostFS versioning. |
|
test
Package versiontest provides functions for testing version package.
|
Package versiontest provides functions for testing version package. |