Import std.net.http.client

std.net.http.client

HttpClient, which sends HTTP and HTTPS requests and gives their responses, over libcurl, whose TLS is mbedTLS's: it follows redirects, decompresses what comes compressed, keeps cookies, and trusts the OS's roots unless it's given its own. A download goes to memory, or atomically to a file as it comes. Each request has an Async twin, which the I/O thread runs. Http's Static Methods send one request each, through a client of their own.

std/net/http/client.fb

Types

`HttpMethod` enum

Public Enum HttpMethod

The methods a request can have.

std/net/http/client.fb, line 61

GET enum member #

GET, which asks for what's at the URL.
HEAD enum member #

HEAD, which asks for a GET's headers alone.
POST enum member #

POST, which sends what the URL handles.
PUT enum member #

PUT, which puts what it sends at the URL.
PATCH enum member #

PATCH, which changes part of what's at the URL.
DELETE enum member #

DELETE, which removes what's at the URL.
OPTIONS enum member #

OPTIONS, which asks what the URL allows.

`Body` struct

Public Struct Body

What a request sends: its bytes, and what they are, as its Content-Type header says unless the request's headers say it themselves. Panics for a contentType a header's value can't be, as Headers.Add does.

std/net/http/client.fb, line 81

Public ReadOnly Field Bytes: UInt8[] field #

Its bytes.
Public ReadOnly Field ContentType: String? field #

Its Content-Type, or Null to send none.
@PanicsAtCaller Public New(bytes: UInt8[], contentType: String? = "application/octet-stream") constructor #

A Body of bytes, which are what contentType says.
@PanicsAtCaller Public Static Method Text(text: String, contentType: String = "text/plain; charset=utf-8"): Body static method #

text's UTF-8, as plain text unless contentType says another kind.
Public Static Method Json(json: String): Body static method #

JSON's text, as application/json.
Public Static Method Form(fields: Map<String, String>): Body static method #

A form's fields, in their order, as application/x-www-form-urlencoded: each name and value with each byte but the letters, digits, '-', '.', '_', and '~' as %XX, which servers read as they read a browser's '+' for a space, each pair as name=value, and '&' between them.

`HttpResponse` class

Public Class HttpResponse

What a server answered: its status, its headers, its body's bytes, the URL it came from, after the redirects followed, and the HTTP it came over, "HTTP/1.1" or "HTTP/2".

std/net/http/client.fb, line 119

Public ReadOnly Field Status: Int field #

Its status, like 200 or 404.
Public ReadOnly Field Headers: Headers field #

Its headers.
Public ReadOnly Field Bytes: UInt8[] field #

Its body's bytes.
Public ReadOnly Field Url: String field #

The URL it came from, after the redirects followed.
Public ReadOnly Field Version: String field #

The HTTP it came over: "HTTP/1.1" or "HTTP/2".
Public New(status: Int, headers: Headers, bytes: UInt8[], url: String, version: String = "HTTP/1.1") constructor #

A response of status, with headers and bytes, from url, over version.
Public Property Text: String property #

The body as text, its UTF-8, with U+FFFD for each byte that doesn't start well-formed UTF-8.
Public Property IsSuccess: Bool property #

Whether its Status says the request worked: from 200 to 299.
Public Method EnsureSuccess() Throws NetError method #

Throws a NetError of HTTP_STATUS unless IsSuccess.

`HttpClient` class

Public Class HttpClient

Sends requests and gives their responses. A client keeps the cookies its responses set, for the requests after, and the connections it made, which those reuse; its DefaultHeaders go with each request, before the request's own, which replace those of their names. It follows up to MaxRedirects redirects, as a browser does: a POST changes to a GET after a 301, 302, or 303, and any request but a HEAD after a 303, and a redirect to another origin takes no Authorization, Cookie, or Host of the request's own. It asks for gzip, deflate, and zstd, and decompresses what comes so. It speaks HTTP/2 to an HTTPS server that agrees to it, and HTTP/1.1 otherwise. It goes through Proxy, or else the proxy the environment names, as http_proxy, https_proxy, and no_proxy do. A failure throws: a NetError for the network's or the server's, or for a URL that isn't HTTP's or HTTPS's, and a TimeoutError for a request that took longer than its Timeout, or connecting that took longer than its ConnectTimeout.

