mirror of
https://github.com/nim-lang/Nim.git
synced 2026-04-19 05:50:30 +00:00
Improves httpclient documentation.
This commit is contained in:
Dominik Picheta
@@ -8,76 +8,99 @@
|
||||
#
|
||||
|
||||
## This module implements a simple HTTP client that can be used to retrieve
|
||||
## webpages/other data.
|
||||
##
|
||||
##
|
||||
## **Note**: This module is not ideal, connection is not kept alive so sites with
|
||||
## many redirects are expensive. As such in the future this module may change,
|
||||
## and the current procedures will be deprecated.
|
||||
## webpages and other data.
|
||||
##
|
||||
## Retrieving a website
|
||||
## ====================
|
||||
##
|
||||
## This example uses HTTP GET to retrieve
|
||||
## ``http://google.com``
|
||||
## ``http://google.com``:
|
||||
##
|
||||
## .. code-block:: Nim
|
||||
## var client = newHttpClient()
|
||||
## echo(getContent("http://google.com"))
|
||||
##
|
||||
## The same action can also be performed asynchronously, simply use the
|
||||
## ``AsyncHttpClient``:
|
||||
##
|
||||
## .. code-block:: Nim
|
||||
## var client = newAsyncHttpClient()
|
||||
## echo(await getContent("http://google.com"))
|
||||
##
|
||||
## The functionality implemented by ``HttpClient`` and ``AsyncHttpClient``
|
||||
## is the same, so you can use whichever one suits you best in the examples
|
||||
## shown here.
|
||||
##
|
||||
## **Note:** You will need to run asynchronous examples in an async proc
|
||||
## otherwise you will get an ``Undeclared identifier: 'await'`` error.
|
||||
##
|
||||
## Using HTTP POST
|
||||
## ===============
|
||||
##
|
||||
## This example demonstrates the usage of the W3 HTML Validator, it
|
||||
## uses ``multipart/form-data`` as the ``Content-Type`` to send the HTML to
|
||||
## the server.
|
||||
## uses ``multipart/form-data`` as the ``Content-Type`` to send the HTML to be
|
||||
## validated to the server.
|
||||
##
|
||||
## .. code-block:: Nim
|
||||
## var client = newHttpClient()
|
||||
## var data = newMultipartData()
|
||||
## data["output"] = "soap12"
|
||||
## data["uploaded_file"] = ("test.html", "text/html",
|
||||
## "<html><head></head><body><p>test</p></body></html>")
|
||||
##
|
||||
## echo postContent("http://validator.w3.org/check", multipart=data)
|
||||
## echo client.postContent("http://validator.w3.org/check", multipart=data)
|
||||
##
|
||||
## Asynchronous HTTP requests
|
||||
## ==========================
|
||||
## Progress reporting
|
||||
## ==================
|
||||
##
|
||||
## You simply have to create a new instance of the ``AsyncHttpClient`` object.
|
||||
## You may then use ``await`` on the functions defined for that object.
|
||||
## Keep in mind that the following code needs to be inside an asynchronous
|
||||
## procedure.
|
||||
##
|
||||
## .. code-block::nim
|
||||
## You may specify a callback procedure to be called during an HTTP request.
|
||||
## This callback will be executed every second with information about the
|
||||
## progress of the HTTP request.
|
||||
##
|
||||
## .. code-block:: Nim
|
||||
## var client = newAsyncHttpClient()
|
||||
## var resp = await client.request("http://google.com")
|
||||
## proc onProgressChanged(total, progress, speed: BiggestInt) {.async.} =
|
||||
## echo("Downloaded ", progress, " of ", total)
|
||||
## echo("Current rate: ", speed div 1000, "kb/s")
|
||||
## client.onProgressChanged = onProgressChanged
|
||||
## discard await client.getContent("http://speedtest-ams2.digitalocean.com/100mb.test")
|
||||
##
|
||||
## If you would like to remove the callback simply set it to ``nil``.
|
||||
##
|
||||
## .. code-block:: Nim
|
||||
## client.onProgressChanged = nil
|
||||
##
|
||||
## SSL/TLS support
|
||||
## ===============
|
||||
## This requires the OpenSSL library, fortunately it's widely used and installed
|
||||
## on many operating systems. httpclient will use SSL automatically if you give
|
||||
## any of the functions a url with the ``https`` schema, for example:
|
||||
## ``https://github.com/``, you also have to compile with ``ssl`` defined like so:
|
||||
## ``https://github.com/``.
|
||||
##
|
||||
## You will also have to compile with ``ssl`` defined like so:
|
||||
## ``nim c -d:ssl ...``.
|
||||
##
|
||||
## Timeouts
|
||||
## ========
|
||||
## Currently all functions support an optional timeout, by default the timeout is set to
|
||||
## `-1` which means that the function will never time out. The timeout is
|
||||
##
|
||||
## Currently only the synchronous functions support a timeout.
|
||||
## The timeout is
|
||||
## measured in milliseconds, once it is set any call on a socket which may
|
||||
## block will be susceptible to this timeout, however please remember that the
|
||||
## block will be susceptible to this timeout.
|
||||
##
|
||||
## It may be surprising but the
|
||||
## function as a whole can take longer than the specified timeout, only
|
||||
## individual internal calls on the socket are affected. In practice this means
|
||||
## that as long as the server is sending data an exception will not be raised,
|
||||
## if however data does not reach client within the specified timeout an ETimeout
|
||||
## exception will then be raised.
|
||||
## if however data does not reach the client within the specified timeout a
|
||||
## ``TimeoutError`` exception will be raised.
|
||||
##
|
||||
## Proxy
|
||||
## =====
|
||||
##
|
||||
## A proxy can be specified as a param to any of these procedures, the ``newProxy``
|
||||
## constructor should be used for this purpose. However,
|
||||
## currently only basic authentication is supported.
|
||||
## A proxy can be specified as a param to any of the procedures defined in
|
||||
## this module. To do this, use the ``newProxy`` constructor. Unfortunately,
|
||||
## only basic authentication is supported at the moment.
|
||||
|
||||
import net, strutils, uri, parseutils, strtabs, base64, os, mimetypes,
|
||||
math, random, httpcore, times
|
||||
@@ -958,8 +981,6 @@ proc request*(client: HttpClient | AsyncHttpClient, url: string,
|
||||
## Connection will kept alive. Further requests on the same ``client`` to
|
||||
## the same hostname will not require a new connection to be made. The
|
||||
## connection can be closed by using the ``close`` procedure.
|
||||
##
|
||||
## The returned future will complete once the request is completed.
|
||||
let connectionUrl =
|
||||
if client.proxy.isNil: parseUri(url) else: client.proxy.url
|
||||
let requestUrl = parseUri(url)
|
||||
@@ -1012,8 +1033,6 @@ proc request*(client: HttpClient | AsyncHttpClient, url: string,
|
||||
##
|
||||
## When a request is made to a different hostname, the current connection will
|
||||
## be closed.
|
||||
##
|
||||
## The returned future will complete once the request is completed.
|
||||
result = await request(client, url, $httpMethod, body)
|
||||
|
||||
proc get*(client: HttpClient | AsyncHttpClient,
|
||||
|
||||
Reference in New Issue
Block a user