http
The http
module provides a rich library to help in building HTTP clients and servers. The module also provides a few generic abstractions for simple HTTP operations such as a GET request.
Examples
The example below shows making a GET request to fetch a webpage.
import http
echo http.get('http://example.com')
# <class HttpResponse instance at 0x600002adacd0>
There is a post()
and put()
alternative to the get()
method called above and they are documented below.
For a more controlled HTTP request, you should use the HttpClient class. Below is an example of such implementation that sets the timeout for receiving response back from the server to 30 seconds.
import http
var client = http.HttpClient()
client.receive_timeout = 30000
var res = client.send_request('http://example/endpoint?query=1', 'GET')
echo res.body
Creating a server with the http
module is also a breeze. The example below shows an implementation of an HTTP API server listening on port 3000 and simple returns the JSON of the request object itself.
import http
import json
var server = http.server(3000)
server.on_receive(@(request, response) {
echo 'Request from ${request.ip} to ${request.path}.'
response.headers['Content-Type'] = 'application/json'
response.write(json.encode(request))
})
echo 'Listening on Port 3000...'
server.listen()
The http
module does not make any assumption as to the type of data to be sent in request bodies and for this reason, it should not be expected to automatically convert dictionaries into JSON objects or create multipart/form-data request for you. Rather, it gives the tools required to craft any request body of your choice.
Properties
- http.CONTINUE
- 100 continue
- http.SWITCHING_PROTOCOLS
- 101 switching protocols
- http.PROCESSING
- 102 processing
- http.OK
- 200 ok
- http.CREATED
- 201 created
- http.ACCEPTED
- 202 accepted
- http.NON_AUTHORITATIVE_INFORMATION
- 203 non authoritative information
- http.NO_CONTENT
- 204 no content
- http.RESET_CONTENT
- 205 reset content
- http.PARTIAL_CONTENT
- 206 partial content
- http.MULTI_STATUS
- 207 multi status
- http.ALREADY_REPORTED
- 208 already reported
- http.IM_USED
- 226 im used
- http.MULTIPLE_CHOICES
- 300 multiple choices
- http.MOVED_PERMANENTLY
- 301 moved permanently
- http.FOUND
- 302 found
- http.SEE_OTHER
- 303 see other
- http.NOT_MODIFIED
- 304 not modified
- http.USE_PROXY
- 305 use proxy
- http.TEMPORARY_REDIRECT
- 307 temporary redirect
- http.PERMANENT_REDIRECT
- 308 permanent redirect
- http.BAD_REQUEST
- 400 bad request
- http.UNAUTHORIZED
- 401 unauthorized
- http.PAYMENT_REQUIRED
- 402 payment required
- http.FORBIDDEN
- 403 forbidden
- http.NOT_FOUND
- 404 not found
- http.METHOD_NOT_ALLOWED
- 405 method not allowed
- http.NOT_ACCEPTABLE
- 406 not acceptable
- http.PROXY_AUTHENTICATION_REQUIRED
- 407 proxy authentication required
- http.REQUEST_TIMEOUT
- 408 request timeout
- http.CONFLICT
- 409 conflict
- http.GONE
- 410 gone
- http.LENGTH_REQUIRED
- 411 length required
- http.PRECONDITION_FAILED
- 412 precondition failed
- http.PAYLOAD_TOO_LARGE
- 413 payload too large
- http.REQUEST_URI_TOO_LONG
- 414 request uri too long
- http.UNSUPPORTED_MEDIA_TYPE
- 415 unsupported media type
- http.REQUESTED_RANGE_NOT_SATISFIABLE
- 416 requested range not satisfiable
- http.EXPECTATION_FAILED
- 417 expectation failed
- http.TEAPOT
- 418 teapot
- http.MISDIRECTED_REQUEST
- 421 misdirected request
- http.UNPROCESSABLE_ENTITY
- 422 unprocessable entity
- http.LOCKED
- 423 locked
- http.FAILED_DEPENDENCY
- 424 failed dependency
- http.UPGRADE_REQUIRED
- 426 upgrade required
- http.PRECONDITION_REQUIRED
- 428 precondition required
- http.TOO_MANY_REQUESTS
- 429 too many requests
- http.REQUEST_HEADER_FIELDS_TOO_LARGE
- 431 request header fields too large
- http.CONNECTION_CLOSED_WITHOUT_RESPONSE
- 444 connection closed without response
- http.UNAVAILABLE_FOR_LEGAL_REASONS
- 451 unavailable for legal reasons
- http.CLIENT_CLOSED_REQUEST
- 499 client closed request
- http.INTERNAL_SERVER_ERROR
- 500 internal server error
- http.NOT_IMPLEMENTED
- 501 not implemented
- http.BAD_GATEWAY
- 502 bad gateway
- http.SERVICE_UNAVAILABLE
- 503 service unavailable
- http.GATEWAY_TIMEOUT
- 504 gateway timeout
- http.HTTP_VERSION_NOT_SUPPORTED
- 505 http version not supported
- http.VARIANT_ALSO_NEGOTIATES
- 506 variant also negotiates
- http.INSUFFICIENT_STORAGE
- 507 insufficient storage
- http.LOOP_DETECTED
- 508 loop detected
- http.NOT_EXTENDED
- 510 not extended
- http.NETWORK_AUTHENTICATION_REQUIRED
- 511 network authentication required
- http.NETWORK_CONNECT_TIMEOUT_ERROR
- 599 network connect timeout error
- http.map
- A map of status code to their string representation.
Functions
- http.set_headers(headers: dict)
- Sets the request headers for the current module instance.
This function returns HttpClient in order to allow for idiomatic chaining such as:
import http var client = http.set_headers({ 'Authorization': 'Bearer SomeAPIBearerToken', 'Host': 'example.com', }) echo client.get('/current-user').body.to_string()
returns HttpClientthrows Exception
- http.get(url: string)
- sends an Http GET request and returns an HttpResponse or throws one of SocketException or Exception if it fails. returns HttpResponsethrows Exception, SocketExcepion, HttpException
- http.post(url: string, [data: string | bytes])
- sends an Http POST request and returns an HttpResponse. returns HttpResponsethrows Exception, SocketExcepion, HttpException
- http.put(url: string, [data: string | bytes])
- sends an Http PUT request and returns an HttpResponse. returns HttpResponsethrows Exception, SocketExcepion, HttpException
- http.delete(url: string)
- sends an Http DELETE request and returns an HttpResponse. returns HttpResponsethrows Exception, SocketExcepion, HttpException
- http.server(port: int, address: string)
- Creates an new HttpServer instance. returns HttpServerthrows Exception, SocketExcepion, HttpException
Classes
class HttpRequest
Http request handler and object. @serializable @printable
class HttpRequest properties
- HttpRequest.request_uri
- The original request URL as sent in the raw request. type string
- HttpRequest.path
- The requested path or file. E.g. if the Request URI is
/users?sort=desc
, then the path is/users
.type string - HttpRequest.method
- The HTTP method of the request: GET, POST, PUT, etc. type stringdefault GET
- HttpRequest.host
- The hostname derived from the
Host
header or the first instance ofX-Forwarded-Host
if set.type string - HttpRequest.ip
- The IP address of the remote client that initiated the request. type string
- HttpRequest.ipv6
- The IPv6 address of the remote client that initiated the request. type string
- HttpRequest.headers
- A dictionary containing the headers sent with the request. type dictionary
- HttpRequest.queries
- A dictionary containing the entries of the URI query string. type dictionary
- A dictionary containing the cookies sent with the request. type dictionary
- HttpRequest.body
- A dictionary containing all data submitted in the request body. type dictionary
- HttpRequest.files
- A dictionary containing the data of all files uploaded in the request. type dictionary
- HttpRequest.http_version
- The HTTP version used for the request. type string
- HttpRequest.auth_method
- The HTTP authentication method to use when the uri contains a credential. type Authdefault Auth.ANY
class HttpRequest methods
- parse(raw_data: string [, client: Socket | TLSSocket])
- Parses a raw HTTP request string into a correct HttpRequest return boolean
- send(uri: Url, method: string [, data: string | bytes [, options: dict]])
- default follow_redirect: true
class HttpException < Exception
HTTP related Exceptions @printable
class HttpServer
HTTP server @printable
class HttpServer properties
- HttpServer.host
- The host address to which this server will be bound default socket.IP_LOCAL (127.0.0.1)
- HttpServer.port
- The port to which this server will be bound to on the host.
- HttpServer.socket
- The working Socket instance for the HttpServer.
- HttpServer.resuse_address
- A boolean value indicating whether to reuse socket addresses or not. default true
- HttpServer.read_timeout
- The timeout in milliseconds after which an attempt to read clients request data will be terminated. default 2000 (2 seconds)
- HttpServer.write_timeout
- The timeout in milliseconds after which an attempt to write response data to clients will be terminated.
If we cannot send response to a client after the stipulated time, it will be assumed such clients have disconnected and existing connections for that client will be closed and their respective sockets will be discarded.
default 2000 (2 seconds)
class HttpServer methods
- HttpServer(port: int [, host: string])
- constructor
- close()
- stops the server
- on_connect(fn: function)
- Adds a function to be called when a new client connects.
- Function fn MUST accept at one parameter which will be passed the client Socket object.
- multiple
on_connect()
may be set on a single instance.
- on_disconnect(fn: function)
- Adds a function to be called when a new client disconnects.
- Function fn MUST accept at one parameter which will be passed the client information.
- multiple
on_disconnect()
may be set on a single instance.
- on_receive(fn: function)
- Adds a function to be called when the server receives a message from a client.
Function fn MUST accept TWO parameters. First parameter will accept the HttpRequest object and the second will accept the HttpResponse object.
- multiple
on_receive()
may be set on a single instance.
- multiple
- on_reply(fn: function)
- Adds a function to be called when the server sends a reply to a client.
Function fn MUST accept one parameter which will be passed the HttpResponse object.
- multiple
on_sent()
may be set on a single instance.
- multiple
- on_error(fn: function)
- Adds a function to be called when the server encounters an error with a client.
Function fn MUST accept two parameters. The first argument will be passed the
Exception
object and the second will be passed the clientSocket
object.- multiple
on_error()
may be set on a single instance.
- multiple
- listen()
- Binds to the instance port and host and starts listening for incoming connection from HTTP clients.
class HttpClient
Handles http requests. @note This client do not currently support the compress, deflate and gzip transfer encoding.
class HttpClient properties
- HttpClient.user_agent
- The user agent of the client used to make the request default Blade HTTP Client/1.0
- HttpClient.follow_redirect
- Indicates if we receive a redirect from a server, this flag tells us whether we should follow it or not. default true
- HttpClient.skip_hostname_verification
- Indicates if the site you’re connecting to uses a different host name that what they have mentioned in their server certificate’s commonName (or subjectAltName) fields, connection will fail. You can skip this check by setting to true, but this will make the connection less secure. default false
- HttpClient.skip_peer_verification
- Indicates if you want to connect to a site who isn’t using a certificate that is signed by one of the certs in the CA bundle you have, you can skip the verification of the server’s certificate. This makes the connection A LOT LESS SECURE. default false
- HttpClient.referer
- the site that refers us to the current site default nil
- HttpClient.ca_cert
- If you have a CA cert for the server stored someplace else than in the default bundle
- HttpClient.connect_timeout
- The connect timeout duration in milliseconds default 60s
- HttpClient.receive_timeout
- The receive timeout duration in milliseconds default 300s
- HttpClient.headers
- A dictionary of headers sent along with the request
- HttpClient.no_expect
- Indicates whether to remove the expect header or not only applies to requests with files in the body default false
class HttpClient methods
- send_request(url: string, [method: string = ‘GET’, data: string])
- Sends an Http request and returns a HttpResponse. default method: GETreturn HttpResponsethrows SocketException, Exception
- get(url: string)
- sends an Http GET request and returns an HttpResponse. returns HttpResponsethrows Exception, SocketExcepion, HttpException
- post(url: string, [data: string | bytes])
- sends an Http POST request and returns an HttpResponse. returns HttpResponsethrows Exception, SocketExcepion, HttpException
- put(url: string, [data: string | bytes])
- sends an Http PUT request and returns an HttpResponse. returns HttpResponsethrows Exception, SocketExcepion, HttpException
- delete(url: string)
- sends an Http DELETE request and returns an HttpResponse. returns HttpResponsethrows Exception, SocketExcepion, HttpException
class HttpResponse
Represents the response to an Http request @serializable @printable
class HttpResponse properties
- HttpResponse.version
- The HTTP version of the response type string
- HttpResponse.status
- The HTTP response status code type number
- HttpResponse.headers
- The HTTP response headers type dictionary
- HttpResponse.time_taken
- Total time taken for the HTTP request that generated this HttpResponse to complete type number
- HttpResponse.redirects
- The number of times the HTTP request that generated this HttpResponse was redirected. type number
- HttpResponse.responder
- The final URL that provided the HttpResponse type string
- This might differ from the original request URI.
- HttpResponse.body
- The content of the HTTP response as bytes type bytes
- The cookies to be sent back to the client type list
class HttpResponse methods
- HttpResponse(body: string, status: int, headers: dict, cookies: list, version: string, time_taken: number, redirects: int, responder: string)
- constructor
- write(data: string | bytes)
- Writes data to the response response.
This method should be prefered over writing directly to the body property to prevent unexpected behaviors.
- set_cookie(key: string, value: string [, domain: string [, path: string [, expires: string [, secure: bool [, extras]]]]])
- Sets a cookie to be send back to a client with the given key and value. When other parameters are given, they are used to construct a correct Set-Cookie header based on their named properties. throw HttpException
- redirect(location: string [, status: string])
- Redirects the client to a new location. This function simultaneously sets the
Location
header and returns a 30x status code. If thestatus
parameter is not given, the function defaults to302
.throw HttpException- when supplying a status, it must be a 30x