File Coverage

blib/lib/Backblaze/B2V2Client.pm

Criterion	Covered	Total	%
statement	69	253	27.2
branch	15	86	17.4
condition	4	59	6.7
subroutine	13	25	52.0
pod	13	17	76.4
total	114	440	25.9

package Backblaze::B2V2Client;
# API client library for V2 of the API to Backblaze B2 object storage
# Allows for creating/deleting buckets, listing files in buckets, and uploading/downloading files

$Backblaze::B2V2Client::VERSION = '1.6';

# our dependencies:
use Cpanel::JSON::XS;
use Digest::SHA qw(sha1_hex);
use MIME::Base64;
use Path::Tiny;
use URI::Escape;
use WWW::Mechanize;

# I wish I could apply this to my diet.
use strict;
use warnings;

# object constructor; will automatically authorize this session
sub new {
	my $class = shift;

	# required args are the account ID and application_key
	my ($application_key_id, $application_key) = @_;

	# cannot operate without these
	if (!$application_key_id || !$application_key) {
		die "ERROR: Cannot create B2V5Client object without both application_key_id and application_key arguments.\n";
	}

	# initiate class with my keys + WWW::Mechanize object
	my $self = bless {
		'application_key_id' => $application_key_id,
		'application_key' => $application_key,
		'mech' => WWW::Mechanize->new(
			timeout => 60,
			autocheck => 0,
			cookie_jar => {},
			keep_alive => 1,
		),
	}, $class;

	# now start our B2 session via method below
	$self->b2_authorize_account();  # this adds more goodness to $self for use in the other methods

	return $self;
}

# method to start your backblaze session:  authorize the account and get your api URL's
sub b2_authorize_account {
	my $self = shift;

	# prepare our authorization header
	my $encoded_auth_string = encode_base64($self->{application_key_id}.':'.$self->{application_key});

	# add that header in
	$self->{mech}->add_header( 'Authorization' => 'Basic '.$encoded_auth_string );

	# call the b2_talker() method to authenticate our session
	$self->b2_talker('url' => 'https://api.backblazeb2.com/b2api/v2/b2_authorize_account' );

	# if we succeeded, load in our authentication and prepare to proceed
	if ($self->{current_status} eq 'OK') {

		$self->{account_id} = $self->{b2_response}{accountId};
		$self->{api_url} = $self->{b2_response}{apiUrl};
		$self->{account_authorization_token} = $self->{b2_response}{authorizationToken};
		$self->{download_url} = $self->{b2_response}{downloadUrl};
		# for uploading large files
		$self->{recommended_part_size} = $self->{b2_response}{recommendedPartSize} || 104857600;
		# ready!

	# otherwise, not ready!
	} else {
		$self->{b2_login_error} = 1;
	}

	# return current status
	return $self->{current_status};

}

# method to download a file by ID; probably most commonly used
sub b2_download_file_by_id {
	my $self = shift;

	# required arg is the file ID
	# option arg is a target directory to auto-save the new file into
	my ($file_id, $save_to_location) = @_;

	if (!$file_id) {
		$self->error_tracker('The file_id must be provided for b2_download_file_by_id().');
		return $self->{current_status};
	}

	# send the request, as a GET
	$self->b2_talker(
		'url' => $self->{download_url}.'/b2api/v2/b2_download_file_by_id?fileId='.$file_id,
		'authorization' => $self->{account_authorization_token},
	);

	# if the file was found, you will have the relevant headers in %{ $self->{b2_response} }
	# as well as the file's contents in $self->{b2_response}{file_contents}

	# if they provided a save-to location (a directory) and the file was found, let's save it out
	if ($self->{current_status} eq 'OK' && $save_to_location) {
		$self->save_downloaded_file($save_to_location);
	}

	# return current status
	return $self->{current_status};

}

