Page MenuHomePhorge

final class HTTPSFuture
libphutil Technical Documentation (Futures)

Very basic HTTPS future.

Tasks

Creating a New Request

  • final public function __construct($uri, $data) — Build a new future which will make an HTTP request to a given URI, with some optional data payload. Since this class is abstract you can't actually instantiate it; instead, build a new @{class:HTTPFuture} or @{class:HTTPSFuture}.

Configuring the Request

  • public function setTimeout($timeout) — Set a timeout for the service call. If the request hasn't resolved yet, the future will resolve with a status that indicates the request timed out. You can determine if a status is a timeout status by calling isTimeout() on the status object.
  • public function getTimeout() — Get the currently configured timeout.
  • final public function setMethod($method) — Select the HTTP method (e.g., "GET", "POST", "PUT") to use for the request. By default, requests use "GET".
  • final public function getMethod() — Get the HTTP method the request will use.
  • public function setURI($uri) — Set the URI to send the request to. Note that this is also a constructor parameter.
  • public function getURI() — Get the fully-qualified URI the request will be made to.
  • public function setData($data) — Provide data to send along with the request. Note that this is also a constructor parameter; it may be more convenient to provide it there. Data must be a string (in which case it will be sent raw) or an array (in which case it will be encoded and sent as 'application/x-www-form-urlencoded').
  • public function getData() — Get the data which will be sent with the request.
  • public function addHeader($name, $value) — Add an HTTP header to the request. The same header name can be specified more than once, which will cause multiple headers to be sent.
  • public function getHeaders($filter) — Get headers which will be sent with the request. Optionally, you can provide a filter, which will return only headers with that name. For example:
  • public function setExpectStatus($status_codes) — Set the status codes that are expected in the response. If set, isError on the status object will return true for status codes that are not in the input array. Otherwise, isError will be true for any HTTP status code outside the 2xx range (notwithstanding other errors such as connection or transport issues).
  • public function setHTTPBasicAuthCredentials($username, $password) — Add a HTTP basic authentication header to the request.

Resolving the Request

  • final public function resolvex() — Exception-oriented @{method:resolve}. Throws if the status indicates an error occurred.
  • public static function getHeader($headers, $search) — Find value of the first header with given name.

Internals

  • protected function parseRawHTTPResponse($raw_response) — Parse a raw HTTP response into a <status, body, headers> tuple.
  • protected function parseHeaders($head_raw) — Parse an HTTP header block.
  • protected function buildMalformedResult($raw_response) — Build a result tuple indicating a parse error resulting from a malformed HTTP response.

Other Methods

  • public function __get($name)
  • public function __set($name, $value)
  • public function current()
  • public function key()
  • public function next()
  • public function rewind()
  • public function valid()
  • private function throwOnAttemptedIteration()
  • public function getPhobjectClassConstant($key, $byte_limit) — Read the value of a class constant.
  • public function isReady()
  • public function resolve() — Resolve a future and return its result, blocking until the result is ready if necessary.
  • final public function updateFuture()
  • private function startServiceProfiler()
  • private function endServiceProfiler()
  • protected function getServiceProfilerStartParameters()
  • protected function getServiceProfilerResultParameters()
  • public function getReadSockets() — Retrieve a list of sockets which we can wait to become readable while a future is resolving. If your future has sockets which can be `select()`ed, return them here (or in @{method:getWriteSockets}) to make the resolve loop do a `select()`. If you do not return sockets in either case, you'll get a busy wait.
  • public function getWriteSockets() — Retrieve a list of sockets which we can wait to become writable while a future is resolving. See @{method:getReadSockets}.
  • public function getDefaultWait() — Default amount of time to wait on stream select for this future. Normally 1 second is fine, but if the future has a timeout sooner than that it should return the amount of time left before the timeout.
  • public function start()
  • final protected function getResult() — Retrieve the final result of the future.
  • final protected function setResult($result)
  • final public function hasResult()
  • private function setException($exception)
  • private function getException()
  • final public function hasException()
  • final public function setFutureKey($key)
  • final public function getFutureKey()
  • final public function setRaiseExceptionOnStart($raise)
  • final public function getHasFutureStarted()
  • final public function canResolve()
  • private function endFuture()
  • public function getExpectStatus() — Return list of expected status codes, or null if not set.
  • public function getHTTPRequestByteLength()
  • public function setDisableContentDecoding($disable_decoding)
  • public function getDisableContentDecoding()
  • public function setCABundleFromString($certificate) — Create a temp file containing an SSL cert, and use it for this session.
  • public function setCABundleFromPath($path) — Set the SSL certificate to use for this session, given a path.
  • public function getCABundle() — Get the path to the SSL certificate for this session.
  • public function setFollowLocation($follow) — Set whether Location headers in the response will be respected. The default is true.
  • public function getFollowLocation() — Get whether Location headers in the response will be respected.
  • public static function setGlobalCABundleFromPath($path) — Set the fallback CA certificate if one is not specified for the session, given a path.
  • public static function setGlobalCABundleFromString($certificate) — Set the fallback CA certificate if one is not specified for the session, given a string.
  • public static function getGlobalCABundle() — Get the fallback global CA certificate
  • public static function loadContent($uri, $timeout) — Load contents of remote URI. Behaves pretty much like `@file_get_contents($uri)` but doesn't require `allow_url_fopen`.
  • public function setDownloadPath($download_path)
  • public function setProgressSink($progress_sink)
  • public function getProgressSink()
  • public function addCURLOption($option_key, $option_value) — See T13533. This supports an install-specific Kerberos workflow.
  • public function attachFileData($key, $data, $name, $mime_type) — Attach a file to the request.
  • public function didReceiveDataCallback($handle, $data) — Callback invoked by cURL as it reads HTTP data from the response. We save the data to a buffer.
  • public function read() — Read data from the response buffer.
  • public function discardBuffers() — Discard any buffered data. Normally, you call this after reading the data with @{method:read}.
  • private function formatRequestDataForCURL() — Produces a value safe to pass to `CURLOPT_POSTFIELDS`.
  • private function checkForDangerousCURLMagic($string, $is_query_string) — Detect strings which will cause cURL to do horrible, insecure things.
  • private function canSetCAInfo() — Determine whether CURLOPT_CAINFO is usable on this system.
  • public function write($raw_body) — Write a raw HTTP body into the request.
  • public function willWriteBody($handle, $infile, $len) — Callback to pass data to cURL.
  • private function shouldReuseHandles()
  • private function isDownload()
  • private function canAcceptGzip()

