Network

HTTP requests, binary WebSocket messages and local WebSocket servers.

11 functionssUNC 100%Lynx 0.747

HTTP calls yield and require a yieldable coroutine. Response bodies are binary-safe strings.

HTTP

httpget

Yields
httpget(url: string): string

httpget sends an HTTP GET request and returns the response body.

Also available as http_get.

Parameters

urlstring
The URL of the remote endpoint.

Returns

string

The binary-safe HTTP response body.

game:HttpGet

Yields
game:HttpGet(url: string): string

game:HttpGet sends an HTTP GET request and returns the response body.

Also available as game:HttpGetAsync.

Parameters

urlstring
The URL of the remote endpoint.

Returns

string

The binary-safe HTTP response body.

http_request

Yields
http_request(options: RequestOptions): HttpResponse

http_request sends an HTTP request with the supplied method, headers, and body, then returns its response details.

Also available as request and http.request.

Parameters

optionsRequestOptions
RequestOptions containing Url and optional Method, Body, and Headers.

Returns

HttpResponse

StatusCode, StatusMessage, Success, Body, Headers, and Error for the request.

Example

local response = request({
Url = "https://example.com/",
Method = "GET",
Headers = {["Accept"] = "text/html"},
})
print(response.StatusCode, response.Success)
print(response.Body)
Url
Type / defaultstring, required
Request URL.
Method
Type / defaultstring = "GET"
GET, POST, PUT, DELETE or PATCH.
Body
Type / defaultstring = ""
Binary-safe body for POST, PUT and PATCH.
Headers
Type / default{[string]: string}?
Additional headers; the module also applies its runtime request headers.
StatusCode
Typenumber
HTTP status code.
StatusMessage
Typestring
HTTP status/reason text.
Success
Typeboolean
Native request success flag.
Body
Typestring
Binary-safe response bytes.
Headers
Type{[string]: string}
Response header map.
Error
Typestring
Request failure diagnostic, including HTTP-status or transport errors; empty when none was reported.

WebSocket clients and local servers

WebSocket, Websocket and websocket refer to the same read-only API table. Socket/server objects are read-only tables with Signal objects for events. Message data is always delivered as a binary-safe string plus an isBinary boolean. Use ws://127.0.0.1 for a server created here; create does not configure TLS.

WebSocket.connect

Yields
WebSocket.connect(url: string): WebSocketConnection

WebSocket.connect opens a connection to a WebSocket server.

Also available as WebSocket.Connect, WebSocket.new, WebSocket.New, Websocket.connect, Websocket.Connect, Websocket.new, Websocket.New, websocket.connect, websocket.Connect, websocket.new and websocket.New.

Parameters

urlstring
A WebSocket server URL beginning with ws:// or wss://.

Returns

WebSocketConnection

A connected WebSocketConnection object.

WebSocket.create

WebSocket.create(port: number, allowLocalConnection: boolean?): WebSocketServer

WebSocket.create starts a WebSocket server on the selected local port.

Also available as WebSocket.Create, Websocket.create, Websocket.Create, websocket.create and websocket.Create.

Parameters

portnumber
The local port on which the server should listen.
allowLocalConnectionboolean??
Optional.Whether to listen on all local IPv4 interfaces instead of loopback only. Default false.

Returns

WebSocketServer

The listening WebSocketServer object.

Example

local server = WebSocket.create(5018, false)
server.OnConnection:Connect(function(peer)
peer.OnMessage:Connect(function(data, isBinary)
peer:Send(data, isBinary)
end)
end)
local client = WebSocket.connect("ws://127.0.0.1:5018")
client.OnMessage:Connect(function(data, isBinary)
print(#data, isBinary)
end)
client:SendBinary(buffer.fromstring("hello\0binary"))
task.delay(2, function()
client:Close()
server:Shutdown()
end)

Connection methods and state

Use colon calls. A send queues data for the transport; it does not wait for a peer response. Text frames require valid UTF-8. Binary frames do not perform UTF-8 validation. Both have an 8 MiB message limit and bounded outgoing queues (16 MiB). Sending after closure is a no-op after argument validation.

WebSocketConnection:Send

socket:Send(data: string | buffer, binary: boolean?): ()

WebSocketConnection:Send sends a text or binary message to the connected peer.

Parameters

datastring | buffer
The binary data to process.
binaryboolean??
Optional.Whether the message should use binary framing instead of text framing. Default false.

Returns

()

This function returns no values.

WebSocketConnection:SendBinary

socket:SendBinary(data: string | buffer): ()

WebSocketConnection:SendBinary sends a message as binary data.

Parameters

datastring | buffer
The binary data to process.

Returns

()

This function returns no values.

WebSocketConnection:Close

socket:Close(): ()

WebSocketConnection:Close closes the WebSocket connection.

Returns

()

This function returns no values.

IsClosed
Typeboolean, read-only
True once the underlying transport is closed.
LastError
Typestring, read-only
Last close/transport error; empty if no error was recorded.
OnMessage
Callback arguments(data: string, isBinary: boolean)
A complete incoming data message.
OnClose
Callback arguments()
Connection closure; no status-code/reason arguments are supplied.
OnError
Callback arguments(message: string, isBinary: boolean)
An error message followed by false. OnClose fires afterward.

Server methods, state and signals

WebSocketServer:Send

server:Send(data: string | buffer, binary: boolean?): ()

WebSocketServer:Send broadcasts a text or binary message to all connected clients.

Parameters

datastring | buffer
The binary data to process.
binaryboolean??
Optional.Whether the message should use binary framing instead of text framing. Default false.

Returns

()

This function returns no values.

WebSocketServer:SendBinary

server:SendBinary(data: string | buffer): ()

WebSocketServer:SendBinary broadcasts a binary message to all connected clients.

Parameters

datastring | buffer
The binary data to process.

Returns

()

This function returns no values.

WebSocketServer:Shutdown

server:Shutdown(): ()

WebSocketServer:Shutdown stops the server and closes its client connections.

Returns

()

This function returns no values.

Port
Typenumber, read-only
Bound port.
Address
Typestring, read-only
127.0.0.1 when loopback-only; 0.0.0.0 when allowLocalConnection=true.
AllowLocalConnection
Typeboolean, read-only
The allowLocalConnection setting supplied to create.
IsClosed
Typeboolean, read-only
Whether the server transport has shut down.
LastError
Typestring, read-only
Last recorded server error.
OnConnection
Callback arguments(peer: WebSocketConnection)
A peer completed the handshake.
OnMessage
Callback arguments(data: string, isBinary: boolean, peer: WebSocketConnection)
A message from a peer, after that peer's own OnMessage signal.
OnClientClose
Callback arguments(peer: WebSocketConnection)
A peer closed while the server is still active.
OnClose
Callback arguments()
The server shut down.
OnError
Callback arguments(message: string, isBinary: boolean)
An error message followed by false. The server shuts down afterward.