# method to download a file via the bucket name + file name
sub b2_download_file_by_name {
	my $self = shift;

	# required args are the bucket name and file name
	my ($bucket_name, $file_name, $save_to_location) = @_;

	if (!$bucket_name || !$file_name) {
		$self->error_tracker('The bucket_name and file_name must be provided for b2_download_file_by_name().');
		return $self->{current_status};
	}

	# send the request, as a GET
	$self->b2_talker(
		'url' => $self->{download_url}.'/file/'.uri_escape($bucket_name).'/'.uri_escape($file_name),
		'authorization' => $self->{account_authorization_token},
	);


	# if the file was found, you will have the relevant headers in %{ $self->{b2_response} }
	# as well as the file's contents in $self->{b2_response}{file_contents}

	# if they provided a save-to location (a directory) and the file was found, let's save it out
	if ($self->{current_status} eq 'OK' && $save_to_location) {
		$self->save_downloaded_file($save_to_location);
	}

	# return current status
	return $self->{current_status};

}

# method to save downloaded files into a target location
# only call after successfully calling b2_download_file_by_id() or b2_download_file_by_name()
sub save_downloaded_file {
	my $self = shift;

	# required arg is a valid directory on this file system
	my ($save_to_location) = @_;

	# error out if that location don't exist
	if (!$save_to_location || !(-d "$save_to_location") ) {
		$self->error_tracker("Can not auto-save file without a valid location. $save_to_location");
		return $self->{current_status};
	}

	# make sure they actually downloaded a file
	if ( !$self->{b2_response}{'X-Bz-File-Name'} || !length($self->{b2_response}{file_contents}) ) {
		$self->error_tracker("Can not auto-save without first downloading a file.");
		return $self->{current_status};
	}

	# still here?  do the save

	# add the filename
	$save_to_location .= '/'.$self->{b2_response}{'X-Bz-File-Name'};

	# i really love Path::Tiny
	path($save_to_location)->spew_raw( $self->{b2_response}{file_contents} );

	# return current status
	return $self->{current_status};

}

# method to upload a file into Backblaze B2
sub b2_upload_file {
	my $self = shift;

	my (%args) = @_;
	# this must include valid entries for 'new_file_name' and 'bucket_name'
	# and it has to include either the raw file contents in 'file_contents'
	# or a valid location in 'file_location'
	# also, you can include 'content_type' (which would be the MIME Type'
	# if you do not want B2 to auto-determine the MIME/content-type

	# did they provide a file location or path?
	if ($args{file_location} && -e "$args{file_location}") {
		$args{file_contents} = path( $args{file_location} )->slurp_raw;

		# if they didn't provide a file-name, use the one on this file
		$args{new_file_name} = path( $args{file_location} )->basename;
	}

	# were these file contents either provided or found?
	if (!length($args{file_contents})) {
		$self->error_tracker(qq{You must provide either a valid 'file_location' or 'file_contents' arg for b2_upload_file().});
		return 'Error';
	}

	# check the other needed args
	if (!$args{bucket_name} || !$args{new_file_name}) {
		$self->error_tracker(qq{You must provide 'bucket_name' and 'new_file_name' args for b2_upload_file().});
		return 'Error';
	}

	# default content-type
	$args{content_type} ||= 'b2/x-auto';

	# OK, let's continue:  get the upload URL and authorization token for this bucket
	$self->b2_get_upload_url( $args{bucket_name} );

	# send the special request
	$self->b2_talker(
		'url' => $self->{bucket_info}{ $args{bucket_name} }{upload_url},
		'authorization' => $self->{bucket_info}{ $args{bucket_name} }{authorization_token},
		'file_contents' => $args{file_contents},
		'special_headers' => {
			'X-Bz-File-Name' => uri_escape( $args{new_file_name} ),
			'X-Bz-Content-Sha1' => sha1_hex( $args{file_contents} ),
			'Content-Type' => $args{content_type},
		},
	);
	# b2_talker will handle the rest

	# return current status
	return $self->{current_status};

}