Methods

public function __get($name)
Inherited

This method is not documented.
Parameters
$name
Return
wild

public function __set($name, $value)
Inherited

This method is not documented.
Parameters
$name
$value
Return
wild

public function current()
Inherited

This method is not documented.
Return
wild

public function key()
Inherited

This method is not documented.
Return
wild

public function next()
Inherited

This method is not documented.
Return
wild

public function rewind()
Inherited

This method is not documented.
Return
wild

public function valid()
Inherited

This method is not documented.
Return
wild

private function throwOnAttemptedIteration()
Inherited

This method is not documented.
Return
wild

public function getPhobjectClassConstant($key, $byte_limit)
Inherited

Phobject

Read the value of a class constant.

This is the same as just typing self::CONSTANTNAME, but throws a more useful message if the constant is not defined and allows the constant to be limited to a maximum length.

Parameters
string$keyName of the constant.
int|null$byte_limitMaximum number of bytes permitted in the value.
Return
stringValue of the constant.

public function isReady()

Future

Is this future's process complete? Specifically, can this future be resolved without blocking?

HTTPSFuture
This method is not documented.
Return
boolIf true, the external process is complete and resolving this future will not block.

public function resolve()
Inherited

Future

Resolve a future and return its result, blocking until the result is ready if necessary.

Return
wildFuture result.

final public function updateFuture()
Inherited

This method is not documented.
Return
wild

private function startServiceProfiler()
Inherited

This method is not documented.
Return
wild

private function endServiceProfiler()
Inherited

This method is not documented.
Return
wild
This method is not documented.
Return
wild

protected function getServiceProfilerResultParameters()
Inherited

This method is not documented.
Return
wild

public function getReadSockets()
Inherited

Future

Retrieve a list of sockets which we can wait to become readable while a future is resolving. If your future has sockets which can be select()ed, return them here (or in getWriteSockets()) to make the resolve loop do a select(). If you do not return sockets in either case, you'll get a busy wait.

Return
listA list of sockets which we expect to become readable.

public function getWriteSockets()
Inherited

Future

Retrieve a list of sockets which we can wait to become writable while a future is resolving. See getReadSockets().

Return
listA list of sockets which we expect to become writable.

public function getDefaultWait()
Inherited

Future

Default amount of time to wait on stream select for this future. Normally 1 second is fine, but if the future has a timeout sooner than that it should return the amount of time left before the timeout.

Return
wild

public function start()
Inherited

This method is not documented.
Return
wild

final protected function getResult()
Inherited

Future

Retrieve the final result of the future.

Return
wildFinal resolution of this future.

final protected function setResult($result)
Inherited

This method is not documented.
Parameters
$result
Return
wild

final public function hasResult()
Inherited

This method is not documented.
Return
wild

private function setException($exception)
Inherited

This method is not documented.
Parameters
$exception
Return
wild

private function getException()
Inherited

This method is not documented.
Return
wild

final public function hasException()
Inherited

This method is not documented.
Return
wild

