Next | Previous

http

IMPORTANT NOTICE:

THIS MODULE IS DEPRECIATED AND WILL BE REMOVED FROM THE CORE LIBRARY AS SOON AS THE PURE BLADE IMPLEMENTATION IS STABLE. IT IS ONLY HERE FOR HISTORICAL REASONS AND TO SERVE AS A BASE BENCHMARK FOR THE DEVELOPMENT OF THE http MODULE.

YOU SHOULD USE THE http MODULE INSTEAD AS ITS MORE SUPPORTED, AND ALL FURTHER DEVELOPMENTS TOWARDS HTTP WILL BE DONE THERE.

BUG REPORTS AND ISSUES FOR THIS MODULE WILL NOT BE TREATED AS PRIORITY. The chttp 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 chttp
echo chttp.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 chttp
var client = chttp.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 chttp 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 chttp
import json
var server = chttp.server(3000)
server.handle('GET', '/', @(request, response) {
  response.json(request)
})
server.listen()

The chttp 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

  • 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 request headers for the current module instance.

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

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

get(url)

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

Parameters
  • string url
Returns
  • HttpResponse
Raises Exception
  • Exception @raises

post(url, data)

Sends an Http POST request and returns an HttpResponse.

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

put(url, data)

Sends an Http PUT request and returns an HttpResponse.

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

delete(url)

Sends an Http DELETE request and returns an HttpResponse.

Parameters
  • string url
Returns
  • HttpResponse
Raises Exception
  • Exception @raises

server(port, address)

Creates an new HttpServer instance.

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

client()

Returns the default client.

Returns
  • HttpClient

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 ⇢ dictionary:

    A 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.

  • auth_method ⇢ Auth:

    The HTTP authentication method to use when the uri contains a credential. Default value is Auth.ANY.

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, options)

Sends the given request to the given uri using the given method and optionally passing the data if given.

Parameters
  • Url uri
  • string method
  • string|bytes|nil data
  • dict? options
Returns
  • HttpResponse

to_dict()

Returns a dictionary representation of the HttpRequest instance.

Returns
  • dict

to_string()

Returns a string representation of the HttpRequest instance.

Returns
  • string

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 information.
  • 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 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.

  • skip_hostname_verification ⇢ 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.

  • skip_peer_verification ⇢ 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 300,000 (5 minutes).

  • 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)

Sends an Http request and returns a HttpResponse.

Parameters
  • string uri
  • string? method: : Default value is GET.
  • string|dict|nil data
Returns
  • HttpResponse
Raises Exception
  • SocketException @raises

get(url)

Sends an Http GET request and returns an HttpResponse.

Parameters
  • string url
Returns
  • HttpResponse
Raises Exception
  • Exception @raises

post(url, data)

Sends an Http POST request and returns an HttpResponse.

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

put(url, data)

Sends an Http PUT request and returns an HttpResponse.

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

delete(url)

Sends an Http DELETE request and returns an HttpResponse.

Parameters
  • string url
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

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