chatterino2
Code Issues

Introduce HTTP API for plugins (#5383)

Browse Source
This commit is contained in:
Mm2PL
2024-06-22 12:04:30 +02:00
committed by GitHub
parent 7dc80bc599
commit c980162656
19 changed files with 1166 additions and 11 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/chatterino.d.ts
Vendored
+32
View File
@@ -32,6 +32,8 @@ declare module c2 {
is_valid(): boolean;
}
interface ISharedResource {}
class RoomModes {
unique_chat: boolean;
subscriber_only: boolean;
@@ -69,6 +71,36 @@ declare module c2 {
static by_twitch_id(id: string): null | Channel;
}
enum HTTPMethod {
Get,
Post,
Put,
Delete,
Patch,
}
class HTTPResponse implements ISharedResource {
data(): string;
status(): number | null;
error(): string;
}
type HTTPCallback = (res: HTTPResponse) => void;
class HTTPRequest implements ISharedResource {
on_success(callback: HTTPCallback): void;
on_error(callback: HTTPCallback): void;
finally(callback: () => void): void;
set_timeout(millis: number): void;
set_payload(data: string): void;
set_header(name: string, value: string): void;
execute(): void;
// might error
static create(method: HTTPMethod, url: string): HTTPRequest;
}
function log(level: LogLevel, ...data: any[]): void;
function register_command(
name: String,
docs/plugin-meta.lua
+83 -1
View File
@@ -5,7 +5,6 @@
-- Add the folder this file is in to "Lua.workspace.library".
c2 = {}
---@alias c2.LogLevel integer
---@type { Debug: c2.LogLevel, Info: c2.LogLevel, Warning: c2.LogLevel, Critical: c2.LogLevel }
c2.LogLevel = {}
@@ -159,6 +158,89 @@ function c2.Channel.by_twitch_id(id) end
-- End src/controllers/plugins/api/ChannelRef.hpp
-- Begin src/controllers/plugins/api/HTTPRequest.hpp
---@class HTTPResponse
---@field data string Data received from the server
---@field status integer? HTTP Status code returned by the server
---@field error string A somewhat human readable description of an error if such happened
---@alias HTTPCallback fun(result: HTTPResponse): nil
---@class HTTPRequest
HTTPRequest = {}
--- Sets the success callback
---
---@param callback HTTPCallback Function to call when the HTTP request succeeds
function HTTPRequest:on_success(callback) end
--- Sets the failure callback
---
---@param callback HTTPCallback Function to call when the HTTP request fails or returns a non-ok status
function HTTPRequest:on_error(callback) end
--- Sets the finally callback
---
---@param callback fun(): nil Function to call when the HTTP request finishes
function HTTPRequest:finally(callback) end
--- Sets the timeout
---
---@param timeout integer How long in milliseconds until the times out
function HTTPRequest:set_timeout(timeout) end
--- Sets the request payload
---
---@param data string
function HTTPRequest:set_payload(data) end
--- Sets a header in the request
---
---@param name string
---@param value string
function HTTPRequest:set_header(name, value) end
--- Executes the HTTP request
---
function HTTPRequest:execute() end
--- Creates a new HTTPRequest
---
---@param method HTTPMethod Method to use
---@param url string Where to send the request to
---@return HTTPRequest
function HTTPRequest.create(method, url) end
-- End src/controllers/plugins/api/HTTPRequest.hpp
-- Begin src/controllers/plugins/api/HTTPResponse.hpp
---@class HTTPResponse
HTTPResponse = {}
--- Returns the data. This is not guaranteed to be encoded using any
--- particular encoding scheme. It's just the bytes the server returned.
---
function HTTPResponse:data() end
--- Returns the status code.
---
function HTTPResponse:status() end
--- A somewhat human readable description of an error if such happened
---
function HTTPResponse:error() end
-- End src/controllers/plugins/api/HTTPResponse.hpp
-- Begin src/common/network/NetworkCommon.hpp
---@alias HTTPMethod integer
---@type { Get: HTTPMethod, Post: HTTPMethod, Put: HTTPMethod, Delete: HTTPMethod, Patch: HTTPMethod }
HTTPMethod = {}
-- End src/common/network/NetworkCommon.hpp
--- Registers a new command called `name` which when executed will call `handler`.
---
---@param name string The name of the command.
docs/wip-plugins.md
+150
View File
@@ -85,6 +85,24 @@ Example:
}
```
### Network
Allows the plugin to send HTTP requests.
Example:
```json
{
...,
"permissions": [
{
"type": "Network"
},
...
]
}
```
## Plugins with Typescript
If you prefer, you may use [TypescriptToLua](https://typescripttolua.github.io)
@@ -370,6 +388,138 @@ Returns `true` if the channel can be moderated by the current user.
Returns `true` if the current user is a VIP in the channel.
#### `HTTPMethod` enum
This table describes HTTP methods available to Lua Plugins. The values behind
the names may change, do not count on them. It has the following keys:
- `Get`
- `Post`
- `Put`
- `Delete`
- `Patch`
#### `HTTPResponse`
An `HTTPResponse` is a table you receive in the callback after a completed `HTTPRequest`.
##### `HTTPResponse.data()`
This function returns the data received from the server as a string. Usually
this will be UTF-8-encoded however that is not guaranteed, this could be any
binary data.
##### `HTTPResponse.error()`
If an error happened this function returns a human readable description of it.
It returns something like: `"ConnectionRefusedError"`, `"401"`.
##### `HTTPResponse.status()`
This function returns the HTTP status code of the request or `nil` if there was
an error before a status code could be received.
```lua
{
data = "This is the data received from the server as a string",
status = 200, -- HTTP status code returned by the server or nil if no response was received because of an error
error = "A somewhat human readable description of an error if such happened"
}
```
#### `HTTPRequest`
Allows you to send an HTTP request to a URL. Do not create requests that you
don't want to call `execute()` on. For the time being that leaks callback
functions and all their upvalues with them.
##### `HTTPRequest.create(method, url)`
Creates a new `HTTPRequest`. The `method` argument is an
[`HTTPMethod`](#HTTPMethod-enum). The `url` argument must be a string
containing a valid URL (ex. `https://example.com/path/to/api`).
```lua
local req = c2.HTTPRequest.create(c2.HTTPMethod.Get, "https://example.com")
req:on_success(function (res)
print(res.data)
end)
req:execute()
```
##### `HTTPRequest:on_success(callback)`
Sets the success callback. It accepts a function that takes a single parameter
of type `HTTPResponse`. The callback will be called on success. This function
returns nothing.
##### `HTTPRequest:on_error(callback)`
Sets the error callback. It accepts a function that takes a single parameter of
type `HTTPResponse`. The callback will be called if the request fails. To see why
it failed check the `error` field of the result. This function returns nothing.
##### `HTTPRequest:finally(callback)`
Sets the finally callback. It accepts a function that takes no parameters and
returns nothing. It will be always called after `success` or `error`. This
function returns nothing.
##### `HTTPRequest:set_timeout(timeout)`
Sets how long the request will take before it times out. The `timeout`
parameter is in milliseconds. This function returns nothing.
##### `HTTPRequest:set_payload(data)`
Sets the data that will be sent with the request. The `data` parameter must be
a string. This function returns nothing.
##### `HTTPRequest:set_header(name, value)`
Adds or overwrites a header in the request. Both `name` and `value` should be
strings. If they are not strings they will be converted to strings. This
function returns nothing.
##### `HTTPRequest:execute()`
Sends the request. This function returns nothing.
```lua
local url = "http://localhost:8080/thing"
local request = c2.HTTPRequest.create("Post", url)
request:set_timeout(1000)
request:set_payload("TEST!")
request:set_header("X-Test", "Testing!")
request:set_header("Content-Type", "text/plain")
request:on_success(function (res)
print('Success!')
-- Data is in res.data
print(res.status)
end)
request:on_error(function (res)
print('Error!')
print(res.status)
print(res.error)
end)
request:finally(function ()
print('Finally')
end)
request:execute()
-- This prints:
-- Success!
-- [content of /thing]
-- 200
-- Finally
-- Or:
-- Error!
-- nil
-- ConnectionRefusedError
```
### Input/Output API
These functions are wrappers for Lua's I/O library. Functions on file pointer