gmsv_reqwest

https://github.com/williamvenner/gmsv_reqwest
Admin
A Garry's Mod binary module written in Rust that provides a robust, drop-in replacement for the...
Tokens:8,411
Snippets:25
Trust Score:9.3
License:MIT
Update:11 months ago
Show doc for...
Tokens:
Raw
### HTTPRequest Structure - GET with Query Parameters

Source: https://context7.com/williamvenner/gmsv_reqwest/llms.txt

Demonstrates how to perform HTTP GET requests with URL-encoded form parameters. When no request body is provided, the `parameters` field is automatically converted and appended to the URL.

```APIDOC
## HTTPRequest Structure - GET with Query Parameters

### Description
Performs HTTP GET requests with URL-encoded form parameters. When no body is provided, the parameters field is automatically converted to form-encoded data and appended to the request.

### Method
GET

### Endpoint
N/A (handled internally by the module)

### Parameters
#### Path Parameters
None

#### Query Parameters
None (these are passed via the `parameters` field in the HTTPRequest table for GET requests)

#### Request Body
- **HTTPRequest** (table) - Required - A table containing request details:
  - **method** (string) - Must be "GET".
  - **url** (string) - Required - The base URL for the GET request.
  - **parameters** (table) - Required for GET with query parameters - A table of key-value pairs to be form-encoded and appended to the URL.
  - **timeout** (number) - Optional - Request timeout in seconds.
  - **success** (function) - Optional - Callback function for successful requests.
  - **failed** (function) - Optional - Callback function for failed requests.

### Request Example
```lua
require("reqwest")

reqwest({
    method = "GET",
    url = "https://api.steam.com/ISteamUser/GetPlayerSummaries/v2/",
    timeout = 15,
    parameters = {
        key = "YOUR_STEAM_API_KEY",
        steamids = "76561197960435530,76561197960435531"
    },
    success = function(status, body, headers)
        if status == 200 then
            local response = util.JSONToTable(body)
            for _, player in ipairs(response.response.players) do
                print(player.personaname .. " - " .. player.profileurl)
            end
        end
    end,
    failed = function(err, errExt)
        ErrorNoHalt("Steam API request failed: " .. errExt)
    end
})
```

### Response
#### Success Response (200)
- **status** (number) - The HTTP status code (e.g., 200).
- **body** (string) - The JSON response body from the API.
- **headers** (table) - A table of response headers.

#### Response Example (in success callback)
```lua
-- Inside the success callback:
-- PlayerName1 - https://steamcommunity.com/id/profile1/
-- PlayerName2 - https://steamcommunity.com/id/profile2/
```
```

--------------------------------

### Complete REST API Integration with Reqwest in Lua

Source: https://context7.com/williamvenner/gmsv_reqwest/llms.txt

This Lua script demonstrates a full REST API integration pattern using the `reqwest` library for Garry's Mod. It includes authentication, request configuration (method, URL, timeout, headers, body), and handles both successful responses and network failures. The example shows how to structure an API wrapper and use it to update player statistics, with callbacks for processing results or errors.

