Next | Previous

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 and supports basic routing.

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 # Optional
var res = client.send_request('http://example.com/endpoint?query=1', 'GET')
echo res.body.to_string()

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.handle('GET', '/', @(request, response) {
  response.json(request)
})
server.listen()

Not only is it super simple to create an HTTP server, it is also very easy to create a TLS/HTTPS server with few modifications.

The following code creates a TLS versionof the same server we created above.

import http
import json

var server = http.tls_server(3000)
if server.load_certs('/path/to/tlscert.crt', '/path/to/tlskey.key') {
  server.handle('GET', '/', @(request, response) {
    response.json(request)
  })
  server.listen()
}

To create a TLS server, we use the tls_server() alternative to the server() function and load our certificates before we start to listen for incoming connections. It's that simple.

The http module client does make some basic assumption as to the type of data to be sent in request bodies and for this reason, it will (unless asked not to) automatically convert dictionaries into JSON objects and create multipart/form-data request for you.

Natively, the http module will automatically encode and decode requests with the following content types:

  • multipart/form-data
  • application/x-www-form-urlencoded
  • application/json

In the abscence of any content-type in the request header or reponse header from a server as the case may be, the module defaults to the application/x-www-form-urlencoded content type.

That been said, it gives the tools required to craft any request body of your choice.