# method to get the information needed to upload into a specific B2 bucket
sub b2_get_upload_url {
	my $self = shift;

	# the bucket name is required
	my ($bucket_name) = @_;

	# bucket_name is required
	if (!$bucket_name) {
		$self->error_tracker('The bucket_name must be provided for b2_get_upload_url().');
		return $self->{current_status};
	}

	# no need to proceed if we already have done for this bucket this during this session
	# return if $self->{bucket_info}{$bucket_name}{upload_url};
	# COMMENTED OUT:  It seems like B2 wants a new upload_url endpoint for each upload,
	# and we may want to upload multiple files into each bucket...so this won't work

	# if we don't have the info for the bucket name, retrieve the bucket's ID
	if (ref($self->{buckets}{$bucket_name}) ne 'HASH') {
		$self->b2_list_buckets($bucket_name);
	}

	# send the request
	$self->b2_talker(
		'url' => $self->{api_url}.'/b2api/v2/b2_get_upload_url',
		'authorization' => $self->{account_authorization_token},
		'post_params' => {
			'bucketId' => $self->{buckets}{$bucket_name}{bucket_id},
		},
	);

	# if we succeeded, get the info for this bucket
	if ($self->{current_status} eq 'OK') {

		$self->{bucket_info}{$bucket_name} = {
			'upload_url' => $self->{b2_response}{uploadUrl},
			'authorization_token' => $self->{b2_response}{authorizationToken},
		};

	}

	# send the status for consistency
	return $self->{current_status};

}

# method to get information on one bucket or all buckets
# specify the bucket-name to search by name
sub b2_list_buckets {
	my $self = shift;

	# optional first arg is a target bucket name
	# optional second arg tells us to auto-create a bucket, if the name is provided but it was not found
	my ($bucket_name, $auto_create_bucket) = @_;

	# send the request
	$self->b2_talker(
		'url' => $self->{api_url}.'/b2api/v2/b2_list_buckets',
		'authorization' => $self->{account_authorization_token},
		'post_params' => {
			'accountId' => $self->{account_id},
			'bucketName' => $bucket_name,
		},
	);

	# if we succeeded, load in all the found buckets to $self->{buckets}
	# that will be a hash of info, keyed by name

	if ($self->{current_status} eq 'OK') {
		foreach my $bucket_info (@{ $self->{b2_response}{buckets} }) {
			$bucket_name = $$bucket_info{bucketName};

			$self->{buckets}{$bucket_name} = {
				'bucket_id' => $$bucket_info{bucketId},
				'bucket_type' => $$bucket_info{bucketType},
			};
		}
	} else {
		return $self->{current_status};
	}

	# if that bucket was not found, maybe they want to go ahead and create it?
	if ($bucket_name && !$self->{buckets}{$bucket_name} && $auto_create_bucket) {
		$self->b2_bucket_maker($bucket_name);
		# this will call back to me and get the info
	}

	return $self->{current_status};

}

# method to retrieve file names / info from a bucket
# this client library is bucket-name-centric, so it looks for the bucket name as a arg
# if there are more than 1000 files, then call this repeatedly
our $B2_MAX_FILE_COUNT = 1000;
sub b2_list_file_names {
	my ($self, $bucket_name, %args) = @_;

	# bucket_name is required
	if (!$bucket_name) {
		$self->error_tracker('The bucket_name must be provided for b2_list_file_names().');
		return $self->{current_status};
	}

	# we need the bucket ID
	# if we don't have the info for the bucket name, retrieve the bucket's ID
	if (ref($self->{buckets}{$bucket_name}) ne 'HASH') {
		$self->b2_list_buckets($bucket_name);
	}

	# retrieve the files
	$self->b2_talker(
		'url' => $self->{api_url}.'/b2api/v2/b2_list_file_names',
		'authorization' => $self->{account_authorization_token},
		'post_params' => {
			'bucketId'      => $self->{buckets}{$bucket_name}{bucket_id},
			'prefix'        => $args{prefix} // undef,
			'delimiter'     => $args{delimiter} // undef,
			'startFileName' => $args{startFileName} // $self->{buckets}{$bucket_name}{next_file_name},
			'maxFileCount'  => $args{maxFileCount} // $B2_MAX_FILE_COUNT,
		},
	);

	# if we succeeded, read in the files
	if ($self->{current_status} eq 'OK') {
		$self->{buckets}{$bucket_name}{next_file_name} = $self->{b2_response}{nextFileName};

		# i am not going to waste the CPU cycles de-camelizing these sub-keys
		# add to our possibly-started array of file info for this bucket
		push(
			@{ $self->{buckets}{$bucket_name}{files} },
			@{ $self->{b2_response}{files} }
		);

		# kindly return the request results as a refernce (arrayref)
		return $self->{b2_response}{files};

	# otherwise, return an error
	} else {
		return $self->{current_status};
	}


}

# method to get info for a specific file
# I assume you have the File ID for the file
sub b2_get_file_info {
	my $self = shift;

	# required arg is the file ID
	my ($file_id) = @_;

	if (!$file_id) {
		$self->error_tracker('The file_id must be provided for b2_get_file_info().');
		return $self->{current_status};
	}

	# kick out if we already have it
	return 'Error' if ref($self->{file_info}{$file_id}) eq 'HASH';

	# retrieve the file information
	$self->b2_talker(
		'url' => $self->{api_url}.'/b2api/v2/b2_get_file_info',
		'authorization' => $self->{account_authorization_token},
		'post_params' => {
			'fileId' => $file_id,
		},
	);

	# if we succeeded, read in the information
	if ($self->{current_status} eq 'OK') {
		# i am not going to waste the CPU cycles de-camelizing these sub-keys
		$self->{file_info}{$file_id} = $self->{b2_response};
	}

	return $self->{current_status};

}

# combo method to create a bucket
sub b2_bucket_maker {
	my $self = shift;

	my ($bucket_name, $disable_encryption) = @_;

	# can't proceed without the bucket_name
	if (!$bucket_name) {
		$self->error_tracker('The bucket_name must be provided for b2_bucket_maker().');
		return $self->{current_status};
	}

	# prepare the basics for our request
	my $post_params = {
		'accountId' => $self->{account_id},
		'bucketName' => $bucket_name,
		'bucketType' => 'allPrivate',
	};

	# unless instructed otherwise, we should encrypt the files in this bucket
	unless ($disable_encryption) {
		$$post_params{defaultServerSideEncryption} = {
			'mode' => 'SSE-B2',
			'algorithm' => 'AES256',
		};
	}

	# create the bucket...
	$self->b2_talker(
		'url' => $self->{api_url}.'/b2api/v2/b2_create_bucket',
		'authorization' => $self->{account_authorization_token},
		'post_params' => $post_params,
	);

	if ($self->{current_status} eq 'OK') { # if successful...

		# stash our new bucket into $self->{buckets}
		$self->{buckets}{$bucket_name} = {
			'bucket_id' => $self->{b2_response}{bucketId},
			'bucket_type' => 'allPrivate',
		};

	}

	return $self->{current_status};

}

# method to delete a bucket -- please don't use ;)
sub b2_delete_bucket {
	my $self = shift;

	my ($bucket_name) = @_;

	# bucket_id is required
	if (!$bucket_name) {
		$self->error_tracker('The bucket_name must be provided for b2_delete_bucket().');
		return $self->{current_status};
	}

	# resolve that bucket_name to a bucket_id
	$self->b2_list_buckets($bucket_name);

	# send the request
	$self->b2_talker(
		'url' => $self->{api_url}.'/b2api/v2/b2_delete_bucket',
		'authorization' => $self->{account_authorization_token},
		'post_params' => {
			'accountId' => $self->{account_id},
			'bucketId' => $self->{buckets}{$bucket_name}{bucket_id},
		},
	);

	return $self->{current_status};
}

# method to delete a stored file object.  B2 thinks of these as 'versions,'
# but if you use unique names, one version = one file
sub b2_delete_file_version {
	my $self = shift;

	# required arguments are the file_name and file_id for the target file
	my ($file_name, $file_id) = @_;

	# bucket_id is required
	if (!$file_name || !$file_id) {
		$self->error_tracker('The file_name and file_id args must be provided for b2_delete_file_version().');
		return $self->{current_status};
	}

	# send the request
	$self->b2_talker(
		'url' => $self->{api_url}.'/b2api/v2/b2_delete_file_version',
		'authorization' => $self->{account_authorization_token},
		'post_params' => {
			'fileName' => $file_name,
			'fileId' => $file_id,
		},
	);

	return $self->{current_status};

}

# method to upload a large file (>100MB)
sub b2_upload_large_file {
	my $self = shift;
	my (%args) = @_;
	# this must include valid entries for 'new_file_name' and 'bucket_name'
	# and it has to a valid location in 'file_location' (Do not load in file contents)
	# also, you can include 'content_type' (which would be the MIME Type'
	# if you do not want B2 to auto-determine the MIME/content-type

	# did they provide a file location or path?
	if ($args{file_location} && -e "$args{file_location}") {
		# if they didn't provide a file-name, use the one on this file
		$args{new_file_name} = path( $args{file_location} )->basename;
	} else {
		$self->error_tracker(qq{You must provide a valid 'file_location' arg for b2_upload_large_file().});
		return $self->{current_status};
	}

	# protect my sanity...
	my ($bucket_name, $file_contents_part, $file_location, $large_file_id, $part_number, $remaining_file_size, $sha1_array, $size_sent, $stat);
	$file_location = $args{file_location};
	$bucket_name = $args{bucket_name};

	# must be 100MB or bigger
	$stat = path($file_location)->stat;
	if ($stat->size < $self->{recommended_part_size} ) {
		$self->error_tracker(qq{Please use b2_upload_large_file() for files larger than $self->{recommended_part_size} .});
		return $self->{current_status};
	}

	# need a bucket name
	if (!$bucket_name) {
		$self->error_tracker(qq{You must provide a valid 'bucket_name' arg for b2_upload_large_file().});
		return $self->{current_status};
	}

	# default content-type
	$args{content_type} ||= 'b2/x-auto';

	# get the bucket ID
	$self->b2_list_buckets($bucket_name);

	# kick off the upload in the API
	$self->b2_talker(
		'url' => $self->{api_url}.'/b2api/v2/b2_start_large_file',
		'authorization' => $self->{account_authorization_token},
		'post_params' => {
			'bucketId' => $self->{buckets}{$bucket_name}{bucket_id},
			'fileName' => $args{new_file_name},
			'contentType' => $args{content_type},
		},
	);

	# these are all needed for each b2_upload_part web call
	$large_file_id = $self->{b2_response}{fileId};
	return 'Error' if !$large_file_id; # there was an error in the request

	# open the large file
	open(FH, $file_location);

	$remaining_file_size = $stat->size;

	$part_number = 1;

	# cycle thru each chunk of the file
	while ($remaining_file_size >= 0) {
		# how much to send?
		if ($remaining_file_size < $self->{recommended_part_size} ) {
			$size_sent = $remaining_file_size;
		} else {
			$size_sent = $self->{recommended_part_size} ;
		}

		# get the next upload url for this part
		$self->b2_talker(
			'url' => $self->{api_url}.'/b2api/v2/b2_get_upload_part_url',
			'authorization' => $self->{account_authorization_token},
			'post_params' => {
				'fileId' => $large_file_id,
			},
		);

		# read in that section of the file and prep the SHA
		sysread FH, $file_contents_part, $size_sent;
		push(@$sha1_array,sha1_hex( $file_contents_part ));

		# upload that part
		$self->b2_talker(
			'url' => $self->{b2_response}{uploadUrl},
			'authorization' => $self->{b2_response}{authorizationToken},
			'special_headers' => {
				'X-Bz-Content-Sha1' => $$sha1_array[-1],
				'X-Bz-Part-Number' => $part_number,
				'Content-Length' => $size_sent,
			},
			'file_contents' => $file_contents_part,
		);

		# advance
		$part_number++;
		$remaining_file_size -= $self->{recommended_part_size} ;
	}

	# close the file
	close FH;

	# and tell B2
	$self->b2_talker(
		'url' => $self->{api_url}.'/b2api/v2/b2_finish_large_file',
		'authorization' => $self->{account_authorization_token},
		'post_params' => {
			'fileId' => $large_file_id,
			'partSha1Array' => $sha1_array,
		},
	);

	# phew, i'm tired...
	return $self->{current_status};
}


# generic method to handle communication to B2
sub b2_talker {
	my $self = shift;

	# args hash must include 'url' for the target API endpoint URL
	# most other requests will also include a 'post_params' hashref, and 'authorization' value for the header
	# for the b2_upload_file function, there will be several other headers + a file_contents arg
	my (%args) = @_;

	if (!$args{url}) {
		$self->error_tracker('Can not use b2_talker() without an endpoint URL.');
	}

	# if they sent an Authorization header, set that value
	if ($args{authorization}) {
		$self->{mech}->delete_header( 'Authorization' );
		$self->{mech}->add_header( 'Authorization' => $args{authorization} );
	}

	my ($response, $response_code, $error_message, $header, @header_keys);

	# short-circuit if we had difficulty logging in previously
	if ($self->{b2_login_error}) {

		# track the error / set current state
		$self->error_tracker("Problem logging into Backblaze.  Please check the 'errors' array in this object.", $args{url});

		return $self->{current_status};
	}

	# are we uploading a file?
	if ($args{url} =~ /b2_upload_file|b2_upload_part/) {

		# add the special headers
		@header_keys = keys %{ $args{special_headers} };
		foreach $header (@header_keys) {
			$self->{mech}->delete_header( $header );
			$self->{mech}->add_header( $header => $args{special_headers}{$header} );
		}

		# now upload the file
		eval {
			$response = $self->{mech}->post( $args{url}, content => $args{file_contents} );

			# we want this to be 200
			$response_code = $response->{_rc};

			$self->{b2_response} = decode_json( $self->{mech}->content() );

		};

		# remove those special headers, cleaned-up for next time
		foreach $header (@header_keys) {
			$self->{mech}->delete_header( $header );
		}

	# if not uploading and they sent POST params, we are doing a POST
	} elsif (ref($args{post_params}) eq 'HASH') {
		eval {
			# send the POST
			$response = $self->{mech}->post( $args{url}, content => encode_json($args{post_params}) );

			# we want this to be 200
			$response_code = $response->code;

			# decode results
			$self->{b2_response} = decode_json( $self->{mech}->content() );
		};

	# otherwise, we are doing a GET
	} else {

		# attempt the GET
		eval {
			$response = $self->{mech}->get( $args{url} );

			# we want this to be 200
			$response_code = $response->code;

			# did we download a file?
			if ($response->header( 'X-Bz-File-Name' )) {

				# grab those needed headers
				foreach $header ('Content-Length','Content-Type','X-Bz-File-Id','X-Bz-File-Name','X-Bz-Content-Sha1') {
					$self->{b2_response}{$header} = $response->header( $header );
				}

				# and the file itself
				$self->{b2_response}{file_contents} = $self->{mech}->content();

			} elsif ($response_code eq '200') { # no, regular JSON, decode results
				$self->{b2_response} = decode_json( $self->{mech}->content() );
			}
		};
	}

	# there is a problem if there is a problem
	if ($@ || $response_code ne '200') {
		if ($self->{b2_response}{message}) {
			$error_message = 'API Message: '.$self->{b2_response}{message};
		} else {
			$error_message = 'Error: '.$@;
		}

		# track the error / set current state
		$self->error_tracker($error_message, $args{url}, $response_code);

	# otherwise, we are in pretty good shape
	} else {

		$self->{current_status} = 'OK';
	}

	return $self->{current_status};

}

# for tracking errors into $self->{errrors}[];
sub error_tracker {
	my $self = shift;

	my ($error_message, $url, $response_code) = @_;
	# required is the error message; optional is the URL we were trying to call,
	# and the HTTP status code returned in that API call

	return 'Error - No Message' if !$error_message;

	# defaults
	$url ||= 'N/A';
	$response_code ||= 'N/A';

	# we must currently be in an error state
	$self->{current_status} = 'Error';

	# track the error
	push(@{ $self->{errors} }, {
		'error_message' => $error_message,
		'url' => $url,
		'response_code' => $response_code,
	});

	return 'Error';

}

# please tell me the lastest error message
sub latest_error {
	my $self = shift;

	# don't fall for the old "Modification of non-creatable array value attempted" trick
	return 'No error message found' if !$self->{errors}[0];

	my $error = $self->{errors}[-1];
	return $$error{error_message}.' ('.$$error{response_code}.')';

}

1;

__END__