```lua
require("reqwest")

-- API wrapper with authentication and error handling
local GameAPI = {}
GameAPI.base_url = "https://api.gameserver.com/v1"
GameAPI.api_key = "your_api_key_here"

function GameAPI:Request(endpoint, method, data, callback)
    local url = self.base_url .. endpoint
    local body = data and util.TableToJSON(data) or nil

    reqwest({
        method = method or "GET",
        url = url,
        timeout = 30,
        body = body,
        type = "application/json",

        headers = {
            ["Authorization"] = "Bearer " .. self.api_key,
            ["X-Server-ID"] = game.GetIPAddress(),
            ["User-Agent"] = "GMod-Server/1.0"
        },

        success = function(status, body, headers)
            if status >= 200 and status < 300 then
                local response = util.JSONToTable(body)
                callback(true, response, status)
            else
                callback(false, "HTTP " .. status .. ": " .. body, status)
            end
        end,

        failed = function(err, errExt)
            callback(false, "Request failed: " .. errExt, 0)
        end
    })
end

-- Usage example: Update player stats
function UpdatePlayerStats(ply)
    GameAPI:Request("/players/update", "POST", {
        steam_id = ply:SteamID64(),
        kills = ply:Frags(),
        deaths = ply:Deaths(),
        playtime = ply:TimeConnected()
    }, function(success, response, status)
        if success then
            print("Stats updated for " .. ply:Nick())
            print("New rank: " .. response.rank)
            print("Total score: " .. response.total_score)
            -- Expected output:
            -- Stats updated for PlayerName
            -- New rank: Gold III
            -- Total score: 15420
        else
            ErrorNoHalt("Failed to update stats: " .. response)
            -- Example output:
            -- Failed to update stats: Request failed: connection timeout
        end
    end)
end

-- Hook into player disconnect to save stats
hook.Add("PlayerDisconnected", "SavePlayerStats", function(ply)
    UpdatePlayerStats(ply)
end)

```

--------------------------------

### Lua: Implement Fallback HTTP Module Interface

Source: https://context7.com/williamvenner/gmsv_reqwest/llms.txt

Provides a robust pattern for using either the `gmsv_reqwest` or `gmsv_chttp` module for HTTP requests. It attempts to load `reqwest` first, then falls back to `chttp`, offering a unified interface regardless of availability. This ensures consistent HTTP functionality across different server setups.

```lua
-- Automatic detection and loading of available HTTP modules
if not reqwest and not CHTTP then
    local suffix = ({"osx64", "osx", "linux64", "linux", "win64", "win32"})[
        (system.IsWindows() and 4 or 0) +
        (system.IsLinux() and 2 or 0) +
        (jit.arch == "x86" and 1 or 0) + 1
    ]

    local fmt = "lua/bin/gm" .. (CLIENT and "cl" or "sv") .. "_%s_%s.dll"

    local function installed(name)
        if file.Exists(string.format(fmt, name, suffix), "GAME") then
            return true
        end
        if jit.versionnum ~= 20004 and jit.arch == "x86" and system.IsLinux() then
            return file.Exists(string.format(fmt, name, "linux32"), "GAME")
        end
        return false
    end

    if installed("reqwest") then
        require("reqwest")
    end
    if not reqwest and installed("chttp") then
        require("chttp")
    end
    if not CHTTP and not reqwest then
        error("reqwest or CHTTP is required!")
    end
end

-- Unified HTTP interface
local HTTP = reqwest or CHTTP

-- Now use HTTP() consistently regardless of implementation
HTTP({
    url = "https://example.com/api",
    success = function(status, body, headers)
        print("Loaded with " .. (reqwest and "reqwest" or "CHTTP"))
        print("Status: " .. status)
    end,
    failed = function(err, errExt)
        print("Error: " .. (errExt or err))
    end
})
```

--------------------------------

### Blocking HTTP GET Request (Lua)

Source: https://context7.com/williamvenner/gmsv_reqwest/llms.txt

Executes a synchronous HTTP GET request that blocks the main thread until completion. Results are returned directly. This mode is useful for initialization but should be used sparingly. Callbacks can still be defined.

```lua
require("reqwest")

-- Blocking GET request with immediate return values
local success, status, body, headers = reqwest({
    blocking = true,
    url = "https://api.example.com/server/status",
    timeout = 10,

    headers = {
        ["API-Key"] = "your_api_key_here"
    },

    -- Callbacks still work with blocking mode
    success = function(status, body, headers)
        print("Callback executed: " .. status)
    end,
    failed = function(err, errExt)
        print("Callback error: " .. errExt)
    end
})

if success then
    print("HTTP " .. status)
    local data = util.JSONToTable(body)
    PrintTable(data)
    -- Expected output:
    -- HTTP 200
    -- {
    --   players = 24,
    --   maxplayers = 32,
    --   map = "gm_construct"
    -- }
else
    local err, errExt = status, body
    print("Request failed: " .. err .. " - " .. errExt)
    -- Example output:
    -- Request failed: unsuccessful - DNS resolution failed
end
```