Properties

  • CONTINUE ⇢ readonly int:

    100 continue.

  • SWITCHING_PROTOCOLS ⇢ readonly int:

    101 switching protocols.

  • PROCESSING ⇢ readonly int:

    102 processing.

  • OK ⇢ readonly int:

    200 ok.

  • CREATED ⇢ readonly int:

    201 created.

  • ACCEPTED ⇢ readonly int:

    202 accepted.

  • NON_AUTHORITATIVE_INFORMATION ⇢ readonly int:

    203 non authoritative information.

  • NO_CONTENT ⇢ readonly int:

    204 no content.

  • RESET_CONTENT ⇢ readonly int:

    205 reset content.

  • PARTIAL_CONTENT ⇢ readonly int:

    206 partial content.

  • MULTI_STATUS ⇢ readonly int:

    207 multi status.

  • ALREADY_REPORTED ⇢ readonly int:

    208 already reported.

  • IM_USED ⇢ readonly int:

    226 im used.

  • MULTIPLE_CHOICES ⇢ readonly int:

    300 multiple choices.

  • MOVED_PERMANENTLY ⇢ readonly int:

    301 moved permanently.

  • FOUND ⇢ readonly int:

    302 found.

  • SEE_OTHER ⇢ readonly int:

    303 see other.

  • NOT_MODIFIED ⇢ readonly int:

    304 not modified.

  • USE_PROXY ⇢ readonly int:

    305 use proxy.

  • TEMPORARY_REDIRECT ⇢ readonly int:

    307 temporary redirect.

  • PERMANENT_REDIRECT ⇢ readonly int:

    308 permanent redirect.

  • BAD_REQUEST ⇢ readonly int:

    400 bad request.

  • UNAUTHORIZED ⇢ readonly int:

    401 unauthorized.

  • PAYMENT_REQUIRED ⇢ readonly int:

    402 payment required.

  • FORBIDDEN ⇢ readonly int:

    403 forbidden.

  • NOT_FOUND ⇢ readonly int:

    404 not found.

  • METHOD_NOT_ALLOWED ⇢ readonly int:

    405 method not allowed.

  • NOT_ACCEPTABLE ⇢ readonly int:

    406 not acceptable.

  • PROXY_AUTHENTICATION_REQUIRED ⇢ readonly int:

    407 proxy authentication required.

  • REQUEST_TIMEOUT ⇢ readonly int:

    408 request timeout.

  • CONFLICT ⇢ readonly int:

    409 conflict.

  • GONE ⇢ readonly int:

    410 gone.

  • LENGTH_REQUIRED ⇢ readonly int:

    411 length required.

  • PRECONDITION_FAILED ⇢ readonly int:

    412 precondition failed.

  • PAYLOAD_TOO_LARGE ⇢ readonly int:

    413 payload too large.

  • REQUEST_URI_TOO_LONG ⇢ readonly int:

    414 request uri too long.

  • UNSUPPORTED_MEDIA_TYPE ⇢ readonly int:

    415 unsupported media type.

  • REQUESTED_RANGE_NOT_SATISFIABLE ⇢ readonly int:

    416 requested range not satisfiable.

  • EXPECTATION_FAILED ⇢ readonly int:

    417 expectation failed.

  • TEAPOT ⇢ readonly int:

    418 teapot.

  • MISDIRECTED_REQUEST ⇢ readonly int:

    421 misdirected request.

  • UNPROCESSABLE_ENTITY ⇢ readonly int:

    422 unprocessable entity.

  • LOCKED ⇢ readonly int:

    423 locked.

  • FAILED_DEPENDENCY ⇢ readonly int:

    424 failed dependency.

  • UPGRADE_REQUIRED ⇢ readonly int:

    426 upgrade required.

  • PRECONDITION_REQUIRED ⇢ readonly int:

    428 precondition required.

  • TOO_MANY_REQUESTS ⇢ readonly int:

    429 too many requests.

  • REQUEST_HEADER_FIELDS_TOO_LARGE ⇢ readonly int:

    431 request header fields too large.

  • CONNECTION_CLOSED_WITHOUT_RESPONSE ⇢ readonly int:

    444 connection closed without response.

  • UNAVAILABLE_FOR_LEGAL_REASONS ⇢ readonly int:

    451 unavailable for legal reasons.

  • CLIENT_CLOSED_REQUEST ⇢ readonly int:

    499 client closed request.

  • INTERNAL_SERVER_ERROR ⇢ readonly int:

    500 internal server error.

  • NOT_IMPLEMENTED ⇢ readonly int:

    501 not implemented.

  • BAD_GATEWAY ⇢ readonly int:

    502 bad gateway.

  • SERVICE_UNAVAILABLE ⇢ readonly int:

    503 service unavailable.

  • GATEWAY_TIMEOUT ⇢ readonly int:

    504 gateway timeout.

  • HTTP_VERSION_NOT_SUPPORTED ⇢ readonly int:

    505 http version not supported.

  • VARIANT_ALSO_NEGOTIATES ⇢ readonly int:

    506 variant also negotiates.

  • INSUFFICIENT_STORAGE ⇢ readonly int:

    507 insufficient storage.

  • LOOP_DETECTED ⇢ readonly int:

    508 loop detected.

  • NOT_EXTENDED ⇢ readonly int:

    510 not extended.

  • NETWORK_AUTHENTICATION_REQUIRED ⇢ readonly int:

    511 network authentication required.

  • NETWORK_CONNECT_TIMEOUT_ERROR ⇢ readonly int:

    599 network connect timeout error.

  • map ⇢ readonly dictionary:

    A map of status code to their string representation..

Functions

set_headers(headers)

Sets the default request headers for the current module instance.

This function returns HttpClient in order to allow for idiomatic chaining such as:

import http
echo http.set_headers({
  'Authorization': 'Bearer SomeAPIBearerToken',
  'Host': 'example.com',
}).get('http://example.com/current-user').body.to_string()
Parameters
  • dict headers
Returns
  • HttpClient

get(url, headers)

Sends an Http GET request and returns an HttpResponse or throws one of SocketException or Exception if it fails.

Parameters
  • string url
  • dict? headers
Returns
  • HttpResponse
Raises Exception
  • Exception @raises

post(url, data, headers)

Sends an Http POST request and returns an HttpResponse.

Parameters
  • string url
  • string|bytes|nil data
  • dict? headers
Returns
  • HttpResponse
Raises Exception
  • Exception @raises

put(url, data, headers)

