X-Git-Url: http://code.vuplus.com/gitweb/?a=blobdiff_plain;f=Websites%2Fbugs.webkit.org%2FBugzilla%2FWebService.pm;fp=Websites%2Fbugs.webkit.org%2FBugzilla%2FWebService.pm;h=0e429241d686c58e025b04c012ec960e012a4518;hb=186b2535c234ccc42a8c27998f11be6f718f604f;hp=0000000000000000000000000000000000000000;hpb=1c567be6144228b511852e3cab689fc41b052875;p=vuplus_webkit diff --git a/Websites/bugs.webkit.org/Bugzilla/WebService.pm b/Websites/bugs.webkit.org/Bugzilla/WebService.pm new file mode 100644 index 0000000..0e42924 --- /dev/null +++ b/Websites/bugs.webkit.org/Bugzilla/WebService.pm @@ -0,0 +1,287 @@ +# -*- 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 +# Max Kanat-Alexander + +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 + +The endpoint for Bugzilla WebServices is the C script in +your Bugzilla installation. For example, if your Bugzilla is at +C, then your XML-RPC client would access the +API via: C + +=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 for +L. So, for example, +L, is called as C in XML-RPC. + +=head1 PARAMETERS + +In addition to the standard parameter types like C, C, etc., +XML-RPC has two data structures, a C<< >> and an C<< >>. + +=head2 Structs + +In Perl, we call a C<< >> 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: + + + + fruit + oranges + + + vegetable + lettuce + + + +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: + + + + 1 + 2 + 3 + + + +In our example code in these API docs, that would look like: + + [1, 2, 3] + +=head2 How Bugzilla WebService Methods Take Parameters + +B Bugzilla WebServices functions take their parameters in +a C<< >>. Another way of saying this would be: All functions +take a single argument, a C<< >> that contains all parameters. +The names of the parameters listed in the API docs for each function are +the C element for the struct Cs. + +=head1 LOGGING IN + +You can use L 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 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. 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 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 if +we I 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, +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.