--------------------------------

### Discord Webhook Request Example with gmsv_reqwest

Source: https://github.com/williamvenner/gmsv_reqwest/blob/master/README.md

This Lua example demonstrates how to send a POST request to a Discord webhook using the 'reqwest' module. It includes setting the method, URL, timeout, request body (as JSON), content type, headers (including a required User-Agent), and defines callbacks for success and failure scenarios. The 'errExt' parameter provides extended error information on failure.

```lua
require("reqwest")

reqwest({
    method = "POST",
    url = "https://discord.com/api/webhooks/988854737435070417/pHbHIjR15oa4ZmJ1PMCwEPaK4hdlCC21AIme94Iw9Xh7M9Mhg6GLLV2u6Q1rppH_7esX",
    timeout = 30,
    
    body = util.TableToJSON({ content = "Hello, world!" }), -- https://discord.com/developers/docs/resources/webhook#execute-webhook
    type = "application/json",

    headers = {
        ["User-Agent"] = "My User Agent", -- This is REQUIRED to dispatch a Discord webhook
    },

    success = function(status, body, headers) 
        print("HTTP " .. status)
        PrintTable(headers)
        print(body)
    end,

    failed = function(err, errExt) 
        print("Error: " .. err .. " (" .. errExt .. ")")
    end
})
```

--------------------------------

### HTTP GET Request with Query Parameters (Lua)

Source: https://context7.com/williamvenner/gmsv_reqwest/llms.txt

Performs an HTTP GET request with URL-encoded form parameters appended to the URL. This is useful for APIs that accept parameters in the query string. The `parameters` field is automatically converted and appended.

```lua
require("reqwest")

-- GET request with query parameters
reqwest({
    method = "GET",
    url = "https://api.steam.com/ISteamUser/GetPlayerSummaries/v2/",
    timeout = 15,

    parameters = {
        key = "YOUR_STEAM_API_KEY",
        steamids = "76561197960435530,76561197960435531"
    },

    success = function(status, body, headers)
        if status == 200 then
            local response = util.JSONToTable(body)
            for _, player in ipairs(response.response.players) do
                print(player.personaname .. " - " .. player.profileurl)
            end
            -- Expected output:
            -- PlayerName1 - https://steamcommunity.com/id/profile1/
            -- PlayerName2 - https://steamcommunity.com/id/profile2/
        end
    end,

    failed = function(err, errExt)
        ErrorNoHalt("Steam API request failed: " .. errExt)
    end
})
```

--------------------------------

### Fallback HTTP Implementation

Source: https://context7.com/williamvenner/gmsv_reqwest/llms.txt

Illustrates a pattern for automatically detecting and loading either `gmsv_reqwest` or `gmsv_chttp`, providing a unified interface regardless of which module is available.

```APIDOC
## Fallback HTTP Implementation

### Description
This pattern demonstrates how to create a robust HTTP interface by attempting to load `gmsv_reqwest` first and falling back to `gmsv_chttp` if `reqwest` is not available. This ensures a consistent API for making HTTP requests, regardless of which module is installed on the server.

### Method
N/A (Code snippet demonstrates module loading logic)

### Endpoint
N/A (Applies to any HTTP request made using the unified interface)

### Parameters
N/A

### Request Example
```lua
-- Automatic detection and loading of available HTTP modules
if not reqwest and not CHTTP then
    local suffix = ({"osx64", "osx", "linux64", "linux", "win64", "win32"})[
        (system.IsWindows() and 4 or 0) +
        (system.IsLinux() and 2 or 0) +
        (jit.arch == "x86" and 1 or 0) + 1
    ]

    local fmt = "lua/bin/gm" .. (CLIENT and "cl" or "sv") .. "_%s_%s.dll"

    local function installed(name)
        if file.Exists(string.format(fmt, name, suffix), "GAME") then
            return true
        end
        if jit.versionnum ~= 20004 and jit.arch == "x86" and system.IsLinux() then
            return file.Exists(string.format(fmt, name, "linux32"), "GAME")
        end
        return false
    end

    if installed("reqwest") then
        require("reqwest")
    end
    if not reqwest and installed("chttp") then
        require("chttp")
    end
    if not CHTTP and not reqwest then
        error("reqwest or CHTTP is required!")
    end
