includes/libs/virtualrest/VirtualRESTService.php

   1 <?php
   2 /**
   3  * Virtual HTTP service client
   4  *
   5  * This program 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 2 of the License, or
   8  * (at your option) any later version.
   9  *
  10  * This program 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 along
  16  * with this program; if not, write to the Free Software Foundation, Inc.,
  17  * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
  18  * http://www.gnu.org/copyleft/gpl.html
  19  *
  20  * @file
  21  */
  22
  23 /**
  24  * Virtual HTTP service instance that can be mounted on to a VirtualRESTService
  25  *
  26  * Sub-classes manage the logic of either:
  27  *   - a) Munging virtual HTTP request arrays to have qualified URLs and auth headers
  28  *   - b) Emulating the execution of virtual HTTP requests (e.g. brokering)
  29  *
  30  * Authentication information can be cached in instances of the class for performance.
  31  * Such information should also be cached locally on the server and auth requests should
  32  * have reasonable timeouts.
  33  *
  34  * @since 1.23
  35  */
  36 abstract class VirtualRESTService {
  37         /** @var array Key/value map */
  38         protected $params = array();
  39
  40         /**
  41          * @param array $params Key/value map
  42          */
  43         public function __construct( array $params ) {
  44                 $this->params = $params;
  45         }
  46
  47         /**
  48          * Return the name of this service, in a form suitable for error
  49          * reporting or debugging.
  50          *
  51          * @return string The name of the service behind this VRS object.
  52          */
  53         public function getName() {
  54                 return isset( $this->params['name'] ) ? $this->params['name'] :
  55                         get_class( $this );
  56         }
  57
  58         /**
  59          * Prepare virtual HTTP(S) requests (for this service) for execution
  60          *
  61          * This method should mangle any of the $reqs entry fields as needed:
  62          *   - url      : munge the URL to have an absolute URL with a protocol
  63          *                and encode path components as needed by the backend [required]
  64          *   - query    : include any authentication signatures/parameters [as needed]
  65          *   - headers  : include any authentication tokens/headers [as needed]
  66          *
  67          * The incoming URL parameter will be relative to the service mount point.
  68          *
  69          * This method can also remove some of the requests as well as add new ones
  70          * (using $idGenerator to set each of the entries' array keys). For any existing
  71          * or added request, the 'response' array can be filled in, which will prevent the
  72          * client from executing it. If an original request is removed, at some point it
  73          * must be added back (with the same key) in onRequests() or onResponses();
  74          * it's reponse may be filled in as with other requests.
  75          *
  76          * @param array $reqs Map of Virtual HTTP request arrays
  77          * @param Closure $idGeneratorFunc Method to generate unique keys for new requests
  78          * @return array Modified HTTP request array map
  79          */
  80         public function onRequests( array $reqs, Closure $idGeneratorFunc ) {
  81                 $result = array();
  82                 foreach ( $reqs as $key => $req ) {
  83                         // The default encoding treats the URL as a REST style path that uses
  84                         // forward slash as a hierarchical delimiter (and never otherwise).
  85                         // Subclasses can override this, and should be documented in any case.
  86                         $parts = array_map( 'rawurlencode', explode( '/', $req['url'] ) );
  87                         $req['url'] = $this->params['baseUrl'] . '/' . implode( '/', $parts );
  88                         $result[$key] = $req;
  89                 }
  90                 return $result;
  91         }
  92
  93         /**
  94          * Mangle or replace virtual HTTP(S) requests which have been responded to
  95          *
  96          * This method may mangle any of the $reqs entry 'response' fields as needed:
  97          *   - code    : perform any code normalization [as needed]
  98          *   - reason  : perform any reason normalization [as needed]
  99          *   - headers : perform any header normalization [as needed]
 100          *
 101          * This method can also remove some of the requests as well as add new ones
 102          * (using $idGenerator to set each of the entries' array keys). For any existing
 103          * or added request, the 'response' array can be filled in, which will prevent the
 104          * client from executing it. If an original request is removed, at some point it
 105          * must be added back (with the same key) in onRequests() or onResponses();
 106          * it's reponse may be filled in as with other requests. All requests added to $reqs
 107          * will be passed through onRequests() to handle any munging required as normal.
 108          *
 109          * The incoming URL parameter will be relative to the service mount point.
 110          *
 111          * @param array $reqs Map of Virtual HTTP request arrays with 'response' set
 112          * @param Closure $idGeneratorFunc Method to generate unique keys for new requests
 113          * @return array Modified HTTP request array map
 114          */
 115         public function onResponses( array $reqs, Closure $idGeneratorFunc ) {
 116                 return $reqs;
 117         }
 118 }