std/net/http/client.fb, line 172

Public ReadOnly Field DefaultHeaders: Headers field #

The headers each request sends, before its own.
Public Field FollowRedirects: Bool field #

Whether a request follows redirects, or gives a redirect's response.
Public Field Decompress: Bool field #

Whether a request asks for its response compressed, which it decompresses.
Public Field Proxy: String? field #

The proxy each request goes through, like "http://proxy:3128", "" for none, or Null for the environment's.
Public New() constructor #

A new HttpClient, with no default headers, and 30 seconds to connect.
@PanicsAtCaller Public Property Timeout: Duration? property #

How long a request may take in all, after which it throws a TimeoutError, or Null for as long as it takes, as it is to start. Panics when it's set to a Duration that isn't above 0.
@PanicsAtCaller Public Property ConnectTimeout: Duration property #

How long a request's connecting, TLS's handshake too, may take, 30 seconds unless it's set, after which it throws a TimeoutError. Panics when it's set to a Duration that isn't above 0.
@PanicsAtCaller Public Property UserAgent: String property #

The User-Agent header a request sends unless its headers have one. Panics when it's set to what a header's value can't be, as Headers.Add does.
@PanicsAtCaller Public Property MaxRedirects: Int property #

The most redirects a request follows before it throws a NetError. Panics when it's set below 0.
Public Method TrustOnly(roots: Certificate[]) method #

Trusts only roots for HTTPS from then on, instead of the OS's roots, as for a server whose certificate a private authority signed.
Public Method TrustOsRoots() method #

Trusts the OS's roots again, from then on.
Public Method ClearCookies() method #

Forgets the cookies it keeps.
Public Method Get(url: String): HttpResponse Throws NetError, TimeoutError method #

Sends a GET to url, and gives the response.
Public Method Head(url: String): HttpResponse Throws NetError, TimeoutError method #

Sends a HEAD to url, and gives the response, without a body.
Public Method Post(url: String, body: Body): HttpResponse Throws NetError, TimeoutError method #

Sends a POST of body to url, and gives the response.
Public Method Put(url: String, body: Body): HttpResponse Throws NetError, TimeoutError method #

Sends a PUT of body to url, and gives the response.
Public Method Patch(url: String, body: Body): HttpResponse Throws NetError, TimeoutError method #

Sends a PATCH of body to url, and gives the response.
Public Method Delete(url: String): HttpResponse Throws NetError, TimeoutError method #

Sends a DELETE to url, and gives the response.
Public Method Send(method: HttpMethod, url: String, body: Body? = Null, headers: Headers? = Null): HttpResponse Throws NetError, TimeoutError method #

A request of method to url, with body, if it has one, and headers, after the client's.
Public Method Download(url: String, progress: Func(Int64, Int64)? = Null): UInt8[] Throws NetError, TimeoutError method #

The body of url's response, which progress, unless it's Null, is told of as it comes: how many bytes came, and how many the response said it has, or -1 when it didn't say, but nothing of a redirect's own body. Throws a NetError of HTTP_STATUS when the response's status isn't success.
Public Method Download(url: String, path: Path, progress: Func(Int64, Int64)? = Null) Throws NetError, TimeoutError, IOError method #

Writes url's body to the file at path as it comes, atomically, as File.WriteBytesAtomic does: to a new temporary file in its folder, which is renamed over the file, onto the disk, once all of it came, so the file holds either all of it or what it held before. progress is told of it as Download's is. Throws a NetError of HTTP_STATUS when the response's status isn't success, and an IOError when the file can't be written, which a folder that isn't there throws before anything's sent; each leaves the file as it was.
Public Async Method GetAsync(url: String): HttpResponse Throws NetError, TimeoutError method #

What Get does, without blocking its thread: a call gives its Task.
Public Async Method HeadAsync(url: String): HttpResponse Throws NetError, TimeoutError method #

What Head does, without blocking its thread: a call gives its Task.
Public Async Method PostAsync(url: String, body: Body): HttpResponse Throws NetError, TimeoutError method #

What Post does, without blocking its thread: a call gives its Task.
Public Async Method PutAsync(url: String, body: Body): HttpResponse Throws NetError, TimeoutError method #