end

-- Unified HTTP interface
local HTTP = reqwest or CHTTP

-- Now use HTTP() consistently regardless of implementation
HTTP({
    url = "https://example.com/api",
    success = function(status, body, headers)
        print("Loaded with " .. (reqwest and "reqwest" or "CHTTP") .. ".")
        print("Status: " .. status)
    end,
    failed = function(err, errExt)
        print("Error: " .. (errExt or err))
    end
})
```

### Response
N/A (This code snippet sets up a unified HTTP interface and demonstrates its usage. The actual response depends on the `https://example.com/api` endpoint.)
```

--------------------------------

### Custom TLS Certificate Loading

Source: https://context7.com/williamvenner/gmsv_reqwest/llms.txt

Explains how the module automatically loads custom root certificates from a specified directory, enabling secure connections to servers with self-signed or custom certificate authorities.

```APIDOC
## Custom TLS Certificate Loading

### Description
The `gmsv_reqwest` module automatically loads custom root certificates from the `garrysmod/tls_certificates/client` directory. It supports both PEM and DER encoded X509 certificates, allowing connections to servers that use self-signed certificates or custom certificate authorities.

No explicit Lua code is required to load the certificates; they are loaded automatically when the module is initialized.

### Directory Structure
```
garrysmod/
└── tls_certificates/
    └── client/
        ├── custom_ca.pem
        ├── self_signed.der
        └── corporate_root.pem
```

All valid certificates placed in the `garrysmod/tls_certificates/client` directory will be automatically loaded. Invalid certificates will be skipped, and a warning will be printed to the console (e.g., `[gmsv_reqwest] Error loading certificate "invalid.pem": invalid certificate extension`).

### Method
N/A (Automatic loading)

### Endpoint
N/A (Applies to all HTTPS requests)

### Parameters
N/A

### Request Example
```lua
require("reqwest")

-- Example of making a request to an internal server with a custom certificate
reqwest({
    url = "https://internal-server.company.local/api/data",
    success = function(status, body, headers)
        print("Successfully connected to internal server")
        print("Response: " .. body)
    end,
    failed = function(err, errExt)
        print("TLS Error: " .. errExt)
        -- This would fail without the custom certificate being loaded:
        -- TLS Error: invalid certificate: UnknownIssuer
    end
})
```

### Response
N/A (Success/Failure depends on the target API endpoint after successful TLS handshake)
```

--------------------------------

### Lua: Send POST Request with Custom Headers and Body

Source: https://context7.com/williamvenner/gmsv_reqwest/llms.txt

Sends a POST request with custom headers, raw body data, and automatically sets the Content-Type. It ensures a User-Agent header is present, defaulting to Valve's Steam client if not specified. The `reqwest` library is required for this functionality.

```lua
require("reqwest")

-- POST request with custom content type and headers
reqwest({
    method = "POST",
    url = "https://api.example.com/data/submit",
    timeout = 20,

    body = '<?xml version="1.0"?><data><item>value</item></data>',
    type = "application/xml",

    headers = {
        ["User-Agent"] = "GMod-Server/4.0",
        ["X-API-Version"] = "2",
        ["X-Request-ID"] = "req_" .. os.time()
    },

    success = function(status, body, headers) 
        print("Status: " .. status)
        print("Content-Type: " .. (headers["content-type"] or "unknown"))
        print("Response: " .. body)
        -- Expected output:
        -- Status: 201
        -- Content-Type: application/json
        -- Response: {"id": "12345", "status": "created"}
    end,

    failed = function(err, errExt)
        print("Failed: " .. errExt)
    end
})
```

--------------------------------

### Lua: Connect to Internal Server with Custom TLS Certificates

Source: https://context7.com/williamvenner/gmsv_reqwest/llms.txt

Connects to servers using custom or self-signed TLS certificates by automatically loading certificates from the `garrysmod/tls_certificates/client` directory. This enables secure connections to internal services. The `reqwest` library is required, and no explicit Lua code is needed to load the certificates themselves as it's handled on module initialization.

```lua
-- No Lua code required - certificates are loaded automatically at module initialization
--
-- Directory structure:
-- garrysmod/
-- └── tls_certificates/
--     └── client/
--         ├── custom_ca.pem
--         ├── self_signed.der
--         └── corporate_root.pem
--
-- All valid certificates in this directory are automatically loaded when the module starts.
-- Invalid certificates are skipped with a console warning:
-- [gmsv_reqwest] Error loading certificate "invalid.pem": invalid certificate extension
--
-- Example usage after certificates are loaded:

require("reqwest")

reqwest({
    url = "https://internal-server.company.local/api/data",
    success = function(status, body, headers)
        print("Successfully connected to internal server")
        print("Response: " .. body)
        -- Expected output:
        -- Successfully connected to internal server
        -- Response: {"internal": "data"}
    end,
    failed = function(err, errExt)
        print("TLS Error: " .. errExt)
        -- Would fail without custom certificate:
        -- TLS Error: invalid certificate: UnknownIssuer
    end
})
```

--------------------------------

### Load gmsv_reqwest or gmsv_chttp

Source: https://github.com/williamvenner/gmsv_reqwest/blob/master/README.md

This Lua code prioritizes loading either the 'reqwest' module or 'chttp' module if they are available. It includes logic to determine the correct file suffix based on the operating system and architecture. If neither module is found, it throws an error, ensuring that an HTTP module is available for subsequent code.

```lua
if not reqwest and not CHTTP then
    local suffix = ({"osx64", "osx", "linux64", "linux", "win64", "win32"})[(system.IsWindows() and 4 or 0) + (system.IsLinux() and 2 or 0) + (jit.arch == "x86" and 1 or 0) + 1]
    local fmt = "lua/bin/gm" .. (CLIENT and "cl" or "sv") .. "_%s_%s.dll"
    local function installed(name) 
        if file.Exists(string.format(fmt, name, suffix), "GAME") then return true end
        if jit.versionnum ~= 20004 and jit.arch == "x86" and system.IsLinux() then return file.Exists(string.format(fmt, name, "linux32"), "GAME") end
        return false
    end

    if installed("reqwest") then
        require("reqwest")
    end
    if not reqwest and installed("chttp") then
        require("chttp")
    end
    if not CHTTP then 
        error("reqwest or CHTTP is required to use this!")
    end
end

local HTTP = reqwest or CHTTP

-- Your code
```

--------------------------------

### Module Version Detection

Source: https://context7.com/williamvenner/gmsv_reqwest/llms.txt

Details how to access the module's version string, `REQWEST_VERSION`, for compatibility checks and feature detection in Lua scripts.

```APIDOC
## Module Version Detection

### Description
The `gmsv_reqwest` module exposes a global string variable named `REQWEST_VERSION`. This variable contains the current version of the loaded module, which is useful for performing compatibility checks and detecting the availability of specific features.

### Method
N/A (Accessing a global variable)

### Endpoint
N/A

### Parameters
N/A

### Request Example
```lua
require("reqwest")

-- Print the loaded reqwest version
print("Loaded reqwest version: " .. REQWEST_VERSION)
-- Expected output: Loaded reqwest version: 4.0.0

-- Example of version-based feature detection
local version_parts = string.Split(REQWEST_VERSION, ".")
local major_version = tonumber(version_parts[1])

if major_version >= 4 then
    print("Blocking mode supported")
    -- Use blocking features available in version 4.0.0 and later
else
    print("Legacy version, using callbacks only")
    -- Fallback to callback-only mode for older versions
end
```

