v23/services/syncbase/nosql/types.vdl

// Copyright 2015 The Vanadium Authors. All rights reserved.
// Use of this source code is governed by a BSD-style
// license that can be found in the LICENSE file.

package nosql

import (
	"v.io/v23/security/access"
)

// BatchOptions configures a batch.
// TODO(sadovsky): Add more options, e.g. to configure isolation, timeouts,
// whether to track the read set and/or write set, etc.
// TODO(sadovsky): Maybe add a DefaultBatchOptions() function that initializes
// BatchOptions with our desired defaults. Clients would be encouraged to
// initialize their BatchOptions object using that function and then modify it
// to their liking.
type BatchOptions struct {
	// Arbitrary string, typically used to describe the intent behind a batch.
	// Hints are surfaced to clients during conflict resolution.
	// TODO(sadovsky): Use "any" here?
	Hint string

	// ReadOnly specifies whether the batch should allow writes.
	// If ReadOnly is set to true, Abort() should be used to release any resources
	// associated with this batch (though it is not strictly required), and
	// Commit() will always fail.
	ReadOnly bool
}

// PrefixPermissions represents a pair of (prefix, perms).
type PrefixPermissions struct {
	Prefix string
	Perms  access.Permissions
}

// KeyValue is a key-value pair.
type KeyValue struct {
	Key   string
	Value []byte
}

// SyncGroupSpec contains the specification for a SyncGroup.
type SyncGroupSpec struct {
	// Human readable description.
	Description string

	// Permissions for the SyncGroup.
	Perms access.Permissions

	// SyncGroup prefixes (relative to the database).  Prefixes
	// must take the form "<tableName>/<rowKeyPrefix>" where
	// tableName is non-empty.
	Prefixes []string

	// Mount tables at which to advertise this SyncGroup. These
	// are the mount tables used for rendezvous in addition to the
	// one in the neighborhood. Typically, we will have only one
	// entry.  However, an array allows mount tables to be changed
	// over time.
	//
	// TODO(hpucha): Figure out a convention for
	// advertising SyncGroups in the mount table.
	MountTables []string

	// Option to change the privacy of the SyncGroup. Configures
	// whether blobs in a SyncGroup can be served to clients
	// holding blobrefs obtained from other SyncGroups.
	IsPrivate bool
}

// SyncGroupMemberInfo contains per-member metadata.
type SyncGroupMemberInfo struct {
	SyncPriority byte
}

// BlobRef is a reference to a blob.
type BlobRef string

const (
	NullBlobRef = BlobRef("")
)

// FetchState represents the state transitions of a blob fetch.
type FetchState enum {
	Pending // Fetch request is queued.
	Locating // Blob discovery is in progress to find a source for the blob.
	Fetching // Blob transfer is in progress.
	Done // Blob is locally cached.
}

// FetchStatus describes the progress of an asynchronous blob fetch.
type FetchStatus struct {
	State FetchState // State of the blob fetch request.
	Received uint64 // Total number of bytes received.
	Total uint64 // Blob size.
}

// ResumeMarker is a pointer in the database event log.
type ResumeMarker string

// TablePrefixRange describes a prefix range in a table.
type TablePrefixRange struct {
	Table  string
	Prefix string
}

// WatchRequest specifies which rows should be watched and a starting point
// in the database event log from which to receive updates.
type WatchRequest struct {
	// Ranges specifies the subset of the database for which the client wants
	// updates.
	Ranges []TablePrefixRange

	// ResumeMarker is the starting point in the database event log from which
	// to receive updates.
	ResumeMarker ResumeMarker
}

// ChangeType describes the type of the row change: Put or Delete.
// TODO(rogulenko): Consider adding the Shell type.
type ChangeType enum {
	Put
	Delete
}

// Change is the new value for a watched entity.
type Change struct {
	// Table is the name of the table that contains the changed row.
	Table string

	// Row is the key of the changed row.
	Row string

	// ChangeType describes the type of the change. If the ChangeType equals to
	// Put, then the row exists in the table and the Value contains the new
	// value for this row. If the state equals to Delete, then the row was
	// removed from the table.
	ChangeType ChangeType

	// Value is the new value for the row if the state equals to Put,
	// otherwise the Value is nil.
	Value []byte

	// ResumeMarker provides a compact representation of all the messages
	// that have been received by the caller for the given Watch call.
	// This marker can be provided in the Request message to allow the caller
	// to resume the stream watching at a specific point without fetching the
	// initial state.
	ResumeMarker ResumeMarker

	// FromSync indicates whether the change came from sync. If FromSync is
	// false, then the change originated from the local device.
	FromSync bool

	// If true, this Change is followed by more Changes that are in the
	// same batch as this Change.
	Continued bool
}