http library

Contents

• Configuration
• Methods
  • http.request(url: string[, postData: string[, headers: table[, binary: boolean]]]): nil
  • http.get(url: string[, headers: table[, binary: boolean]]): table|false, string, table
  • http.post(url: string[, postData: string[, headers: table[, binary: boolean]]]): table|false, string, table
  • http.checkURL(url: string): true|false, string
  • http.checkURLAsync(url: string): true|false, string
  • http.websocket(url: string[, headers: table]): table|false, string
  • http.websocketAsync(url: string[, headers: table]): true|false, string
• Websocket handles
  • handle.send(messsage: string)
  • handle.receive(): string
  • handle.close()
  • Event websocket_message: url: string, contents: string
  • Event websocket_closed: url: string

The http library allows communicating with web servers, sending and receiving data from them. For more complete documentation, please refer to the associated CC wiki page.

Configuration

• http_enable = true: Whether the HTTP library is enabled.

• http_websocket_enable = true: Whether websocket support is enabled.

• http_whitelist = ["*"]: A list of domain wildcards and IP ranges in CIDR notation that computers are allowed to access.

• http_blacklist = [ "127.0.0.0/8", …​ ]: A list of domain wildcards and IP ranges in CIDR notation that computers cannot access.

Methods

http.request(url: string[, postData: string[, headers: table[, binary: boolean]]]): nil

Fetch a webpage with the given url and headers. If postData is specified then a POST request will be sent instead. If binary is true then the request will not be UTF8 encoded nor the response UTF8 decoded.

Note that this will not return the handle: one should listen to http_success and http_failure events.

http.get(url: string[, headers: table[, binary: boolean]]): table|false, string, table

Attempt to fetch a webpage, using the same arguments as http.request. This will return the response table or false, an error message and (optionally) a handle with the failing response’s content.

local headers = {
  [ "User-Agent" ] = "My fancy User-Agent",
}

local handle, err, err_handle = http.get( "http://example.com/", headers )
if handle then 
  print(handle.readAll())
else
  printError(err)
  if err_handle then 
    print(err_handle.readAll()) 
    err_handle.close()
  end
end
handle.close()

http.post(url: string[, postData: string[, headers: table[, binary: boolean]]]): table|false, string, table

Attempt to fetch a webpage, using the same arguments as http.request. This will return the response table or false, an error message and (optionally) a handle with the failing response’s content.

http.checkURL(url: string): true|false, string

Determine whether a URL can be visited.

local ok, err = http.checkURL("http://example.com")
if not ok then 
  printError(err)
end

http.checkURLAsync(url: string): true|false, string

Determine whether a URL can be visited. If this returns true, one should also listen to http_check events which will contain further whitelist/blacklisting information.

local ok, err = http.checkURLAsync("http://example.com")
if not ok then 
  printError(err)
else
  while true do
    local event, url, ok, err = os.pullEvent( "http_check" )
    if url == "http://example.com" then
      if not ok then printError(err) end
      break
    end
  end
end

http.websocket(url: string[, headers: table]): table|false, string

Attempt to open a websocket connection with the given url and headers. Returns a websocket handle on success or false and an error message on failure.

local handle, err = http.websocket("ws://demos.kaazing.com/echo")
if not handle then
  printError(err)
else
  local input = read()
  handle.send(input)
  print(input.receive())
end

http.websocketAsync(url: string[, headers: table]): true|false, string

Attempt to open a websocket connection with the given url and headers. This will queue a websocket_success event if the socket could be opened successfully or websocket_failure if it failed.

Websocket handles

The handle enclosed in the websocket_success event acts very similarly to the rednet API.

handle.send(messsage: string)

Send a message to the remote server. This will error if the socket has been disconnected.

handle.receive(): string

Wait until a message has been received from this handle. This is equivalent to the following Lua code:

local function receive()
  while true do
    local event, url, contents = os.pullEvent()
    if event == "websocket_message" and url == _url then
      return contents
    end
  end
end

handle.close()

Close this handle. One should always do this after finishing using a handle, in order to free up resources.

Event websocket_message: url: string, contents: string

Queued when a websocket recieves a message. One may listen to this event instead of using .receive()

Event websocket_closed: url: string

Queued when a websocket is closed.