kms

Documentation

Index

• type Conn
• type Iter
  • func FuseIter(iter Iter) Iter
• type State
  • func Dial(ctx context.Context, addr string) (State, error)
• type Unavailable
  • func IsUnavailable(err error) (*Unavailable, bool)
  • func (e *Unavailable) Error() string
  • func (e *Unavailable) Unwrap() error
• type Unreachable
  • func IsUnreachable(err error) (*Unreachable, bool)
  • func (e *Unreachable) Error() string
  • func (e *Unreachable) Timeout() bool
  • func (e *Unreachable) Unwrap() error

Examples

• Iter

Types

type Conn

type Conn interface {
	// Status returns the current state of the
	// Conn or an error explaining why fetching
	// the State failed.
	//
	// Status returns Unreachable when it fails
	// to reach the KMS.
	// It returns Unavailable when it successfully
	// reaches the KMS but the KMS seems to cannot
	// process some or any requests. One example,
	// would be a KMS that listens and accepts
	// network requests but hasn't been initialized.
	Status(context.Context) (State, error)

	// Create creates a new name-value entry at
	// the KMS if and only if no entry for the
	// given name exists.
	//
	// If such an entry already exists, Create
	// returns kes.ErrKeyExists.
	Create(ctx context.Context, name string, value []byte) error

	// Get returns the value for the given name or
	// an error explaining why fetching the value
	// from the KMS failed.
	//
	// If no entry for the given name exists, Get
	// returns kes.ErrKeyNotFound.
	Get(ctx context.Context, name string) ([]byte, error)

	// Delete deletes the specified entry at the KMS.
	//
	// If no entry for the given name exists, Delete
	// returns kes.ErrKeyNotFound.
	Delete(ctx context.Context, name string) error

	// List returns an iterator over the entries
	// at the KMS.
	//
	// The returned Iter stops fetching entries
	// from the KMS once ctx.Done() returns.
	List(context.Context) (Iter, error)
}

Conn is a connection to a KMS.

Multiple goroutines may invoke methods on a Conn simultaneously.

type Iter

type Iter interface {
	// Next fetches the next entry from the KMS.
	// It returns false when there are no more entries
	// or once it encounters an error.
	//
	// Once Next returns false, it returns false on any
	// subsequent Next call.
	Next() bool

	// Name returns the name of the latest fetched entry.
	// It returns the same name until Next is called again.
	//
	// As long as Next hasn't been called once or once Next
	// returns false, Name returns the empty string.
	Name() string

	// Close closes the Iter. Once closed, any subsequent
	// Next call returns false.
	//
	// Close returns the first error encountered while iterating
	// over the entires, if any. Otherwise, it returns the error
	// encountered while cleaning up any resources, if any.
	// Subsequent calls to Close return the same error.
	Close() error
}

Iter is an iterator over entries at a KMS.

Example

package main

import (
	"fmt"
	"log"
)

func main() {
	names := []string{
		"key-1",
		"key-2",
		"key-3",
	}
	iter := &Iter{
		Values: names,
	}
	defer iter.Close() // Make sure we close the iterator

	// Loop over the Iter until Next returns false.
	// Then we either reached EOF or encountered an
	// error.
	for iter.Next() {
		fmt.Println(iter.Name())
	}

	// Check whether we encountered an error while
	// iterating or encounter an error when closing
	// the iterator.
	if err := iter.Close(); err != nil {
		log.Fatalln(err)
	}
}

type Iter struct {
	Values []string
	name   string
	closed bool
}

func (i *Iter) Next() bool {
	if i.closed || len(i.Values) == 0 {
		return false
	}
	i.name = i.Values[0]
	i.Values = i.Values[1:]
	return true
}

func (i *Iter) Name() string { return i.name }

func (i *Iter) Close() error {
	i.closed, i.name = true, ""
	return nil
}

Output:

key-1
key-2
key-3

func FuseIter

func FuseIter(iter Iter) Iter

FuseIter wraps iter and returns an Iter that guarantees:

• Next always returns false once it gets closed or encounters an error.
• Name always returns the empty string once it gets closed or encounters an error.
• Close closes the underlying Iter and always returns the same error on any subsequent call.

type State

type State struct {
	// Latency is the connection latency.
	Latency time.Duration
}

State is a structure describing the state of a KMS Conn.

func Dial

func Dial(ctx context.Context, addr string) (State, error)

Dial dials the given addr and returns a new State describing the established connection.

If Dial fails to establish a connection due to a network error, it returns an error of type Unreachable.

type Unavailable

type Unavailable struct {
	Err error
}

Unavailable is an error that indicates that the KMS is reachable over the network but not ready to process requests - e.g. the KMS might not be initialized.

func IsUnavailable

func IsUnavailable(err error) (*Unavailable, bool)

IsUnavailable reports whether err is an Unavailable error. If IsUnavailable returns true it returns err as Unavailable error.

func (*Unavailable) Error

func (e *Unavailable) Error() string

func (*Unavailable) Unwrap

func (e *Unavailable) Unwrap() error

Unwrap returns the Unavailable's underlying error, if any.

type Unreachable

type Unreachable struct {
	Err error
}

Unreachable is an error that indicates that the KMS is not reachable - for example due to a a network error.

func IsUnreachable

func IsUnreachable(err error) (*Unreachable, bool)

IsUnreachable reports whether err is an Unreachable error. If IsUnreachable returns true it returns err as Unreachable error.

func (*Unreachable) Error

func (e *Unreachable) Error() string

func (*Unreachable) Timeout

func (e *Unreachable) Timeout() bool

Timeout reports whether the Unreachable error is caused by a network timeout.

func (*Unreachable) Unwrap

func (e *Unreachable) Unwrap() error

Unwrap returns the Unreachable's underlying error, if any.