# -*- 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;
    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.