final public function setFutureKey($key)
Inherited

This method is not documented.
Parameters
$key
Return
wild

final public function getFutureKey()
Inherited

This method is not documented.
Return
wild

final public function setRaiseExceptionOnStart($raise)
Inherited

This method is not documented.
Parameters
$raise
Return
wild

final public function getHasFutureStarted()
Inherited

This method is not documented.
Return
wild

final public function canResolve()
Inherited

This method is not documented.
Return
wild

private function endFuture()
Inherited

This method is not documented.
Return
wild

final public function __construct($uri, $data)
Inherited

BaseHTTPFuture

Build a new future which will make an HTTP request to a given URI, with some optional data payload. Since this class is abstract you can't actually instantiate it; instead, build a new HTTPFuture or HTTPSFuture.

Parameters
string$uriFully-qualified URI to send a request to.
mixed$dataString or array to include in the request. Strings will be transmitted raw; arrays will be encoded and sent as 'application/x-www-form-urlencoded'.
Return
this//Implicit.//

public function setTimeout($timeout)
Inherited

BaseHTTPFuture

Set a timeout for the service call. If the request hasn't resolved yet, the future will resolve with a status that indicates the request timed out. You can determine if a status is a timeout status by calling isTimeout() on the status object.

Parameters
float$timeoutMaximum timeout, in seconds.
Return
this

public function getTimeout()
Inherited

BaseHTTPFuture

Get the currently configured timeout.

Return
floatMaximum number of seconds the request will execute for.

final public function setMethod($method)
Inherited

BaseHTTPFuture

Select the HTTP method (e.g., "GET", "POST", "PUT") to use for the request. By default, requests use "GET".

Parameters
string$methodHTTP method name.
Return
this

final public function getMethod()
Inherited

BaseHTTPFuture

Get the HTTP method the request will use.

Return
stringHTTP method name, like "GET".

public function setURI($uri)
Inherited

BaseHTTPFuture

Set the URI to send the request to. Note that this is also a constructor parameter.

Parameters
string$uriURI to send the request to.
Return
this

public function getURI()
Inherited

BaseHTTPFuture

Get the fully-qualified URI the request will be made to.

Return
stringURI the request will be sent to.

public function setData($data)
Inherited

BaseHTTPFuture

Provide data to send along with the request. Note that this is also a constructor parameter; it may be more convenient to provide it there. Data must be a string (in which case it will be sent raw) or an array (in which case it will be encoded and sent as 'application/x-www-form-urlencoded').

Parameters
mixed$dataData to send with the request.
Return
this

public function getData()
Inherited

BaseHTTPFuture

Get the data which will be sent with the request.

Return
mixedData which will be sent.

public function addHeader($name, $value)
Inherited

BaseHTTPFuture

Add an HTTP header to the request. The same header name can be specified more than once, which will cause multiple headers to be sent.

Parameters
string$nameHeader name, like "Accept-Language".
string$valueHeader value, like "en-us".
Return
this

public function getHeaders($filter)
Inherited

BaseHTTPFuture

Get headers which will be sent with the request. Optionally, you can provide a filter, which will return only headers with that name. For example:

$all_headers = $future->getHeaders();
$just_user_agent = $future->getHeaders('User-Agent');

In either case, an array with all (or all matching) headers is returned.

Parameters
string|null$filterOptional filter, which selects only headers with that name if provided.
Return
arrayList of all (or all matching) headers.

public function setExpectStatus($status_codes)
Inherited

BaseHTTPFuture

Set the status codes that are expected in the response. If set, isError on the status object will return true for status codes that are not in the input array. Otherwise, isError will be true for any HTTP status code outside the 2xx range (notwithstanding other errors such as connection or transport issues).

Parameters
array|null$status_codesList of expected HTTP status codes.
Return
this

public function getExpectStatus()
Inherited

BaseHTTPFuture

Return list of expected status codes, or null if not set.

Return
array|nullList of expected status codes.

public function setHTTPBasicAuthCredentials($username, $password)
Inherited

BaseHTTPFuture

Add a HTTP basic authentication header to the request.

Parameters
string$usernameUsername to authenticate with.
PhutilOpaqueEnvelope$passwordPassword to authenticate with.
Return
this

public function getHTTPRequestByteLength()
Inherited

This method is not documented.
Return
wild

public function setDisableContentDecoding($disable_decoding)
Inherited

This method is not documented.
Parameters
$disable_decoding
Return
wild

public function getDisableContentDecoding()
Inherited

This method is not documented.
Return
wild

final public function resolvex()
Inherited

BaseHTTPFuture

Exception-oriented resolve(). Throws if the status indicates an error occurred.

Return
tupleHTTP request result <body, headers> tuple.

protected function parseRawHTTPResponse($raw_response)
Inherited