### Response
N/A (This is for querying module information, not making external API calls)
```

--------------------------------

### Garry's Mod System Information Check

Source: https://github.com/williamvenner/gmsv_reqwest/blob/master/README.md

This Lua snippet prints the operating system and architecture of the Garry's Mod server. It checks if the system is Windows or Linux, and the JIT architecture (x86-64 or x86), providing a string that combines these details. This is useful for debugging or ensuring compatibility.

```lua
lua_run print((system.IsWindows()and"Windows"or system.IsLinux()and"Linux"or"Unsupported").." "..(jit.arch=="x64"and"x86-64"or"x86"))
```

--------------------------------

### reqwest() - Blocking HTTP Request

Source: https://context7.com/williamvenner/gmsv_reqwest/llms.txt

Executes a synchronous HTTP request that halts the main thread until completion, returning results directly. Use this mode cautiously for initialization or critical operations requiring immediate feedback.

```APIDOC
## reqwest() - Blocking HTTP Request

### Description
Executes a synchronous HTTP request that blocks the main thread until completion, returning results directly instead of using callbacks. This mode is useful for initialization or critical operations where you need immediate results, but should be used sparingly to avoid freezing the server.

### Method
GET (or other methods as specified in HTTPRequest)

### Endpoint
N/A (handled internally by the module)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **HTTPRequest** (table) - Required - A table containing request details (same structure as asynchronous mode, but `blocking = true` is key):
  - **blocking** (boolean) - Required - Set to `true` for blocking requests.
  - **url** (string) - Required - The URL to send the request to.
  - **timeout** (number) - Optional - Request timeout in seconds.
  - **headers** (table) - Optional - A table of custom headers.
  - **parameters** (table) - Optional - Form parameters for GET requests.
  - **success** (function) - Optional - Callback function that will still be called even in blocking mode.
  - **failed** (function) - Optional - Callback function that will still be called even in blocking mode.

### Request Example
```lua
require("reqwest")

local success, status, body, headers = reqwest({
    blocking = true,
    url = "https://api.example.com/server/status",
    timeout = 10,
    headers = {
        ["API-Key"] = "your_api_key_here"
    },
    success = function(status, body, headers)
        print("Callback executed: " .. status)
    end,
    failed = function(err, errExt)
        print("Callback error: " .. errExt)
    end
})

if success then
    print("HTTP " .. status)
    local data = util.JSONToTable(body)
    PrintTable(data)
else
    local err, errExt = status, body
    print("Request failed: " .. err .. " - " .. errExt)
end
```

### Response
#### Success Response (Direct Return)
- **success** (boolean) - `true` if the request was successful.
- **status** (number) - The HTTP status code (if `success` is `true`).
- **body** (string) - The response body (if `success` is `true`).
- **headers** (table) - A table of response headers (if `success` is `true`).

#### Response Example (Direct Return)
```lua
-- If successful:
-- HTTP 200
-- {
--   players = 24,
--   maxplayers = 32,
--   map = "gm_construct"
-- }
```

#### Error Response (Direct Return)
- **success** (boolean) - `false` if the request failed.
- **status** (string) - An error message (if `success` is `false`).
- **body** (string) - Extended error details (if `success` is `false`).

#### Error Response Example (Direct Return)
```lua
-- If failed:
-- Request failed: unsuccessful - DNS resolution failed
```
```

--------------------------------

### Lua: Detect and Use Reqwest Module Version

Source: https://context7.com/williamvenner/gmsv_reqwest/llms.txt

Checks the version of the `gmsv_reqwest` module using the global `REQWEST_VERSION` string. This allows for compatibility checks and feature detection, enabling fallback logic for older versions or ensuring specific features are available.

```lua
require("reqwest")

print("Loaded reqwest version: " .. REQWEST_VERSION)
-- Expected output: Loaded reqwest version: 4.0.0

-- Version-based feature detection
local version_parts = string.Split(REQWEST_VERSION, ".")
local major_version = tonumber(version_parts[1])

if major_version >= 4 then
    print("Blocking mode supported")
    -- Use blocking features
else
    print("Legacy version, using callbacks only")
    -- Fallback to callback-only mode
