summaryrefslogtreecommitdiffstats
path: root/lib
diff options
context:
space:
mode:
authorFlorian Pritz <bluewind@xinu.at>2017-06-11 16:05:28 +0200
committerFlorian Pritz <bluewind@xinu.at>2017-06-11 16:05:28 +0200
commitfb0148d9827433f6afeeb1588b6c1e851a265454 (patch)
treea7ff31ff86266f9b37a5ef46cf6737c9f656bc0e /lib
parentef8c42d5140a28313821ad9ef46976ca424e43ec (diff)
downloadApp-BorgRestore-fb0148d9827433f6afeeb1588b6c1e851a265454.tar.gz
App-BorgRestore-fb0148d9827433f6afeeb1588b6c1e851a265454.tar.xz
Document main package
Signed-off-by: Florian Pritz <bluewind@xinu.at>
Diffstat (limited to 'lib')
-rw-r--r--lib/App/BorgRestore.pm128
1 files changed, 128 insertions, 0 deletions
diff --git a/lib/App/BorgRestore.pm b/lib/App/BorgRestore.pm
index 92faa4f..a3f4838 100644
--- a/lib/App/BorgRestore.pm
+++ b/lib/App/BorgRestore.pm
@@ -41,6 +41,8 @@ App::BorgRestore - Restore paths from borg backups
# Restore a path from a backup that is at least 5 days old. Optionally
# restore it to a different directory than the original.
+ # Look at the implementation of this method if you want to know how the
+ # other parts of this module work together.
$app->restore_simple($path, "5days", $optional_destination_directory);
=head1 DESCRIPTION
@@ -60,13 +62,29 @@ usage.
This package uses L<Log::Any> for logging.
+=head1 METHODS
+=head2 Constructors
+=head3 new
+ App::BorgRestore->new(\%deps);
+Returns a new instance. The following dependencies can be injected:
+=over
+=item * borg (optional)
+This object is used to interact with the borg repository of the system.
+Defaults to L<App::BorgRestore::Borg>
+
+=item * db (optional)
+
+This object is used to store the extracted data (the cache). Defaults to
+L<App::BorgRestore::DB>
+
+=back
=cut
@@ -83,6 +101,13 @@ method new($class: $deps = {}) {
return $self;
}
+=head3 new_no_defaults
+
+Same as C<new> except that this does not initialize unset dependencies with
+their default values. This is probably only useful for tests.
+
+=cut
+
method new_no_defaults($class: $deps) {
my $self = {};
bless $self, $class;
@@ -93,6 +118,16 @@ method new_no_defaults($class: $deps) {
return $self;
}
+=head2 Public Methods
+
+=head3 resolve_relative_path
+
+ my $abs_path = $app->resolve_relative_path($path);
+
+Returns an absolute path for a given path.
+
+=cut
+
method resolve_relative_path($path) {
my $canon_path = File::Spec->canonpath($path);
my $abs_path = abs_path($canon_path);
@@ -106,6 +141,18 @@ method resolve_relative_path($path) {
return $abs_path;
}
+=head3 map_path_to_backup_path
+
+ my $path_in_backup = $app->map_path_to_backup_path($abs_path);
+
+Maps an absolute path from the system to the path that needs to be looked up in
+/ extracted from the backup using C<@backup_prefixes> from
+L<App::BorgRestore::Settings>.
+
+Returns the mapped path (string).
+
+=cut
+
method map_path_to_backup_path($abs_path) {
my $backup_path = $abs_path;
@@ -119,6 +166,17 @@ method map_path_to_backup_path($abs_path) {
return $backup_path;
}
+=head3 find_archives
+
+ my $archives = $app->find_archives($path);
+
+Returns an arrayref of archives (hash with "modification_time" and "archive")
+from the database that contain a path. Duplicates are filtered based on the
+modification time of the path in the
+archives.
+
+=cut
+
method find_archives($path) {
my %seen_modtime;
my @ret;
@@ -145,6 +203,18 @@ method find_archives($path) {
return \@ret;
}
+=head3 get_all_archives
+
+ my $archives = $app->get_all_archives();
+
+Returns an arrayref of archives (hash with "modification_time" and "archive")
+from borg directly. This does not require the database to be populated. Instead
+it just fetches a list of archives from borg at runtime and returns it.
+
+The returned data structure is the same as that returned by C<find_archives>.
+
+=cut
+
method get_all_archives() {
#my %seen_modtime;
my @ret;
@@ -167,6 +237,18 @@ method get_all_archives() {
return \@ret;
}
+=head3 select_archive_timespec
+
+ my $archive = $app->select_archive_timespec($archives, $timespec);
+
+Returns one archive from C<$archives> that is older than the value of
+C<$timespec>.
+
+I<timespec> is a string of the form "<I<number>><I<unit>>" with I<unit> being one of the following:
+s (seconds), min (minutes), h (hours), d (days), m (months = 31 days), y (year). Example: "5.5d"
+
+=cut
+
method select_archive_timespec($archives, $timespec) {
my $seconds = $self->_timespec_to_seconds($timespec);
if (!defined($seconds)) {
@@ -221,6 +303,22 @@ method _timespec_to_seconds($timespec) {
return;
}
+=head3 restore
+
+ $app->restore($backup_path, $archive, $destination);
+
+Restore a backup path (returned by C<map_path_to_backup_path>) from an archive
+(returned by C<find_archives> or C<get_all_archives>) to a destination
+directory.
+
+If the destination path (C<$destination/$last_elem_of_backup_path>) exists, it
+is removed before beginning extraction from the backup.
+
+Warning: This method temporarily modifies the current working directory of the
+process during method execution since this is required by C<`borg extract`>.
+
+=cut
+
method restore($path, $archive, $destination) {
$destination = App::BorgRestore::Helper::untaint($destination, qr(.*));
$path = App::BorgRestore::Helper::untaint($path, qr(.*));
@@ -244,6 +342,19 @@ method restore($path, $archive, $destination) {
$self->{borg}->restore($components_to_strip, $archive_name, $path);
}
+=head3 restore_simple
+
+ $app->restore_simple($path, $timespec, $destination);
+
+Restores a C<$path> based on a C<$timespec> to an optional C<$destination>. If
+C<$destination> is not specified, it is set to the parent directory of C<$path>
+so that C<$path> is restored to its original place.
+
+Refer to L</"select_archive_timespec"> for an explanation of the C<$timespec>
+variable.
+
+=cut
+
method restore_simple($path, $timespec, $destination) {
my $abs_path = $self->resolve_relative_path($path);
my $backup_path = $self->map_path_to_backup_path($abs_path);
@@ -281,6 +392,14 @@ method _add_path_to_hash($hash, $path, $time) {
}
}
+=head3 get_missing_items
+
+ my $items = $app->get_missing_items($have, $want);
+
+Returns an arrayref of items that are part of C<$want>, but not of C<$have>.
+
+=cut
+
method get_missing_items($have, $want) {
my $ret = [];
@@ -366,6 +485,15 @@ method _save_node($archive_id, $prefix, $node) {
}
}
+
+=head3 update_cache
+
+ $app->update_cache();
+
+Updates the database used by e.g. C<find_archives>.
+
+=cut
+
method update_cache() {
$log->debug("Updating cache if required");