garage-k2v-go

Go client for K2V, an experimental small object key-value storage engine built as part of Garage.

Because the K2V API is not stable, breaking changes in this Go module should be expected until then.

Import

import k2v "code.notaphish.fyi/milas/garage-k2v-go"

Create API client

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

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:

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

K2V_ENDPOINT="http://[::1]:3904" \
K2V_KEY_ID="GK..." \
K2V_KEY_SECRET="..." \
  go test ./...

Usage

Review the K2V API spec and the integration tests in this module for complete examples.

License

Go API client licensed under Apache 2.0