Imports

asyncloop, asyncsync, config, asyncstream, tlsstream, chunkstream, boundstream, httptable, httpcommon, httpagent, httpbodyrw, multipart

Types

HttpAddress = object id*: string scheme*: HttpClientScheme hostname*: string port*: uint16 path*: string query*: string anchor*: string username*: string password*: string addresses*: seq[TransportAddress] ## If addresses are set, name resolution is not performed and the client ## will instead attempt to connect to the given addresses (in order): Source Edit
HttpAddressResult = Result[HttpAddress, HttpAddressErrorType]: Source Edit
HttpClientBodyFlag {.pure.} = enum NoBody, Sized, ## `Content-Length` present Chunked, ## `Transfer-Encoding: chunked` present Custom ## None of the above: Source Edit
HttpClientConnection = object of RootObj id*: uint64 case kind*: HttpClientScheme of HttpClientScheme.NonSecure: nil of HttpClientScheme.Secure: treader*: AsyncStreamReader twriter*: AsyncStreamWriter tls*: TLSAsyncStream transp*: StreamTransport reader*: AsyncStreamReader writer*: AsyncStreamWriter state*: HttpClientConnectionState error*: ref HttpError remoteHostname*: string flags*: set[HttpClientConnectionFlag] timestamp*: Moment duration*: Duration: Source Edit
HttpClientConnectionFlag {.pure.} = enum Request, ## Connection has pending request Response, ## Connection has pending response KeepAlive, ## Connection should be kept alive NoBody ## Connection response do not have body: Source Edit
HttpClientConnectionRef = ref HttpClientConnection: Source Edit
HttpClientConnectionState {.pure.} = enum Closed, ## Connection has been closed Closing, ## Connection is closing Connecting, ## Connecting to remote server Ready, ## Connected to remote server Acquired, ## Connection is acquired for use RequestHeadersSending, ## Sending request headers RequestHeadersSent, ## Request headers has been sent RequestBodySending, ## Sending request body RequestBodySent, ## Request body has been sent ResponseHeadersReceiving, ## Receiving response headers ResponseHeadersReceived, ## Response headers has been received ResponseBodyReceiving, ## Receiving response body ResponseBodyReceived, ## Response body has been received Error ## Error happens: Source Edit
HttpClientFlag {.pure.} = enum NoVerifyHost, ## Skip remote server certificate verification NoVerifyServerName, ## Skip remote server name CN verification NoInet4Resolution, ## Do not resolve server hostname to IPv4 addresses NoInet6Resolution, ## Do not resolve server hostname to IPv6 addresses NoAutomaticRedirect, ## Do not handle HTTP redirection automatically NewConnectionAlways, ## Disable HTTP Persistent connections Http11Pipeline {....deprecated.} ## (deprecated, pipelining is not implemented): Source Edit
HttpClientFlags = set[HttpClientFlag]: Source Edit
HttpClientRequest = object state: HttpReqRespState meth*: HttpMethod address*: HttpAddress version*: HttpVersion headers*: HttpTable bodyFlag: HttpClientBodyFlag flags: set[HttpClientRequestFlag] connection*: HttpClientConnectionRef session*: HttpSessionRef error*: ref HttpError buffer*: seq[byte] writer*: HttpBodyWriter redirectCount: int timestamp*: Moment duration*: Duration headersBuffer: seq[byte]: Source Edit
HttpClientRequestFlag {.pure.} = enum DedicatedConnection, ## Create new HTTP connection for request CloseConnection ## Send `Connection: close` in request: Source Edit
HttpClientRequestRef = ref HttpClientRequest: Source Edit
HttpClientResponse = object state: HttpReqRespState requestMethod*: HttpMethod address*: HttpAddress status*: int reason*: string version*: HttpVersion headers*: HttpTable connection*: HttpClientConnectionRef session*: HttpSessionRef reader*: HttpBodyReader error*: ref HttpError bodyFlag*: HttpClientBodyFlag contentEncoding*: set[ContentEncodingFlags] transferEncoding*: set[TransferEncodingFlags] contentLength*: uint64 contentType*: Opt[ContentTypeData] timestamp*: Moment duration*: Duration: Source Edit
HttpClientResponseRef = ref HttpClientResponse: Source Edit
HttpClientScheme {.pure.} = enum NonSecure, ## Non-secure connection Secure ## Secure TLS connection: Source Edit
HttpConnectionProvider = proc (request: HttpClientRequestRef): Future[ HttpClientConnectionRef] {.async: (...raises: [CancelledError, HttpConnectionError]).}: Source Edit
HttpHeaderTuple = tuple[key: string, value: string]: Source Edit
HttpReqRespState {.pure.} = enum Closed, ## Request/response has been closed Closing, ## Request/response is closing Ready, ## Request/response is ready Open, ## Request/response started Finished, ## Request/response has been sent/received Error ## Request/response in error state: Source Edit
HttpResponseTuple = tuple[status: int, data: seq[byte]]: Source Edit
HttpSessionRef = ref object connections*: Table[string, seq[HttpClientConnectionRef]] counter*: uint64 maxRedirections*: int connectTimeout*: Duration headersTimeout*: Duration idleTimeout: Duration idlePeriod: Duration watcherFut: Future[void].Raising([]) connectionBufferSize*: int maxConnections*: int connectionsCount*: int socketFlags*: set[SocketFlags] flags*: HttpClientFlags dualstack*: DualStackType provider: HttpConnectionProvider: Source Edit
ServerSentEvent = object name*: string data*: string: Source Edit

