session.go

package qi

import (
	"sync"

	"github.com/iamseth/yin"
)

// Session tracks generation-scoped per-peer cursors around a caller-supplied
// JSONFile. Its mutex serializes Session operations and validates identity before
// yin ingest, but callers retain the file and must not mutate it concurrently.
// Store is the preferred owning, concurrency-safe end-to-end boundary.
type Session struct {
	mu       sync.Mutex
	identity DocumentIdentity
	file     *JSONFile
	cursors  map[yin.ReplicaID]Cursor
}

// NewSession wraps file for the default document generation. It does not copy or
// take exclusive ownership of file; the caller must coordinate all direct use.
// NewSession panics if file is nil.
func NewSession(file *JSONFile) *Session {
	return NewSessionForDocument(file, DocumentIdentity{DocumentID: DefaultDocumentID, Generation: InitialGeneration})
}

// NewSessionForDocument wraps file at an explicit document boundary. It does
// not copy or take exclusive ownership of file; the caller must coordinate all
// direct use. It panics if file is nil or identity is invalid.
func NewSessionForDocument(file *JSONFile, identity DocumentIdentity) *Session {
	if file == nil {
		panic("qi: nil JSONFile")
	}
	if err := validateIdentity(identity); err != nil {
		panic(err)
	}
	return &Session{identity: identity, file: file, cursors: make(map[yin.ReplicaID]Cursor)}
}

// Cursor returns a copy of the generation-scoped cursor recorded for peer.
func (s *Session) Cursor(peer yin.ReplicaID) Cursor {
	s.mu.Lock()
	defer s.mu.Unlock()
	cursor, ok := s.cursors[peer]
	if !ok {
		return Cursor{Identity: s.identity}
	}
	cursor.Version = cursor.Version.Clone()
	return cursor
}

// SetCursor replaces a peer cursor after validating its identity.
func (s *Session) SetCursor(peer yin.ReplicaID, cursor Cursor) error {
	s.mu.Lock()
	defer s.mu.Unlock()
	if err := compareIdentity(s.identity, cursor.Identity); err != nil {
		return err
	}
	cursor.Version = cursor.Version.Clone()
	s.cursors[peer] = cursor
	return nil
}

// Mark joins version into a peer's current-generation cursor.
func (s *Session) Mark(peer yin.ReplicaID, cursor Cursor) error {
	s.mu.Lock()
	defer s.mu.Unlock()
	if err := compareIdentity(s.identity, cursor.Identity); err != nil {
		return err
	}
	current := s.cursors[peer]
	current.Identity = s.identity
	current.Version = current.Version.Join(cursor.Version)
	s.cursors[peer] = current
	return nil
}

// ExtractDeltaFor returns changes beyond a peer's generation-scoped cursor
// without advancing it. Call Mark or SetCursor only after the caller's protocol
// has established the corresponding peer coverage.
func (s *Session) ExtractDeltaFor(peer yin.ReplicaID) (DeltaArtifact, bool, error) {
	s.mu.Lock()
	defer s.mu.Unlock()
	cursor, ok := s.cursors[peer]
	if !ok {
		cursor = Cursor{Identity: s.identity}
	}
	return s.extractLocked(cursor)
}

// ExtractDeltaSince returns changes beyond cursor without advancing it.
func (s *Session) ExtractDeltaSince(cursor Cursor) (DeltaArtifact, bool, error) {
	s.mu.Lock()
	defer s.mu.Unlock()
	return s.extractLocked(cursor)
}

// ApplyDeltaFrom rejects a mismatched artifact before decoding or applying yin
// and marks the sender cursor only after successful decoding.
func (s *Session) ApplyDeltaFrom(peer yin.ReplicaID, artifact DeltaArtifact) (bool, error) {
	s.mu.Lock()
	defer s.mu.Unlock()
	if err := compareIdentity(s.identity, artifact.Identity); err != nil {
		return false, err
	}
	delta, err := decodeDelta(artifact.Payload)
	if err != nil {
		return false, err
	}
	changed := s.file.doc.ApplyDelta(delta)
	current := s.cursors[peer]
	current.Identity = s.identity
	current.Version = current.Version.Join(delta.Version())
	s.cursors[peer] = current
	return changed, nil
}

func (s *Session) extractLocked(cursor Cursor) (DeltaArtifact, bool, error) {
	if err := compareIdentity(s.identity, cursor.Identity); err != nil {
		return DeltaArtifact{}, false, err
	}
	delta := s.file.doc.ExtractDelta(cursor.Version.Clone())
	if delta == nil {
		return DeltaArtifact{}, false, nil
	}
	data, err := encodeDelta(delta)
	if err != nil {
		return DeltaArtifact{}, false, err
	}
	return DeltaArtifact{Identity: s.identity, Payload: data}, true, nil
}