# iot

IOT is a communication system to the internet.
You can use this to create secure connections to external backends you create.

# Enums

# iot.method: {[index: string]: string}


iot.method: {[index: string]: string}

Contains a list of method procedures for HTTP/HTTPS

# iot.status: {[index: string | number]: string | number}


iot.status: {[index: string | number]: string | number}

Contains a list of status codes for HTTP/HTTPS

# iot.opcode: {[index: string | number]: string | number}


iot.opcode: {[index: string | number]: string | number}

Contains a list of opcode procedures for sockets

# iot.closure: {[index: string | number]: string | number}


iot.closure: {[index: string | number]: string | number}

Contains a list of closure procedures for sockets
These are usually needed when dealing withiot.closure.closecases

# Functions

# iot.http(url: string, callback?: function(response: http_response), options?: http_options)


iot.http(url: string, callback?: function(response: http_response), options?: http_options)

Makes an HTTP/HTTPS request to an address or domain.
This function is asynchronous, meaning this will not "freeze" Lua.
The interface typeshttp_options&http_responsecan be seen here:

body?: string
method?: string
headers?: {[index: string]: string}
parameters?: {[index: string]: string}
progress?: function(dl_total: number, dl_now: number, up_total: number, up_now: number): boolean?

headers: {[index: string]: string}
body: string
status: number
reason: string
url: string

# iot.stream(url: string, callback?: function(response: http_response), options?: http_options)


iot.stream(url: string, callback?: function(response: http_response), options?: http_options)

Similar toiot.httpexcept allows multiple returns from segments of encoded chunks.
When receiving chunks, all responses will have a 100 status code for continuing.
Once finished, the status code will either be 200 or a different value if it errored.
Returning false inside the callback will cancel the stream.

# iot.socket(url: string, options?: socket_options): socket_class


iot.socket(url: string, headers?: {[index: string]: string}): socket_class

Creates a socket object which is connected to an address or domain.
Upon creation, the socket isn't activated until you invoke it to do so.
Sockets work by reference, so if there is no-longer a use in lua, it will destroy itself.

# iot.serve(port: number): serve_class


iot.serve(port: number): serve_class

Creates an HTTP server for requests, similar to express/deno.
Do note that the server doesn't actually start until you invokeserve:start()
Unlike client sockets, if the object gets GC'ed, it won't cleanup the callbacks or invoke a destructor.
If you "lose" the handle object, you can retrieve it back by simply calling the function again and its exact port number.

# Serve

These are interface & function definitions for how we handle serve_class. All callbacks use these interfaces for HTTP IO.

# serve.request

{
    method: string,
    path: string,
    query: string,
    body: string,
    headers: table
}

# serve.response

This is the accepted returns for the responses.
If there is incorrect values it will default to its original value defined in the interface.
This has higher precedence than the funtional version.

{
    status: number? = 501,
    body: string? = "",
    headers: {[index: string]: string}? = {}
}

# serve.response.functional

Serve's response also has a functional version which doesn't require a return.
You can call these multiple times allow you to override previous values.
However this has lower precedence to serve.response returns.

# res:status(state: number)


res:status(state: number)

Sets the response status number
If this isn't set it will default to 501

# res:body(data: string)


res:body(data: string)

Sets the response body

# res:header(key: string, value: string)


res:header(key: string, value: string)

Adds a header to the response

# res:headers(headers: {[index: string]: string})


res:headers(headers: {[index: string]: string})

Sets the headers in the response

# serve:start(): boolean


serve:start(): boolean

Attempts to allocate a port for HTTP connections.
If this fails it will return false.
Usually a failure indicates a port is already in-use.

# serve:stop()


serve:stop()

De-allocates and stops serving under the allocated port.
This doesn't actually destroy the object.

# serve:active(): boolean


serve:active(): boolean

Checks if the current serve is active on its port.

# serve:port(): number


serve:port(): number

Gets the current port the serve is on.

# serve:handlers(): {method: string, path: string, callback: function}[]


serve:handlers(): {method: string, path: string, callback: function}[]

Gets all handlers associated with the serve.

# serve:sockets(path: string): serve_socket[]


serve:sockets(path: string): serve_socket[]

Gets all sockets associated with the serve.

# serve:upgrade(): serve_socket


serve:upgrade(): serve_socket

Upgrades a connection into a socket.
Must be used inside of a HTTP request.

# serve:socket(path: string, callback: function(connection: serve_socket, opcode: number, data: string | number, extra: string))


serve:socket(path: string, callback: function(connection: serve_socket, opcode: number, data: string | number, extra: string))

Adds a callback for a certain path for socket-based messages.
Do note that the path must be the same to the socket you upgraded in.
Opcodes can be seen underiot.opcode

# serve:any(path: string, callback?: function(req: serve.request, res: serve.response.functional): serve.response?)


serve:any(path: string, callback?: function(req: serve.request, res: serve.response.functional): serve.response?)

By inputing nothing as the callback (nil), will deleted any callbacks under the path.
Any is a form of method that allows all types of methods to be seen in callback under the path.
You can check the method by seeing req.method
If you set the path to ANY it will also act as a any filter, allowing you to process paths individually.
Do note this is first-order making it called first before any other methods

# serve:get(path: string, callback?: function(req: serve.request, res: serve.response.functional): serve.response?)


serve:get(path: string, callback?: function(req: serve.request, res: serve.response.functional): serve.response?)

By inputing nothing as the callback (nil), will deleted any callbacks under the path.
Adds a callback for a certain path under "GET" requests
The GET method requests a representation of the specified resource.
Requests using GET should only retrieve data and should not contain a request content.

# serve:post(path: string, callback?: function(req: serve.request, res: serve.response.functional): serve.response?)


