f3f1795e6f
Patch By Max Kanat-Alexander <mkanat@bugzilla.org> r=dkl, a=mkanat git-svn-id: svn://10.0.0.236/trunk@255780 18797224-902f-48f8-a5cc-f745e15eee43
445 lines
14 KiB
Perl
445 lines
14 KiB
Perl
# -*- Mode: perl; indent-tabs-mode: nil -*-
|
|
#
|
|
# The contents of this file are subject to the Mozilla Public
|
|
# License Version 1.1 (the "License"); you may not use this file
|
|
# except in compliance with the License. You may obtain a copy of
|
|
# the License at http://www.mozilla.org/MPL/
|
|
#
|
|
# Software distributed under the License is distributed on an "AS
|
|
# IS" basis, WITHOUT WARRANTY OF ANY KIND, either express or
|
|
# implied. See the License for the specific language governing
|
|
# rights and limitations under the License.
|
|
#
|
|
# The Original Code is the Bugzilla Bug Tracking System.
|
|
#
|
|
# Contributor(s): Marc Schumann <wurblzap@gmail.com>
|
|
# Max Kanat-Alexander <mkanat@bugzilla.org>
|
|
|
|
package Bugzilla::WebService;
|
|
|
|
use strict;
|
|
use Bugzilla::WebService::Constants;
|
|
use Bugzilla::Util;
|
|
use Date::Parse;
|
|
use XMLRPC::Lite;
|
|
|
|
sub fail_unimplemented {
|
|
my $this = shift;
|
|
|
|
die SOAP::Fault
|
|
->faultcode(ERROR_UNIMPLEMENTED)
|
|
->faultstring('Service Unimplemented');
|
|
}
|
|
|
|
sub datetime_format {
|
|
my ($self, $date_string) = @_;
|
|
|
|
my $time = str2time($date_string);
|
|
my ($sec, $min, $hour, $mday, $mon, $year) = localtime $time;
|
|
# This format string was stolen from SOAP::Utils->format_datetime,
|
|
# which doesn't work but which has almost the right format string.
|
|
my $iso_datetime = sprintf('%d%02d%02dT%02d:%02d:%02d',
|
|
$year + 1900, $mon + 1, $mday, $hour, $min, $sec);
|
|
return $iso_datetime;
|
|
}
|
|
|
|
sub handle_login {
|
|
my ($classes, $action, $uri, $method) = @_;
|
|
|
|
my $class = $classes->{$uri};
|
|
eval "require $class";
|
|
|
|
return if $class->login_exempt($method);
|
|
Bugzilla->login();
|
|
|
|
# Even though we check for the need to redirect in
|
|
# Bugzilla->login() we check here again since Bugzilla->login()
|
|
# does not know what the current XMLRPC method is. Therefore
|
|
# ssl_require_redirect in Bugzilla->login() will have returned
|
|
# false if system was configured to redirect for authenticated
|
|
# sessions and the user was not yet logged in.
|
|
# So here we pass in the method name to ssl_require_redirect so
|
|
# it can then check for the extra case where the method equals
|
|
# User.login, which we would then need to redirect if not
|
|
# over a secure connection.
|
|
my $full_method = $uri . "." . $method;
|
|
Bugzilla->cgi->require_https(Bugzilla->params->{'sslbase'})
|
|
if ssl_require_redirect($full_method);
|
|
|
|
return;
|
|
}
|
|
|
|
# For some methods, we shouldn't call Bugzilla->login before we call them
|
|
use constant LOGIN_EXEMPT => { };
|
|
|
|
sub login_exempt {
|
|
my ($class, $method) = @_;
|
|
|
|
return $class->LOGIN_EXEMPT->{$method};
|
|
}
|
|
|
|
sub type {
|
|
my ($self, $type, $value) = @_;
|
|
if ($type eq 'dateTime') {
|
|
$value = $self->datetime_format($value);
|
|
}
|
|
return XMLRPC::Data->type($type)->value($value);
|
|
}
|
|
|
|
1;
|
|
|
|
package Bugzilla::WebService::XMLRPC::Transport::HTTP::CGI;
|
|
use strict;
|
|
eval { require XMLRPC::Transport::HTTP; };
|
|
our @ISA = qw(XMLRPC::Transport::HTTP::CGI);
|
|
|
|
sub initialize {
|
|
my $self = shift;
|
|
my %retval = $self->SUPER::initialize(@_);
|
|
$retval{'serializer'} = Bugzilla::WebService::XMLRPC::Serializer->new;
|
|
$retval{'deserializer'} = Bugzilla::WebService::XMLRPC::Deserializer->new;
|
|
return %retval;
|
|
}
|
|
|
|
sub make_response {
|
|
my $self = shift;
|
|
|
|
$self->SUPER::make_response(@_);
|
|
|
|
# XMLRPC::Transport::HTTP::CGI doesn't know about Bugzilla carrying around
|
|
# its cookies in Bugzilla::CGI, so we need to copy them over.
|
|
foreach (@{Bugzilla->cgi->{'Bugzilla_cookie_list'}}) {
|
|
$self->response->headers->push_header('Set-Cookie', $_);
|
|
}
|
|
}
|
|
|
|
1;
|
|
|
|
# This exists to validate input parameters (which XMLRPC::Lite doesn't do)
|
|
# and also, in some cases, to more-usefully decode them.
|
|
package Bugzilla::WebService::XMLRPC::Deserializer;
|
|
use strict;
|
|
# We can't use "use base" because XMLRPC::Serializer doesn't return
|
|
# a true value.
|
|
eval { require XMLRPC::Lite; };
|
|
our @ISA = qw(XMLRPC::Deserializer);
|
|
|
|
use Bugzilla::Error;
|
|
|
|
# Some method arguments need to be converted in some way, when they are input.
|
|
sub decode_value {
|
|
my $self = shift;
|
|
my ($type) = @{ $_[0] };
|
|
my $value = $self->SUPER::decode_value(@_);
|
|
|
|
# We only validate/convert certain types here.
|
|
return $value if $type !~ /^(?:int|i4|boolean|double|dateTime\.iso8601)$/;
|
|
|
|
# Though the XML-RPC standard doesn't allow an empty <int>,
|
|
# <double>,or <dateTime.iso8601>, we do, and we just say
|
|
# "that's undef".
|
|
if (grep($type eq $_, qw(int double dateTime))) {
|
|
return undef if $value eq '';
|
|
}
|
|
|
|
my $validator = $self->_validation_subs->{$type};
|
|
if (!$validator->($value)) {
|
|
ThrowUserError('xmlrpc_invalid_value',
|
|
{ type => $type, value => $value });
|
|
}
|
|
|
|
# We convert dateTimes to a DB-friendly date format.
|
|
if ($type eq 'dateTime.iso8601') {
|
|
# We leave off the $ from the end of this regex to allow for possible
|
|
# extensions to the XML-RPC date standard.
|
|
$value =~ /^(\d{4})(\d{2})(\d{2})T(\d{2}):(\d{2}):(\d{2})/;
|
|
$value = "$1-$2-$3 $4:$5:$6";
|
|
}
|
|
|
|
return $value;
|
|
}
|
|
|
|
sub _validation_subs {
|
|
my $self = shift;
|
|
return $self->{_validation_subs} if $self->{_validation_subs};
|
|
# The only place that XMLRPC::Lite stores any sort of validation
|
|
# regex is in XMLRPC::Serializer. We want to re-use those regexes here.
|
|
my $lookup = Bugzilla::WebService::XMLRPC::Serializer->new->typelookup;
|
|
|
|
# $lookup is a hash whose values are arrayrefs, and whose keys are the
|
|
# names of types. The second item of each arrayref is a subroutine
|
|
# that will do our validation for us.
|
|
my %validators = map { $_ => $lookup->{$_}->[1] } (keys %$lookup);
|
|
# Add a boolean validator
|
|
$validators{'boolean'} = sub {$_[0] =~ /^[01]$/};
|
|
# Some types have multiple names, or have a different name in
|
|
# XMLRPC::Serializer than their standard XML-RPC name.
|
|
$validators{'dateTime.iso8601'} = $validators{'dateTime'};
|
|
$validators{'i4'} = $validators{'int'};
|
|
|
|
$self->{_validation_subs} = \%validators;
|
|
return \%validators;
|
|
}
|
|
|
|
1;
|
|
|
|
# This package exists to fix a UTF-8 bug in SOAP::Lite.
|
|
# See http://rt.cpan.org/Public/Bug/Display.html?id=32952.
|
|
package Bugzilla::WebService::XMLRPC::Serializer;
|
|
use strict;
|
|
# We can't use "use base" because XMLRPC::Serializer doesn't return
|
|
# a true value.
|
|
eval { require XMLRPC::Lite; };
|
|
our @ISA = qw(XMLRPC::Serializer);
|
|
|
|
sub new {
|
|
my $class = shift;
|
|
my $self = $class->SUPER::new(@_);
|
|
# This fixes UTF-8.
|
|
$self->{'_typelookup'}->{'base64'} =
|
|
[10, sub { !utf8::is_utf8($_[0]) && $_[0] =~ /[^\x09\x0a\x0d\x20-\x7f]/},
|
|
'as_base64'];
|
|
# This makes arrays work right even though we're a subclass.
|
|
# (See http://rt.cpan.org//Ticket/Display.html?id=34514)
|
|
$self->{'_encodingStyle'} = '';
|
|
return $self;
|
|
}
|
|
|
|
sub as_string {
|
|
my $self = shift;
|
|
my ($value) = @_;
|
|
# Something weird happens with XML::Parser when we have upper-ASCII
|
|
# characters encoded as UTF-8, and this fixes it.
|
|
utf8::encode($value) if utf8::is_utf8($value)
|
|
&& $value =~ /^[\x00-\xff]+$/;
|
|
return $self->SUPER::as_string($value);
|
|
}
|
|
|
|
1;
|
|
|
|
__END__
|
|
|
|
=head1 NAME
|
|
|
|
Bugzilla::WebService - The Web Service interface to Bugzilla
|
|
|
|
=head1 DESCRIPTION
|
|
|
|
This is the standard API for external programs that want to interact
|
|
with Bugzilla. It provides various methods in various modules.
|
|
|
|
Currently the only method of accessing the API is via XML-RPC. The XML-RPC
|
|
standard is described here: L<http://www.xmlrpc.com/spec>
|
|
|
|
The endpoint for Bugzilla WebServices is the C<xmlrpc.cgi> script in
|
|
your Bugzilla installation. For example, if your Bugzilla is at
|
|
C<bugzilla.yourdomain.com>, then your XML-RPC client would access the
|
|
API via: C<http://bugzilla.yourdomain.com/xmlrpc.cgi>
|
|
|
|
=head1 CALLING METHODS
|
|
|
|
Methods are called in the normal XML-RPC fashion. Bugzilla does not currently
|
|
implement any extensions to the standard method of XML-RPC method calling.
|
|
|
|
Methods are grouped into "packages", like C<Bug> for
|
|
L<Bugzilla::WebService::Bug>. So, for example,
|
|
L<Bugzilla::WebService::Bug/get>, is called as C<Bug.get> in XML-RPC.
|
|
|
|
=head1 PARAMETERS
|
|
|
|
In addition to the standard parameter types like C<int>, C<string>, etc.,
|
|
XML-RPC has two data structures, a C<< <struct> >> and an C<< <array> >>.
|
|
|
|
=head2 Structs
|
|
|
|
In Perl, we call a C<< <struct> >> a "hash" or a "hashref". You may see
|
|
us refer to it that way in the API documentation.
|
|
|
|
In example code, you will see the characters C<{> and C<}> used to represent
|
|
the beginning and end of structs.
|
|
|
|
For example, here's a struct in XML-RPC:
|
|
|
|
<struct>
|
|
<member>
|
|
<name>fruit</name>
|
|
<value><string>oranges</string></value>
|
|
</member>
|
|
<member>
|
|
<name>vegetable</name>
|
|
<value><string>lettuce</string></value>
|
|
</member>
|
|
</struct>
|
|
|
|
In our example code in these API docs, that would look like:
|
|
|
|
{ fruit => 'oranges', vegetable => 'lettuce' }
|
|
|
|
=head2 Arrays
|
|
|
|
In example code, you will see the characters C<[> and C<]> used to
|
|
represent the beginning and end of arrays.
|
|
|
|
For example, here's an array in XML-RPC:
|
|
|
|
<array>
|
|
<data>
|
|
<value><i4>1</i4></value>
|
|
<value><i4>2</i4></value>
|
|
<value><i4>3</i4></value>
|
|
</data>
|
|
</array>
|
|
|
|
In our example code in these API docs, that would look like:
|
|
|
|
[1, 2, 3]
|
|
|
|
=head2 How Bugzilla WebService Methods Take Parameters
|
|
|
|
B<All> Bugzilla WebServices functions take their parameters in
|
|
a C<< <struct> >>. Another way of saying this would be: All functions
|
|
take a single argument, a C<< <struct> >> that contains all parameters.
|
|
The names of the parameters listed in the API docs for each function are
|
|
the C<name> element for the struct C<member>s.
|
|
|
|
=head1 LOGGING IN
|
|
|
|
You can use L<Bugzilla::WebService::User/login> to log in as a Bugzilla
|
|
user. This issues standard HTTP cookies that you must then use in future
|
|
calls, so your XML-RPC client must be capable of receiving and transmitting
|
|
cookies.
|
|
|
|
=head1 STABLE, EXPERIMENTAL, and UNSTABLE
|
|
|
|
Methods are marked B<STABLE> if you can expect their parameters and
|
|
return values not to change between versions of Bugzilla. You are
|
|
best off always using methods marked B<STABLE>. We may add parameters
|
|
and additional items to the return values, but your old code will
|
|
always continue to work with any new changes we make. If we ever break
|
|
a B<STABLE> interface, we'll post a big notice in the Release Notes,
|
|
and it will only happen during a major new release.
|
|
|
|
Methods (or parts of methods) are marked B<EXPERIMENTAL> if
|
|
we I<believe> they will be stable, but there's a slight chance that
|
|
small parts will change in the future.
|
|
|
|
Certain parts of a method's description may be marked as B<UNSTABLE>,
|
|
in which case those parts are not guaranteed to stay the same between
|
|
Bugzilla versions.
|
|
|
|
=head1 ERRORS
|
|
|
|
If a particular webservice call fails, it will throw a standard XML-RPC
|
|
error. There will be a numeric error code, and then the description
|
|
field will contain descriptive text of the error. Each error that Bugzilla
|
|
can throw has a specific code that will not change between versions of
|
|
Bugzilla.
|
|
|
|
The various errors that functions can throw are specified by the
|
|
documentation of those functions.
|
|
|
|
If your code needs to know what error Bugzilla threw, use the numeric
|
|
code. Don't try to parse the description, because that may change
|
|
from version to version of Bugzilla.
|
|
|
|
Note that if you display the error to the user in an HTML program, make
|
|
sure that you properly escape the error, as it will not be HTML-escaped.
|
|
|
|
=head2 Transient vs. Fatal Errors
|
|
|
|
If the error code is a number greater than 0, the error is considered
|
|
"transient," which means that it was an error made by the user, not
|
|
some problem with Bugzilla itself.
|
|
|
|
If the error code is a number less than 0, the error is "fatal," which
|
|
means that it's some error in Bugzilla itself that probably requires
|
|
administrative attention.
|
|
|
|
Negative numbers and positive numbers don't overlap. That is, if there's
|
|
an error 302, there won't be an error -302.
|
|
|
|
=head2 Unknown Errors
|
|
|
|
Sometimes a function will throw an error that doesn't have a specific
|
|
error code. In this case, the code will be C<-32000> if it's a "fatal"
|
|
error, and C<32000> if it's a "transient" error.
|
|
|
|
=head1 COMMON PARAMETERS
|
|
|
|
Many Webservice methods take similar arguments. Instead of re-writing
|
|
the documentation for each method, we document the parameters here, once,
|
|
and then refer back to this documentation from the individual methods
|
|
where these parameters are used.
|
|
|
|
=head2 Limiting What Fields Are Returned
|
|
|
|
Many WebService methods return an array of structs with various
|
|
fields in the structs. (For example, L<Bugzilla::WebService::Bug/get>
|
|
returns a list of C<bugs> that have fields like C<id>, C<summary>,
|
|
C<creation_time>, etc.)
|
|
|
|
These parameters allow you to limit what fields are present in
|
|
the structs, to possibly improve performance or save some bandwidth.
|
|
|
|
=over
|
|
|
|
=item C<include_fields> (array)
|
|
|
|
An array of strings, representing the (case-sensitive) names of fields.
|
|
Only the fields specified in this hash will be returned, the rest will
|
|
not be included.
|
|
|
|
If you specify an empty array, then this function will return empty
|
|
hashes.
|
|
|
|
Invalid field names are ignored.
|
|
|
|
Example:
|
|
|
|
User.get( ids => [1], include_fields => ['id', 'name'] )
|
|
|
|
would return something like:
|
|
|
|
{ users => [{ id => 1, name => 'user@domain.com' }] }
|
|
|
|
=item C<exclude_fields> (array)
|
|
|
|
An array of strings, representing the (case-sensitive) names of fields.
|
|
The fields specified will not be included in the returned hashes.
|
|
|
|
If you specify all the fields, then this function will return empty
|
|
hashes.
|
|
|
|
Invalid field names are ignored.
|
|
|
|
Specifying fields here overrides C<include_fields>, so if you specify a
|
|
field in both, it will be excluded, not included.
|
|
|
|
Example:
|
|
|
|
User.get( ids => [1], exclude_fields => ['name'] )
|
|
|
|
would return something like:
|
|
|
|
{ users => [{ id => 1, real_name => 'John Smith' }] }
|
|
|
|
=back
|
|
|
|
|
|
=head1 EXTENSIONS TO THE XML-RPC STANDARD
|
|
|
|
=head2 Undefined Values
|
|
|
|
Normally, XML-RPC does not allow empty values for C<int>, C<double>, or
|
|
C<dateTime.iso8601> fields. Bugzilla does--it treats empty values as
|
|
C<undef> (called C<NULL> or C<None> in some programming languages).
|
|
|
|
Bugzilla also accepts a type called C<< <nil> >>, which is always considered
|
|
to be C<undef>, no matter what it contains.
|
|
|
|
=begin private
|
|
|
|
nil is implemented by XMLRPC::Lite, in XMLRPC::Deserializer::decode_value.
|
|
|
|
=end private
|