objstore

type FieldMap interface {
	// Has returns true if the fieldKey is specified.
	Has(fieldKey string) bool
	// Fields returns all the specified fields.
	Fields() []string
}

type KVOp func(opts *KVOptions)

type KVOptions struct {
	LeaseID int64
	Rev     int64
}

type KVStore interface {
	// Create creates an object with the given string key and value.
	// Create should fail if the key already exists.
	// It returns the revision (transaction) number and any error.
	Create(ctx context.Context, key, val string) (int64, error)
	// Update updates an object with the given string key and value.
	// Update should fail if the key does not exist, or if the version
	// doesn't match (meaning some other thread has already updated it).
	// It returns the revision (transaction) number and any error.
	Update(ctx context.Context, key, val string, version int64) (int64, error)
	// Delete deletes an object with the given key string.
	// It returns the revision (transaction) number and any error.
	Delete(ctx context.Context, key string) (int64, error)
	// Get retrieves a single object with the given key string.
	// Get returns the data, a version, mod revision, and any error.
	Get(key string, opts ...KVOp) ([]byte, int64, int64, error)
	// Put the key-value pair, regardless of whether it already exists or not.
	Put(ctx context.Context, key, val string, opts ...KVOp) (int64, error)
	// List retrives all objects that have the given key string prefix.
	List(key string, cb ListCb) error
	// Sync is a blocking call used to keep in sync with the database.
	// The initial call (or sometimes after a reconnect), the full set
	// of objects will be called back. Afterwards, or after reconnect
	// if the history is still present, only changes will be called back.
	// It is up to the caller to resync their local cache given actions
	// of SyncAllStart and SyncAllEnd. Any objects that were not received
	// during that time must be removed from the local cache.
	// Use a context with cancel to be able to cancel the call.
	Sync(ctx context.Context, key string, cb SyncCb) error
	// ApplySTM applies a Software Transaction Model which basically
	// collects gets/puts and does an all-or-nothing transaction.
	// It tracks revisions for all gets and puts. If any keys were
	// changed before the transaction commits, all changes are aborted.
	// Apply func is the function to make the changes which uses the
	// STM to make the changes.
	// Unfortunately the way etcd sets this up, there's no way to wrap
	// the STM with an objstore-specific interface, so we're stuck exactly
	// implementing the etcd-specific interface.
	// Important: Etcd apparently does not honor the order in which
	// multiple puts appear within an apply func, at least for watch
	// callbacks (perhaps because they all have the same revision ID).
	// If ordering is important, do not use multiple puts in the same STM.
	ApplySTM(ctx context.Context, apply func(concurrency.STM) error) (int64, error)
	// Leases work like etcd leases. A key committed with a lease will
	// automatically be deleted once the lease expires.
	// To avoid that, the KeepAlive call must remain active.
	// Grant creates a new lease
	Grant(ctx context.Context, ttl int64) (int64, error)
	// Revoke a lease
	Revoke(ctx context.Context, lease int64) error
	// KeepAlive keeps a lease alive. This call blocks.
	KeepAlive(ctx context.Context, leaseID int64) error
}

type ListCb func(key, val []byte, rev, modRev int64) error

type Obj interface {
	// Validate checks all object fields to make sure they do not
	// contain invalid data. Primarily used to validate data passed
	// in by a user. FieldMap specifies fields for update, allowing
	// to distinguish between the zero value and "not set".
	// It will be nil for create.
	Validate(fmap FieldMap) error
	// CopyInFields copies in modified fields for an Update.
	//CopyInFields(src Obj)
	// GetObjKey returns the ObjKey that uniquely identifies the object.
	GetObjKey() ObjKey
	// HasFields returns true if the object contains a Fields []string
	// field used for updating only certain fields on Update.
	HasFields() bool
}

type ObjKey interface {
	// GetKeyString returns a string representation of the ObjKey
	GetKeyString() string
	// Validate checks that the key object fields do not contain
	// invalid or missing data.
	ValidateKey() error
	// NotFoundError returns a not found error describing the key.
	NotFoundError() error
	// ExistsError returns an already exists error describing the key.
	ExistsError() error
	// Get key tags for logging and tagging
	GetTags() map[string]string
}

type SyncCb func(ctx context.Context, data *SyncCbData)

type SyncCbAction int32

type SyncCbData struct {
	// action on the data
	Action SyncCbAction
	// key - will be nil for action SyncListAllStart/End/Error
	Key []byte
	// value - will be nil for action SyncListAllStart/End/Error
	Value []byte
	// global revision of the data
	Rev int64
	// last modified revision of the data
	ModRev int64
	// MoreEvents indicates there are more changes in the revision.
	// With transactions, multiple changes can be done in the same
	// revision, but each change is called back separately.
	// MoreEvents is set to true if there are more changes to be
	// called back for the current revision.
	MoreEvents bool
}