BaseHTTPFuture

Parse a raw HTTP response into a <status, body, headers> tuple.

Parameters
string$raw_responseRaw HTTP response.
Return
tupleValid resolution tuple.

protected function parseHeaders($head_raw)
Inherited

BaseHTTPFuture

Parse an HTTP header block.

Parameters
string$head_rawRaw HTTP headers.
Return
listList of HTTP header tuples.

public static function getHeader($headers, $search)
Inherited

BaseHTTPFuture

Find value of the first header with given name.

Parameters
list$headersList of headers from `resolve()`.
string$searchCase insensitive header name.
Return
stringValue of the header or null if not found.

protected function buildMalformedResult($raw_response)
Inherited

BaseHTTPFuture

Build a result tuple indicating a parse error resulting from a malformed HTTP response.

Parameters
$raw_response
Return
tupleValid resolution tuple.

public function setCABundleFromString($certificate)

Create a temp file containing an SSL cert, and use it for this session.

This allows us to do host-specific SSL certificates in whatever client is using libphutil. e.g. in Arcanist, you could add an "ssl_cert" key to a specific host in ~/.arcrc and use that.

cURL needs this to be a file, it doesn't seem to be able to handle a string which contains the cert. So we make a temporary file and store it there.

Parameters
string$certificateThe multi-line, possibly lengthy, SSL certificate to use.
Return
this

public function setCABundleFromPath($path)

Set the SSL certificate to use for this session, given a path.

Parameters
string$pathThe path to a valid SSL certificate for this session
Return
this

public function getCABundle()

Get the path to the SSL certificate for this session.

Return
string|null

public function setFollowLocation($follow)

Set whether Location headers in the response will be respected. The default is true.

Parameters
boolean$followtrue to follow any Location header present in the response, false to return the request directly
Return
this

public function getFollowLocation()

Get whether Location headers in the response will be respected.

Return
boolean

public static function setGlobalCABundleFromPath($path)

Set the fallback CA certificate if one is not specified for the session, given a path.

Parameters
string$pathThe path to a valid SSL certificate
Return
void

public static function setGlobalCABundleFromString($certificate)

Set the fallback CA certificate if one is not specified for the session, given a string.

Parameters
string$certificateThe certificate
Return
void

public static function getGlobalCABundle()

Get the fallback global CA certificate

Return
string

public static function loadContent($uri, $timeout)

Load contents of remote URI. Behaves pretty much like @file_get_contents($uri) but doesn't require allow_url_fopen.

Parameters
string$uri
float$timeout
Return
string|false

public function setDownloadPath($download_path)

This method is not documented.
Parameters
$download_path
Return
wild

public function setProgressSink($progress_sink)

This method is not documented.
Parameters
PhutilProgressSink$progress_sink
Return
wild

public function getProgressSink()

This method is not documented.
Return
wild

public function addCURLOption($option_key, $option_value)

See T13533. This supports an install-specific Kerberos workflow.

Parameters
$option_key
$option_value
Return
wild

public function attachFileData($key, $data, $name, $mime_type)

Attach a file to the request.

Parameters
string$keyHTTP parameter name.
string$dataFile content.
string$nameFile name.
string$mime_typeFile mime type.
Return
this

public function didReceiveDataCallback($handle, $data)

Callback invoked by cURL as it reads HTTP data from the response. We save the data to a buffer.

Parameters
$handle
$data
Return
wild

public function read()

Read data from the response buffer.

NOTE: Like ExecFuture, this method advances a read cursor but does not discard the data. The data will still be buffered, and it will all be returned when the future resolves. To discard the data after reading it, call discardBuffers().
Return
stringResponse data, if available.

public function discardBuffers()

Discard any buffered data. Normally, you call this after reading the data with read().

Return
this

private function formatRequestDataForCURL()

Produces a value safe to pass to CURLOPT_POSTFIELDS.

Return
wildSome value, suitable for use in `CURLOPT_POSTFIELDS`.

private function checkForDangerousCURLMagic($string, $is_query_string)

Detect strings which will cause cURL to do horrible, insecure things.

Parameters
string$stringPossibly dangerous string.
bool$is_query_stringTrue if this string is being used as part of a query string.
Return
void

private function canSetCAInfo()

Determine whether CURLOPT_CAINFO is usable on this system.

Return
wild

public function write($raw_body)

Write a raw HTTP body into the request.

You must write the entire body before starting the request.

Parameters
string$raw_bodyRaw body.
Return
this

public function willWriteBody($handle, $infile, $len)

Callback to pass data to cURL.

Parameters
$handle
$infile
$len
Return
wild

private function shouldReuseHandles()

This method is not documented.
Return
wild

private function isDownload()

This method is not documented.
Return
wild

private function canAcceptGzip()

This method is not documented.
Return
wild