Consts

HttpClientConnectionTrackerName = "httpclient.connection"

HttpClient connection leaks tracker name Source Edit

HttpClientRequestTrackerName = "httpclient.request"

HttpClient request leaks tracker name Source Edit

HttpClientResponseTrackerName = "httpclient.response"

HttpClient response leaks tracker name Source Edit

HttpConnectionCheckPeriod = (value: 10000000000)

Period of time between idle connections checks in HttpSession's connection pool (10 sec) Source Edit

HttpConnectionIdleTimeout = (value: 60000000000)

Time after which idle connections are removed from the HttpSession's connections pool (60 sec)

TODO Persistent connections currently must be explicitly enabled due to: the lack of idle connection monitoring (via MSG_PEEK, to discover EOF)

Source Edit

HttpConnectTimeout = (value: 12000000000)

Timeout for connecting to host (12 sec) Source Edit

HttpHeadersTimeout = (value: 120000000000)

Timeout for receiving response headers (120 sec) Source Edit

HttpMaxHeadersSize = 8192

Maximum size of HTTP headers in octets Source Edit

HttpMaxRedirections = 10

Maximum number of Location redirections. Source Edit

Procs

proc closeWait(request: HttpClientRequestRef): InternalRaisesFuture[void, void] {.
    stackTrace: false, ...raises: [], gcsafe, raises: [], raises: [],
    tags: [RootEffect].}

Source Edit

proc closeWait(response: HttpClientResponseRef): InternalRaisesFuture[void, void] {.
    stackTrace: false, ...raises: [], gcsafe, raises: [], raises: [],
    tags: [RootEffect].}

Source Edit

proc closeWait(session: HttpSessionRef): InternalRaisesFuture[void, void] {.
    stackTrace: false, ...raises: [], gcsafe, raises: [], raises: [],
    tags: [RootEffect].}

Closes HTTP session object.

This closes all the connections opened to remote servers.

Source Edit

proc consumeBody(response: HttpClientResponseRef): InternalRaisesFuture[int,
    (CancelledError, HttpError)] {.stackTrace: false, ...raises: [], gcsafe,
                                   raises: [], raises: [], tags: [RootEffect].}

Consume/discard response and return number of bytes consumed.

