// 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 interfaces

import (
	wire "v.io/syncbase/v23/services/syncbase/nosql"
	"v.io/v23/security/access"
)

// Sync defines methods for data exchange between Syncbases.
// TODO(hpucha): Flesh this out further.
type Sync interface {
	// GetDeltas returns the responder's current generation vector and all
	// the missing log records when compared to the initiator's generation
	// vector. This process happens one Database at a time encompassing all
	// the SyncGroups common to the initiator and the responder. For each
	// Database, the initiator sends a DeltaReq. In response, the
	// responder sends a "Start" DeltaResp record, all the missing log
	// records, the responder's genvector, and a "Finish" DeltaResp
	// record. The initiator parses the stream between a Start and a Finish
	// record as the response to its DeltaReq, and then moves on to the
	// next Database in common with this responder.
	GetDeltas(initiator string) stream<DeltaReq, DeltaResp> error {access.Read}

	// SyncGroup-related methods.

	// PublishSyncGroup is typically invoked on a "central" peer to publish
	// the SyncGroup.
	PublishSyncGroup(sg SyncGroup) error {access.Write}

	// JoinSyncGroupAtAdmin is invoked by a prospective SyncGroup member's
	// Syncbase on a SyncGroup admin. It checks whether the requestor is
	// allowed to join the named SyncGroup, and if so, adds the requestor to
	// the SyncGroup.
	JoinSyncGroupAtAdmin(sgName, joinerName string, myInfo wire.SyncGroupMemberInfo) (SyncGroup | error) {access.Read}

	// BlobSync methods.

	// HaveBlob verifies that the peer has the requested blob, and if
	// present, returns its size.
	HaveBlob(br wire.BlobRef) (int64 | error)

	// FetchBlob fetches the requested blob.
	FetchBlob(br wire.BlobRef) stream<_, []byte> error

	// Methods for incremental blob transfer. The transfer starts with the
	// receiver making a FetchBlobRecipe call to the sender for a given
	// BlobRef. The sender, in turn, sends the chunk hashes of all the
	// chunks that make up the requested blob (blob recipe). The receiver
	// looks up the chunk hashes in its local blob store, and identifies the
	// missing ones. The receiver then fetches the missing chunks using a
	// FetchChunks call from the sender. Finally, the receiver finishes the
	// blob fetch by combining the chunks obtained over the network with the
	// already available local chunks as per the blob recipe.
	FetchBlobRecipe(br wire.BlobRef) stream<_, ChunkHash> error
	FetchChunks() stream<ChunkHash, ChunkData> error
}