end
```

--------------------------------

### POST Request with Custom Headers

Source: https://context7.com/williamvenner/gmsv_reqwest/llms.txt

Demonstrates how to send a POST request with custom headers and a raw body. The Content-Type is automatically set based on the 'type' field, and a User-Agent header is enforced.

```APIDOC
## POST /data/submit

### Description
Sends a POST request to the specified URL with custom headers and raw body data. The Content-Type is automatically determined by the `type` field in the configuration, and the module ensures a `User-Agent` header is included.

### Method
POST

### Endpoint
`https://api.example.com/data/submit`

### Parameters
#### Request Body
- **body** (string) - Required - The raw data to send in the request body. Example: `"<?xml version=\"1.0\"?><data><item>value</item></data>"`
- **type** (string) - Required - The Content-Type for the request. Example: `"application/xml"`
- **method** (string) - Required - Must be set to `"POST"`.
- **url** (string) - Required - The target URL for the request.
- **timeout** (number) - Optional - The request timeout in seconds. Example: `20`
- **headers** (table) - Optional - A table of custom headers to include in the request.
  - **User-Agent** (string) - Optional - The User-Agent string. Defaults to Valve's Steam client if not specified.
  - **X-API-Version** (string) - Example: `"2"`
  - **X-Request-ID** (string) - Example: `"req_" .. os.time()`
- **success** (function) - Optional - Callback function executed on successful request.
  - Parameters: `status` (number), `body` (string), `headers` (table)
- **failed** (function) - Optional - Callback function executed on failed request.
  - Parameters: `err` (string), `errExt` (string)

### Request Example
```lua
reqwest({
    method = "POST",
    url = "https://api.example.com/data/submit",
    timeout = 20,
    body = '<?xml version="1.0"?><data><item>value</item></data>',
    type = "application/xml",
    headers = {
        ["User-Agent"] = "GMod-Server/4.0",
        ["X-API-Version"] = "2",
        ["X-Request-ID"] = "req_" .. os.time()
    },
    success = function(status, body, headers)
        print("Status: " .. status)
        print("Content-Type: " .. (headers["content-type"] or "unknown"))
        print("Response: " .. body)
    end,
    failed = function(err, errExt)
        print("Failed: " .. errExt)
    end
})
```

### Response
#### Success Response (201)
- **id** (string) - The identifier of the created resource.
- **status** (string) - The status of the creation operation.

#### Response Example
```json
{
  "id": "12345",
  "status": "created"
}
```
```

--------------------------------

### reqwest() - Asynchronous HTTP Request

Source: https://context7.com/williamvenner/gmsv_reqwest/llms.txt

Performs a non-blocking HTTP request using callbacks for result handling. The request is sent to a background thread, preventing the main game server thread from freezing.

```APIDOC
## reqwest() - Asynchronous HTTP Request

### Description
Performs a non-blocking HTTP request with callback-based result handling. The function accepts an HTTPRequest table and dispatches the request to a background worker thread, allowing the game server to continue processing without blocking the main thread.

### Method
POST (or other methods as specified in HTTPRequest)

### Endpoint
N/A (handled internally by the module)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **HTTPRequest** (table) - Required - A table containing request details:
  - **method** (string) - Required - The HTTP method (e.g., "GET", "POST").
  - **url** (string) - Required - The URL to send the request to.
  - **timeout** (number) - Optional - Request timeout in seconds.
  - **body** (string) - Optional - The request body content.
  - **type** (string) - Optional - The Content-Type of the request body (e.g., "application/json").
  - **headers** (table) - Optional - A table of custom headers.
  - **parameters** (table) - Optional - Form parameters for GET requests.
  - **success** (function) - Optional - Callback function for successful requests.
  - **failed** (function) - Optional - Callback function for failed requests.