Sends an Http PUT request and returns an HttpResponse.

Parameters
  • string url
  • string|bytes|nil data
  • dict? headers
Returns
  • HttpResponse
Raises Exception
  • Exception @raises

patch(url, data, headers)

Sends an Http PATCH request and returns an HttpResponse.

Parameters
  • string url
  • string|bytes|nil data
  • dict? headers
Returns
  • HttpResponse
Raises Exception
  • Exception @raises

delete(url, headers)

Sends an Http DELETE request and returns an HttpResponse.

Parameters
  • string url
  • dict? headers
Returns
  • HttpResponse
Raises Exception
  • Exception @raises

options(url, headers)

Sends an Http OPTIONS request and returns an HttpResponse.

Parameters
  • string url
  • dict? headers
Returns
  • HttpResponse
Raises Exception
  • Exception @raises

trace(url, headers)

Sends an Http TRACE request and returns an HttpResponse.

Parameters
  • string url
  • dict? headers
Returns
  • HttpResponse
Raises Exception
  • Exception @raises

head(url, headers)

Sends an Http HEAD request and returns an HttpResponse.

Parameters
  • string url
  • dict? headers
Returns
  • HttpResponse
Raises Exception
  • Exception @raises

client()

Returns the default shared client.

Returns
  • HttpClient

server(port, address)

Creates an new HttpServer instance.

Parameters
  • int port
  • string address
Returns
  • HttpServer
Raises Exception
  • Exception @raises

tls_server(port, host)

Creates an new TLSServer instance.

@throws Exception, SocketExcepion, HttpException

Parameters
  • int port
  • string? host
Returns
  • TLSServer

Classes

class HttpRequest

Http request handler and object.

Properties

  • @printable
  • @serializable

