Websockets

doc/index.md

@@ -908,6 +908,95 @@ Returns the time in HTTP preferred date format (See [RFC 7231 section 7.1.1.1](h
 Current version of lua-http as a string.
 
 
+## http.websocket
+
+
+### `new_from_uri(uri, protocols)` <!-- --> {#http.websocket.new_from_uri}
+
+Creates a new `http.websocket` object of type `"client"` from the given URI.
+
+  - `protocols` (optional) should be a lua table containing a sequence of protocols to send to the server
+
+
+### `new_from_stream(headers, stream)` <!-- --> {#http.websocket.new_from_stream}
+
+Attempts to create a new `http.websocket` object of type `"server"` from the given request headers and stream.
+
+  - [`headers`](#http.headers) should be headers of a suspected websocket upgrade request from a HTTP 1 client.
+  - [`stream`](#http.h1_stream) should be a live HTTP 1 stream of the `"server"` type.
+
+This function does **not** have side effects, and is hence okay to use tentatively.
+
+
+### `websocket.close_timeout` <!-- --> {#http.websocket.close_timeout}
+
+Amount of time (in seconds) to wait between sending a close frame and actually closing the connection.
+Defaults to `3` seconds.
+
+
+### `websocket:accept(protocols, timeout)` <!-- --> {#http.websocket:accept}
+
+Completes negotiation with a websocket client.
+
+  - `protocols` (optional) should be a lua table containing a sequence of protocols to to allow from the client
+
+Usually called after a successful [`new_from_stream`](#http.websocket.new_from_stream)
+
+
+### `websocket:connect(timeout)` <!-- --> {#http.websocket:connect}
+
+Connect to a websocket server.
+
+Usually called after a successful [`new_from_uri`](#http.websocket.new_from_uri)
+
+
+### `websocket:receive(timeout)` <!-- --> {#http.websocket:receive}
+
+Reads and returns the next data frame plus its opcode.
+Any ping frames received while reading will be responded to.
+
+The opcode `0x1` will be returned as `"text"` and `0x2` will be returned as `"binary"`.
+
+
+### `websocket:each()` <!-- --> {#http.websocket:each}
+
+Iterator over [`websocket:receive()`](#http.websocket:receive).
+
+
+### `websocket:send_frame(frame, timeout)` <!-- --> {#http.websocket:send_frame}
+
+Low level function to send a raw frame.
+
+
+### `websocket:send(data, opcode, timeout)` <!-- --> {#http.websocket:send}
+
+Send the given `data` as a data frame.
+
+  - `data` should be a string
+  - `opcode` can be a numeric opcode, `"text"` or `"binary"`. If `nil`, defaults to a text frame
+
+
+### `websocket:close(code, reason, timeout)` <!-- --> {#http.websocket:close}
+
+Closes the websocket connection.
+
+  - `code` defaults to `1000`
+  - `reason` is an optional string
+
+
+### Example
+
+```lua
+local websocket = require "http.websocket"
+local ws = websocket.new_from_uri("wss://echo.websocket.org")
+assert(ws:connect())
+assert(ws:send("koo-eee!"))
+local data = assert(ws:receive())
+assert(data == "koo-eee!")
+assert(ws:close())
+```
+
+
 ## http.zlib
 
 An abstraction layer over the various lua zlib libraries.

examples/websocket_client.lua

@@ -0,0 +1,20 @@
+--[[
+Example of websocket client usage
+
+  - Connects to the coinbase feed.
+  - Sends a subscribe message
+  - Prints off 5 messages
+  - Close the socket and clean up.
+]]
+
+local json = require "cjson"
+local websocket = require "http.websocket"
+
+local ws = websocket.new_from_uri("ws://ws-feed.exchange.coinbase.com")
+assert(ws:connect())
+assert(ws:send(json.encode({type = "subscribe", product_id = "BTC-USD"})))
+for _=1, 5 do
+	local data = assert(ws:receive())
+	print(data)
+end
+assert(ws:close())

http-scm-0.rockspec

@@ -41,6 +41,7 @@ build = {
 		["http.tls"] = "http/tls.lua";
 		["http.util"] = "http/util.lua";
 		["http.version"] = "http/version.lua";
+		["http.websocket"] = "http/websocket.lua";
 		["http.zlib"] = "http/zlib.lua";
 		["http.compat.prosody"] = "http/compat/prosody.lua";
 	};

http/request.lua

@@ -346,6 +346,7 @@ function request_methods:go(timeout)
 end
 
 return {
+	new_from_uri_t = new_from_uri_t;
 	new_from_uri = new_from_uri;
 	new_connect = new_connect;
 	new_from_stream = new_from_stream;