https://github.com/bjornbytes/lovr-http
An HTTP library for Lua/LÖVR
https://github.com/bjornbytes/lovr-http
Last synced: 12 months ago
JSON representation
An HTTP library for Lua/LÖVR
- Host: GitHub
- URL: https://github.com/bjornbytes/lovr-http
- Owner: bjornbytes
- License: mit
- Created: 2023-09-07T21:44:17.000Z (almost 3 years ago)
- Default Branch: main
- Last Pushed: 2024-03-28T19:47:19.000Z (about 2 years ago)
- Last Synced: 2024-05-02T00:44:05.012Z (about 2 years ago)
- Language: C
- Size: 50.8 KB
- Stars: 6
- Watchers: 2
- Forks: 0
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
lovr-http
===
A Lua library for performing HTTP(S) requests. It's basically a teeny tiny version of
[lua-https](https://github.com/love2d/lua-https) included by default in [LÖVR](https://lovr.org).
Although lovr's in the name, the library is self-contained and it should work in any Lua program.
Example
---
```lua
http = require 'http'
status, data = http.request('https://zombo.com')
print('welcome')
print(status)
print(data)
```
API
---
The module has one function:
```lua
status, data, headers = http.request(url, [options])
```
### Arguments
`url` is the URL to request. If it doesn't have a protocol, then `http://` will be added.
`options` is optional, and is used for advanced request settings.
`options.method` is the HTTP method to use, also called the verb. `GET` is used by default if
there's no data in the request, otherwise it defauls to `POST`. It will be converted to all-caps.
`options.data` is the data to send to the server, also called the body. It can be a few different
types:
- When `data` is nil, no request body will be sent (and `method` will default to `GET`).
- When `data` is a string, the string will be used directly as the request body.
- When `data` is a table, then pairs in the table will be URL encoded and concatenated together to
form an `application/x-www-form-urlencoded` body. For example, if data is `{ n = 10, k = 'v!' }`,
then the request body will be something like `k=v%21&n=10`. Keys can appear in any order. Table
pairs will only be used if the key is a string and the value is a string or number.
- When `data` is a lightuserdata, the data pointed to by the lightuserdata will be used as the
request body. Additionally, the `datasize` option should be an integer indicating how big the
request body is, in bytes.
When `options.data` is set, the `Content-Type` request header will default to
`application/x-www-urlencoded` unless it's set to something else.
`options.headers` is a table of request headers to send to the server. Pairs in the table will only
be used if the key is a string and the value is a string or number.
### Returns
If an error occurs, the function returns `nil, errormessage`.
Otherwise, 3 values are returned:
- `status` is an integer with the HTTP status code (200 is OK, 404 is Not Found, etc.).
- `data` is a string with the data sent by the server (HTML, JSON, binary, etc.).
- `headers` is a table of response headers.
Limitations
---
- `multipart/form-data` request bodies are not supported.
- Multi-line response headers are not parsed correctly on all platforms.
- There is no way to specify a request timeout, because not all platforms support it.
- There is currently no way to limit or restrict HTTP redirects. Redirects are generally followed.
- Adding credentials in the URL is not supported. Use the `Authorization` request header instead.
- There are differences in behavior between platforms. If you encounter any that are causing you
problems, please open an issue.
- I don't even know what a proxy is but it's probably not going to work.
Compiling
---
The build system is CMake. The CMake script doesn't have any logic to link against Lua yet, so it
will only build properly in LÖVR's `plugins` folder, where it will automatically use LÖVR's copy of
Lua.
Implementation
---
`lovr-http` uses system-provided HTTP libraries:
- Windows uses wininet.
- Linux uses curl (must install e.g. `libcurl4` package, but most systems have it).
- Android uses Java's HttpURLConnection via JNI.
- macOS uses NSURLSession.
The system's certificates are used for HTTPS.
License
---
MIT, see the [LICENSE](./LICENSE) file for details.