Go implementation of FrostFS SDK
Find a file
Evgenii Baidakov e2a88bc258
client: Remove status returning from processResponse function
Signed-off-by: Evgenii Baidakov <evgenii@nspcc.io>
2023-05-23 14:49:36 +04:00
.github .github: extend CODEOWNERS list 2023-05-11 18:26:42 +03:00
accounting [#378] accounting: Add binary encoding for Decimal type 2023-01-31 12:51:47 +04:00
audit [#308] audit: Add CollectMembers function 2022-11-17 16:31:45 +03:00
bearer tests: Use dedicated function to generate signers in tests 2023-04-26 15:03:55 +04:00
checksum [#322] *: Go fmt -s 2022-08-24 18:58:59 +03:00
client client: Remove status returning from processResponse function 2023-05-23 14:49:36 +04:00
container tests: Use dedicated function to generate signers in tests 2023-04-26 15:03:55 +04:00
crypto tests: Use dedicated function to generate signers in tests 2023-04-26 15:03:55 +04:00
eacl tests: Use dedicated function to generate signers in tests 2023-04-26 15:03:55 +04:00
netmap client: Fix linter - unnecessary leading newline 2023-05-19 12:19:19 +04:00
ns *: replace interface{} with any keyword 2023-04-18 12:28:25 +04:00
object slicer: Replace panics with errors 2023-05-19 14:45:49 +04:00
pool pool: Refactor handleError to updateErrorRate 2023-05-19 12:21:16 +04:00
reputation tests: Use dedicated function to generate signers in tests 2023-04-26 15:03:55 +04:00
session client: Replace panics with errors 2023-05-19 14:45:48 +04:00
storagegroup client: Fix linter - unused parameter 2023-05-19 12:19:19 +04:00
subnet tests: Use dedicated function to generate signers in tests 2023-04-26 15:03:55 +04:00
user *: Update documentation 2023-05-19 14:45:50 +04:00
version [#378] version: Add JSON encoding for Version type 2023-01-31 12:51:51 +04:00
.gitattributes [#3] policy: use ANTLRv4 parser generator 2021-06-15 11:42:14 +03:00
.gitignore gitignore: ignore text editor backup files 2023-04-27 12:58:11 +03:00
.golangci.yml [#37] ci: Replace golint by revive 2021-10-15 17:37:18 +03:00
CHANGELOG.md CHANGELOG: add it, release 1.0.0-rc.8 2023-04-27 12:58:06 +03:00
go.mod go.mod: update tzhash 2023-05-18 16:21:39 +03:00
go.sum go.mod: update tzhash 2023-05-18 16:21:39 +03:00
LICENSE Initial commit 2021-02-25 11:35:04 +03:00
Makefile [nspcc-dev/neofs-node#166] *: Add project files 2021-05-20 23:57:51 +03:00
README.md client: Remove ResolveNeoFSFailures 2023-05-19 12:19:19 +04:00

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

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