oc-ws

oc-ws a WebSocket library for OpenComputers.

Limitations

I haven't done a lot of testing, so let me know if you get this to work or not. This is only supports the basic websocket protocol with no extensions. Here are some things that are not supported

• Masked messages from server
• Binary websocket messages

Installation

To use oc-ws in your OpenComputers project, follow these steps:

1. Run the following command:

   wget https://raw.githubusercontent.com/bluescorpian/oc-ws/main/src/ws.lua /usr/lib/ws.lua

2. In your OpenComputers program, import the oc-ws library using the require function:

   local WebSocket = require("ws")

Usage

Here's a basic example of how to create a WebSocket client and send a message using oc-ws:

-- Import the oc-ws library
local WebSocket = require("ws")

-- Create a new WebSocket instance
local ws = WebSocket.new({
    address = "ws://example.com",
    port = 80,
    path = "/websocket",
})

-- Connect to the WebSocket server
while true do
	local connected, err = socket:finishConnect()
	if connected then break end
	if err then return print('Failed to connect: ' .. err) end
	if event.pull(1) == 'interrupted' then return end
end
print("Connected to WebSocket server!")

-- Send a message
ws:send("Hello, WebSocket!")

-- Read incoming messages
while true do
	local messageType, message, err = ws:readMessage()
	if err then return print('Websocket Error: ' .. err) end
	if messageType == WebSocket.MESSAGE_TYPES.TEXT then
		print('Message Received: ' .. message)
	elseif messageType == WebSocket.MESSAGE_TYPES.PING then
		print('Ping')
		ws:pong(message)
	elseif messageType == WebSocket.MESSAGE_TYPES.PONG then
		print('Pong')
	end

	if event.pull(5) == 'interrupted' then return end
end


-- Close the WebSocket connection when done
ws:close()

API

Constants

• READY_STATES: An enum representing the WebSocket connection states.

  • CONNECTING (0): The WebSocket is in the process of connecting.
  • OPEN (1): The WebSocket connection is open and ready to send/receive messages.
  • CLOSING (2): The WebSocket connection is in the process of closing.
  • CLOSED (3): The WebSocket connection is closed.

• MESSAGE_TYPES: An enum representing WebSocket message types.

  • TEXT (0): Text message.
  • PING (1): Ping message.
  • PONG (2): Pong message.
  • CLOSE (3): Close message.

WebSocket.new(socketOptions: table) -> WebSocket

Creates a new WebSocket instance with the specified options.

• socketOptions (table):
  • address (string): The WebSocket server address (required).
  • port (number): The WebSocket server port (default: 80).
  • path (string): The path for the WebSocket connection (default: '/').
  • internet (object): The internet component (default: primary internet component).

Returns a WebSocket instance.

WebSocket:finishConnect() -> boolean, string?

Completes the WebSocket connection process, call as often as possible.

Returns a boolean indicating whether the connection was successful and an optional error message if the connection failed.

WebSocket:send(message: string)

Sends a text message over the WebSocket connection.

• message (string): The message to send.

WebSocket:ping(data: string)

Sends a ping message over the WebSocket connection.

• data (string): Optional data to include in the ping message.

WebSocket:pong(data: string)

Sends a pong message over the WebSocket connection.

• data (string): Optional data to include in the pong message.

WebSocket:readMessage() -> messageType?, string?, string?

Reads a WebSocket message from the connection.

Returns the message type (TEXT, PING, PONG, CLOSE), the message content (string), and an optional error message.

WebSocket:close()

Closes the WebSocket connection.

WebSocket:isOpen() -> boolean

Checks if the WebSocket connection is open.

Returns true if the connection is open; otherwise, returns false.

License

oc-ws is licensed under the GNU Affero General Public License (AGPL).

Credits

I used feldim2425 project to help with my implementation.