Bug 357322: Make the login/logout of webservice conform to the bugzilla webservice standard

Patch By Mads Bondo Dydensborg <mbd@dbc.dk> r=mkanat, a=justdave

2 files changed, 148 insertions, 38 deletions

diff --git a/Bugzilla/WebService/User.pm b/Bugzilla/WebService/User.pm
index aa3c7490b..74e8f8e03 100755
--- a/Bugzilla/WebService/User.pm
+++ b/Bugzilla/WebService/User.pm
@@ -14,6 +14,7 @@
 #
 # Contributor(s): Marc Schumann <wurblzap@gmail.com>
 #                 Max Kanat-Alexander <mkanat@bugzilla.org>
+#                 Mads Bondo Dydensborg <mbd@dbc.dk>
 
 package Bugzilla::WebService::User;
 
@@ -34,9 +35,9 @@ use Bugzilla::Token;
 ##############
 
 sub login {
-    my $self = shift;
-    my ($login, $password, $remember) = @_;
-
+    my ($self, $params) = @_;
+    my $remember = $params->{remember};
+    
     # Convert $remember from a boolean 0/1 value to a CGI-compatible one.
     if (defined($remember)) {
         $remember = $remember? 'on': '';
@@ -49,12 +50,12 @@ sub login {
 
     # Make sure the CGI user info class works if necessary.
     my $cgi = Bugzilla->cgi;
-    $cgi->param('Bugzilla_login', $login);
-    $cgi->param('Bugzilla_password', $password);
+    $cgi->param('Bugzilla_login', $params->{login});
+    $cgi->param('Bugzilla_password', $params->{password});
     $cgi->param('Bugzilla_remember', $remember);
 
     Bugzilla->login;
-    return Bugzilla->user->id;
+    return { id => type('int')->value(Bugzilla->user->id) };
 }
 
 sub logout {
@@ -62,6 +63,8 @@ sub logout {
 
     Bugzilla->login(LOGIN_OPTIONAL);
     Bugzilla->logout;
+
+    return undef;
 }
 
 #################
@@ -102,7 +105,7 @@ sub create {
         cryptpassword => $password
     });
 
-    return { user_id => type('int')->value($user->id) };
+    return { id => type('int')->value($user->id) };
 }
 
 1;
@@ -115,27 +118,115 @@ Bugzilla::Webservice::User - The User Account and Login API
 
 =head1 DESCRIPTION
 
-This part of the Bugzilla API allows you to create User Accounts.
+This part of the Bugzilla API allows you to create User Accounts and
+log in/out using an existing account.
 
 =head1 METHODS
 
 See L<Bugzilla::WebService> for a description of what B<STABLE>, B<UNSTABLE>,
 and B<EXPERIMENTAL> mean, and for more information about error codes.
 
+=head2 Logging In and Out
+
+=over
+
+=item C<login> B<EXPERIMENTAL>
+
+=over
+
+=item B<Description>
+
+Logging in, with a username and password, is required for many
+Bugzilla installations, in order to search for bugs, post new bugs,
+etc. This method logs in an user.
+
+=item B<Params>
+
+=over
+
+=item C<login> (string) - The user's login name. 
+
+=item C<password> (string) - The user's password.
+
+=item C<remember> (bool) B<Optional> - if the cookies returned by the
+call to login should expire with the session or not.  In order for
+this option to have effect the Bugzilla server must be configured to
+allow the user to set this option - the Bugzilla parameter
+I<rememberlogin> must be set to "defaulton" or
+"defaultoff". Addionally, the client application must implement
+management of cookies across sessions.
+
+=back
+
+=item B<Returns>
+
+On success, a hash containing one item, C<id>, the numeric id of the
+user that was logged in.  A set of http cookies is also sent with the
+response.  These cookies must be sent along with any future requests
+to the webservice, for the duration of the session.
+
+=item B<Errors>
+
+=over
+
+=item 300 (Invalid Username or Password)
+
+The username does not exist, or the password is wrong.
+
+=item 301 (Account Disabled)
+
+The account has been disabled.  A reason may be specified with the
+error.
+
+=back
+
+=back
+
+=item C<logout> B<EXPERIMENTAL>
+
+=over
+
+=item B<Description>
+
+Log out the user. Does nothing if there is no user logged in.
+
+=item B<Params> (none)
+
+=item B<Returns> (nothing)
+
+=item B<Errors> (none)
+
+=back
+
+=back
+
 =head2 Account Creation
 
 =over
 
 =item C<offer_account_by_email> B<EXPERIMENTAL>
 
-Description: Sends an email to the user, offering to create an account.
-             The user will have to click on a URL in the email, and
-             choose their password and real name.
-             This is the recommended way to create a Bugzilla account.
+=over
+
+=item B<Description>
 
-Params:     C<email> - The email to send the offer to.
+Sends an email to the user, offering to create an account.  The user
+will have to click on a URL in the email, and choose their password
+and real name.
 
-Returns:    nothing
+This is the recommended way to create a Bugzilla account.
+
+=item B<Param>
+
+=over
+
+=item C<email> (string) - the email to send the offer to.
+
+=back
+
+=item B<Returns> (nothing)
+
+=item B<Errors>
 
 =over
 
@@ -150,30 +241,46 @@ An account with that email address already exists in Bugzilla.
 
 =back
 
+=back
+
 =item C<create> B<EXPERIMENTAL>
 
-Description: Creates a user account directly in Bugzilla, password and all.
-             Instead of this, you should use L</offer_account_by_email>
-             when possible, because that makes sure that the email address
-             specified can actually receive an email. This function
-             does not check that.
-
-Params:      C<email> B<Required> - The email address for the new user.
-             C<full_name> - A string, the user's full name. Will be
-                 set to empty if not specified.
-             C<password> - The password for the new user account, in
-                 plain text. It will be stripped of leading and trailing
-                 whitespace. If blank or not specified, the newly
-                 created account will exist in Bugzilla, but will not
-                 be allowed to log in using DB authentication until a
-                 password is set either by the user (through resetting
-                 their password) or by the administrator.
-
-Returns:    A hash containing one item, C<user_id>, the numeric id of
-            the user that was created.
-
-Errors:     The same as L</offer_account_by_email>. If a password
-            is specified, the function may also throw:
+=over
+
+=item B<Description>
+
+Creates a user account directly in Bugzilla, password and all.
+Instead of this, you should use L</offer_account_by_email> when
+possible, because that makes sure that the email address specified can
+actually receive an email. This function does not check that.
+
+=item B<Params>
+
+=over
+
+=item C<email> (string) - The email address for the new user.
+
+=item C<full_name> (string) B<Optional> - The user's full name. Will
+be set to empty if not specified.
+
+=item C<password> (string) B<Optional> - The password for the new user
+account, in plain text.  It will be stripped of leading and trailing
+whitespace.  If blank or not specified, the newly created account will
+exist in Bugzilla, but will not be allowed to log in using DB
+authentication until a password is set either by the user (through
+resetting their password) or by the administrator.
+
+=back
+
+=item B<Returns>
+
+A hash containing one item, C<id>, the numeric id of the user that was
+created.
+
+=item B<Errors>
+
+The same as L</offer_account_by_email>. If a password is specified,
+the function may also throw:
 
 =over
 
@@ -190,3 +297,5 @@ password is over ten characters.)
 =back
 
 =back
+
+=back
diff --git a/contrib/bz_webservice_demo.pl b/contrib/bz_webservice_demo.pl
index 7b59a7efb..aba7544f0 100755
--- a/contrib/bz_webservice_demo.pl
+++ b/contrib/bz_webservice_demo.pl
@@ -184,8 +184,9 @@ if (defined($Bugzilla_login)) {
     if ($Bugzilla_login ne '') {
         # Log in.
         $soapresult = $proxy->call('User.login',
-                                   $Bugzilla_login, $Bugzilla_password,
-                                   $Bugzilla_remember);
+                                   { login => $Bugzilla_login, 
+                                     password => $Bugzilla_password,
+                                     remember => $Bugzilla_remember } );
         _die_on_fault($soapresult);
         print "Login successful.\n";
     }