mirror of
https://github.com/nextcloud/server.git
synced 2024-12-29 16:38:28 +00:00
dcd27fd986
Will be used to set default where we are able to override the default timeout. See https://github.com/nextcloud/server/pull/48418 Signed-off-by: Thomas Citharel <tcit@tcit.fr>
440 lines
18 KiB
PHP
440 lines
18 KiB
PHP
<?php
|
|
|
|
declare(strict_types=1);
|
|
/**
|
|
* SPDX-FileCopyrightText: 2016-2024 Nextcloud GmbH and Nextcloud contributors
|
|
* SPDX-FileCopyrightText: 2016 ownCloud, Inc.
|
|
* SPDX-License-Identifier: AGPL-3.0-only
|
|
*/
|
|
namespace OCP\Http\Client;
|
|
|
|
/**
|
|
* Interface IClient
|
|
*
|
|
* @since 8.1.0
|
|
*/
|
|
interface IClient {
|
|
|
|
/**
|
|
* Default request timeout for requests
|
|
*
|
|
* @since 31.0.0
|
|
*/
|
|
public const DEFAULT_REQUEST_TIMEOUT = 30;
|
|
|
|
/**
|
|
* Sends a GET request
|
|
* @param string $uri
|
|
* @param array $options Array such as
|
|
* 'query' => [
|
|
* 'field' => 'abc',
|
|
* 'other_field' => '123',
|
|
* 'file_name' => fopen('/path/to/file', 'r'),
|
|
* ],
|
|
* 'headers' => [
|
|
* 'foo' => 'bar',
|
|
* ],
|
|
* 'cookies' => [
|
|
* 'foo' => 'bar',
|
|
* ],
|
|
* 'allow_redirects' => [
|
|
* 'max' => 10, // allow at most 10 redirects.
|
|
* 'strict' => true, // use "strict" RFC compliant redirects.
|
|
* 'referer' => true, // add a Referer header
|
|
* 'protocols' => ['https'] // only allow https URLs
|
|
* ],
|
|
* 'sink' => '/path/to/file', // save to a file or a stream
|
|
* 'verify' => true, // bool or string to CA file
|
|
* 'debug' => true,
|
|
* @return IResponse
|
|
* @throws \Exception If the request could not get completed
|
|
* @since 8.1.0
|
|
*/
|
|
public function get(string $uri, array $options = []): IResponse;
|
|
|
|
/**
|
|
* Sends a HEAD request
|
|
* @param string $uri
|
|
* @param array $options Array such as
|
|
* 'headers' => [
|
|
* 'foo' => 'bar',
|
|
* ],
|
|
* 'cookies' => [
|
|
* 'foo' => 'bar',
|
|
* ],
|
|
* 'allow_redirects' => [
|
|
* 'max' => 10, // allow at most 10 redirects.
|
|
* 'strict' => true, // use "strict" RFC compliant redirects.
|
|
* 'referer' => true, // add a Referer header
|
|
* 'protocols' => ['https'] // only allow https URLs
|
|
* ],
|
|
* 'sink' => '/path/to/file', // save to a file or a stream
|
|
* 'verify' => true, // bool or string to CA file
|
|
* 'debug' => true,
|
|
* @return IResponse
|
|
* @throws \Exception If the request could not get completed
|
|
* @since 8.1.0
|
|
*/
|
|
public function head(string $uri, array $options = []): IResponse;
|
|
|
|
/**
|
|
* Sends a POST request
|
|
* @param string $uri
|
|
* @param array $options Array such as
|
|
* 'body' => [
|
|
* 'field' => 'abc',
|
|
* 'other_field' => '123',
|
|
* 'file_name' => fopen('/path/to/file', 'r'),
|
|
* ],
|
|
* 'headers' => [
|
|
* 'foo' => 'bar',
|
|
* ],
|
|
* 'cookies' => [
|
|
* 'foo' => 'bar',
|
|
* ],
|
|
* 'allow_redirects' => [
|
|
* 'max' => 10, // allow at most 10 redirects.
|
|
* 'strict' => true, // use "strict" RFC compliant redirects.
|
|
* 'referer' => true, // add a Referer header
|
|
* 'protocols' => ['https'] // only allow https URLs
|
|
* ],
|
|
* 'sink' => '/path/to/file', // save to a file or a stream
|
|
* 'verify' => true, // bool or string to CA file
|
|
* 'debug' => true,
|
|
* @return IResponse
|
|
* @throws \Exception If the request could not get completed
|
|
* @since 8.1.0
|
|
*/
|
|
public function post(string $uri, array $options = []): IResponse;
|
|
|
|
/**
|
|
* Sends a PUT request
|
|
* @param string $uri
|
|
* @param array $options Array such as
|
|
* 'body' => [
|
|
* 'field' => 'abc',
|
|
* 'other_field' => '123',
|
|
* 'file_name' => fopen('/path/to/file', 'r'),
|
|
* ],
|
|
* 'headers' => [
|
|
* 'foo' => 'bar',
|
|
* ],
|
|
* 'cookies' => [
|
|
* 'foo' => 'bar',
|
|
* ],
|
|
* 'allow_redirects' => [
|
|
* 'max' => 10, // allow at most 10 redirects.
|
|
* 'strict' => true, // use "strict" RFC compliant redirects.
|
|
* 'referer' => true, // add a Referer header
|
|
* 'protocols' => ['https'] // only allow https URLs
|
|
* ],
|
|
* 'sink' => '/path/to/file', // save to a file or a stream
|
|
* 'verify' => true, // bool or string to CA file
|
|
* 'debug' => true,
|
|
* @return IResponse
|
|
* @throws \Exception If the request could not get completed
|
|
* @since 8.1.0
|
|
*/
|
|
public function put(string $uri, array $options = []): IResponse;
|
|
|
|
/**
|
|
* Sends a PATCH request
|
|
* @param string $uri
|
|
* @param array $options Array such as
|
|
* 'body' => [
|
|
* 'field' => 'abc',
|
|
* 'other_field' => '123',
|
|
* 'file_name' => fopen('/path/to/file', 'r'),
|
|
* ],
|
|
* 'headers' => [
|
|
* 'foo' => 'bar',
|
|
* ],
|
|
* 'cookies' => [
|
|
* 'foo' => 'bar',
|
|
* ],
|
|
* 'allow_redirects' => [
|
|
* 'max' => 10, // allow at most 10 redirects.
|
|
* 'strict' => true, // use "strict" RFC compliant redirects.
|
|
* 'referer' => true, // add a Referer header
|
|
* 'protocols' => ['https'] // only allow https URLs
|
|
* ],
|
|
* 'sink' => '/path/to/file', // save to a file or a stream
|
|
* 'verify' => true, // bool or string to CA file
|
|
* 'debug' => true,
|
|
* @return IResponse
|
|
* @throws \Exception If the request could not get completed
|
|
* @since 29.0.0
|
|
*/
|
|
public function patch(string $uri, array $options = []): IResponse;
|
|
|
|
/**
|
|
* Sends a DELETE request
|
|
* @param string $uri
|
|
* @param array $options Array such as
|
|
* 'body' => [
|
|
* 'field' => 'abc',
|
|
* 'other_field' => '123',
|
|
* 'file_name' => fopen('/path/to/file', 'r'),
|
|
* ],
|
|
* 'headers' => [
|
|
* 'foo' => 'bar',
|
|
* ],
|
|
* 'cookies' => [
|
|
* 'foo' => 'bar',
|
|
* ],
|
|
* 'allow_redirects' => [
|
|
* 'max' => 10, // allow at most 10 redirects.
|
|
* 'strict' => true, // use "strict" RFC compliant redirects.
|
|
* 'referer' => true, // add a Referer header
|
|
* 'protocols' => ['https'] // only allow https URLs
|
|
* ],
|
|
* 'sink' => '/path/to/file', // save to a file or a stream
|
|
* 'verify' => true, // bool or string to CA file
|
|
* 'debug' => true,
|
|
* @return IResponse
|
|
* @throws \Exception If the request could not get completed
|
|
* @since 8.1.0
|
|
*/
|
|
public function delete(string $uri, array $options = []): IResponse;
|
|
|
|
/**
|
|
* Sends an OPTIONS request
|
|
* @param string $uri
|
|
* @param array $options Array such as
|
|
* 'body' => [
|
|
* 'field' => 'abc',
|
|
* 'other_field' => '123',
|
|
* 'file_name' => fopen('/path/to/file', 'r'),
|
|
* ],
|
|
* 'headers' => [
|
|
* 'foo' => 'bar',
|
|
* ],
|
|
* 'cookies' => [
|
|
* 'foo' => 'bar',
|
|
* ],
|
|
* 'allow_redirects' => [
|
|
* 'max' => 10, // allow at most 10 redirects.
|
|
* 'strict' => true, // use "strict" RFC compliant redirects.
|
|
* 'referer' => true, // add a Referer header
|
|
* 'protocols' => ['https'] // only allow https URLs
|
|
* ],
|
|
* 'sink' => '/path/to/file', // save to a file or a stream
|
|
* 'verify' => true, // bool or string to CA file
|
|
* 'debug' => true,
|
|
* @return IResponse
|
|
* @throws \Exception If the request could not get completed
|
|
* @since 8.1.0
|
|
*/
|
|
public function options(string $uri, array $options = []): IResponse;
|
|
|
|
/**
|
|
* Get the response of a Throwable thrown by the request methods when possible
|
|
*
|
|
* @param \Throwable $e
|
|
* @return IResponse
|
|
* @throws \Throwable When $e did not have a response
|
|
* @since 29.0.0
|
|
*/
|
|
public function getResponseFromThrowable(\Throwable $e): IResponse;
|
|
|
|
/**
|
|
* Sends a HTTP request
|
|
* @param string $method The HTTP method to use
|
|
* @param string $uri
|
|
* @param array $options Array such as
|
|
* 'query' => [
|
|
* 'field' => 'abc',
|
|
* 'other_field' => '123',
|
|
* 'file_name' => fopen('/path/to/file', 'r'),
|
|
* ],
|
|
* 'headers' => [
|
|
* 'foo' => 'bar',
|
|
* ],
|
|
* 'cookies' => [
|
|
* 'foo' => 'bar',
|
|
* ],
|
|
* 'allow_redirects' => [
|
|
* 'max' => 10, // allow at most 10 redirects.
|
|
* 'strict' => true, // use "strict" RFC compliant redirects.
|
|
* 'referer' => true, // add a Referer header
|
|
* 'protocols' => ['https'] // only allow https URLs
|
|
* ],
|
|
* 'sink' => '/path/to/file', // save to a file or a stream
|
|
* 'verify' => true, // bool or string to CA file
|
|
* 'debug' => true,
|
|
* @return IResponse
|
|
* @throws \Exception If the request could not get completed
|
|
* @since 29.0.0
|
|
*/
|
|
public function request(string $method, string $uri, array $options = []): IResponse;
|
|
|
|
/**
|
|
* Sends an asynchronous GET request
|
|
* @param string $uri
|
|
* @param array $options Array such as
|
|
* 'query' => [
|
|
* 'field' => 'abc',
|
|
* 'other_field' => '123',
|
|
* 'file_name' => fopen('/path/to/file', 'r'),
|
|
* ],
|
|
* 'headers' => [
|
|
* 'foo' => 'bar',
|
|
* ],
|
|
* 'cookies' => [
|
|
* 'foo' => 'bar',
|
|
* ],
|
|
* 'allow_redirects' => [
|
|
* 'max' => 10, // allow at most 10 redirects.
|
|
* 'strict' => true, // use "strict" RFC compliant redirects.
|
|
* 'referer' => true, // add a Referer header
|
|
* 'protocols' => ['https'] // only allow https URLs
|
|
* ],
|
|
* 'sink' => '/path/to/file', // save to a file or a stream
|
|
* 'verify' => true, // bool or string to CA file
|
|
* 'debug' => true,
|
|
* @return IPromise
|
|
* @since 28.0.0
|
|
*/
|
|
public function getAsync(string $uri, array $options = []): IPromise;
|
|
|
|
/**
|
|
* Sends an asynchronous HEAD request
|
|
* @param string $uri
|
|
* @param array $options Array such as
|
|
* 'headers' => [
|
|
* 'foo' => 'bar',
|
|
* ],
|
|
* 'cookies' => [
|
|
* 'foo' => 'bar',
|
|
* ],
|
|
* 'allow_redirects' => [
|
|
* 'max' => 10, // allow at most 10 redirects.
|
|
* 'strict' => true, // use "strict" RFC compliant redirects.
|
|
* 'referer' => true, // add a Referer header
|
|
* 'protocols' => ['https'] // only allow https URLs
|
|
* ],
|
|
* 'sink' => '/path/to/file', // save to a file or a stream
|
|
* 'verify' => true, // bool or string to CA file
|
|
* 'debug' => true,
|
|
* @return IPromise
|
|
* @since 28.0.0
|
|
*/
|
|
public function headAsync(string $uri, array $options = []): IPromise;
|
|
|
|
/**
|
|
* Sends an asynchronous POST request
|
|
* @param string $uri
|
|
* @param array $options Array such as
|
|
* 'body' => [
|
|
* 'field' => 'abc',
|
|
* 'other_field' => '123',
|
|
* 'file_name' => fopen('/path/to/file', 'r'),
|
|
* ],
|
|
* 'headers' => [
|
|
* 'foo' => 'bar',
|
|
* ],
|
|
* 'cookies' => [
|
|
* 'foo' => 'bar',
|
|
* ],
|
|
* 'allow_redirects' => [
|
|
* 'max' => 10, // allow at most 10 redirects.
|
|
* 'strict' => true, // use "strict" RFC compliant redirects.
|
|
* 'referer' => true, // add a Referer header
|
|
* 'protocols' => ['https'] // only allow https URLs
|
|
* ],
|
|
* 'sink' => '/path/to/file', // save to a file or a stream
|
|
* 'verify' => true, // bool or string to CA file
|
|
* 'debug' => true,
|
|
* @return IPromise
|
|
* @since 28.0.0
|
|
*/
|
|
public function postAsync(string $uri, array $options = []): IPromise;
|
|
|
|
/**
|
|
* Sends an asynchronous PUT request
|
|
* @param string $uri
|
|
* @param array $options Array such as
|
|
* 'body' => [
|
|
* 'field' => 'abc',
|
|
* 'other_field' => '123',
|
|
* 'file_name' => fopen('/path/to/file', 'r'),
|
|
* ],
|
|
* 'headers' => [
|
|
* 'foo' => 'bar',
|
|
* ],
|
|
* 'cookies' => [
|
|
* 'foo' => 'bar',
|
|
* ],
|
|
* 'allow_redirects' => [
|
|
* 'max' => 10, // allow at most 10 redirects.
|
|
* 'strict' => true, // use "strict" RFC compliant redirects.
|
|
* 'referer' => true, // add a Referer header
|
|
* 'protocols' => ['https'] // only allow https URLs
|
|
* ],
|
|
* 'sink' => '/path/to/file', // save to a file or a stream
|
|
* 'verify' => true, // bool or string to CA file
|
|
* 'debug' => true,
|
|
* @return IPromise
|
|
* @since 28.0.0
|
|
*/
|
|
public function putAsync(string $uri, array $options = []): IPromise;
|
|
|
|
/**
|
|
* Sends an asynchronous DELETE request
|
|
* @param string $uri
|
|
* @param array $options Array such as
|
|
* 'body' => [
|
|
* 'field' => 'abc',
|
|
* 'other_field' => '123',
|
|
* 'file_name' => fopen('/path/to/file', 'r'),
|
|
* ],
|
|
* 'headers' => [
|
|
* 'foo' => 'bar',
|
|
* ],
|
|
* 'cookies' => [
|
|
* 'foo' => 'bar',
|
|
* ],
|
|
* 'allow_redirects' => [
|
|
* 'max' => 10, // allow at most 10 redirects.
|
|
* 'strict' => true, // use "strict" RFC compliant redirects.
|
|
* 'referer' => true, // add a Referer header
|
|
* 'protocols' => ['https'] // only allow https URLs
|
|
* ],
|
|
* 'sink' => '/path/to/file', // save to a file or a stream
|
|
* 'verify' => true, // bool or string to CA file
|
|
* 'debug' => true,
|
|
* @return IPromise
|
|
* @since 28.0.0
|
|
*/
|
|
public function deleteAsync(string $uri, array $options = []): IPromise;
|
|
|
|
/**
|
|
* Sends an asynchronous OPTIONS request
|
|
* @param string $uri
|
|
* @param array $options Array such as
|
|
* 'body' => [
|
|
* 'field' => 'abc',
|
|
* 'other_field' => '123',
|
|
* 'file_name' => fopen('/path/to/file', 'r'),
|
|
* ],
|
|
* 'headers' => [
|
|
* 'foo' => 'bar',
|
|
* ],
|
|
* 'cookies' => [
|
|
* 'foo' => 'bar',
|
|
* ],
|
|
* 'allow_redirects' => [
|
|
* 'max' => 10, // allow at most 10 redirects.
|
|
* 'strict' => true, // use "strict" RFC compliant redirects.
|
|
* 'referer' => true, // add a Referer header
|
|
* 'protocols' => ['https'] // only allow https URLs
|
|
* ],
|
|
* 'sink' => '/path/to/file', // save to a file or a stream
|
|
* 'verify' => true, // bool or string to CA file
|
|
* 'debug' => true,
|
|
* @return IPromise
|
|
* @since 28.0.0
|
|
*/
|
|
public function optionsAsync(string $uri, array $options = []): IPromise;
|
|
}
|