https://github.com/bungle/lua-resty-reqargs
Read application/x-www-form-urlencoded, multipart/form-data, and application/json request args
https://github.com/bungle/lua-resty-reqargs
Last synced: 26 days ago
JSON representation
Read application/x-www-form-urlencoded, multipart/form-data, and application/json request args
- Host: GitHub
- URL: https://github.com/bungle/lua-resty-reqargs
- Owner: bungle
- License: bsd-2-clause
- Created: 2015-11-04T11:22:20.000Z (over 9 years ago)
- Default Branch: master
- Last Pushed: 2017-07-14T13:36:40.000Z (almost 8 years ago)
- Last Synced: 2024-02-13T00:46:12.953Z (about 1 year ago)
- Language: Lua
- Homepage:
- Size: 26.4 KB
- Stars: 52
- Watchers: 8
- Forks: 16
- Open Issues: 5
-
Metadata Files:
- Readme: README.md
- Changelog: Changes.md
- License: LICENSE
Awesome Lists containing this project
- awesome-resty - lua-resty-reqargs - www-form-urlencoded, multipart/form-data, and application/json Request Arguments (Libraries)
README
# lua-resty-reqargs
Helper to Retrieve `application/x-www-form-urlencoded`, `multipart/form-data`, and `application/json` Request Arguments.
## Synopsis
```lua
local get, post, files = require "resty.reqargs"()
if not get then
error(post)
end
-- Use get, post, and files...
```
## Installation
Just place [`reqargs.lua`](https://github.com/bungle/lua-resty-reqargs/blob/master/lib/resty/reqargs.lua)
somewhere in your `package.path`, under `resty` directory. If you are using OpenResty, the default location
would be `/usr/local/openresty/lualib/resty`.
### Using OpenResty Package Manager (opm)
```Shell
$ opm get bungle/lua-resty-reqargs
```
### Using LuaRocks
```Shell
$ luarocks install lua-resty-reqargs
```
LuaRocks repository for `lua-resty-reqargs` is located at https://luarocks.org/modules/bungle/lua-resty-reqargs.
## API
This module has only one function, and that function is loaded with require:
```lua
local reqargs = require "resty.reqargs"
```
### get, post, files reqargs(options)
When you call the function (`reqargs`) you can pass it `options`. These
options override whatever you may have defined in your Nginx configuration
(or the defaults). You may use the following options:
```lua
{
tmp_dir = "/tmp",
timeout = 1000,
chunk_size = 4096,
max_get_args = 100,
mas_post_args = 100,
max_line_size = 512,
max_file_size = 10240,
max_file_uploads = 10
}
```
This function will return three (3) return values, and they are called
`get`, `post`, and `files`. These are Lua tables containing the data
that was (HTTP) requested. `get` contains HTTP request GET arguments
retrieved with [ngx.req.get_uri_args](https://github.com/openresty/lua-nginx-module#ngxreqget_uri_args).
`post` contains either HTTP request POST arguments retrieved with
[ngx.req.get_post_args](https://github.com/openresty/lua-nginx-module#ngxreqget_post_args),
or in case of `application/json` (as a content type header for the request),
it will read the request body and decode the JSON, and the `post` will
then contain the decoded JSON structure presented as Lua tables. The
last return value `files` contains all the files uploaded. The `files`
return value will only contain data when there are actually files uploaded
and that the request content type is set to `multipart/form-data`. `files`
has the same structure as `get` and `post` for the keys, but the values
are presented as a Lua tables, that look like this (think about PHP's `$_FILES`):
```lua
{
-- The name of the file upload form field (same as the key)
name = "photo",
-- The name of the file that the user selected for the upload
file = "cat.jpg",
-- The mimetype of the uploaded file
type = "image/jpeg"
-- The file size of the uploaded file (in bytes)
size = 123465
-- The location where the uploaded file was streamed
temp = "/tmp/????"
}
```
In case of error, this function will return `nil`, `error message`.
## Nginx Configuration Variables
You can configure several aspects of `lua-resty-reqargs` directly from
the Nginx configuration, here are the configuration values that you may
use, and their default values:
```nginx
# the default is the system temp dir
set $reqargs_tmp_dir /tmp;
# see https://github.com/openresty/lua-resty-upload
set $reqargs_timeout 1000;
# see https://github.com/openresty/lua-resty-upload
set $reqargs_chunk_size 4096;
# see https://github.com/openresty/lua-nginx-module#ngxreqget_uri_args
set $reqargs_max_get_args 100;
# see https://github.com/openresty/lua-nginx-module#ngxreqget_post_args
set $reqargs_max_post_args 100;
# see https://github.com/openresty/lua-resty-upload
set $reqargs_max_line_size 512;
# the default is unlimited
set $reqargs_max_file_size 10240;
# the default is unlimited
set $reqargs_max_file_uploads 10;
```
## Changes
The changes of every release of this module is recorded in [Changes.md](https://github.com/bungle/lua-resty-reqargs/blob/master/Changes.md) file.
## Roadmap
* Add safeguards and streaming parsing to `application/json` bodies
* Add support for pluggable stream writer (e.g. non-blocking network / db writer)
## See Also
* [lua-resty-route](https://github.com/bungle/lua-resty-route) — Routing library
* [lua-resty-session](https://github.com/bungle/lua-resty-session) — Session library
* [lua-resty-template](https://github.com/bungle/lua-resty-template) — Templating engine
* [lua-resty-validation](https://github.com/bungle/lua-resty-validation) — Validation and filtering library
## License
`lua-resty-reqargs` uses two clause BSD license.
```
Copyright (c) 2015 - 2017, Aapo Talvensaari
All rights reserved.
Redistribution and use in source and binary forms, with or without modification,
are permitted provided that the following conditions are met:
* Redistributions of source code must retain the above copyright notice, this
list of conditions and the following disclaimer.
* Redistributions in binary form must reproduce the above copyright notice, this
list of conditions and the following disclaimer in the documentation and/or
other materials provided with the distribution.
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR
ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES`