filesystem_store.go

package qi

import (
	"errors"
	"os"
	"path/filepath"

	"github.com/iamseth/yin"
)

// DocumentSnapshotFilename is the durable qi generation-checkpoint filename
// stored under a data directory. A checkpoint envelopes document identity and a
// yin snapshot; it is not the visible JSON projection, a bare yin snapshot, or
// a yin delta.
const DocumentSnapshotFilename = "document.snapshot.json"

// SnapshotPath returns the durable qi generation-checkpoint path for dataDir.
func SnapshotPath(dataDir string) string {
	return filepath.Join(dataDir, DocumentSnapshotFilename)
}

// OpenStore uses qi startup precedence: load the complete qi checkpoint
// <dataDir>/document.snapshot.json when present, else seed from visiblePath
// when present, else create an empty document. replica is always the continuing
// runtime-local author; checkpoint data never supplies it. A non-empty dataDir
// makes every subsequent mutation durable. An empty dataDir keeps the Store
// in-memory.
//
// visiblePath is used only while opening. The returned Store retains no file
// paths; callers own subsequent visible-projection reads and writes.
func OpenStore(replica yin.ReplicaID, dataDir, visiblePath string) (*Store, error) {
	return OpenStoreForDocument(replica, DocumentIdentity{DocumentID: DefaultDocumentID, Generation: InitialGeneration}, dataDir, visiblePath)
}

// OpenStoreForDocument opens or seeds a Store with an explicit stable document
// identity. An existing checkpoint may have a later generation, but its stable
// document ID must match identity.DocumentID. Checkpoint decode uses replica
// for future local writes rather than adopting a replica identity from the
// payload. A non-empty dataDir installs an atomic filesystem committer before
// the Store is returned; opening visible or empty state alone does not create a
// checkpoint.
//
// visiblePath is startup input only. Callers own later projection I/O through
// ExportVisibleJSON and ImportVisibleJSON.
func OpenStoreForDocument(replica yin.ReplicaID, identity DocumentIdentity, dataDir, visiblePath string) (*Store, error) {
	if err := validateStoreIdentity(replica, identity); err != nil {
		return nil, err
	}

	var committer CheckpointCommitter
	if dataDir != "" {
		committer = newFileCheckpointCommitter(SnapshotPath(dataDir), 0o644)
		checkpoint, err := os.ReadFile(SnapshotPath(dataDir))
		if err == nil {
			return newDurableStore(replica, identity, checkpoint, committer)
		}
		if !errors.Is(err, os.ErrNotExist) {
			return nil, err
		}
	}

	var file *JSONFile
	if visiblePath != "" {
		data, err := os.ReadFile(visiblePath)
		if err == nil {
			file, err = ParseJSONFile(replica, data)
			if err != nil {
				return nil, err
			}
		} else if !errors.Is(err, os.ErrNotExist) {
			return nil, err
		}
	}
	if file == nil {
		var err error
		file, err = NewJSONFile(replica)
		if err != nil {
			return nil, err
		}
	}
	return newStoreWithCommitter(replica, identity, file, committer)
}