Note: This procedure performs automatic finishing for response.

Source Edit

proc directProvider(): HttpConnectionProvider {....raises: [], tags: [].}

Return a connection provider that supplies connections directly to the requested address. Source Edit

proc fetch(request: HttpClientRequestRef): InternalRaisesFuture[
    HttpResponseTuple, (CancelledError, HttpError)] {.stackTrace: false,
    ...raises: [], gcsafe, raises: [], raises: [], tags: [RootEffect].}

Source Edit

proc fetch(session: HttpSessionRef; url: Uri): InternalRaisesFuture[
    HttpResponseTuple, (CancelledError, HttpError)] {.stackTrace: false,
    ...raises: [], gcsafe, raises: [], raises: [], tags: [RootEffect].}

Fetch resource pointed by url using HTTP GET method and session parameters.

This procedure supports HTTP redirections.

Source Edit

proc finish(request: HttpClientRequestRef): InternalRaisesFuture[
    HttpClientResponseRef, (CancelledError, HttpError)] {.stackTrace: false,
    ...raises: [], gcsafe, raises: [], raises: [], tags: [RootEffect].}

Finish sending request and receive response. Source Edit

proc finish(response: HttpClientResponseRef): InternalRaisesFuture[void,
    (HttpUseClosedError,)] {.stackTrace: false, ...raises: [], gcsafe, raises: [],
                             raises: [], tags: [RootEffect].}

Finish receiving response.

Because finish() returns nothing, this operation become NOP for response which is not in Open state.

Source Edit

proc getAddress(address: TransportAddress;
                ctype: HttpClientScheme = HttpClientScheme.NonSecure;
                queryString: string = "/"): HttpAddress {....raises: [], tags: [].}

Create new HTTP address using Transport address address, connection type ctype and query string queryString. Source Edit

proc getAddress(session: HttpSessionRef; url: string): HttpResult[HttpAddress] {.
    ...deprecated: "use getHttpAddress", raises: [], tags: [].}

Deprecated: use getHttpAddress

Create new HTTP address using URL string url and . Source Edit

proc getAddress(session: HttpSessionRef; url: Uri): HttpResult[HttpAddress] {.
    ...deprecated: "use getHttpAddress", raises: [], tags: [].}

Deprecated: use getHttpAddress

Source Edit

proc getBodyBytes(response: HttpClientResponseRef): InternalRaisesFuture[
    seq[byte], (CancelledError, HttpError)] {.stackTrace: false, ...raises: [],
    gcsafe, raises: [], raises: [], tags: [RootEffect].}

Read all bytes from response response.

Note: This procedure performs automatic finishing for response.

Source Edit

proc getBodyBytes(response: HttpClientResponseRef; nbytes: int): InternalRaisesFuture[
    seq[byte], (CancelledError, HttpError)] {.stackTrace: false, ...raises: [],
    gcsafe, raises: [], raises: [], tags: [RootEffect].}

Read all bytes (nbytes <= 0) or exactly nbytes bytes from response response.

Note: This procedure performs automatic finishing for response.

Source Edit

proc getBodyReader(response: HttpClientResponseRef): HttpBodyReader {.
    ...raises: [HttpUseClosedError], raises: [], tags: [RootEffect].}

Returns stream's reader instance which can be used to read response's body.

Streams which was obtained using this procedure must be closed to avoid leaks.

Source Edit

proc getHttpAddress(session: HttpSessionRef; url: string): HttpAddressResult {.
    ...deprecated: "No DNS resolution in getHttpAddress, no session needed",
    raises: [], tags: [].}

Deprecated: No DNS resolution in getHttpAddress, no session needed

Create new HTTP address using URL string url and . Source Edit

proc getHttpAddress(session: HttpSessionRef; url: Uri): HttpAddressResult {.
    ...deprecated: "No DNS resolution in getHttpAddress, no session needed",
    raises: [], tags: [].}