Fields

  • request_uri ⇢ string:

    The original request URL as sent in the raw request.

  • path ⇢ string:

    The requested path or file. E.g. if the Request URI is /users?sort=desc, then the path is /users.

  • method ⇢ string:

    The HTTP method of the request: GET (the default), POST, PUT, etc.

  • host ⇢ string:

    The hostname derived from the Host header or the first instance of X-Forwarded-Host if set.

  • ip ⇢ string:

    The IP address of the remote client that initiated the request.

  • ipv6 ⇢ string:

    The IPv6 address of the remote client that initiated the request.

  • headers ⇢ dictionary:

    A dictionary containing the headers sent with the request.

  • queries ⇢ dictionary:

    A dictionary containing the entries of the URI query string.

  • cookies ⇢ {list|dictionary:

    A list or dictionary containing the cookies sent with the request.

  • body ⇢ dictionary:

    A dictionary containing all data submitted in the request body.

  • files ⇢ dictionary:

    A dictionary containing the data of all files uploaded in the request.

  • http_version ⇢ string:

    The HTTP version used for the request.

Methods

parse(raw_data, client)

Parses a raw HTTP request string into a correct HttpRequest.

Parameters
  • string raw_data
  • Socket|TLSSocket|nil client
Returns
  • boolean

send(uri, method, data, headers, options)

Send HTTP requests to the given uri for the given method and data (if given).

Parameters
  • url uri
  • string method
  • string|bytes|dict|nil data
  • dict? headers
  • dict? options

class HttpException < Exception

HTTP related Exceptions.

Properties

  • @printable

class HttpServer

HTTP server.

Properties

  • @printable

Fields

  • host ⇢ string:

    The host address to which this server will be bound. Default value is socket.IP_LOCAL (127.0.0.1)

  • port ⇢ number:

    The port to which this server will be bound to on the host.

  • socket ⇢ {Socket:

    The working Socket instance for the HttpServer.

  • resuse_address ⇢ bool:

    A boolean value indicating whether to reuse socket addresses or not. Default value is true.

  • read_timeout ⇢ number:

    The timeout in milliseconds after which an attempt to read clients request data will be terminated. Default value is 2,000 (2 seconds).

  • write_timeout ⇢ number:

    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 value is 2,000 (2 seconds).

Methods

HttpServer(port, host) ⇢ Constructor

Parameters
  • int port
  • string? host

close()

Stops the server.

on_connect(function)

Adds a function to be called when a new client connects.

Parameters
  • function(1) function
Notes
  • Function function 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(function)

Adds a function to be called when a new client disconnects.

Parameters
  • function(1) function
Notes
  • Function function MUST accept at one parameter which will be passed the client.
  • Multiple on_disconnect() may be set on a single instance.

on_receive(handler)

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.

Parameters
  • function(2) handler
Notes
  • Multiple on_receive() may be set on a single instance.

on_reply(function)

Adds a function to be called when the server sends a reply to a client.

Function function MUST accept one parameter which will be passed the HttpResponse object.

Parameters
  • function(1) function
Notes
  • Multiple on_sent() may be set on a single instance.

on_error(function)

Adds a function to be called when the server encounters an error with a client.

Function function MUST accept two parameters. The first argument will be passed the Exception object and the second will be passed the client Socket object.

Parameters
  • function(2) function
Notes
  • Multiple on_error() may be set on a single instance.

handle(method, path, handler)

Sets up a request handler that will be called when a request with the given method has a path that matches the one specified.

Parameters
  • string method
  • string path
  • function(2) handler

none_handler(handler)

Sets up the handle to invoke when a request is not processed. That is, when it does not match a registered route and no on_receive() handler is set.

Parameters
  • function(2) handler

listen()

Binds to the instance port and host and starts listening for incoming connection from HTTP clients.

class TLSServer < HttpServer

TLS server

Properties

  • @printable

Fields

  • cert_file ⇢ string:

    The SSL/TLS certificate file that will be used be used by a secured server for serving requests.

  • private_key_file ⇢ string:

    The SSL/TLS private key file that will be used be used by a secured server for serving requests.

  • verify_certs ⇢ boolean:

    This value controls whether the client certificate should be verified or not.

Methods

TLSServer(port, host) ⇢ Constructor

Parameters
  • int port
  • string? host

load_certs(cert_file, private_key_file)

Loads the given SSL/TLS certificate pairs for the given SSL/TLS context.

Parameters
  • string|file cert_file
  • string|file|nil private_key_file
Returns
  • bool

listen()

Binds to the instance port and host and starts listening for incoming connection from HTTPS clients.

class HttpClient

Handles http requests.

@note This client do not currently support the compress, deflate and gzip transfer encoding.

Fields

  • user_agent ⇢ string:

    The user agent of the client used to make the request. Default value — Blade HTTP Client/1.0.

  • follow_redirect ⇢ bool:

    Indicates if we receive a redirect from a server, this flag tells us whether we should follow it or not. Default value is true.

  • verify_hostname ⇢ bool:

    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.

  • verify_peer ⇢ bool:

    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.

  • referer ⇢ string:

    The site that refers us to the current site

  • ca_cert ⇢ string:

    If you have a CA cert for the server stored someplace else than in the default bundle.

  • connect_timeout ⇢ number:

    The connect timeout duration in milliseconds. Default value is 60,000 (1 minute).

  • receive_timeout ⇢ number:

    The receive timeout duration in milliseconds. Default value is 2,000 (2 seconds).

  • headers ⇢ dict:

    A dictionary of headers sent along with the request.

  • no_expect ⇢ bool:

    Indicates whether to remove the expect header or not only applies to requests with files in the body

Methods

send_request(uri, method, data, headers, options)

Sends an Http request and returns a HttpResponse.

This can be very useful if you want to reuse the same instance for multiple requests and headers scenarios.

Parameters
  • string uri
  • string? method: : Default value is GET.
  • string|dict|nil data
  • dict? headers: : To override the instance options.
  • dict? client: request options
Returns
  • HttpResponse
Raises Exception
  • SocketException @raises

get(url, headers)

Sends an Http GET request and returns an HttpResponse.

Parameters
  • string url
  • dict? headers
Returns
  • HttpResponse
Raises Exception
  • Exception @raises

post(url, data, headers)

Sends an Http POST request and returns an HttpResponse.

Parameters
  • string url
  • string|bytes|nil data
  • dict? headers
Returns
  • HttpResponse
Raises Exception
  • Exception @raises

put(url, data, headers)

Sends an Http PUT request and returns an HttpResponse.

Parameters
  • string url
  • string|bytes|nil data
  • dict? headers
Returns
  • HttpResponse
Raises Exception
  • Exception @raises

patch(url, data, headers)

Sends an Http PATCH request and returns an HttpResponse.

Parameters
  • string url
  • string|bytes|nil data
  • dict? headers
Returns
  • HttpResponse
Raises Exception
  • Exception @raises

delete(url, headers)

Sends an Http DELETE request and returns an HttpResponse.

Parameters
  • string url
  • dict? headers
Returns
  • HttpResponse
Raises Exception
  • Exception @raises

options(url, headers)

Sends an Http OPTIONS request and returns an HttpResponse.

Parameters
  • string url
  • dict? headers
Returns
  • HttpResponse
Raises Exception
  • Exception @raises

trace(url, headers)

Sends an Http TRACE request and returns an HttpResponse.

Parameters
  • string url
  • dict? headers
Returns
  • HttpResponse
Raises Exception
  • Exception @raises

head(url, headers)

Sends an Http HEAD request and returns an HttpResponse.

Parameters
  • string url
  • dict? headers
Returns
  • HttpResponse
Raises Exception
  • Exception @raises

class HttpResponse

Represents the response to an Http request.

Properties

  • @printable
  • @serializable

Fields

  • version ⇢ string:

    The HTTP version of the response

  • status ⇢ number:

    The HTTP response status code

  • headers ⇢ dictionary:

    The HTTP response headers

  • time_taken ⇢ number:

    Total time taken for the HTTP request that generated this HttpResponse to complete

  • redirects ⇢ number:

    The number of times the HTTP request that generated this HttpResponse was redirected.

  • responder ⇢ string:

    The final URL that provided the HttpResponse. This will sometimes differ from the original request URI.

  • body ⇢ bytes:

    The content of the HTTP response as bytes

  • cookies ⇢ list:

    The cookies to be sent back to the client

  • certificate ⇢ dict|nil:

    The SSL certificate for the secure connection. This is only available when visiting HTTPS/SSL/TLS secured websites.

Methods

HttpResponse(body, status, headers, cookies, version, time_taken, redirects, responder) ⇢ Constructor

Parameters
  • string body
  • int status
  • dict headers
  • list[string] cookies
  • string version
  • number time_taken
  • int redirects
  • string responder

write(data)

Writes data to the response stream.

This method should be prefered over writing directly to the body property to prevent unexpected behaviors.

Parameters
  • string|bytes data

json(data, status_code)

Writes a json encoded data to the response stream and sets the response Content-Type to application/json. If the status code is given, the response will be sent with the given status code.

Parameters
  • any data
  • number? status_code

file(path, status_code)

Writes a file into the response stream and sets the Content-Type to the correct mimetype for the file. If the status code is given, the response will be sent with the given status code.

Parameters
  • string path
  • number? status_code

set_cookie(key, value, domain, path, expires, secure, 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.

Parameters
  • string key
  • string value
  • string? domain
  • string? path
  • string? expires
  • bool? secure
  • string? extras

redirect(location, status)

Redirects the client to a new location. This function simultaneously sets the Location header and returns a 30x status code. If the status parameter is not given, the function defaults to 302.

@throw HttpException

Parameters
  • string location
  • string? status
Notes
  • When supplying a status, it must be a 30x

content_type(mimetype)

Sets the content type of the HTTP response.

Parameters
  • string mimetype

Search

Navigation