services/syncbase/vsync/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 vsync

import (
	"v.io/x/ref/services/syncbase/server/interfaces"
)

// Key prefixes for sync data structures. All these prefixes are prepended with
// util.SyncPrefix.
const (
	logPrefix     = "log"  // log state.
	logDataPrefix = "data" // data log state.
	dbssPrefix    = "dbss" // database sync state.
	dagPrefix     = "dag"  // dag state.
	sgPrefix      = "sg"   // syncgroup state.
)

// syncData represents the persistent state of the sync module.
type syncData struct {
	Id uint64
}

// localGenInfo represents the persistent state corresponding to local generations.
type localGenInfo struct {
	Gen        uint64 // local generation number incremented on every local update.
	CheckptGen uint64 // local generation number advertised to remote peers (used by the responder).
}

// dbSyncState represents the persistent sync state of a Database.
type dbSyncState struct {
	Data     localGenInfo
	Sgs      map[interfaces.GroupId]localGenInfo
	GenVec   interfaces.GenVector // generation vector capturing the locally-known generations of remote peers for data in Database.
	SgGenVec interfaces.GenVector // generation vector capturing the locally-known generations of remote peers for SyncGroups in Database.
}

// localLogRec represents the persistent local state of a log record. Metadata
// is synced across peers, while pos is local-only.
type localLogRec struct {
	Metadata interfaces.LogRecMetadata
	Pos      uint64 // position in the Database log.
}

// sgLocalState holds the SyncGroup local state, only relevant to this member
// (i.e. the local Syncbase).  This is needed for crash recovery of the internal
// state transitions of the SyncGroup.
type sgLocalState struct {
	// The count of local joiners to the same SyncGroup.
	NumLocalJoiners uint32

	// The SyncGroup is watched when the sync Watcher starts processing the
	// SyncGroup data.  When a SyncGroup is created or joined, an entry is
	// added to the Watcher queue (log) to inform it from which point to
	// start accepting store mutations, an asynchronous notification similar
	// to regular store mutations.  When the Watcher processes that queue
	// entry, it sets this bit to true.  When Syncbase restarts, the value
	// of this bit allows the new sync Watcher to recreate its in-memory
	// state by resuming to watch only the prefixes of SyncGroups that were
	// previously being watched.
	Watched bool

	// The SyncGroup was published here by this remote peer (if non-empty
	// string), typically the SyncGroup creator.  In this case the SyncGroup
	// cannot be GCed locally even if it has no local joiners.
	RemotePublisher string

	// The SyncGroup is in pending state on a device that learns the current
	// state of the SyncGroup from another device but has not yet received
	// through peer-to-peer sync the history of the changes (DAG and logs).
	// This happens in two cases:
	// 1- A joiner was accepted into a SyncGroup by a SyncGroup admin and
	//    only given the current SyncGroup info synchronously and will
	//    receive the full history later via p2p sync.
	// 2- A remote server where the SyncGroup is published was told by the
	//    SyncGroup publisher the current SyncGroup info synchronously and
	//    will receive the full history later via p2p sync.
	// The pending state is over when the device reaches or exceeds the
	// knowledge level indicated in the pending genvec.  While SyncPending
	// is true, no local SyncGroup mutations are allowed (i.e. no join or
	// set-spec requests).
	SyncPending   bool
	PendingGenVec interfaces.PrefixGenVector
}

// dagNode holds the information on an object mutation in the DAG.  The node
// information is extracted from the log records exchanged between Syncbases.
// They are also stored in the DAG node to improve DAG traversal for conflict
// resolution and pruning without having to fetch the full log record.
type dagNode struct {
	Level    uint64   // node distance from root
	Parents  []string // references to parent versions
	Logrec   string   // reference to log record
	BatchId  uint64   // ID of a write batch
	Shell    bool     // true when the data is hidden due to permissions
	Deleted  bool     // true if the change was a delete
	PermId   string   // ID of the permissions controlling this version
	PermVers string   // current version of the permissions object
}

// batchInfo holds the information on a write batch:
// - The map of syncable (versioned) objects: {oid: version}
// - The total count of batch objects, including non-syncable ones.
// TODO(rdaoud): add support to track the read and scan sets.
type batchInfo struct {
	Objects map[string]string
	Count   uint64
}