# 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
endpoint := "http://localhost:3904"

// Read K2V_KEY_ID and K2V_SECRET_KEY from OS environment variables.
key := k2v.KeyFromEnv()
// key := k2v.Key{ID: "GK49e661847883e4813993a0db", 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)
```

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