serve:post(path: string, callback?: function(req: serve.request, res: serve.response.functional): serve.response?)

By inputing nothing as the callback (nil), will deleted any callbacks under the path.
Adds a callback for a certain path under "POST" requests
The HEAD method asks for a response identical to a GET request, but without a response body.

# serve:head(path: string, callback?: function(req: serve.request, res: serve.response.functional): serve.response?)


serve:head(path: string, callback?: function(req: serve.request, res: serve.response.functional): serve.response?)

By inputing nothing as the callback (nil), will deleted any callbacks under the path.
Adds a callback for a certain path under "HEAD" requests
The POST method submits an entity to the specified resource, often causing a change in state or side effects on the server.

# serve:put(path: string, callback?: function(req: serve.request, res: serve.response.functional): serve.response?)


serve:put(path: string, callback?: function(req: serve.request, res: serve.response.functional): serve.response?)

By inputing nothing as the callback (nil), will deleted any callbacks under the path.
Adds a callback for a certain path under "PUT" requests
The PUT method replaces all current representations of the target resource with the request content.

# serve:delete(path: string, callback?: function(req: serve.request, res: serve.response.functional): serve.response?)


serve:delete(path: string, callback?: function(req: serve.request, res: serve.response.functional): serve.response?)

By inputing nothing as the callback (nil), will deleted any callbacks under the path.
Adds a callback for a certain path under "DELETE" requests
The DELETE method deletes the specified resource.

# serve:options(path: string, callback?: function(req: serve.request, res: serve.response.functional): serve.response?)


serve:options(path: string, callback?: function(req: serve.request, res: serve.response.functional): serve.response?)

By inputing nothing as the callback (nil), will deleted any callbacks under the path.
Adds a callback for a certain path under "OPTIONS" requests
The OPTIONS method describes the communication options for the target resource.

# Serve Socket

These are interface & function definitions for how we handle serve_socket

# serve_socket:id(): string


serve_socket:id(): string

Gets the socket's unique ID.
Useful if you need to manually track them.

# serve_socket:disconnect(code?: string | number, reason?: string)


serve_socket:disconnect(code?: string | number, reason?: string)

Forces a socket to disconnect.
By providing a string in the code parameter, it will become a reason with normal closure.

# serve_socket:text(payload: string)


serve_socket:text(payload: string)

Sends a text-based payload.

# serve_socket:binary(payload: string)


serve_socket:binary(payload: string)

Sends a binary-based payload.

# serve_socket:ping(payload?: string)


serve_socket:ping(payload?: string)

Sends a ping payload, typically used to keep connections alive.

# serve_socket:pong(payload?: string)


serve_socket:pong(payload?: string)

Sends a pong payload, typically used to keep connections alive.

# Socket

These are interface & function definitions for how we handle socket_class

# Functions

# socket:connect()


socket:connect()

Attempt to connect the socket to the constructed URL from creation.

# socket:disconnect(reason?: string)


socket:disconnect(reason?: string)

Disconnects from a socket server with a message if needed.

# socket:text(payload: string)


socket:text(payload: string)

Send a payload message to the socket server.

# socket:utf8(payload: string)


socket:utf8(payload: string)

Send a payload message to the socket server in UTF8 format.

# socket:binary(payload: string)


socket:binary(payload: string)

Send a payload message to the socket server in binary format.

# socket:close(reason?: string)


socket:close(reason?: string)

Closes the socket connection, this usually also sends a message.
If you want to re-open the connection, simply run socket.connect()

# socket:ping(reason?: string)


socket:ping(message?: string)

Sends a ping payload to the socket server.

# socket:get_url(): string


socket:get_url(): string

Gets the current full connection URL.

# socket:get_host(): string


socket:get_host(): string

Gets the current host from the URL.

# socket:get_port(): string


socket:get_port(): string

Gets the current port from the URL.

# socket:get_path(): string


socket:get_path(): string

Gets the current path from the URL.

# socket:headers_add(key: string, value: string)


socket:headers_add(key: string, value: string)

Adds a header to the list of headers to be sent on connection.

# socket:headers_remove(key: string)


socket:headers_remove(key: string)

Removes a header from the list of headers to be sent on connection.

# socket:headers_get(key: string): string?


socket:headers_get(key: string): string?

Gets a header by the key-name.

# socket:headers_all(key: string): {[index: string]: string}


socket:headers_all(key: string): {[index: string]: string}

Gets a list of all headers applied.

# socket:is_open(): boolean


socket:is_open(): boolean

If the socket is currently connected.

# socket:is_connecting(): boolean


socket:is_connecting(): boolean

If the socket is currently connecting.

# socket:is_closing(): boolean


socket:is_closing(): boolean

If the socket is currently closing.

# socket:is_closed(): boolean


socket:is_closed(): boolean

If the socket is currently closed.

# socket:is_tls(): boolean


socket:is_tls(): boolean

If the socket is using TLS as it's connection layer.

# Events

This internally uses the Signal library for C++ communication.
These can be accessed for example by: socket_class.add(...)

Signal

../signal/#library-functions

# open()


open()

Called when the socket engine has made a successful connection.

# error(code: number, reason: string)


error(code: number, reason: string)

Called if there was a connection failure.

# close(status: number, reason: string)


close(status: number, reason: string)

Called when the connection closes, this can contain an error reason.

# message(payload: string)


message(payload: string, is_binary: boolean)

Called when a message has been received.

# ping(reason: string)


ping(message: string)

Called when the socket server sent a ping.
This can be used as an "isalive" status refresh.
However this is managed internally by interstellar.

# pong(reason: string)


pong(message: string)

Called when the socket server sent a pong.
This can be used as an "isalive" status refresh.