frostfs-sdk-go

module
v0.0.0-...-5e759bf Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Mar 1, 2023 License: Apache-2.0

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.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL