File Coverage

blib/lib/WWW/Newzbin.pm

Criterion	Covered	Total	%
statement	35	194	18.0
branch	6	130	4.6
condition	0	55	0.0
subroutine	8	18	44.4
pod	7	7	100.0
total	56	404	13.8

package WWW::Newzbin;

use 5.005;
use strict;
use warnings;

use Carp qw(carp croak);
use WWW::Newzbin::Constants qw(:all);

use LWP::UserAgent;

our $VERSION = '0.07';

# lwp::useragent object for communicating with newzbin
my $ua = LWP::UserAgent->new(
	agent => "WWW::Newzbin/$VERSION"
);

#=============================================================================#

# internal carp() - gives us a chance to stop them if user has requested no warnings
sub _carp {
	my $self = shift;
	my $err = shift;

	carp("WARNING: WWW::Newzbin " . $err) unless $self->{param}->{nowarnings};
}

sub _croak {
	my $self = shift;
	my $err = shift;

	croak("ERROR: WWW::Newzbin " . $err);
}

sub new {
	my $class = shift;
	my $self = {};

	bless($self, $class);

	if (my $err = $self->_init(@_)) {
		$self->_croak("new(): Cannot initialise object: $err");
		return undef;
	} else {
		return $self;
	}
}

sub _init {
	my $self = shift;

	(%{$self->{param}}) = @_;

	# dismiss unrecognised constructor parameters
	foreach my $param (keys %{$self->{param}}) {
		if ($param !~ /^(username|password|nowarnings|proxy)$/) {
			$self->_carp("new(): Unknown constructor parameter '$param'");
			delete $self->{param}->{"$param"};
		}
	}

	# check for existence of required parameters
	foreach my $required (qw(username password)) {
		if (!$self->{param}->{"$required"}) {
			return "missing required parameter '$required'";
		}
	}

	# if a proxy has been specified, pass it to lwp::useragent
	if (exists $self->{param}->{proxy}) {
		eval { $ua->proxy("http", $self->{param}->{proxy}); };
		if ($@) {
			$self->_carp("new(): Cannot use proxy '$self->{param}->{proxy}'");
			delete $self->{param}->{proxy};
		}
	}
}

sub _set_error {
	my $self = shift;
	$self->{error}->{code} = shift;
	$self->{error}->{message} = shift;
}

sub error_code {
	my $self = shift;
	return $self->{error}->{code} || undef;
}

sub error_message {
	my $self = shift;
	return $self->{error}->{message} || undef;
}

sub lwp_useragent {
	my $self = shift;
	return $ua;
}

#-----------------------------------------------------------------------------#

# interface to v3's filefind api
sub search_files {
	my $self = shift;
	$self->_set_error(undef, undef);
	$self->_set_search_files_total(undef);

	my (%criteria) = @_;

	# check for unrecognised parameters
	foreach my $key (keys %criteria) {
		if ($key !~ /^(query|category|group|retention|minsize|maxsize|filetype|resultoffset|resultlimit|sortfield|sortorder)$/) {
			$self->_carp("search_files(): Unknown parameter '$key'");
			delete $criteria{"$key"};
		}
	}

	# check for required parameters
	foreach my $req (qw(query)) {
		if (!$criteria{"$req"}) {
			$self->_croak("search_files(): Missing required parameter '$req'");
		}
	}

	# build post request for filefind
	my %post = (
		username => $self->{param}->{username},
		password => $self->{param}->{password},
		query => $criteria{query},
		filetype => $criteria{filetype},
	);

	# validation for "category"
	if (exists $criteria{category}) {
		if (ref($criteria{category}) =~ /^ARRAY/) {
			$post{category} = join(",", @{$criteria{category}});
		} elsif (!ref($criteria{category})) {
			$post{category} = $criteria{category};
		} else {
			$self->_carp("search_files(): 'category' parameter must be a string or arrayref of strings; parameter not included in search");
		}
	}

	# validation for "group"
	if (exists $criteria{group}) {
		if (ref($criteria{group}) =~ /^ARRAY/) {
			$post{group} = join(",", @{$criteria{group}});
		} elsif (!ref($criteria{group})) {
			$post{group} = $criteria{group};
		} else {
			$self->_carp("search_files(): 'group' parameter must be a string or arrayref of strings; parameter not included in search");
		}
	}

	# validation for "retention"
	if (exists $criteria{retention}) {
		if (($criteria{retention} =~ /^\d+$/) && ($criteria{retention} > 0)) {
			$post{retention} = $criteria{retention};
		} else {
			$self->_carp("search_files(): 'retention' parameter must be a positive integer; parameter not included in search");
		}
	}

	# validation for "minsize"
	if (exists $criteria{minsize}) {
		if (($criteria{minsize} =~ /\D/) || ($criteria{minsize} < 0)) {
			$self->_carp("search_files(): 'minsize' parameter must be a positive integer; parameter not included in search");
			delete $criteria{minsize};
		} elsif ((exists $criteria{maxsize}) && ($criteria{minsize} > $criteria{maxsize})) {
			$self->_carp("search_files(): 'minsize' parameter must be less than 'maxsize' parameter; both parameters not included in search");
			delete $criteria{minsize};
			delete $criteria{maxsize};
		} else {
			$post{bytesmin} = $criteria{minsize};
		}
	}

	# validation for "maxsize"
	if (exists $criteria{maxsize}) {
		if (($criteria{maxsize} =~ /\D/) || ($criteria{maxsize} < 0)) {
			$self->_carp("search_files(): 'maxsize' parameter must be a positive integer; parameter not included in search");
			delete $criteria{maxsize};
		} elsif ((exists $criteria{minsize}) && ($criteria{minsize} > $criteria{maxsize})) {
			$self->_carp("search_files(): 'minsize' parameter must be less than 'maxsize' parameter; both parameters not included in search");
			delete $criteria{minsize};
			delete $criteria{maxsize};
		} else {
			$post{bytesmax} = $criteria{maxsize};
		}
	}

	# validation for "resultoffset"
	if (exists $criteria{resultoffset}) {
		if (($criteria{resultoffset} =~ /\D/) || ($criteria{resultoffset} < -1)) {
			$self->_carp("search_files(): 'resultoffset' parameter must be an integer >= 0; offset/limit parameters not included in search");
			delete $criteria{resultlimit};
		} else {
			$post{offset} = $criteria{resultoffset};
		}
	}

	# validation for "resultlimit"
	if (exists $criteria{resultlimit}) {
		if (($criteria{resultlimit} =~ /\D/) || ($criteria{resultlimit} < 0)) {
			$self->_carp("search_files(): 'resultlimit' parameter must be a positive integer; offset/limit parameters not included in search");
			delete $post{offset};
		} else {
			$post{limit} = $criteria{resultlimit};
		}
	}

	# validation for "sortfield"
	if (exists $criteria{sortfield}) {
		if (
			($criteria{sortfield} ne NEWZBIN_SORTFIELD_DATE) &&
			($criteria{sortfield} ne NEWZBIN_SORTFIELD_SUBJECT) &&
			($criteria{sortfield} ne NEWZBIN_SORTFIELD_FILESIZE)
		) {
			$self->_carp("search_files(): 'sortfield' parameter does not have an allowed value; sort parameters not included in search");
			delete $criteria{sortorder};
		} else {
			$post{sortfield} = $criteria{sortfield};
		}
	}

	# validation for "sortorder"
	if (exists $criteria{sortorder}) {
		if (
			($criteria{sortorder} ne NEWZBIN_SORTORDER_ASC) &&
			($criteria{sortorder} ne NEWZBIN_SORTORDER_DESC)
		) {
			$self->_carp("search_files(): 'sortorder' parameter does not have an allowed value; sort parameters not included in search");
			delete $post{sortfield};
		} else {
			$post{sortorder} = $criteria{sortorder};
		}
	}

	# now we're ready to query newzbin
	my $response = $ua->post(
		"http://v3.newzbin.com/api/filefind3/",
		\%post,
		"Content-type" => "application/x-www-form-urlencoded"
	) or $self->_set_error(-1, "Could not send HTTP POST request to Newzbin's FileFind API") and return undef;

	# check for valid response
	if (!$response->is_success) {
		if ($response->code == 500) {
			$self->_set_error(-1, "Newzbin's FileFind API is currently unavailable");
		} elsif ($response->code == 403) {
			$self->_set_error(-2, "Invalid Newzbin login credentials given");
		} elsif ($response->code == 402) {
			$self->_set_error(-3, "This is not a Newzbin Premium account");
		} else {
			$self->_set_error(-1, "Invalid response from Newzbin's FileFind API");
		}

		return undef;
	}

	# were there results for the given query?
	if ($response->code == 204) {
		$self->_set_error(-4, "No search results found");
		return undef;
	}

	# process results
	my @raw_results = split(/\n/, $response->content);

	# first line holds the total number of results that would have been returned if offset/limit were not present
	my $total_results = shift(@raw_results);
	$total_results =~ s/^TOTAL=//i;
	$self->_set_search_files_total($total_results);

	my @results;
	foreach (@raw_results) {
		my @result = split(/\t/, $_);

		push(@results, {
			fileid => $result[0],
			subject => $result[1],
			posttime => $result[2],
			filesize => $result[3],
			author => $result[4],
			groups => [ split(/,/, $result[5]) ],
		});
	}

	return @results;
}

sub _set_search_files_total {
	my $self = shift;
	$self->{searchfiles}->{total} = shift;
}

sub search_files_total {
	my $self = shift;
	return $self->{searchfiles}->{total} || undef;
}

#-----------------------------------------------------------------------------#

# interface to v3's directnzb api
sub get_nzb {
	my $self = shift;
	$self->_set_error(undef, undef);

	my (%request) = @_;

	# check for unrecognised parameters
	foreach my $key (keys %request) {
		if ($key !~ /^(reportid|fileid|nogzip|leavegzipped)$/) {
			$self->_carp("get_nzb(): Unknown parameter '$key'");
			delete $request{"$key"};
		}
	}

	# can only specify either reportid or fileid, not both...
	if ((exists $request{reportid}) && (exists $request{fileid})) {
		$self->_croak("get_nzb(): 'reportid' and 'fileid' cannot both be passed as parameters");
	# ...but still must supply one of them
	} elsif ((!exists $request{reportid}) && (!exists $request{fileid})) {
		$self->_croak("get_nzb(): must supply either 'reportid' or 'fileid' as a parameter");
	}

	if (exists $request{reportid}) {
		if ($request{reportid} =~ /\D/) {
			$self->_croak("get_nzb(): 'reportid' parameter must be an integer");
		}
	} elsif (exists $request{fileid}) {
		# an integer or an arrayref of integers is acceptable here
		if (ref($request{fileid}) =~ /^ARRAY/) {
			foreach my $fid (@{$request{fileid}}) {
				if ($fid =~ /\D/) {
					$self->_croak("get_nzb(): 'fileid' parameter must be an integer or arrayref of integers");
				}
			}
		} else {
			if ($request{fileid} =~ /\D/) {
				$self->_croak("get_nzb(): 'fileid' parameter must be an integer or arrayref of integers");
			}
		}
	}

	# check for compress::zlib
	eval { require Compress::Zlib; };
	my $compress_zlib = ($Compress::Zlib::VERSION ? 1 : 0);

	my $response = $ua->post(
		"http://v3.newzbin.com/api/dnzb/",
		{
			username => $self->{param}->{username},
			password => $self->{param}->{password},
			reportid => (exists $request{reportid} ? $request{reportid} : ""),
			fileid => (exists $request{fileid} ? (ref($request{fileid}) =~ /^ARRAY/ ? join(",", @{$request{fileid}}) : $request{fileid}) : ""),
		},
		# if compress::zlib is installed and gzip compression hasn't been disabled, send a header that will result in a gzipped response
		"Accept-Encoding" => (((!$request{nogzip}) && ($compress_zlib)) ? "gzip" : "")
	);

	# examine http response code, filter out errors
	if (!$response->is_success) {
		if ($response->code == 500) {
			# newzbin server error
			$self->_set_error(-1, "Invalid response from Newzbin's DirectNZB API");
		} elsif ($response->code == 503) {
			# directnzb down for maintenance
			$self->_set_error(-1, "Newzbin's DirectNZB API is currently unavailable");

		# examine newzbin-specific response code, filter out errors
		} elsif ($response->header("X-DNZB-RCode") =~ /^400/) {
			# missing parameters
			$self->_croak("get_nzb(): must supply either 'reportid' or 'fileid' as a parameter; 'reportid' must be an integer, and 'fileid' must be an integer or arrayref of integers");
		} elsif ($response->header("X-DNZB-RCode") =~ /^401/) {
			# invalid credentials
			$self->_set_error(-2, "Invalid Newzbin login credentials given");
		} elsif ($response->header("X-DNZB-RCode") =~ /^402/) {
			# no premium credit
			$self->_set_error(-3, "This is not a Newzbin Premium account");
		} elsif ($response->header("X-DNZB-RCode") =~ /^404/) {
			# data unavailable
			$self->_set_error(-4, "Data requested does not exist or is unavailable");
		} elsif ($response->header("X-DNZB-RCode") =~ /^450/) {
			# too many nzb download requests
			# get number of seconds user has to wait
			my $timeout = $response->header("X-DNZB-RText");
			$timeout =~ s/.*Try Later, wait (\d+) second.*/$1/i;
			$self->_set_error(($timeout =~ /\D/ ? 60 : $timeout), "Too many NZB download requests; try again in $timeout second" . ($timeout == 1 ? "" : "s"));
		} else {
			$self->_set_error(-1, "Newzbin's DirectNZB API is currently unavailable");
		}

		return undef;
	}

	if ($response->header("X-DNZB-RCode") =~ /^200/) {
		# nzb contents are in body of document

		# if response headers indicate that content is compressed with gzip, uncompress it
		my $nzb_file;
		if (($response->header("Content-Encoding") =~ /gzip/) && (!$request{leavegzipped})) {
			my $raw = $response->content;
			$nzb_file = Compress::Zlib::memGunzip($raw) or $self->_carp("get_nzb(): could not decompress NZB file; try passing 'nogzip => 1' as a parameter") and $self->_set_error(-5, "Could not decompress NZB file") and return undef;
		} else {
			$nzb_file = $response->content;
		}

		if ($request{reportid}) {
			# if this is a report download, newzbin also supplies a name and category in the http headers
			return ($nzb_file, $response->header("X-DNZB-Name"), $response->header("X-DNZB-Category"));
		} elsif ($request{fileid}) {
			return $nzb_file;
		}
	} else {
		$self->_set_error(-1, "Invalid response from Newzbin's DirectNZB API");
		return undef;
	}
}

#=============================================================================#

1;

__END__