Introduce HTTP API for plugins

CHANGELOG.md

@@ -14,6 +14,7 @@
 - Minor: Moderators can now see when users are warned. (#5441)
 - Minor: Added support for Brave & google-chrome-stable browsers. (#5452)
 - Minor: Added drop indicator line while dragging in tables. (#5256)
+- Minor: Introduce HTTP API for plugins. (#5383)
 - Bugfix: Fixed tab move animation occasionally failing to start after closing a tab. (#5426)
 - Bugfix: If a network request errors with 200 OK, Qt's error code is now reported instead of the HTTP status. (#5378)
 - Bugfix: Fixed restricted users usernames not being clickable. (#5405)

docs/chatterino.d.ts

@@ -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

@@ -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

@@ -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

scripts/make_luals_meta.py

@@ -41,7 +41,6 @@
 -- Add the folder this file is in to "Lua.workspace.library".
 
 c2 = {}
-
 """
 
 repo_root = Path(__file__).parent.parent

src/CMakeLists.txt

@@ -227,6 +227,10 @@ set(SOURCE_FILES
         controllers/plugins/api/ChannelRef.hpp
         controllers/plugins/api/IOWrapper.cpp
         controllers/plugins/api/IOWrapper.hpp
+        controllers/plugins/api/HTTPRequest.cpp
+        controllers/plugins/api/HTTPRequest.hpp
+        controllers/plugins/api/HTTPResponse.cpp
+        controllers/plugins/api/HTTPResponse.hpp
         controllers/plugins/LuaAPI.cpp
         controllers/plugins/LuaAPI.hpp
         controllers/plugins/PluginPermission.cpp

src/common/network/NetworkCommon.hpp

@@ -15,6 +15,9 @@ using NetworkSuccessCallback = std::function<void(NetworkResult)>;
 using NetworkErrorCallback = std::function<void(NetworkResult)>;
 using NetworkFinallyCallback = std::function<void()>;
 
+/**
+ * @exposeenum HTTPMethod
+ */
 enum class NetworkRequestType {
     Get,
     Post,

src/common/network/NetworkRequest.cpp

@@ -98,6 +98,13 @@ NetworkRequest NetworkRequest::header(QNetworkRequest::KnownHeaders header,
     return std::move(*this);
 }
 
+NetworkRequest NetworkRequest::header(const QByteArray &headerName,
+                                      const QByteArray &value) &&
+{
+    this->data->request.setRawHeader(headerName, value);
+    return std::move(*this);
+}
+
 NetworkRequest NetworkRequest::headerList(
     const std::vector<std::pair<QByteArray, QByteArray>> &headers) &&
 {

src/common/network/NetworkRequest.hpp

@@ -57,6 +57,8 @@ class NetworkRequest final
     NetworkRequest header(const char *headerName, const char *value) &&;
     NetworkRequest header(const char *headerName, const QByteArray &value) &&;
     NetworkRequest header(const char *headerName, const QString &value) &&;
+    NetworkRequest header(const QByteArray &headerName,
+                          const QByteArray &value) &&;
     NetworkRequest header(QNetworkRequest::KnownHeaders header,
                           const QVariant &value) &&;
     NetworkRequest headerList(

src/controllers/plugins/LuaAPI.hpp

@@ -82,6 +82,9 @@ struct CompletionEvent {
 /**
  * @includefile common/Channel.hpp
  * @includefile controllers/plugins/api/ChannelRef.hpp
+ * @includefile controllers/plugins/api/HTTPRequest.hpp
+ * @includefile controllers/plugins/api/HTTPResponse.hpp
+ * @includefile common/network/NetworkCommon.hpp
  */
 
 /**
@@ -133,7 +136,11 @@ int searcherRelative(lua_State *L);
 // This is a fat pointer that allows us to type check values given to functions needing a userdata.
 // Ensure ALL userdata given to Lua are a subclass of this! Otherwise we garbage as a pointer!
 struct UserData {
-    enum class Type { Channel };
+    enum class Type {
+        Channel,
+        HTTPRequest,
+        HTTPResponse,
+    };
     Type type;
     bool isWeak;
 };