x/ref/services/syncbase/sync/vsync.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/v23/security/access"
)

// temporary types
type ObjId string
type Version uint64
type GroupId uint64

// DeviceId is the globally unique Id of a device.
type DeviceId string
// GenId is the unique Id per generation per device.
type GenId uint64
// SeqNum is the log sequence number.
type SeqNum uint64
// GenVector is the generation vector.
type GenVector map[DeviceId]GenId
// TxId is the unique Id per transaction.
type TxId uint64
// GroupIdSet is the list of SyncGroup Ids.
type GroupIdSet []GroupId

const (
	// NodeRec type log record adds a new node in the dag.
	NodeRec = byte(0)
	// LinkRec type log record adds a new link in the dag.
	LinkRec = byte(1)

	// Sync interface has Object name "global/vsync/<devid>/sync".
	SyncSuffix = "sync"

	// temporary nil values
	NoObjId = ObjId("")
	NoVersion = Version(0)
	NoGroupId = GroupId(0)
)

// LogRec represents a single log record that is exchanged between two
// peers.
//
// It contains log related metadata: DevId is the id of the device
// that created the log record, SyncRootId is the id of a SyncRoot this log
// record was created under, GNum is the Id of the generation that the
// log record is part of, SeqNum is the log sequence number of the log
// record in the generation GNum, and RecType is the type of log
// record.
//
// It also contains information relevant to the updates to an object
// in the store: ObjId is the id of the object that was
// updated. CurVers is the current version number of the
// object. Parents can contain 0, 1 or 2 parent versions that the
// current version is derived from, and Value is the actual value of
// the object mutation.
type LogRec struct {
	// Log related information.
	DevId      DeviceId
	SyncRootId ObjId
	GenNum     GenId
	SeqNum     SeqNum
	RecType    byte

	// Object related information.
	ObjId     ObjId
	CurVers   Version
	Parents   []Version
	Value     LogValue
}

// LogValue represents an object mutation within a transaction.
type LogValue struct {
	// Mutation is the store mutation representing the change in the object.
	//Mutation raw.Mutation
	// SyncTime is the timestamp of the mutation when it arrives at the Sync server.
	SyncTime int64
	// Delete indicates whether the mutation resulted in the object being
	// deleted from the store.
	Delete bool
	// TxId is the unique Id of the transaction this mutation belongs to.
	TxId TxId
	// TxCount is the number of mutations in the transaction TxId.
	TxCount uint32
}

// DeviceStats contains high-level information on a device participating in
// peer-to-peer synchronization.
type DeviceStats struct {
	DevId         DeviceId                  // Device Id.
	LastSync      int64                     // Timestamp of last sync from the device.
	GenVectors    map[ObjId]GenVector         // Generation vectors per SyncRoot.
	IsSelf        bool                      // True if the responder is on this device.
}

// SyncGroupStats contains high-level information on a SyncGroup.
type SyncGroupStats struct {
	Name       string         // Global name of the SyncGroup.
	Id         GroupId        // Global Id of the SyncGroup.
	Path       string         // Local store path for the root of the SyncGroup.
	RootObjId  ObjId          // Id of the store object at the root path.
	NumJoiners uint32         // Number of members currently in the SyncGroup.
}

// SyncGroupMember contains information on a SyncGroup member.
type SyncGroupMember struct {
	Name       string         // Name of SyncGroup member.
	Id         GroupId        // Global Id of the SyncGroup.
	Metadata   JoinerMetaData // Extra member metadata.
}

// A SyncGroupInfo is the conceptual state of a SyncGroup object.
type SyncGroupInfo struct {
	Id         GroupId         // Globally unique SyncGroup Id.
	ServerName string          // Global Vanadium name of SyncGroupServer.
	GroupName  string          // Relative name of group; global name is ServerName/GroupName.
	Config     SyncGroupConfig // Configuration parameters of this SyncGroup.
	ETag       string          // Version Id for concurrency control.

	// A map from joiner names to the associated metaData for devices that
	// have called Join() or Create() and not subsequently called Leave()
	// or had Eject() called on them.  The map returned by the calls below
	// may contain only a subset of joiners if the number is large.
	Joiners map[string]JoinerMetaData

	// Blessings for joiners of this SyncGroup will be self-signed by the
	// SyncGroupServer, and will have names matching
	// JoinerBlessingPrefix/Name/...
	JoinerBlessingPrefix string
}

// A SyncGroupConfig contains some fields of SyncGroupInfo that
// are passed at create time, but which can be changed later.
type SyncGroupConfig struct {
	Desc         string               // Human readable description.
	Options      map[string]any       // Options for future evolution.
	Permissions  access.Permissions   // The object's Permissions.

	// Mount tables used to advertise for synchronization.
	// Typically, we will have only one entry.  However, an array allows
	// mount tables to be changed over time.
	MountTables []string

	BlessingsDurationNanos int64   // Duration of blessings, in nanoseconds. 0 => use server default.
}

// A JoinerMetaData contains the non-name information stored per joiner.
type JoinerMetaData struct {
	// SyncPriority is a hint to bias the choice of syncing partners.
	// Members of the SyncGroup should choose to synchronize more often
	// with partners with lower values.
	SyncPriority int32
}

// Sync allows a device to GetDeltas from another device.
type Sync interface {
	// GetDeltas returns a device's current generation vector and all
	// the missing log records when compared to the incoming generation vector.
	GetDeltas(in map[ObjId]GenVector, sgs map[ObjId]GroupIdSet, clientId DeviceId) stream<_, LogRec> (map[ObjId]GenVector | error) {access.Write}

	// GetObjectHistory returns the mutation history of a store object.
	GetObjectHistory(oid ObjId) stream<_, LogRec> (Version | error)

	// GetDeviceStats returns information on devices participating in
	// peer-to-peer synchronization.
	GetDeviceStats() stream<_, DeviceStats> error {access.Admin}

	// GetSyncGroupMembers returns information on SyncGroup members.
	// If SyncGroup names are specified, only members of these SyncGroups
	// are returned.  Otherwise, if the slice of names is nil or empty,
	// members of all SyncGroups are returned.
	GetSyncGroupMembers(sgNames []string) stream<_, SyncGroupMember> error {access.Admin}

	// GetSyncGroupStats returns high-level information on all SyncGroups.
	GetSyncGroupStats() stream<_, SyncGroupStats> error {access.Admin}

	// Dump writes to the Sync log internal information used for debugging.
	Dump() error {access.Admin}
}