What Put does, without blocking its thread: a call gives its Task.
Public Async Method PatchAsync(url: String, body: Body): HttpResponse Throws NetError, TimeoutError method #

What Patch does, without blocking its thread: a call gives its Task.
Public Async Method DeleteAsync(url: String): HttpResponse Throws NetError, TimeoutError method #

What Delete does, without blocking its thread: a call gives its Task.
Public Async Method SendAsync(method: HttpMethod, url: String, body: Body? = Null, headers: Headers? = Null): HttpResponse Throws NetError, TimeoutError method #

Send's Async twin, whose request the I/O thread runs while the main thread goes on.
Public Async Method DownloadAsync(url: String, progress: Func(Int64, Int64)? = Null): UInt8[] Throws NetError, TimeoutError method #

Download's Async twin, whose progress is told on the main thread.
Public Async Method DownloadAsync(url: String, path: Path, progress: Func(Int64, Int64)? = Null) Throws NetError, TimeoutError, IOError method #

The Async twin of Download to a file, whose progress is told on the main thread, and whose file the I/O thread writes and puts onto the disk.

`Http` struct

Public Struct Http

One request each, through a client of its own, with HttpClient's settings as they start.

std/net/http/client.fb, line 558

Public Static Method Get(url: String): HttpResponse Throws NetError, TimeoutError static method #

Sends a GET to url, through a client of its own, and gives the response.
Public Static Method GetText(url: String): String Throws NetError, TimeoutError static method #

The text of url's response. Throws a NetError of HTTP_STATUS when its status isn't success.
Public Static Method GetBytes(url: String): UInt8[] Throws NetError, TimeoutError static method #

The bytes of url's response. Throws a NetError of HTTP_STATUS when its status isn't success.
Public Static Method Head(url: String): HttpResponse Throws NetError, TimeoutError static method #

Sends a HEAD to url, through a client of its own, and gives the response.
Public Static Method Post(url: String, body: Body): HttpResponse Throws NetError, TimeoutError static method #

Sends a POST of body to url, through a client of its own, and gives the response.
Public Static Method Put(url: String, body: Body): HttpResponse Throws NetError, TimeoutError static method #

Sends a PUT of body to url, through a client of its own, and gives the response.
Public Static Method Patch(url: String, body: Body): HttpResponse Throws NetError, TimeoutError static method #

Sends a PATCH of body to url, through a client of its own, and gives the response.
Public Static Method Delete(url: String): HttpResponse Throws NetError, TimeoutError static method #

Sends a DELETE to url, through a client of its own, and gives the response.
Public Static Method Download(url: String, progress: Func(Int64, Int64)? = Null): UInt8[] Throws NetError, TimeoutError static method #

url's body, as HttpClient's Download gives it.
Public Static Method Download(url: String, path: Path, progress: Func(Int64, Int64)? = Null) Throws NetError, TimeoutError, IOError static method #

Writes url's body to the file at path, as HttpClient's Download does.
Public Static Async Method GetAsync(url: String): HttpResponse Throws NetError, TimeoutError static method #

What Get does, without blocking its thread: a call gives its Task.
Public Static Async Method GetTextAsync(url: String): String Throws NetError, TimeoutError static method #

What GetText does, without blocking its thread: a call gives its Task.
Public Static Async Method GetBytesAsync(url: String): UInt8[] Throws NetError, TimeoutError static method #

What GetBytes does, without blocking its thread: a call gives its Task.
Public Static Async Method PostAsync(url: String, body: Body): HttpResponse Throws NetError, TimeoutError static method #

What Post does, without blocking its thread: a call gives its Task.
Public Static Async Method DownloadAsync(url: String, progress: Func(Int64, Int64)? = Null): UInt8[] Throws NetError, TimeoutError static method #

What Download does, without blocking its thread: a call gives its Task.
Public Static Async Method DownloadAsync(url: String, path: Path, progress: Func(Int64, Int64)? = Null) Throws NetError, TimeoutError, IOError static method #

What Download does, without blocking its thread: a call gives its Task.

Report an issue with this page or with FutureBlitz on GitHub.

std.net.http.client

Types

HttpMethod enum

Body struct

HttpResponse class

HttpClient class

Http struct

`HttpMethod` enum

`Body` struct

`HttpResponse` class

`HttpClient` class

`Http` struct