82 lines
3.1 KiB
Markdown
82 lines
3.1 KiB
Markdown
# garage-k2v-go
|
|
|
|
Go client for [K2V][k2v-about], an experimental small object key-value storage engine built as part of [Garage][garage-about].
|
|
|
|
Because the [K2V API][k2v-api] is not stable, breaking changes in this Go module should be expected until then.
|
|
|
|
## Import
|
|
```go
|
|
import k2v "code.notaphish.fyi/milas/garage-k2v-go"
|
|
```
|
|
|
|
## Create API client
|
|
```go
|
|
// Read K2V_ENDPOINT from OS environment variable, e.g. http://localhost:3904.
|
|
endpoint := k2v.EndpointFromEnv()
|
|
|
|
// Read K2V_KEY_ID and K2V_KEY_SECRET from OS environment variables.
|
|
key := k2v.KeyFromEnv()
|
|
|
|
// Alternatively, construct a key by initializing the ID and secret fields on a k2v.Key.
|
|
// key := k2v.Key{ID: "GK...", Secret: "..."}
|
|
|
|
client := k2v.NewClient(endpoint, key)
|
|
```
|
|
|
|
## Operations
|
|
```go
|
|
type Client
|
|
func NewClient(endpoint string, key Key, opts ...ClientOption) *Client
|
|
func (c *Client) Clone(opts ...ClientOption) *Client
|
|
func (c *Client) Close()
|
|
func (c *Client) DeleteItem(ctx context.Context, b Bucket, pk string, sk string, ct CausalityToken) error
|
|
func (c *Client) InsertBatch(ctx context.Context, b Bucket, items []BatchInsertItem) error
|
|
func (c *Client) InsertItem(ctx context.Context, b Bucket, pk string, sk string, ct CausalityToken, item []byte) error
|
|
func (c *Client) PollItem(ctx context.Context, b Bucket, pk string, sk string, ct CausalityToken, timeout time.Duration) (Item, CausalityToken, error)
|
|
func (c *Client) ReadBatch(ctx context.Context, b Bucket, q []ReadBatchSearch) ([]BatchSearchResult, error)
|
|
func (c *Client) ReadIndex(ctx context.Context, b Bucket, q ReadIndexQuery) (*ReadIndexResponse, error)
|
|
func (c *Client) ReadItemMulti(ctx context.Context, b Bucket, pk string, sk string) ([]Item, CausalityToken, error)
|
|
func (c *Client) ReadItemSingle(ctx context.Context, b Bucket, pk string, sk string) (Item, CausalityToken, error)
|
|
```
|
|
|
|
## Scrolling (Client-side / Go API)
|
|
To handle iteration in the K2V API, helper functions for simple cases are provided.
|
|
|
|
For example, to perform a bulk search:
|
|
```go
|
|
handleBatch := func(result *k2v.BatchSearchResult) error {
|
|
log.Println(result.Items)
|
|
return nil
|
|
}
|
|
err := k2v.ScrollBatchSearch(ctx, f.cli, f.bucket, []k2v.BatchSearch{
|
|
{
|
|
PartitionKey: "pk1",
|
|
},
|
|
{
|
|
PartitionKey: "pk2",
|
|
Limit: 1,
|
|
},
|
|
}, handleBatch)
|
|
```
|
|
|
|
This will repeatedly make calls to **ReadBatch** (batch search), using `nextStart` from the responses to generate subsequent requests until all queries are exhausted.
|
|
|
|
See `ScrollIndex(ctx context.Context, client IndexScroller, b Bucket, query ReadIndexQuery, fn ReadIndexResponseHandler) error` for the equivalent for batch index reads.
|
|
|
|
## Integration Tests
|
|
```shell
|
|
K2V_ENDPOINT="http://[::1]:3904" \
|
|
K2V_KEY_ID="GK..." \
|
|
K2V_KEY_SECRET="..." \
|
|
go test ./...
|
|
```
|
|
|
|
## Usage
|
|
Review the [K2V API spec][k2v-api] and the integration tests in this module for complete examples.
|
|
|
|
[garage-about]: https://garagehq.deuxfleurs.fr/
|
|
[k2v-about]: https://garagehq.deuxfleurs.fr/documentation/reference-manual/k2v/
|
|
[k2v-api]: https://git.deuxfleurs.fr/Deuxfleurs/garage/src/branch/main/doc/drafts/k2v-spec.md
|
|
|
|
## License
|
|
Go API client licensed under Apache 2.0
|