lua-resty-reqargs

Helper to Retrieve application/x-www-form-urlencoded, multipart/form-data, and application/json Request Arguments.

Synopsis

local get, post, files = require "resty.reqargs"()
if not get then
    error(post)
end
-- Use get, post, and files...

Installation

Just place 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)

$ opm get bungle/lua-resty-reqargs

Using LuaRocks

$ 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:

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:

{
    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. post contains either HTTP request POST arguments retrieved with ngx.req.get_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):

{
    -- 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:

# 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 file.

Roadmap

Add safeguards and streaming parsing to application/json bodies
Add support for pluggable stream writer (e.g. non-blocking network / db writer)

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`

theSundayProgrammer/lua-resty-reqargs