Deprecated: No DNS resolution in getHttpAddress, no session needed

Source Edit

proc getHttpAddress(uri: Uri; flags: HttpClientFlags): HttpAddressResult {.
    ...deprecated: "No DNS resolution in getHttpAddress, no flags needed",
    raises: [], tags: [].}

Deprecated: No DNS resolution in getHttpAddress, no flags needed

Source Edit

proc getHttpAddress(url: string): HttpAddressResult {....raises: [], tags: [].}

Source Edit

proc getHttpAddress(url: string; flags: HttpClientFlags): HttpAddressResult {.
    ...deprecated: "No DNS resolution in getHttpAddress, no flags needed",
    raises: [], tags: [].}

Deprecated: No DNS resolution in getHttpAddress, no flags needed

Source Edit

proc getHttpAddress(url: Uri): HttpAddressResult {....raises: [], tags: [].}

Source Edit

proc getNewLocation(resp: HttpClientResponseRef): HttpResult[HttpAddress] {.
    ...raises: [], tags: [].}

Returns new address according to response's Location header value. Source Edit

proc getServerSentEvents(response: HttpClientResponseRef; maxEventSize: int = -1): InternalRaisesFuture[
    seq[ServerSentEvent], (CancelledError, HttpError)] {.stackTrace: false,
    ...raises: [], gcsafe, raises: [], raises: [], tags: [RootEffect].}

Read number of server-sent events (SSE) from HTTP response response.

maxEventSize - maximum size of events chunk in one message, use -1 or 0 to set size to unlimited.

Server-sent events parsing is done according to: https://html.spec.whatwg.org/multipage/server-sent-events.html#parsing-an-event-stream

Note: Server-sent event comments are ignored and silently skipped.

Source Edit

proc getUri(address: HttpAddress): Uri {....raises: [], tags: [].}

Retrieve URI from address. Source Edit

proc httpConnectProvider(proxy: HttpAddress): HttpConnectionProvider {.
    ...raises: [], tags: [RootEffect].}

Return a provider that establishes HTTP CONNECT tunnel connections through the given proxy Source Edit

proc httpProxyProvider(proxy: HttpAddress): HttpConnectionProvider {....raises: [],
    tags: [].}

Return a connection provider that supplies connections via a forwarding HTTP proxy.

The connection to the proxy can be established via TLS enabling the use of secure proxies.

Source Edit

proc new(t: typedesc[HttpClientRequestRef]; session: HttpSessionRef;
         ha: HttpAddress; meth: HttpMethod = MethodGet;
         version: HttpVersion = HttpVersion11;
         flags: set[HttpClientRequestFlag] = {};
         maxResponseHeadersSize: int = HttpMaxHeadersSize;
         headers: openArray[HttpHeaderTuple] = []; body: openArray[byte] = []): HttpClientRequestRef {.
    ...raises: [].}

Source Edit

proc new(t: typedesc[HttpClientRequestRef]; session: HttpSessionRef;
         url: string; meth: HttpMethod = MethodGet;
         version: HttpVersion = HttpVersion11;
         flags: set[HttpClientRequestFlag] = {};
         maxResponseHeadersSize: int = HttpMaxHeadersSize;
         headers: openArray[HttpHeaderTuple] = []; body: openArray[byte] = []): HttpResult[
    HttpClientRequestRef] {....raises: [].}

Source Edit

proc new(t: typedesc[HttpSessionRef];
         flags: HttpClientFlags = {NewConnectionAlways};
         maxRedirections = HttpMaxRedirections;
         connectTimeout = HttpConnectTimeout;
         headersTimeout = HttpHeadersTimeout;
         connectionBufferSize = DefaultStreamBufferSize; maxConnections = -1;
         idleTimeout = HttpConnectionIdleTimeout;
         idlePeriod = HttpConnectionCheckPeriod;
         socketFlags: set[SocketFlags] = {}; dualstack = DualStackType.Auto;
         provider: HttpConnectionProvider = nil): HttpSessionRef {....raises: [].}