### Request Example
```lua
require("reqwest")

reqwest({
    method = "POST",
    url = "https://discord.com/api/webhooks/123456789/abcdefg",
    timeout = 30,
    body = util.TableToJSON({
        content = "Player connected!",
        embeds = {{title = "Server Event", description = "A new player has joined", color = 3447003}}
    }),
    type = "application/json",
    headers = {
        ["User-Agent"] = "GMod Server/1.0",
        ["Authorization"] = "Bearer token_here"
    },
    success = function(status, body, headers)
        print("HTTP " .. status)
        print("Response body: " .. body)
        PrintTable(headers)
    end,
    failed = function(err, errExt)
        print("Error: " .. err)
        print("Extended error: " .. errExt)
    end
})
```

### Response
#### Success Response (Callback)
- **status** (number) - The HTTP status code.
- **body** (string) - The response body.
- **headers** (table) - A table of response headers.

#### Response Example (in success callback)
```lua
-- Inside the success callback:
-- HTTP 204
-- Response body: (empty for Discord webhooks)
-- headers table with content-type, date, etc.
```

#### Error Response (Callback)
- **err** (string) - A general error message.
- **errExt** (string) - Extended error details.

#### Error Response Example (in failed callback)
```lua
-- Inside the failed callback:
-- Error: unsuccessful
-- Extended error: connection timeout
```
```

--------------------------------

### Async HTTP POST Request with JSON Body (Lua)

Source: https://context7.com/williamvenner/gmsv_reqwest/llms.txt

Performs an asynchronous HTTP POST request using the reqwest module. This function dispatches the request to a background thread, allowing the game server to continue processing. It handles JSON request bodies and provides callback functions for success and failure.

```lua
require("reqwest")

-- Discord webhook POST request with JSON body
reqwest({
    method = "POST",
    url = "https://discord.com/api/webhooks/123456789/abcdefg",
    timeout = 30,

    body = util.TableToJSON({
        content = "Player connected!",
        embeds = {{ 
            title = "Server Event",
            description = "A new player has joined",
            color = 3447003
        }}
    }),
    type = "application/json",

    headers = {
        ["User-Agent"] = "GMod Server/1.0",
        ["Authorization"] = "Bearer token_here"
    },

    success = function(status, body, headers)
        print("HTTP " .. status)
        print("Response body: " .. body)
        PrintTable(headers)
        -- Expected output:
        -- HTTP 204
        -- Response body: (empty for Discord webhooks)
        -- headers table with content-type, date, etc.
    end,

    failed = function(err, errExt)
        print("Error: " .. err)
        print("Extended error: " .. errExt)
        -- Example output:
        -- Error: unsuccessful
        -- Extended error: connection timeout
    end
})
```

--------------------------------

### Check and Override Garry's Mod HTTP Function

Source: https://github.com/williamvenner/gmsv_reqwest/blob/master/README.md

This Lua snippet checks if the 'reqwest' module is available and assigns it to 'my_http'. If 'reqwest' is not found, it falls back to using the default Garry's Mod 'HTTP' function. This allows for seamless integration and fallback mechanisms.

```lua
if pcall(require, "reqwest") and reqwest ~= nil then
    my_http = reqwest
else
    my_http = HTTP
end
```

--------------------------------

### Make Blocking HTTP Request in Lua

Source: https://github.com/williamvenner/gmsv_reqwest/blob/master/README.md

Performs a synchronous HTTP request using gmsv_reqwest. It is crucial to set `blocking = true` to prevent the main thread from being blocked. The function returns success status, and either response data (status, body, headers) or error details (err, errExt). Callbacks are still executed upon completion.

```lua
require("reqwest")

local success, status, body, headers = reqwest({
    blocking = true, -- note this!

    url = "https://google.com",

    -- callbacks will still be called for blocking requests
    success = function(status, body, headers) PrintTable({status, body, headers}) end,
    failed = function(err, errExt) PrintTable({err, errExt}) end
})
if success then
    print("HTTP " .. status)
    PrintTable(headers)
    print(body)
else
    local err, errExt = status, body
    -- In this case, `status` will be the "error message" that Garry's Mod provides (typically always "unsuccessful")
    --  and `body` will be a custom error message from reqwest which actually describes what the error was.
    print("Error: " .. err .. " (" .. errExt .. ")")
end
```
Tokens:
Raw