MDL-12886 refactored function return full external function info and improved reporti...
[moodle.git] / webservice / lib.php
CommitLineData
06e7fadc 1<?php
cc93c7da 2
3// This file is part of Moodle - http://moodle.org/
4//
5// Moodle is free software: you can redistribute it and/or modify
6// it under the terms of the GNU General Public License as published by
7// the Free Software Foundation, either version 3 of the License, or
8// (at your option) any later version.
9//
10// Moodle is distributed in the hope that it will be useful,
11// but WITHOUT ANY WARRANTY; without even the implied warranty of
12// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
13// GNU General Public License for more details.
14//
15// You should have received a copy of the GNU General Public License
16// along with Moodle. If not, see <http://www.gnu.org/licenses/>.
17
06e7fadc 18/**
cc93c7da 19 * Web services utility functions and classes
06e7fadc 20 *
06e7fadc 21 * @package webservice
551f4420 22 * @copyright 2009 Moodle Pty Ltd (http://moodle.com)
cc93c7da 23 * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
06e7fadc 24 */
25
cc93c7da 26require_once($CFG->libdir.'/externallib.php');
893d7f0f 27
5593d2dc 28/**
29 * Exception indicating access control problem in web service call
30 */
31class webservice_access_exception extends moodle_exception {
32 /**
33 * Constructor
34 */
35 function __construct($debuginfo) {
36 parent::__construct('accessexception', 'exception', '', null, $debuginfo);
37 }
38}
39
cc93c7da 40function webservice_protocol_is_enabled($protocol) {
41 global $CFG;
893d7f0f 42
cc93c7da 43 if (empty($CFG->enablewebservices)) {
44 return false;
893d7f0f 45 }
46
cc93c7da 47 $active = explode(',', $CFG->webserviceprotocols);
893d7f0f 48
cc93c7da 49 return(in_array($protocol, $active));
50}
893d7f0f 51
cc93c7da 52/**
53 * Mandatory web service server interface
54 * @author Petr Skoda (skodak)
55 */
56interface webservice_server {
57 /**
58 * Process request from client.
59 * @param bool $simple use simple authentication
60 * @return void
61 */
62 public function run($simple);
893d7f0f 63}
64
06e7fadc 65/**
cc93c7da 66 * Special abstraction of our srvices that allows
67 * interaction with stock Zend ws servers.
68 * @author skodak
06e7fadc 69 */
cc93c7da 70abstract class webservice_zend_server implements webservice_server {
88098133 71
72 /** @property string name of the zend server class */
73 protected $zend_class;
74
75 /** @property object Zend server instance */
76 protected $zend_server;
77
78 /** @property string $wsname name of the web server plugin */
79 protected $wsname = null;
80
81 /** @property bool $simple true if simple auth used */
82 protected $simple;
83
84 /** @property string $service_class virtual web service class with all functions user name execute, created on the fly */
85 protected $service_class;
86
87 /** @property object restricted context */
88 protected $restricted_context;
89
90 /**
91 * Contructor
92 */
93 public function __construct($zend_class) {
94 $this->zend_class = $zend_class;
95 }
96
97 /**
98 * Process request from client.
99 * @param bool $simple use simple authentication
100 * @return void
101 */
102 public function run($simple) {
103 $this->simple = $simple;
104
105 // we will probably need a lot of memory in some functions
106 @raise_memory_limit('128M');
107
108 // set some longer timeout, this script is not sending any output,
109 // this means we need to manually extend the timeout operations
110 // that need longer time to finish
111 external_api::set_timeout();
112
113 // set up exception handler first, we want to sent them back in correct format that
114 // the other system understands
115 // we do not need to call the original default handler because this ws handler does everything
116 set_exception_handler(array($this, 'exception_handler'));
117
118 // now create the instance of zend server
119 $this->init_zend_server();
120
121 // this sets up $USER and $SESSION and context restrictions
122 $this->authenticate_user();
123
124 // make a list of all functions user is allowed to excecute
125 $this->init_service_class();
126
d4e764ab 127 // TODO: solve debugging level somehow
128 Zend_XmlRpc_Server_Fault::attachFaultException('moodle_exception');
129
88098133 130 // start the server
131 $this->zend_server->setClass($this->service_class);
132 $response = $this->zend_server->handle();
5593d2dc 133/*
134 $grrr = ob_get_clean();
135 error_log($grrr);
136 error_log($response);
137*/
88098133 138 // session cleanup
139 $this->session_cleanup();
140
141 //TODO: we need to send some headers too I guess
142 echo $response;
143 die;
144 }
145
146 /**
147 * Load virtual class needed for Zend api
148 * @return void
149 */
150 protected function init_service_class() {
151 global $USER, $DB;
152
153 // first ofall get a complete list of services user is allowed to access
154 if ($this->simple) {
155 // now make sure the function is listed in at least one service user is allowed to use
156 // allow access only if:
157 // 1/ entry in the external_services_users table if required
158 // 2/ validuntil not reached
159 // 3/ has capability if specified in service desc
160 // 4/ iprestriction
161
162 $sql = "SELECT s.*, NULL AS iprestriction
163 FROM {external_services} s
164 JOIN {external_services_functions} sf ON (sf.externalserviceid = s.id AND s.restrictedusers = 0)
165 WHERE s.enabled = 1
166
167 UNION
168
169 SELECT s.*, su.iprestriction
170 FROM {external_services} s
171 JOIN {external_services_functions} sf ON (sf.externalserviceid = s.id AND s.restrictedusers = 1)
172 JOIN {external_services_users} su ON (su.externalserviceid = s.id AND su.userid = :userid)
173 WHERE s.enabled = 1 AND su.validuntil IS NULL OR su.validuntil < :now";
174 $params = array('userid'=>$USER->id, 'now'=>time());
175 } else {
176
177 //TODO: token may restrict access to one service only
178 die('not implemented yet');
179 }
180
181 $serviceids = array();
182 $rs = $DB->get_recordset_sql($sql, $params);
183
184 // now make sure user may access at least one service
185 $remoteaddr = getremoteaddr();
186 $allowed = false;
187 foreach ($rs as $service) {
188 if (isset($serviceids[$service->id])) {
189 continue;
190 }
191 if ($service->requiredcapability and !has_capability($service->requiredcapability, $this->restricted_context)) {
192 continue; // cap required, sorry
193 }
194 if ($service->iprestriction and !address_in_subnet($remoteaddr, $service->iprestriction)) {
195 continue; // wrong request source ip, sorry
196 }
197 $serviceids[$service->id] = $service->id;
198 }
199 $rs->close();
200
201 // now get the list of all functions
202 if ($serviceids) {
203 list($serviceids, $params) = $DB->get_in_or_equal($serviceids);
204 $sql = "SELECT f.*
205 FROM {external_functions} f
206 WHERE f.name IN (SELECT sf.functionname
207 FROM {external_services_functions} sf
208 WHERE sf.externalserviceid $serviceids)";
209 $functions = $DB->get_records_sql($sql, $params);
210 } else {
211 $functions = array();
212 }
213
214 // now make the virtual WS class with all the fuctions for this particular user
215 $methods = '';
216 foreach ($functions as $function) {
217 $methods .= $this->get_virtual_method_code($function);
218 }
219
5593d2dc 220 // let's use unique class name, there might be problem in unit tests
88098133 221 $classname = 'webservices_virtual_class_000000';
222 while(class_exists($classname)) {
223 $classname++;
224 }
225
226 $code = '
227/**
228 * Virtual class web services for user id '.$USER->id.' in context '.$this->restricted_context->id.'.
229 */
230class '.$classname.' {
231'.$methods.'
232}
233';
234 // load the virtual class definition into memory
235 eval($code);
88098133 236 $this->service_class = $classname;
237 }
238
239 /**
240 * returns virtual method code
241 * @param object $function
242 * @return string PHP code
243 */
244 protected function get_virtual_method_code($function) {
245 global $CFG;
246
5593d2dc 247 $function = external_function_info($function);
88098133 248
249 $params = array();
250 $params_desc = array();
453a7a85 251 foreach ($function->parameters_desc->keys as $name=>$keydesc) {
88098133 252 $params[] = '$'.$name;
453a7a85 253 $type = 'string';
254 if ($keydesc instanceof external_value) {
255 switch($keydesc->type) {
256 case PARAM_BOOL: // 0 or 1 only for now
257 case PARAM_INT:
258 $type = 'int'; break;
259 case PARAM_FLOAT;
260 $type = 'double'; break;
261 default:
262 $type = 'string';
263 }
264 } else if ($keydesc instanceof external_single_structure) {
265 $type = 'struct';
266 } else if ($keydesc instanceof external_multiple_structure) {
267 $type = 'array';
268 }
269 $params_desc[] = ' * @param '.$type.' $'.$name.' '.$keydesc->desc;
88098133 270 }
271 $params = implode(', ', $params);
272 $params_desc = implode("\n", $params_desc);
273
453a7a85 274 if (is_null($function->returns_desc)) {
275 $return = ' * @return void';
276 } else {
277 $type = 'string';
278 if ($function->returns_desc instanceof external_value) {
279 switch($function->returns_desc->type) {
280 case PARAM_BOOL: // 0 or 1 only for now
281 case PARAM_INT:
282 $type = 'int'; break;
283 case PARAM_FLOAT;
284 $type = 'double'; break;
285 default:
286 $type = 'string';
287 }
288 } else if ($function->returns_desc instanceof external_single_structure) {
289 $type = 'struct';
290 } else if ($function->returns_desc instanceof external_multiple_structure) {
291 $type = 'array';
292 }
293 $return = ' * @return '.$type.' '.$function->returns_desc->desc;
294 }
d4e764ab 295
88098133 296 // now crate a virtual method that calls the ext implemenation
297 // TODO: add PHP docs and all missing info here
298
299 $code = '
300 /**
5593d2dc 301 * '.$function->description.'
302 *
88098133 303'.$params_desc.'
453a7a85 304'.$return.'
88098133 305 */
306 public function '.$function->name.'('.$params.') {
307 return '.$function->classname.'::'.$function->methodname.'('.$params.');
308 }
309';
310 return $code;
311 }
312
313 /**
314 * Set up zend serice class
315 * @return void
316 */
317 protected function init_zend_server() {
318 include "Zend/Loader.php";
319 Zend_Loader::registerAutoload();
320 //TODO: set up some server options and debugging too - maybe a new method
321 //TODO: add some zend exeption handler too
322 $this->zend_server = new $this->zend_class();
323 }
324
325 /**
326 * Send the error information to the WS client.
327 * @param exception $ex
328 * @return void
329 */
330 protected function send_error($ex=null) {
331 var_dump($ex);
332 die('TODO');
333 // TODO: find some way to send the error back through the Zend
334 }
335
336 /**
337 * Authenticate user using username+password or token.
338 * This function sets up $USER global.
339 * It is safe to use has_capability() after this.
340 * This method also verifies user is allowed to use this
341 * server.
342 * @return void
343 */
344 protected function authenticate_user() {
345 global $CFG, $DB;
346
347 if (!NO_MOODLE_COOKIES) {
348 throw new coding_exception('Cookies must be disabled in WS servers!');
349 }
350
351 if ($this->simple) {
352 $this->restricted_context = get_context_instance(CONTEXT_SYSTEM);
353
354 if (!is_enabled_auth('webservice')) {
5593d2dc 355 throw new webservice_access_exception('WS auth not enabled');
88098133 356 }
357
358 if (!$auth = get_auth_plugin('webservice')) {
5593d2dc 359 throw new webservice_access_exception('WS auth missing');
88098133 360 }
361
362 // the username is hardcoded as URL parameter because we can not easily parse the request data :-(
363 if (!$username = optional_param('wsusername', '', PARAM_RAW)) {
5593d2dc 364 throw new webservice_access_exception('Missing username');
88098133 365 }
366
367 // the password is hardcoded as URL parameter because we can not easily parse the request data :-(
368 if (!$password = optional_param('wspassword', '', PARAM_RAW)) {
5593d2dc 369 throw new webservice_access_exception('Missing password');
88098133 370 }
371
372 if (!$auth->user_login_webservice($username, $password)) {
5593d2dc 373 throw new webservice_access_exception('Wrong username or password');
88098133 374 }
375
376 $user = $DB->get_record('user', array('username'=>$username, 'mnethostid'=>$CFG->mnet_localhost_id, 'deleted'=>0), '*', MUST_EXIST);
377
378 // now fake user login, the session is completely empty too
379 session_set_user($user);
380
381 } else {
382
383 //TODO: not implemented yet
384 die('token login not implemented yet');
385 //TODO: $this->restricted_context is derived from the token context
386 }
387
388 if (!has_capability("webservice/$this->wsname:use", $this->restricted_context)) {
5593d2dc 389 throw new webservice_access_exception('Access to web service not allowed');
88098133 390 }
391
392 external_api::set_context_restriction($this->restricted_context);
393 }
394
395 /**
396 * Specialised exception handler, we can not use the standard one because
397 * it can not just print html to output.
398 *
399 * @param exception $ex
400 * @return void does not return
401 */
402 public function exception_handler($ex) {
403 global $CFG, $DB, $SCRIPT;
404
405 // detect active db transactions, rollback and log as error
406 if ($DB->is_transaction_started()) {
407 error_log('Database transaction aborted by exception in ' . $CFG->dirroot . $SCRIPT);
408 try {
409 // note: transaction blocks should never change current $_SESSION
410 $DB->rollback_sql();
411 } catch (Exception $ignored) {
412 }
413 }
414
415 // now let the plugin send the exception to client
416 $this->send_error($ex);
417
418 // some hacks might need a cleanup hook
419 $this->session_cleanup($ex);
420
421 // not much else we can do now, add some logging later
422 exit(1);
423 }
424
425 /**
426 * Future hook needed for emulated sessions.
427 * @param exception $exception null means normal termination, $exception received when WS call failed
428 * @return void
429 */
430 protected function session_cleanup($exception=null) {
431 if ($this->simple) {
432 // nothing needs to be done, there is no persistent session
433 } else {
434 // close emulated session if used
435 }
436 }
437
cc93c7da 438}
439
06e7fadc 440
886d7556 441/**
cc93c7da 442 * Web Service server base class, this class handles both
443 * simple and token authentication.
444 * @author Petr Skoda (skodak)
886d7556 445 */
cc93c7da 446abstract class webservice_base_server implements webservice_server {
447
448 /** @property string $wsname name of the web server plugin */
449 protected $wsname = null;
450
451 /** @property bool $simple true if simple auth used */
452 protected $simple;
453
454 /** @property string $username name of local user */
455 protected $username = null;
456
457 /** @property string $password password of the local user */
458 protected $password = null;
459
460 /** @property string $token authentication token*/
461 protected $token = null;
462
88098133 463 /** @property object restricted context */
464 protected $restricted_context;
465
cc93c7da 466 /** @property array $parameters the function parameters - the real values submitted in the request */
467 protected $parameters = null;
468
469 /** @property string $functionname the name of the function that is executed */
470 protected $functionname = null;
471
472 /** @property object $function full function description */
473 protected $function = null;
474
475 /** @property mixed $returns function return value */
476 protected $returns = null;
06e7fadc 477
478 /**
cc93c7da 479 * Contructor
06e7fadc 480 */
cc93c7da 481 public function __construct() {
06e7fadc 482 }
483
24350e06 484 /**
cc93c7da 485 * This method parses the request input, it needs to get:
486 * 1/ user authentication - username+password or token
487 * 2/ function name
488 * 3/ function parameters
489 *
490 * @return void
24350e06 491 */
cc93c7da 492 abstract protected function parse_request();
24350e06 493
cc93c7da 494 /**
495 * Send the result of function call to the WS client.
496 * @return void
497 */
498 abstract protected function send_response();
24350e06 499
fa0797ec 500 /**
cc93c7da 501 * Send the error information to the WS client.
502 * @param exception $ex
503 * @return void
fa0797ec 504 */
cc93c7da 505 abstract protected function send_error($ex=null);
fa0797ec 506
fa0797ec 507
cc93c7da 508 /**
509 * Process request from client.
510 * @param bool $simple use simple authentication
511 * @return void
512 */
513 public function run($simple) {
514 $this->simple = $simple;
fa0797ec 515
cc93c7da 516 // we will probably need a lot of memory in some functions
517 @raise_memory_limit('128M');
fa0797ec 518
cc93c7da 519 // set some longer timeout, this script is not sending any output,
520 // this means we need to manually extend the timeout operations
521 // that need longer time to finish
522 external_api::set_timeout();
fa0797ec 523
cc93c7da 524 // set up exception handler first, we want to sent them back in correct format that
525 // the other system understands
526 // we do not need to call the original default handler because this ws handler does everything
527 set_exception_handler(array($this, 'exception_handler'));
06e7fadc 528
cc93c7da 529 // init all properties from the request data
530 $this->parse_request();
06e7fadc 531
cc93c7da 532 // authenticate user, this has to be done after the request parsing
533 // this also sets up $USER and $SESSION
534 $this->authenticate_user();
06e7fadc 535
cc93c7da 536 // find all needed function info and make sure user may actually execute the function
537 $this->load_function_info();
f7631e73 538
cc93c7da 539 // finally, execute the function - any errors are catched by the default exception handler
540 $this->execute();
06e7fadc 541
cc93c7da 542 // send the results back in correct format
543 $this->send_response();
06e7fadc 544
cc93c7da 545 // session cleanup
546 $this->session_cleanup();
06e7fadc 547
cc93c7da 548 die;
f7631e73 549 }
550
cc93c7da 551 /**
552 * Specialised exception handler, we can not use the standard one because
553 * it can not just print html to output.
554 *
555 * @param exception $ex
556 * @return void does not return
557 */
558 public function exception_handler($ex) {
559 global $CFG, $DB, $SCRIPT;
560
561 // detect active db transactions, rollback and log as error
562 if ($DB->is_transaction_started()) {
563 error_log('Database transaction aborted by exception in ' . $CFG->dirroot . $SCRIPT);
564 try {
565 // note: transaction blocks should never change current $_SESSION
566 $DB->rollback_sql();
567 } catch (Exception $ignored) {
568 }
569 }
06e7fadc 570
cc93c7da 571 // now let the plugin send the exception to client
572 $this->send_error($ex);
f7631e73 573
cc93c7da 574 // some hacks might need a cleanup hook
575 $this->session_cleanup($ex);
06e7fadc 576
cc93c7da 577 // not much else we can do now, add some logging later
578 exit(1);
f7631e73 579 }
580
581 /**
cc93c7da 582 * Future hook needed for emulated sessions.
583 * @param exception $exception null means normal termination, $exception received when WS call failed
584 * @return void
f7631e73 585 */
cc93c7da 586 protected function session_cleanup($exception=null) {
587 if ($this->simple) {
588 // nothing needs to be done, there is no persistent session
589 } else {
590 // close emulated session if used
591 }
f7631e73 592 }
593
cc93c7da 594 /**
595 * Authenticate user using username+password or token.
596 * This function sets up $USER global.
597 * It is safe to use has_capability() after this.
598 * This method also verifies user is allowed to use this
599 * server.
600 * @return void
601 */
602 protected function authenticate_user() {
603 global $CFG, $DB;
06e7fadc 604
cc93c7da 605 if (!NO_MOODLE_COOKIES) {
606 throw new coding_exception('Cookies must be disabled in WS servers!');
607 }
608
609 if ($this->simple) {
88098133 610 $this->restricted_context = get_context_instance(CONTEXT_SYSTEM);
611
cc93c7da 612 if (!is_enabled_auth('webservice')) {
5593d2dc 613 throw new webservice_access_exception('WS auth not enabled');
cc93c7da 614 }
615
616 if (!$auth = get_auth_plugin('webservice')) {
5593d2dc 617 throw new webservice_access_exception('WS auth missing');
cc93c7da 618 }
619
620 if (!$this->username) {
5593d2dc 621 throw new webservice_access_exception('Missing username');
cc93c7da 622 }
623
624 if (!$this->password) {
5593d2dc 625 throw new webservice_access_exception('Missing password');
cc93c7da 626 }
627
628 if (!$auth->user_login_webservice($this->username, $this->password)) {
5593d2dc 629 throw new webservice_access_exception('Wrong username or password');
cc93c7da 630 }
631
632 $user = $DB->get_record('user', array('username'=>$this->username, 'mnethostid'=>$CFG->mnet_localhost_id, 'deleted'=>0), '*', MUST_EXIST);
633
634 // now fake user login, the session is completely empty too
635 session_set_user($user);
06e7fadc 636 } else {
88098133 637
cc93c7da 638 //TODO: not implemented yet
639 die('token login not implemented yet');
88098133 640 //TODO: $this->restricted_context is derived from the token context
641 }
cc93c7da 642
88098133 643 if (!has_capability("webservice/$this->wsname:use", $this->restricted_context)) {
5593d2dc 644 throw new webservice_access_exception('Access to web service not allowed');
886d7556 645 }
88098133 646
647 external_api::set_context_restriction($this->restricted_context);
06e7fadc 648 }
24350e06 649
650 /**
cc93c7da 651 * Fetches the function description from database,
652 * verifies user is allowed to use this function and
653 * loads all paremeters and return descriptions.
654 * @return void
24350e06 655 */
cc93c7da 656 protected function load_function_info() {
657 global $DB, $USER, $CFG;
40f024c9 658
cc93c7da 659 if (empty($this->functionname)) {
660 throw new invalid_parameter_exception('Missing function name');
661 }
24350e06 662
cc93c7da 663 // function must exist
5593d2dc 664 $function = external_function_info($this->functionname);
cc93c7da 665
666 // now let's verify access control
667 if ($this->simple) {
668 // now make sure the function is listed in at least one service user is allowed to use
669 // allow access only if:
670 // 1/ entry in the external_services_users table if required
671 // 2/ validuntil not reached
672 // 3/ has capability if specified in service desc
673 // 4/ iprestriction
674
675 $sql = "SELECT s.*, NULL AS iprestriction
676 FROM {external_services} s
677 JOIN {external_services_functions} sf ON (sf.externalserviceid = s.id AND s.restrictedusers = 0 AND sf.functionname = :name1)
678 WHERE s.enabled = 1
679
680 UNION
681
682 SELECT s.*, su.iprestriction
683 FROM {external_services} s
684 JOIN {external_services_functions} sf ON (sf.externalserviceid = s.id AND s.restrictedusers = 1 AND sf.functionname = :name2)
685 JOIN {external_services_users} su ON (su.externalserviceid = s.id AND su.userid = :userid)
686 WHERE s.enabled = 1 AND su.validuntil IS NULL OR su.validuntil < :now";
88098133 687 $params = array('userid'=>$USER->id, 'name1'=>$function->name, 'name2'=>$function->name, 'now'=>time());
688 } else {
cc93c7da 689
88098133 690 //TODO: token may restrict access to one service only
691 die('not implemented yet');
692 }
693
694 $rs = $DB->get_recordset_sql($sql, $params);
695 // now make sure user may access at least one service
696 $remoteaddr = getremoteaddr();
697 $allowed = false;
698 foreach ($rs as $service) {
699 if ($service->requiredcapability and !has_capability($service->requiredcapability, $this->restricted_context)) {
700 continue; // cap required, sorry
cc93c7da 701 }
88098133 702 if ($service->iprestriction and !address_in_subnet($remoteaddr, $service->iprestriction)) {
703 continue; // wrong request source ip, sorry
cc93c7da 704 }
88098133 705 $allowed = true;
706 break; // one service is enough, no need to continue
707 }
708 $rs->close();
709 if (!$allowed) {
710 throw new invalid_parameter_exception('Access to external function not allowed');
cc93c7da 711 }
9baf6825 712
cc93c7da 713 // we have all we need now
714 $this->function = $function;
715 }
716
717 /**
718 * Execute previously loaded function using parameters parsed from the request data.
719 * @return void
720 */
721 protected function execute() {
722 // validate params, this also sorts the params properly, we need the correct order in the next part
723 $params = call_user_func(array($this->function->classname, 'validate_parameters'), $this->function->parameters_desc, $this->parameters);
9baf6825 724
cc93c7da 725 // execute - yay!
726 $this->returns = call_user_func_array(array($this->function->classname, $this->function->methodname), array_values($params));
9baf6825 727 }
728}
729
730