Create new HTTP session object.

maxRedirections - maximum number of HTTP 3xx redirections connectTimeout - timeout for ongoing HTTP connection headersTimeout - timeout for receiving HTTP response headers idleTimeout - timeout to consider HTTP connection as idle idlePeriod - period of time to check HTTP connections for inactivity

Source Edit

proc open(request: HttpClientRequestRef): InternalRaisesFuture[HttpBodyWriter,
    (CancelledError, HttpError)] {.stackTrace: false, ...raises: [], gcsafe,
                                   raises: [], raises: [], tags: [RootEffect].}

Start sending request's headers and return HttpBodyWriter, which can be used to send request's body. Source Edit

proc post(t: typedesc[HttpClientRequestRef]; session: HttpSessionRef;
          address: HttpAddress | string; version: HttpVersion = HttpVersion11;
          flags: set[HttpClientRequestFlag] = {};
          maxResponseHeadersSize: int = HttpMaxHeadersSize;
          headers: openArray[HttpHeaderTuple] = []; body: openArray[char] = []): auto {.
    ...raises: [].}

Source Edit

proc redirect(request: HttpClientRequestRef; ha: HttpAddress): HttpResult[
    HttpClientRequestRef] {....raises: [], tags: [].}

Create new request object using original request object request and new redirected address ha.

This procedure could return an error if number of redirects exceeded maximum allowed number of redirects in request's session.

Source Edit

proc redirect(request: HttpClientRequestRef; uri: Uri): HttpResult[
    HttpClientRequestRef] {....raises: [], tags: [].}

Create new request object using original request object request and redirected URL uri.

This procedure could return an error if number of redirects exceeded maximum allowed number of redirects in request's session or uri is incorrect or not supported.

Source Edit

proc redirect(session: HttpSessionRef; srcaddr: HttpAddress; uri: Uri): HttpResult[
    HttpAddress] {....raises: [], tags: [].}

Transform original address srcaddr using redirected url uri and session session parameters. Source Edit

proc redirect(srcuri, dsturi: Uri): Uri {....raises: [], tags: [].}

Transform original's URL srcuri to dsturi. Source Edit

proc send(request: HttpClientRequestRef): InternalRaisesFuture[
    HttpClientResponseRef, (CancelledError, HttpError)] {.stackTrace: false,
    ...raises: [], gcsafe, raises: [], raises: [], tags: [RootEffect].}

Source Edit

proc tunnel(response: HttpClientResponseRef): InternalRaisesFuture[AsyncStream,
    (CancelledError, HttpError)] {.stackTrace: false, ...raises: [], gcsafe,
                                   raises: [], raises: [], tags: [RootEffect].}

After a CONNECT request, extract the underlying connection tunnel from the session and return it to the caller.

The caller is responsible for closing both the returned stream and the response itself.

After a successful call to tunnel, closing response will not close the returned tunnel.

Source Edit

Templates

template get(t: typedesc[HttpClientRequestRef]; session: HttpSessionRef; address: HttpAddress | string; version: HttpVersion = HttpVersion11; flags: set[HttpClientRequestFlag] = {}; maxResponseHeadersSize: int = HttpMaxHeadersSize; headers: openArray[HttpHeaderTuple] = []): auto: Source Edit
template post(t: typedesc[HttpClientRequestRef]; session: HttpSessionRef; address: HttpAddress | string; version: HttpVersion = HttpVersion11; flags: set[HttpClientRequestFlag] = {}; maxResponseHeadersSize: int = HttpMaxHeadersSize; headers: openArray[HttpHeaderTuple] = []; body: openArray[byte] | seq[byte]): auto: Source Edit

Exports

chronos/apps/http/httpclient

Imports

Types

Consts

Procs

Templates

Exports