includes/http/HttpRequestFactory.php

   1 <?php
   2 /**
   3  * This program is free software; you can redistribute it and/or modify
   4  * it under the terms of the GNU General Public License as published by
   5  * the Free Software Foundation; either version 2 of the License, or
   6  * (at your option) any later version.
   7  *
   8  * This program is distributed in the hope that it will be useful,
   9  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  10  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
  11  * GNU General Public License for more details.
  12  *
  13  * You should have received a copy of the GNU General Public License along
  14  * with this program; if not, write to the Free Software Foundation, Inc.,
  15  * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
  16  * http://www.gnu.org/copyleft/gpl.html
  17  *
  18  * @file
  19  */
  20 namespace MediaWiki\Http;
  21
  22 use GuzzleHttp\Client;
  23 use GuzzleHttpRequest;
  24 use InvalidArgumentException;
  25 use MediaWiki\Config\ServiceOptions;
  26 use MediaWiki\Logger\LoggerFactory;
  27 use MediaWiki\MainConfigNames;
  28 use MediaWiki\Status\Status;
  29 use MWHttpRequest;
  30 use Profiler;
  31 use Psr\Log\LoggerInterface;
  32 use Wikimedia\Http\MultiHttpClient;
  33
  34 /**
  35  * Factory creating MWHttpRequest objects.
  36  */
  37 class HttpRequestFactory {
  38         /** @var ServiceOptions */
  39         private $options;
  40         /** @var LoggerInterface */
  41         private $logger;
  42         /** @var Telemetry|null */
  43         private $telemetry;
  44
  45         /**
  46          * @internal For use by ServiceWiring
  47          */
  48         public const CONSTRUCTOR_OPTIONS = [
  49                 MainConfigNames::HTTPTimeout,
  50                 MainConfigNames::HTTPConnectTimeout,
  51                 MainConfigNames::HTTPMaxTimeout,
  52                 MainConfigNames::HTTPMaxConnectTimeout,
  53                 MainConfigNames::LocalVirtualHosts,
  54                 MainConfigNames::LocalHTTPProxy,
  55         ];
  56
  57         public function __construct(
  58                 ServiceOptions $options,
  59                 LoggerInterface $logger,
  60                 ?Telemetry $telemetry = null
  61         ) {
  62                 $options->assertRequiredOptions( self::CONSTRUCTOR_OPTIONS );
  63                 $this->options = $options;
  64                 $this->logger = $logger;
  65                 $this->telemetry = $telemetry;
  66         }
  67
  68         /**
  69          * Generate a new MWHttpRequest object
  70          * @param string $url Url to use
  71          * @param array $options Possible keys for the array:
  72          *    - timeout             Timeout length in seconds or 'default'
  73          *    - connectTimeout      Timeout for connection, in seconds (curl only) or 'default'
  74          *    - maxTimeout          Override for the configured maximum timeout. This should not be
  75          *                          used in production code.
  76          *    - maxConnectTimeout   Override for the configured maximum connect timeout. This should
  77          *                          not be used in production code.
  78          *    - postData            An array of key-value pairs or a url-encoded form data
  79          *    - proxy               The proxy to use.
  80          *                          Otherwise it will use $wgHTTPProxy or $wgLocalHTTPProxy (if set)
  81          *                          Otherwise it will use the environment variable "http_proxy" (if set)
  82          *    - noProxy             Don't use any proxy at all. Takes precedence over proxy value(s).
  83          *    - sslVerifyHost       Verify hostname against certificate
  84          *    - sslVerifyCert       Verify SSL certificate
  85          *    - caInfo              Provide CA information
  86          *    - maxRedirects        Maximum number of redirects to follow (defaults to 5)
  87          *    - followRedirects     Whether to follow redirects (defaults to false).
  88          *                          Note: this should only be used when the target URL is trusted,
  89          *                          to avoid attacks on intranet services accessible by HTTP.
  90          *    - userAgent           A user agent, if you want to override the default
  91          *                          "MediaWiki/{MW_VERSION}".
  92          *    - logger              A \Psr\Logger\LoggerInterface instance for debug logging
  93          *    - username            Username for HTTP Basic Authentication
  94          *    - password            Password for HTTP Basic Authentication
  95          *    - originalRequest     Information about the original request (as a WebRequest object or
  96          *                          an associative array with 'ip' and 'userAgent').
  97          * @phpcs:ignore Generic.Files.LineLength
  98          * @phan-param array{timeout?:int|string,connectTimeout?:int|string,postData?:string|array,proxy?:?string,noProxy?:bool,sslVerifyHost?:bool,sslVerifyCert?:bool,caInfo?:?string,maxRedirects?:int,followRedirects?:bool,userAgent?:string,method?:string,logger?:\Psr\Log\LoggerInterface,username?:string,password?:string,originalRequest?:\MediaWiki\Request\WebRequest|array{ip:string,userAgent:string}} $options
  99          * @param string $caller The method making this request, for profiling @phan-mandatory-param
 100          * @return MWHttpRequest
 101          * @see MWHttpRequest::__construct
 102          */
 103         public function create( $url, array $options = [], $caller = __METHOD__ ) {
 104                 if ( !isset( $options['logger'] ) ) {
 105                         $options['logger'] = $this->logger;
 106                 }
 107                 $options['timeout'] = $this->normalizeTimeout(
 108                         $options['timeout'] ?? null,
 109                         $options['maxTimeout'] ?? null,
 110                         $this->options->get( MainConfigNames::HTTPTimeout ),
 111                         $this->options->get( MainConfigNames::HTTPMaxTimeout ) ?: INF
 112                 );
 113                 $options['connectTimeout'] = $this->normalizeTimeout(
 114                         $options['connectTimeout'] ?? null,
 115                         $options['maxConnectTimeout'] ?? null,
 116                         $this->options->get( MainConfigNames::HTTPConnectTimeout ),
 117                         $this->options->get( MainConfigNames::HTTPMaxConnectTimeout ) ?: INF
 118                 );
 119                 $client = new GuzzleHttpRequest( $url, $options, $caller, Profiler::instance() );
 120                 if ( $this->telemetry ) {
 121                         $client->addTelemetry( $this->telemetry );
 122                 }
 123                 return $client;
 124         }
 125
 126         /**
 127          * Given a passed parameter value, a default and a maximum, figure out the
 128          * correct timeout to pass to the backend.
 129          *
 130          * @param int|float|string|null $parameter The timeout in seconds, or "default" or null
 131          * @param int|float|null $maxParameter The maximum timeout specified by the caller
 132          * @param int|float $default The configured default timeout
 133          * @param int|float $maxConfigured The configured maximum timeout
 134          * @return int|float
 135          */
 136         private function normalizeTimeout( $parameter, $maxParameter, $default, $maxConfigured ) {
 137                 if ( $parameter === 'default' || $parameter === null ) {
 138                         if ( !is_numeric( $default ) ) {
 139                                 throw new InvalidArgumentException(
 140                                         '$wgHTTPTimeout and $wgHTTPConnectTimeout must be set to a number' );
 141                         }
 142                         $value = $default;
 143                 } else {
 144                         $value = $parameter;
 145                 }
 146                 $max = $maxParameter ?? $maxConfigured;
 147                 if ( $max && $value > $max ) {
 148                         return $max;
 149                 }
 150
 151                 return $value;
 152         }
 153
 154         /**
 155          * Simple function to test if we can make any sort of requests at all, using
 156          * cURL or fopen()
 157          * @return bool
 158          */
 159         public function canMakeRequests() {
 160                 return function_exists( 'curl_init' ) || wfIniGetBool( 'allow_url_fopen' );
 161         }
 162
 163         /**
 164          * Perform an HTTP request
 165          *
 166          * @since 1.34
 167          * @param string $method HTTP method. Usually GET/POST
 168          * @param string $url Full URL to act on. If protocol-relative, will be expanded to an http://
 169          *  URL
 170          * @param array $options See HttpRequestFactory::create
 171          * @param string $caller The method making this request, for profiling @phan-mandatory-param
 172          * @return string|null null on failure or a string on success
 173          */
 174         public function request( $method, $url, array $options = [], $caller = __METHOD__ ) {
 175                 $logger = LoggerFactory::getInstance( 'http' );
 176                 $logger->debug( "$method: $url" );
 177
 178                 $options['method'] = strtoupper( $method );
 179
 180                 $req = $this->create( $url, $options, $caller );
 181                 $status = $req->execute();
 182
 183                 if ( $status->isOK() ) {
 184                         return $req->getContent();
 185                 } else {
 186                         $errors = array_map( fn ( $msg ) => $msg->getKey(), $status->getMessages( 'error' ) );
 187                         $logger->warning( Status::wrap( $status )->getWikiText( false, false, 'en' ),
 188                                 [ 'error' => $errors, 'caller' => $caller, 'content' => $req->getContent() ] );
 189                         return null;
 190                 }
 191         }
 192
 193         /**
 194          * Simple wrapper for `request( 'GET' )`, parameters have the same meaning as for `request()`
 195          *
 196          * @since 1.34
 197          * @param string $url
 198          * @param array $options
 199          * @param string $caller @phan-mandatory-param
 200          * @return string|null
 201          */
 202         public function get( $url, array $options = [], $caller = __METHOD__ ) {
 203                 return $this->request( 'GET', $url, $options, $caller );
 204         }
 205
 206         /**
 207          * Simple wrapper for `request( 'POST' )`, parameters have the same meaning as for `request()`
 208          *
 209          * @since 1.34
 210          * @param string $url
 211          * @param array $options
 212          * @param string $caller @phan-mandatory-param
 213          * @return string|null
 214          */
 215         public function post( $url, array $options = [], $caller = __METHOD__ ) {
 216                 return $this->request( 'POST', $url, $options, $caller );
 217         }
 218
 219         /**
 220          * @return string
 221          */
 222         public function getUserAgent() {
 223                 return 'MediaWiki/' . MW_VERSION;
 224         }
 225
 226         /**
 227          * Get a MultiHttpClient with MediaWiki configured defaults applied.
 228          *
 229          * Unlike create(), by default, no proxy will be used. To use a proxy,
 230          * specify the 'proxy' option.
 231          *
 232          * @param array $options Options as documented in MultiHttpClient::__construct(),
 233          *   except that for consistency with create(), 'timeout' is accepted as an
 234          *   alias for 'reqTimeout', and 'connectTimeout' is accepted as an alias for
 235          *  'connTimeout'.
 236          * @return MultiHttpClient
 237          */
 238         public function createMultiClient( $options = [] ) {
 239                 $options['reqTimeout'] = $this->normalizeTimeout(
 240                         $options['reqTimeout'] ?? $options['timeout'] ?? null,
 241                         $options['maxReqTimeout'] ?? $options['maxTimeout'] ?? null,
 242                         $this->options->get( MainConfigNames::HTTPTimeout ),
 243                         $this->options->get( MainConfigNames::HTTPMaxTimeout ) ?: INF
 244                 );
 245                 $options['connTimeout'] = $this->normalizeTimeout(
 246                         $options['connTimeout'] ?? $options['connectTimeout'] ?? null,
 247                         $options['maxConnTimeout'] ?? $options['maxConnectTimeout'] ?? null,
 248                         $this->options->get( MainConfigNames::HTTPConnectTimeout ),
 249                         $this->options->get( MainConfigNames::HTTPMaxConnectTimeout ) ?: INF
 250                 );
 251                 $options += [
 252                         'maxReqTimeout' => $this->options->get( MainConfigNames::HTTPMaxTimeout ) ?: INF,
 253                         'maxConnTimeout' =>
 254                                 $this->options->get( MainConfigNames::HTTPMaxConnectTimeout ) ?: INF,
 255                         'userAgent' => $this->getUserAgent(),
 256                         'logger' => $this->logger,
 257                         'localProxy' => $this->options->get( MainConfigNames::LocalHTTPProxy ),
 258                         'localVirtualHosts' => $this->options->get( MainConfigNames::LocalVirtualHosts ),
 259                         'telemetry' => Telemetry::getInstance(),
 260                 ];
 261                 return new MultiHttpClient( $options );
 262         }
 263
 264         /**
 265          * Get a GuzzleHttp\Client instance.
 266          *
 267          * @since 1.36
 268          * @param array $config Client configuration settings.
 269          * @return Client
 270          *
 271          * @see \GuzzleHttp\RequestOptions for a list of available request options.
 272          * @see Client::__construct() for additional options.
 273          * Additional options that should not be used in production code:
 274          *      - maxTimeout          Override for the configured maximum timeout.
 275          *      - maxConnectTimeout   Override for the configured maximum connect timeout.
 276          */
 277         public function createGuzzleClient( array $config = [] ): Client {
 278                 $config['timeout'] = $this->normalizeTimeout(
 279                         $config['timeout'] ?? null,
 280                         $config['maxTimeout'] ?? null,
 281                         $this->options->get( MainConfigNames::HTTPTimeout ),
 282                         $this->options->get( MainConfigNames::HTTPMaxTimeout ) ?: INF
 283                 );
 284
 285                 $config['connect_timeout'] = $this->normalizeTimeout(
 286                         $config['connect_timeout'] ?? null,
 287                         $config['maxConnectTimeout'] ?? null,
 288                         $this->options->get( MainConfigNames::HTTPConnectTimeout ),
 289                         $this->options->get( MainConfigNames::HTTPMaxConnectTimeout ) ?: INF
 290                 );
 291
 292                 if ( !isset( $config['headers']['User-Agent'] ) ) {
 293                         $config['headers']['User-Agent'] = $this->getUserAgent();
 294                 }
 295                 if ( $this->telemetry ) {
 296                         $config['headers'] = array_merge(
 297                                 $this->telemetry->getRequestHeaders(), $config['headers']
 298                         );
 299                 }
 300
 301                 return new Client( $config );
 302         }
 303 }