[#99] docs: add README.md
Signed-off-by: Evgenii Stratonikov <evgeniy@nspcc.ru>
This commit is contained in:
Evgenii Stratonikov
Alex Vanin
parent
2fff3fd9ec
commit
6a7ba33b59
1 changed files with 121 additions and 1 deletions
122
README.md
122
README.md
|
|
@ -1,2 +1,122 @@
|
|||
# neofs-sdk-go
|
||||
Go implementation of NeoFS SDK
|
||||
Go implementation of NeoFS SDK. It contains high-level version-independent wrappers
|
||||
for structures from [neofs-api-go](https://github.com/nspcc-dev/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](https://github.com/nspcc-dev/tzhash) 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](https://docs.neo.org/docs/en-us/basic/concept/wallets.html#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.
|
||||
|
||||
### resolver
|
||||
In NeoFS there are 2 types of name resolution: DNS and NNS. NNS stands for Neo Name Service
|
||||
is just a [contract](https://github.com/nspcc-dev/neofs-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](https://github.com/nspcc-dev/coredns/tree/master/plugin/nns)
|
||||
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.
|
||||
```go
|
||||
c, _ := client.New(
|
||||
client.WithAddress("localhost:40005"), // endpoint address
|
||||
client.WithDefaultPrivateKey(key), // private key for request signing
|
||||
client.WithNeoFSErrorHandling(), // enable erroneous status parsing
|
||||
client.WithTLSConfig(&tls.Config{})) // custom TLS configuration
|
||||
|
||||
ctx, cancel := context.WithTimeout(context.Background(), 5 * time.Second)
|
||||
defer cancel()
|
||||
|
||||
res, err := c.GetBalance(ctx, owner)
|
||||
if err != nil {
|
||||
return
|
||||
}
|
||||
|
||||
fmt.Printf("Balance for %s: %s\n", owner, 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](https://github.com/nspcc-dev/neofs-api/blob/master/status/types.proto). There is also
|
||||
a `client.WithNeoFSErrorHandling()` 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.
|
||||
```go
|
||||
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.
|
||||
|
||||
```go
|
||||
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.
|
||||
Loading…
Reference in a new issue