forked from TrueCloudLab/frostfs-api-go
docs: Update README
Signed-off-by: Stanislav Bogatyrev <stanislav@nspcc.ru>
This commit is contained in:
Stanislav Bogatyrev
parent
e97f7096c6
commit
6b319b410b
3 changed files with 145 additions and 218 deletions
129
.github/logo.svg
vendored
Normal file
129
.github/logo.svg
vendored
Normal file
|
|
@ -0,0 +1,129 @@
|
|||
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
|
||||
<svg
|
||||
xmlns:dc="http://purl.org/dc/elements/1.1/"
|
||||
xmlns:cc="http://creativecommons.org/ns#"
|
||||
xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
|
||||
xmlns:svg="http://www.w3.org/2000/svg"
|
||||
xmlns="http://www.w3.org/2000/svg"
|
||||
xmlns:sodipodi="http://sodipodi.sourceforge.net/DTD/sodipodi-0.dtd"
|
||||
xmlns:inkscape="http://www.inkscape.org/namespaces/inkscape"
|
||||
sodipodi:docname="logo_fs.svg"
|
||||
inkscape:version="1.0 (4035a4fb49, 2020-05-01)"
|
||||
id="svg57"
|
||||
version="1.1"
|
||||
viewBox="0 0 105 25"
|
||||
height="25mm"
|
||||
width="105mm">
|
||||
<defs
|
||||
id="defs51">
|
||||
<clipPath
|
||||
clipPathUnits="userSpaceOnUse"
|
||||
id="clipPath434">
|
||||
<path
|
||||
d="M 0,0 H 1366 V 768 H 0 Z"
|
||||
id="path432" />
|
||||
</clipPath>
|
||||
</defs>
|
||||
<sodipodi:namedview
|
||||
inkscape:window-maximized="0"
|
||||
inkscape:window-y="0"
|
||||
inkscape:window-x="130"
|
||||
inkscape:window-height="1040"
|
||||
inkscape:window-width="1274"
|
||||
height="50mm"
|
||||
units="mm"
|
||||
showgrid="false"
|
||||
inkscape:document-rotation="0"
|
||||
inkscape:current-layer="layer1"
|
||||
inkscape:document-units="mm"
|
||||
inkscape:cy="344.49897"
|
||||
inkscape:cx="468.64708"
|
||||
inkscape:zoom="0.7"
|
||||
inkscape:pageshadow="2"
|
||||
inkscape:pageopacity="0.0"
|
||||
borderopacity="1.0"
|
||||
bordercolor="#666666"
|
||||
pagecolor="#ffffff"
|
||||
id="base" />
|
||||
<metadata
|
||||
id="metadata54">
|
||||
<rdf:RDF>
|
||||
<cc:Work
|
||||
rdf:about="">
|
||||
<dc:format>image/svg+xml</dc:format>
|
||||
<dc:type
|
||||
rdf:resource="http://purl.org/dc/dcmitype/StillImage" />
|
||||
<dc:title></dc:title>
|
||||
</cc:Work>
|
||||
</rdf:RDF>
|
||||
</metadata>
|
||||
<g
|
||||
id="layer1"
|
||||
inkscape:groupmode="layer"
|
||||
inkscape:label="Layer 1">
|
||||
<g
|
||||
id="g424"
|
||||
transform="matrix(0.35277777,0,0,-0.35277777,63.946468,10.194047)">
|
||||
<path
|
||||
d="m 0,0 v -8.093 h 12.287 v -3.94 H 0 V -24.067 H -4.534 V 3.898 H 15.677 V 0 Z"
|
||||
style="fill:#00e396;fill-opacity:1;fill-rule:nonzero;stroke:none"
|
||||
id="path426" />
|
||||
</g>
|
||||
<g
|
||||
transform="matrix(0.35277777,0,0,-0.35277777,-315.43002,107.34005)"
|
||||
id="g428">
|
||||
<g
|
||||
id="g430"
|
||||
clip-path="url(#clipPath434)">
|
||||
<g
|
||||
id="g436"
|
||||
transform="translate(1112.874,278.2981)">
|
||||
<path
|
||||
d="M 0,0 C 1.822,-0.932 3.354,-2.359 4.597,-4.28 L 1.165,-7.373 c -0.791,1.695 -1.779,2.924 -2.966,3.686 -1.186,0.763 -2.768,1.145 -4.745,1.145 -1.949,0 -3.461,-0.389 -4.534,-1.166 -1.074,-0.777 -1.61,-1.772 -1.61,-2.987 0,-1.13 0.523,-2.027 1.568,-2.69 1.045,-0.664 2.909,-1.236 5.593,-1.716 2.514,-0.452 4.512,-1.024 5.995,-1.716 1.483,-0.693 2.564,-1.554 3.242,-2.585 0.677,-1.031 1.016,-2.309 1.016,-3.834 0,-1.639 -0.466,-3.079 -1.398,-4.322 -0.932,-1.243 -2.239,-2.197 -3.919,-2.86 -1.681,-0.664 -3.623,-0.996 -5.826,-0.996 -5.678,0 -9.689,1.892 -12.033,5.678 l 3.178,3.178 c 0.903,-1.695 2.068,-2.939 3.495,-3.729 1.426,-0.791 3.199,-1.186 5.318,-1.186 2.005,0 3.58,0.345 4.724,1.038 1.144,0.692 1.716,1.674 1.716,2.945 0,1.017 -0.516,1.835 -1.547,2.457 -1.031,0.621 -2.832,1.172 -5.402,1.653 -2.571,0.479 -4.618,1.073 -6.143,1.779 -1.526,0.706 -2.635,1.582 -3.326,2.627 -0.693,1.045 -1.039,2.316 -1.039,3.813 0,1.582 0.438,3.023 1.314,4.322 0.875,1.299 2.14,2.33 3.792,3.093 1.653,0.763 3.58,1.144 5.783,1.144 C -4.018,1.398 -1.822,0.932 0,0"
|
||||
style="fill:#00e396;fill-opacity:1;fill-rule:nonzero;stroke:none"
|
||||
id="path438" />
|
||||
</g>
|
||||
<g
|
||||
id="g440"
|
||||
transform="translate(993.0239,277.5454)">
|
||||
<path
|
||||
d="m 0,0 c 2.054,-1.831 3.083,-4.465 3.083,-7.902 v -17.935 h -4.484 v 16.366 c 0,2.914 -0.626,5.024 -1.877,6.332 -1.253,1.308 -2.924,1.962 -5.016,1.962 -1.495,0 -2.896,-0.327 -4.204,-0.981 -1.308,-0.654 -2.381,-1.719 -3.222,-3.194 -0.841,-1.477 -1.261,-3.335 -1.261,-5.576 v -14.909 h -4.484 V 1.328 l 4.086,-1.674 0.118,-1.84 c 0.933,1.681 2.222,2.923 3.867,3.727 1.643,0.803 3.493,1.205 5.548,1.205 C -4.671,2.746 -2.055,1.83 0,0"
|
||||
style="fill:#000033;fill-opacity:1;fill-rule:nonzero;stroke:none"
|
||||
id="path442" />
|
||||
</g>
|
||||
<g
|
||||
id="g444"
|
||||
transform="translate(1027.9968,264.0386)">
|
||||
<path
|
||||
d="m 0,0 h -21.128 c 0.261,-2.84 1.205,-5.044 2.83,-6.613 1.625,-1.57 3.727,-2.355 6.305,-2.355 2.054,0 3.763,0.356 5.128,1.065 1.363,0.71 2.288,1.738 2.774,3.083 l 3.755,-1.961 c -1.121,-1.981 -2.616,-3.495 -4.484,-4.54 -1.868,-1.046 -4.259,-1.569 -7.173,-1.569 -4.223,0 -7.538,1.289 -9.948,3.867 -2.41,2.578 -3.615,6.146 -3.615,10.704 0,4.558 1.149,8.127 3.447,10.705 2.298,2.578 5.557,3.867 9.779,3.867 2.615,0 4.876,-0.58 6.782,-1.738 1.905,-1.158 3.343,-2.728 4.315,-4.707 C -0.262,7.827 0.224,5.605 0.224,3.139 0.224,2.092 0.149,1.046 0,0 m -18.298,10.144 c -1.513,-1.457 -2.438,-3.512 -2.775,-6.165 h 16.982 c -0.3,2.615 -1.159,4.661 -2.578,6.137 -1.42,1.476 -3.307,2.214 -5.661,2.214 -2.466,0 -4.455,-0.728 -5.968,-2.186"
|
||||
style="fill:#000033;fill-opacity:1;fill-rule:nonzero;stroke:none"
|
||||
id="path446" />
|
||||
</g>
|
||||
<g
|
||||
id="g448"
|
||||
transform="translate(1057.8818,276.4246)">
|
||||
<path
|
||||
d="m 0,0 c 2.41,-2.578 3.615,-6.147 3.615,-10.705 0,-4.558 -1.205,-8.126 -3.615,-10.704 -2.41,-2.578 -5.726,-3.867 -9.948,-3.867 -4.222,0 -7.537,1.289 -9.947,3.867 -2.41,2.578 -3.615,6.146 -3.615,10.704 0,4.558 1.205,8.127 3.615,10.705 2.41,2.578 5.725,3.867 9.947,3.867 C -5.726,3.867 -2.41,2.578 0,0 m -16.617,-2.858 c -1.607,-1.906 -2.41,-4.522 -2.41,-7.847 0,-3.326 0.803,-5.94 2.41,-7.846 1.607,-1.905 3.83,-2.858 6.669,-2.858 2.839,0 5.063,0.953 6.67,2.858 1.606,1.906 2.41,4.52 2.41,7.846 0,3.325 -0.804,5.941 -2.41,7.847 C -4.885,-0.953 -7.109,0 -9.948,0 c -2.839,0 -5.062,-0.953 -6.669,-2.858"
|
||||
style="fill:#000033;fill-opacity:1;fill-rule:nonzero;stroke:none"
|
||||
id="path450" />
|
||||
</g>
|
||||
</g>
|
||||
</g>
|
||||
<g
|
||||
id="g452"
|
||||
transform="matrix(0.35277777,0,0,-0.35277777,5.8329581,6.5590171)">
|
||||
<path
|
||||
d="m 0,0 0.001,-38.946 25.286,-9.076 V -8.753 L 52.626,1.321 27.815,10.207 Z"
|
||||
style="fill:#00e599;fill-opacity:1;fill-rule:nonzero;stroke:none"
|
||||
id="path454" />
|
||||
</g>
|
||||
<g
|
||||
id="g456"
|
||||
transform="matrix(0.35277777,0,0,-0.35277777,15.479008,10.041927)">
|
||||
<path
|
||||
d="M 0,0 V -21.306 L 25.293,-30.364 25.282,9.347 Z"
|
||||
style="fill:#00b091;fill-opacity:1;fill-rule:nonzero;stroke:none"
|
||||
id="path458" />
|
||||
</g>
|
||||
</g>
|
||||
</svg>
|
||||
|
After Width: | Height: | Size: 6.5 KiB |
83
.github/markdown.tmpl
vendored
83
.github/markdown.tmpl
vendored
|
|
@ -1,83 +0,0 @@
|
|||
# Protocol Documentation
|
||||
<a name="top"></a>
|
||||
|
||||
## Table of Contents
|
||||
{{range .Files}}
|
||||
{{$file_name := .Name}}- [{{.Name}}](#{{.Name}})
|
||||
{{if .Services}} - Services
|
||||
{{range .Services}}- [{{.Name}}](#{{.FullName}})
|
||||
{{end}}{{end}}
|
||||
{{if .Messages}} - Messages
|
||||
{{range .Messages}}- [{{.LongName}}](#{{.FullName}})
|
||||
{{end}}{{end}}
|
||||
{{end}}
|
||||
- [Scalar Value Types](#scalar-value-types)
|
||||
|
||||
{{range .Files}}
|
||||
{{$file_name := .Name}}
|
||||
<a name="{{.Name}}"></a>
|
||||
<p align="right"><a href="#top">Top</a></p>
|
||||
|
||||
## {{.Name}}
|
||||
{{.Description}}
|
||||
|
||||
{{range .Services}}
|
||||
|
||||
<a name="{{.FullName}}"></a>
|
||||
|
||||
### Service "{{.FullName}}"
|
||||
{{.Description}}
|
||||
|
||||
```
|
||||
{{range .Methods -}}
|
||||
rpc {{.Name}}({{if .RequestStreaming}}stream {{end}}{{.RequestLongType}}) returns ({{if .ResponseStreaming}}stream {{end}}{{.ResponseLongType}});
|
||||
{{end}}
|
||||
```
|
||||
|
||||
{{range .Methods -}}
|
||||
#### Method {{.Name}}
|
||||
|
||||
{{.Description}}
|
||||
|
||||
| Name | Input | Output |
|
||||
| ---- | ----- | ------ |
|
||||
| {{.Name}} | [{{.RequestLongType}}](#{{.RequestFullType}}) | [{{.ResponseLongType}}](#{{.ResponseFullType}}) |
|
||||
{{end}}{{end}} <!-- end services -->
|
||||
|
||||
{{range .Messages}}
|
||||
<a name="{{.FullName}}"></a>
|
||||
|
||||
### Message {{.LongName}}
|
||||
{{.Description}}
|
||||
|
||||
{{if .HasFields}}
|
||||
| Field | Type | Label | Description |
|
||||
| ----- | ---- | ----- | ----------- |
|
||||
{{range .Fields -}}
|
||||
| {{.Name}} | [{{.LongType}}](#{{.FullType}}) | {{.Label}} | {{nobr .Description}}{{if .DefaultValue}} Default: {{.DefaultValue}}{{end}} |
|
||||
{{end}}{{end}}
|
||||
{{end}} <!-- end messages -->
|
||||
|
||||
{{range .Enums}}
|
||||
<a name="{{.FullName}}"></a>
|
||||
|
||||
### {{.LongName}}
|
||||
{{.Description}}
|
||||
|
||||
| Name | Number | Description |
|
||||
| ---- | ------ | ----------- |
|
||||
{{range .Values -}}
|
||||
| {{.Name}} | {{.Number}} | {{nobr .Description}} |
|
||||
{{end}}
|
||||
|
||||
{{end}} <!-- end enums -->
|
||||
|
||||
{{end}}
|
||||
|
||||
## Scalar Value Types
|
||||
|
||||
| .proto Type | Notes | C++ Type | Java Type | Python Type |
|
||||
| ----------- | ----- | -------- | --------- | ----------- |
|
||||
{{range .Scalars -}}
|
||||
| <a name="{{.ProtoType}}" /> {{.ProtoType}} | {{.Notes}} | {{.CppType}} | {{.JavaType}} | {{.PythonType}} |
|
||||
{{end}}
|
||||
151
README.md
151
README.md
|
|
@ -1,150 +1,31 @@
|
|||
# NeoFS API
|
||||
<p align="center">
|
||||
<img src="./.github/logo.svg" width="500px" alt="NeoFS">
|
||||
</p>
|
||||
<p align="center">
|
||||
Golang SDK for <a href="https://fs.neo.org">NeoFS</a>
|
||||
</p>
|
||||
|
||||
---
|
||||
|
||||
[](https://codecov.io/gh/nspcc-dev/neofs-api-go)
|
||||
[](https://goreportcard.com/report/github.com/nspcc-dev/neofs-api-go)
|
||||
[](https://github.com/nspcc-dev/neofs-api-go)
|
||||
|
||||
|
||||
---
|
||||
# Overview
|
||||
|
||||
NeoFS API repository contains implementation of core NeoFS structures that
|
||||
can be used for integration with NeoFS.
|
||||
|
||||
## Сompatibility
|
||||
|
||||
[neofs-api v1.1.0]: https://github.com/nspcc-dev/neofs-api/releases/tag/v1.1.0
|
||||
[neofs-api-go v1.1.0]: https://github.com/nspcc-dev/neofs-api-go/releases/tag/v1.1.0
|
||||
* [neofs-api-go v1.1.0] supports [neofs-api v1.1.0]
|
||||
|
||||
[neofs-api v1.2.0]: https://github.com/nspcc-dev/neofs-api/releases/tag/v1.2.0
|
||||
[neofs-api-go v1.2.0]: https://github.com/nspcc-dev/neofs-api-go/releases/tag/v1.2.0
|
||||
* [neofs-api-go v1.2.0] supports [neofs-api v1.2.0]
|
||||
|
||||
[neofs-api-go v1.3.0]: https://github.com/nspcc-dev/neofs-api-go/releases/tag/v1.3.0
|
||||
* [neofs-api-go v1.3.0] supports [neofs-api v1.2.0]
|
||||
|
||||
## Description
|
||||
|
||||
Repository contains 13 packages that implement NeoFS core structures. These
|
||||
packages mostly contain protobuf files with service and structure definitions
|
||||
or NeoFS core types with complemented functions.
|
||||
|
||||
There is a auto-generated documentation for protobuf files in [docs](docs).
|
||||
|
||||
### Accounting
|
||||
|
||||
Accounting package defines services and structures for accounting operations:
|
||||
balance request and `cheque` operations for withdraw. `Cheque` is a structure
|
||||
with inner ring signatures, which approve that user can withdraw requested
|
||||
amount of assets. NeoFS smart contract takes binary formatted `cheque` as a
|
||||
parameter in withdraw call.
|
||||
|
||||
#### API
|
||||
Accounting package defines:
|
||||
- [Accounting service](docs/accounting.md#accounting.Accounting)
|
||||
- [Withdraw service](docs/accounting.md#accounting.Withdraw)
|
||||
|
||||
|
||||
### Bootstrap
|
||||
|
||||
Bootstrap package defines bootstrap service which is used by storage nodes to
|
||||
connect to the storage network.
|
||||
|
||||
#### API
|
||||
Bootstrap package defines:
|
||||
- [Bootstrap service](docs/bootstrap.md#bootstrap.Bootstrap)
|
||||
|
||||
|
||||
### Chain
|
||||
|
||||
Chain package contains util functions for operations with NEO Blockchain types:
|
||||
wallet addresses, script-hashes.
|
||||
|
||||
### Container
|
||||
|
||||
Container package defines service and structures for operations with containers.
|
||||
Objects in NeoFS are stored in containers. Container defines storage
|
||||
policy for the objects.
|
||||
|
||||
#### API
|
||||
Bootstrap package defines:
|
||||
- [Container service](docs/container.md#container.Service)
|
||||
|
||||
### Decimal
|
||||
|
||||
Decimal defines custom decimal implementation which is used in accounting
|
||||
operations.
|
||||
|
||||
### Hash
|
||||
|
||||
Hash package defines homomorphic hash type.
|
||||
|
||||
### Internal
|
||||
|
||||
Internal package defines constant error type and proto interface for custom
|
||||
protobuf structures.
|
||||
|
||||
### Object
|
||||
|
||||
Object package defines service and structures for object operations. Object is
|
||||
a core storage structure in NeoFS. Package contains detailed information
|
||||
about object internal structure.
|
||||
|
||||
#### API
|
||||
Object package defines:
|
||||
- [Object service](docs/object.md#object.Service)
|
||||
|
||||
### Query
|
||||
|
||||
Query package defines structure for object search requests.
|
||||
|
||||
### Refs
|
||||
|
||||
Refs package defines core identity types: Object ID, Container ID, etc.
|
||||
|
||||
### Service
|
||||
|
||||
Service package defines util structure and functions for all NeoFS services
|
||||
operations: TTL and request signature management, node roles, epoch retriever.
|
||||
|
||||
### Session
|
||||
|
||||
Session package defines service and structures for session obtain. Object
|
||||
operations require an established session with pair of session keys signed by
|
||||
owner of the object.
|
||||
|
||||
#### API
|
||||
Session package defines:
|
||||
- [Session service](docs/session.md#session.Session)
|
||||
|
||||
### State
|
||||
|
||||
State package defines service and structures for metrics gathering.
|
||||
|
||||
#### API
|
||||
State package defines:
|
||||
- [Status service](docs/state.md#state.Status)
|
||||
|
||||
## How to use
|
||||
|
||||
NeoFS API packages contain godoc documentation. Examples of using most of
|
||||
these packages can be found in NeoFS-CLI repository. CLI implements and
|
||||
demonstrates all basic interactions with NeoFS: container, object, storage
|
||||
group, and accounting operations.
|
||||
|
||||
Protobuf files are recompiled with the command:
|
||||
|
||||
```
|
||||
$ make protoc
|
||||
```
|
||||
Go implementation of recent [NeoFS API](https://github.com/nspcc-dev/neofs-api)
|
||||
versions and SDK layer working with all of them in a handy way.
|
||||
|
||||
## Contributing
|
||||
|
||||
At this moment, we do not accept contributions.
|
||||
Feel free to contribute to this project after reading the [contributing
|
||||
guidelines](CONTRIBUTING.md).
|
||||
|
||||
Before starting to work on a certain topic, create an new issue first,
|
||||
describing the feature/topic you are going to implement.
|
||||
|
||||
## License
|
||||
|
||||
This project is licensed under the Apache 2.0 License -
|
||||
This project is licensed under the Apache 2.0 License -
|
||||
see the [LICENSE](LICENSE) file for details
|
||||
|
||||
|
|
|
|||
Loading…
Reference in a new issue