Refactor snapshot management: integrate logging, enhance concurrency with mutex, add clean extraction option, and update gRPC ListSnapshots with ListOptions.

interfaces/snapshot.go

@@ -7,27 +7,40 @@ import (
 	"gitea.unprism.ru/KRBL/Agate/store"
 )
 
-// SnapshotManager defines the interface that the server needs to interact with snapshots
+// SnapshotManager is an interface that defines operations for managing and interacting with snapshots.
 type SnapshotManager interface {
-	// GetSnapshotDetails retrieves detailed metadata for a specific snapshot
+	// CreateSnapshot creates a new snapshot from the specified source directory, associating it with a given name and parent ID.
+	// Returns the created Snapshot with its metadata or an error if the process fails.
+	CreateSnapshot(ctx context.Context, sourceDir string, name string, parentID string) (*store.Snapshot, error)
+
+	// GetSnapshotDetails retrieves detailed metadata for a specific snapshot identified by its unique snapshotID.
+	// Returns a Snapshot object containing metadata
 	GetSnapshotDetails(ctx context.Context, snapshotID string) (*store.Snapshot, error)
 
-	// ListSnapshots retrieves a list of all available snapshots
-	ListSnapshots(ctx context.Context) ([]store.SnapshotInfo, error)
+	// ListSnapshots retrieves a list of available snapshots with filtering and pagination options.
+	ListSnapshots(ctx context.Context, opts store.ListOptions) ([]store.SnapshotInfo, error)
 
-	// OpenFile retrieves and opens a file from the specified snapshot
+	// DeleteSnapshot removes a snapshot identified by snapshotID. Returns an error if the snapshot does not exist or cannot be deleted.
+	DeleteSnapshot(ctx context.Context, snapshotID string) error
+
+	// OpenFile retrieves and opens a file from the specified snapshot, returning a readable stream and an error, if any.
 	OpenFile(ctx context.Context, snapshotID string, filePath string) (io.ReadCloser, error)
 
-	// CreateSnapshot creates a new snapshot from the specified source directory
-	CreateSnapshot(ctx context.Context, sourceDir string, name string, parentID string) (*store.Snapshot, error)
+	// ExtractSnapshot extracts the contents of a specified snapshot to a target directory at the given path.
+	// If cleanTarget is true, the target directory will be cleaned before extraction.
+	// Returns an error if the snapshot ID is invalid or the extraction fails.
+	ExtractSnapshot(ctx context.Context, snapshotID string, path string, cleanTarget bool) error
+
+	// UpdateSnapshotMetadata updates the metadata of an existing snapshot, allowing changes to its name.
+	UpdateSnapshotMetadata(ctx context.Context, snapshotID string, newName string) error
 }
 
 // SnapshotServer defines the interface for a server that can share snapshots
 type SnapshotServer interface {
-	// Start initializes and begins the server's operation
+	// Start initializes and begins the server's operation, handling incoming requests or processes within the provided context.
 	Start(ctx context.Context) error
 
-	// Stop gracefully shuts down the server
+	// Stop gracefully shuts down the server, releasing any allocated resources and ensuring all operations are completed.
 	Stop(ctx context.Context) error
 }