# lureq

A simple, developer-friendly HTTP/HTTPS client library for Lua, heavily inspired by Python's requests.

lureq simplifies networking in Lua by abstracting low-level socket operations into clean, intuitive APIs with automatic JSON handling, cookie jar sessions, multipart uploads, and transparent redirects.

---

## Features

- **Intuitive API:** Simple `get()`, `post()`, `put()`, `delete()`, `patch()`, and `head()` methods.
- **HTTPS & HTTP:** Transparent SSL/TLS support via `luasec` and `luasocket`.
- **Query Parameters:** Pass tables as `params` with automatic URL percent-encoding.
- **JSON Support:** Built-in serialization and parsing (`res:json()`).
- **Multipart Uploads:** Seamless file and form data uploads via `multipart/form-data`.
- **Sessions & Cookies:** Persistent `Session` instances with automatic cookie jar management across redirects.
- **Redirects & Timeouts:** Configurable automatic redirect following (301, 302, 303, etc.) and socket timeouts.
- **Case-Insensitive Headers:** Access response headers effortlessly (`res.headers["Content-Type"]` or `res.headers["content-type"]`).

---

Installation

Via LuaRocks

luarocks install lureq

From Source

git clone [https://github.com/valhalla803/lureq.git](https://github.com/valhalla803/lureq.git)
cd lureq
sudo luarocks make

---

Quick Start

Basic GET Request

local lureq = require("lureq")

local res, err = lureq.get("[https://httpbin.org/get](https://httpbin.org/get)", {
    params = { user = "Ahmed", lang = "Lua" },
    headers = { ["User-Agent"] = "lureq-client/0.1" }
})

if res and res.ok then
    print("Status:", res.status_code)
    local data = res:json()
    print("User:", data.args.user)
end

JSON POST Request

local res = lureq.post("[https://httpbin.org/post](https://httpbin.org/post)", {
    json = {
        name = "lureq",
        type = "HTTP Library"
    }
})

print(res.status_code)
print(res:json().json.name)

Multipart File Upload

local res = lureq.post("[https://httpbin.org/post](https://httpbin.org/post)", {
    data = {
        description = "Profile Picture Upload"
    },
    files = {
        avatar = {
            filename = "avatar.png",
            data = "<raw_binary_data>",
            mime_type = "image/png"
        },
        -- Or directly provide a local file path:
        -- document = "/path/to/document.pdf"
    }
})

print(res.status_code)

Persistent Sessions (Cookies)

local s = lureq.session()

-- Cookies returned from set-cookie are automatically stored and resent
s:get("[https://httpbin.org/cookies/set?token=secret123](https://httpbin.org/cookies/set?token=secret123)")

local res = s:get("[https://httpbin.org/cookies](https://httpbin.org/cookies)")
print(res:json().cookies.token) -- "secret123"

---

Configuration Options

Option	Type	Default	Description
params	table	nil	Query parameters to append to URL
headers	table	nil	Custom request headers
json	table	nil	Lua table to encode as JSON body
data	table/string	nil	Form data or raw body string
files	table	nil	File entries for multipart upload
timeout	number	30	Request timeout in seconds
allow_redirects	boolean	true	Follow HTTP redirects automatically
max_redirects	number	5	Maximum number of redirects to follow

---

Running Tests

lua tests/test_basic.lua

---

License

This project is licensed under the MIT License - see the LICENSE file for details.