http

The http library allows communicating with web servers, sending and receiving data from them.

request(...)Asynchronously make a HTTP request to the given url.
get(...)Make a HTTP GET request to the given url.
post(...)Make a HTTP POST request to the given url.
checkURLAsync(url)Asynchronously determine whether a URL can be requested.
checkURL(url)Determine whether a URL can be requested.
websocket(url[, headers])Open a websocket.
websocketAsync(url[, headers])Asynchronously open a websocket.
request(...)Source

Asynchronously make a HTTP request to the given url.

This returns immediately, a http_success or http_failure will be queued once the request has completed.

Parameters

  1. url string The url to request
  2. body? string An optional string containing the body of the request. If specified, a POST request will be made instead.
  3. headers? { [string] = string } Additional headers to send as part of this request.
  4. binary? boolean Whether to make a binary HTTP request. If true, the body will not be UTF-8 encoded, and the received response will not be decoded.

Or

  1. request { url = string, body? = string, headers? = { [string] = string }, binary? = boolean, method? = string, redirect? = boolean }

    Options for the request.

    This table form is an expanded version of the previous syntax. All arguments from above are passed in as fields instead (for instance, http.request("https://example.com") becomes http.request { url = "https://example.com" }).

    This table also accepts several additional options:

    • method: Which HTTP method to use, for instance "PATCH" or "DELETE".
    • redirect: Whether to follow HTTP redirects. Defaults to true.

See also

  • http.get For a synchronous way to make GET requests.
  • http.post For a synchronous way to make POST requests.
get(...)Source

Make a HTTP GET request to the given url.

Parameters

  1. url string The url to request
  2. headers? { [string] = string } Additional headers to send as part of this request.
  3. binary? boolean Whether to make a binary HTTP request. If true, the body will not be UTF-8 encoded, and the received response will not be decoded.

Or

  1. request { url = string, headers? = { [string] = string }, binary? = boolean, method? = string, redirect? = boolean } Options for the request. See http.request for details on how these options behave.

Returns

  1. Response The resulting http response, which can be read from.

Or

  1. nil When the http request failed, such as in the event of a 404 error or connection timeout.
  2. string A message detailing why the request failed.
  3. Response | nil The failing http response, if available.

Usage

  • Make a request to example.computercraft.cc, and print the returned page.

    local request = http.get("https://example.computercraft.cc")
    print(request.readAll())
    -- => HTTP is working!
    request.close()
post(...)Source

Make a HTTP POST request to the given url.

Parameters

  1. url string The url to request
  2. body string The body of the POST request.
  3. headers? { [string] = string } Additional headers to send as part of this request.
  4. binary? boolean Whether to make a binary HTTP request. If true, the body will not be UTF-8 encoded, and the received response will not be decoded.

Or

  1. request { url = string, body? = string, headers? = { [string] = string }, binary? = boolean, method? = string, redirect? = boolean } Options for the request. See http.request for details on how these options behave.

Returns

  1. Response The resulting http response, which can be read from.

Or

  1. nil When the http request failed, such as in the event of a 404 error or connection timeout.
  2. string A message detailing why the request failed.
  3. Response | nil The failing http response, if available.
checkURLAsync(url)Source

Asynchronously determine whether a URL can be requested.

If this returns true, one should also listen for http_check events which will container further information about whether the URL is allowed or not.

Parameters

  1. url string The URL to check.

Returns

  1. true When this url is not invalid. This does not imply that it is allowed - see the comment above.

Or

  1. false When this url is invalid.
  2. string A reason why this URL is not valid (for instance, if it is malformed, or blocked).

See also

checkURL(url)Source

Determine whether a URL can be requested.

If this returns true, one should also listen for http_check events which will container further information about whether the URL is allowed or not.

Parameters

  1. url string The URL to check.

Returns

  1. true When this url is valid and can be requested via http.request.

Or

  1. false When this url is invalid.
  2. string A reason why this URL is not valid (for instance, if it is malformed, or blocked).

Usage

  • print(http.checkURL("https://example.computercraft.cc/"))
    -- => true
    print(http.checkURL("http://localhost/"))
    -- => false Domain not permitted
    print(http.checkURL("not a url"))
    -- => false URL malformed

See also

websocket(url[, headers])Source

Open a websocket.

Parameters

  1. url string The websocket url to connect to. This should have the ws:// or wss:// protocol.
  2. headers? { [string] = string } Additional headers to send as part of the initial websocket connection.

Returns

  1. Websocket The websocket connection.

Or

  1. false If the websocket connection failed.
  2. string An error message describing why the connection failed.
websocketAsync(url[, headers])Source

Asynchronously open a websocket.

This returns immediately, a websocket_success or websocket_failure will be queued once the request has completed.

Parameters

  1. url string The websocket url to connect to. This should have the ws:// or wss:// protocol.
  2. headers? { [string] = string } Additional headers to send as part of the initial websocket connection.

Types

Websocket

A websocket, which can be used to send an receive messages with a web server.

See also

Websocket.receive([timeout])Source

Wait for a message from the server.

Parameters

  1. timeout? number The number of seconds to wait if no message is received.

Returns

  1. string The received message.
  2. boolean If this was a binary message.

Or

  1. nil If the websocket was closed while waiting, or if we timed out.

Throws

  • If the websocket has been closed.

Websocket.send(message[, binary])Source

Send a websocket message to the connected server.

Parameters

  1. message any The message to send.
  2. binary? boolean Whether this message should be treated as a

Throws

  • If the message is too large.

  • If the websocket has been closed.

Websocket.close()Source

Close this websocket. This will terminate the connection, meaning messages can no longer be sent or received along it.

Response

A http response. This provides the same methods as a file (or binary file if the request used binary mode), though provides several request specific methods.

See also

Response.getResponseCode()Source

Returns the response code and response message returned by the server.

Returns

  1. number The response code (i.e. 200)
  2. string The response message (i.e. "OK")
Response.getResponseHeaders()Source

Get a table containing the response's headers, in a format similar to that required by http.request. If multiple headers are sent with the same name, they will be combined with a comma.

Returns

  1. { [string] = string } The response's headers.

Usage

  • Make a request to example.computercraft.cc, and print the returned headers.

     local request = http.get("https://example.computercraft.cc")
     print(textutils.serialize(request.getResponseHeaders()))
     -- => {
     --  [ "Content-Type" ] = "text/plain; charset=utf8",
     --  [ "content-length" ] = 17,
     --  ...
     -- }
     request.close()