// Package raw defines a raw interface for the Veyron store.
//
// The raw interface supports synchronizing with remote stores by transporting
// Mutations.

package raw

import (
  "veyron2/storage"
  "veyron2/services/watch/types"
)

const (
  // The raw Store has Object name "<mount>/.store.raw", where <mount> is the
  // Object name of the mount point.
  RawStoreSuffix = ".store.raw"

  // NoVersion means the entry is not present in the store.
  NoVersion = Version(0)
)

// Version identifies the value in the store for a key at some point in time.
// The version is a numeric identifier that is globally unique within the space
// of a single ID, meaning that if two stores contain an entry with the same ID
// and version, then the entries represent the same thing, at the same point in
// time (as agreed upon by the two stores).
type Version uint64

// DEntry is a directory entry.
type DEntry struct {
  Name string
  ID   storage.ID
}

// Mutation represents an update to an entry in the store, and contains enough
// information for a privileged service to replicate the update elsewhere.
type Mutation struct {
  // ID is the key that identifies the entry.
  ID storage.ID

  // The version of the entry immediately before the update. For new entries,
  // the PriorVersion is NoVersion.
  PriorVersion Version

  // The version of the entry immediately after the update. For deleted entries,
  // the Version is NoVersion.
  Version Version

  // IsRoot is true if
  // 1) The entry was the store root immediately before being deleted, or
  // 2) The entry is the store root immediately after the update.
  IsRoot bool

  // Value is value stored at this entry.
  Value any

  // Dir is the implicit directory of this entry, and may contain references
  // to other entries in the store.
  Dir []DEntry
}

// Request specifies how to resume from a previous Watch call.
type Request struct {
  // ResumeMarker specifies how to resume from a previous Watch call.
  // See the ResumeMarker type for detailed comments.
  ResumeMarker types.ResumeMarker
}

// Store defines a raw interface for the Veyron store. Mutations can be received
// via the Watcher interface, and committed via PutMutation.
type Store interface {
  // Watch returns a stream of all changes.
  Watch(Req Request) stream<_, types.Change> error

  // PutMutations atomically commits a stream of Mutations when the stream is
  // closed. Mutations are not committed if the request is cancelled before
  // the stream has been closed.
  PutMutations() stream<Mutation, _> error
}