288 lines
9.2 KiB
Perl
288 lines
9.2 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;
|
|
|
|
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};
|
|
}
|
|
|
|
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;
|
|
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 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.
|