{"id":13896113,"url":"https://github.com/lusis/lua-httpclient","last_synced_at":"2025-07-17T12:30:47.744Z","repository":{"id":23837712,"uuid":"27215052","full_name":"lusis/lua-httpclient","owner":"lusis","description":"A unified http/s client library for lua","archived":true,"fork":false,"pushed_at":"2016-10-31T17:07:57.000Z","size":37,"stargazers_count":71,"open_issues_count":2,"forks_count":11,"subscribers_count":7,"default_branch":"master","last_synced_at":"2024-11-25T01:33:25.498Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Lua","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/lusis.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2014-11-27T08:01:41.000Z","updated_at":"2024-11-07T14:30:33.000Z","dependencies_parsed_at":"2022-08-21T23:40:07.935Z","dependency_job_id":null,"html_url":"https://github.com/lusis/lua-httpclient","commit_stats":null,"previous_names":[],"tags_count":8,"template":false,"template_full_name":null,"purl":"pkg:github/lusis/lua-httpclient","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lusis%2Flua-httpclient","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lusis%2Flua-httpclient/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lusis%2Flua-httpclient/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lusis%2Flua-httpclient/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/lusis","download_url":"https://codeload.github.com/lusis/lua-httpclient/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lusis%2Flua-httpclient/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":265606586,"owners_count":23796967,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-08-06T18:02:40.112Z","updated_at":"2025-07-17T12:30:47.490Z","avatar_url":"https://github.com/lusis.png","language":"Lua","funding_links":[],"categories":["Lua","Resources"],"sub_categories":["Network"],"readme":"# httpclient\n`httpclient` is a unified wrapper around a few common http/s libraries and methods.\n\nThe use case for this was being able to use an internal Github API client via openresty/`ngx.location.capture` and also outside of openresty using `luasocket` and `luasec`.\n\nThe `luasocket.http` API is a bit different than the ngx api. This provides a \"familiar\" interface to both.\n\n*NOTE*: the wrappers for `ngx.location.capture` and `lua-resty-http` modules are not yet done. \"Release early/release often\" or something like that...\n\n## Usage\nYou can look at the tests for various usage examples but most interactions use a common pattern.\nThe result of any call will be a table with the following structure:\n\n```lua\n{\n  body = \u003cresponse body\u003e,\n  code = \u003chttp status code\u003e,\n  headers = \u003ctable of headers\u003e,\n  status_line = \u003cthe http status message\u003e,\n  err = \u003cnil or error message\u003e\n}\n```\n\n### Get\n```lua\nhc = require('httpclient').new()\nres = hc:get('http://httpbin.org/get')\nif res.body then\n  print(res.body)\nelse\n  print(res.err)\nend\n-- {\n--   \"args\": {}, \n--   \"headers\": {\n--     \"Accept\": \"*/*\", \n--     \"Connect-Time\": \"1\", \n--     \"Connection\": \"close\", \n--     \"Host\": \"httpbin.org\", \n--     \"Total-Route-Time\": \"0\", \n--     \"User-Agent\": \"LuaSocket 3.0-rc1\", \n--     \"Via\": \"1.1 vegur\", \n--     \"X-Request-Id\": \"b64c0bb9-653a-44ec-8bd2-a768ad80d720\"\n--   }, \n--   \"origin\": \"1.1.1.1\", \n--   \"url\": \"http://httpbin.org/get\"\n-- }\n```\n\n### Post\n```lua\nhc = require('httpclient').new()\nres = hc:post('http://httpbin.org/post','somepostdata')\n```\n\nThe following verbs are supported:\n- `GET`\n- `PUT`\n- `POST`\n- `HEAD`\n- `PATCH`\n- `DELETE`\n\nNote that this library does not do any special handling of the response body other than giving it to you as-is.\nThis library is intended to be used by a higher-level library that handles parsing\n\nAs other drivers are finished out, they'll be passed in to the constructor. Currently the default driver is `httpclient.luasocket_driver`\n\n## openresty/nginx example\n- Install to the appropriate path for luajit\n- Add an `internal` location to the appropriate place for handling the location capture:\n\n```\n        location /capture {\n                internal;\n                resolver 8.8.8.8;\n                set_unescape_uri $clean_url $arg_url;\n                proxy_pass $clean__url;\n        }\n\n```\n\nThe above stanza sets up an internal capture location called `/capture`. When a request is sent to it via `ngx.location.capture`, takes whatever url is sent to that location and strips off the `url` argument from it and then does a standard proxy pass.\n\nYou can use either `content_by_lua` or `content_by_lua_file` with something like so in it:\n\n```lua\nlocal hc = require(\"httpclient\").new('httpclient.ngx_driver')\n\nlocal d,_ = hc:get(\"https://httpbin.org/get\")\n\nngx.header.content_type = d.headers['content-type'];\nngx.say(d.body)\n```\n\nNote the default options for the `ngx_driver` are to use a capture location of `/capture` and for the real url to be passed with an arg name of `url`. This can be overridden like so:\n\n```lua\nlocal hc = require(\"httpclient\").new('httpclient.ngx_driver')\nhc:set_default('capture_url', '/somewhere_else')\nhc:set_default('capture_variable', 'someother_variable')\n```\n\nThose changes would result in your above stanza requiring the following:\n\n```\n        location /somewhere_else {\n                internal;\n                resolver 8.8.8.8;\n                set_unescape_uri $clean_url $arg_someother_variable;\n                proxy_pass $clean__url;\n        }\n```\n\nNote that previous versions of this readme required setting some params in the internal redirect to clear headers. This is no longer needed as the ngx driver will now clear ALL headers before requesting.\n\n## Other bits\nThere are ways to override much of what you pass in to the actual http request specific to the driver.\n\n## Install\nEasiest option is probably to install from luarocks:\n\n`luarocks install httpclient`\n\nAlternately, you can install via the included `Makefile`. You'll probably want to override the `LUA_SHAREDIR` environment variable. You'll also need to make sure you install `luasocket` and ideally `luasec` (for https links).\n\n## Requirements\nThe following versions were tested\n- lua 5.2 (the version that shipped with trusty)\n- luasec 0.5-2 (only required for https support)\n- luasocket 3.0rc1-1\n- net-url (included MIT license - https://github.com/golgote/neturl - see LICENSE.net-url)\n\nIf you want to run the test suite:\n- luacov 0.6-1\nluaunit is included in the test dir\n\n## Third-party\nIncluded third-party code\n\n### neturl\nhttpclient also includes its own url parser provided by [neturl](https://github.com/golgote/neturl). This is because the urlparser shipped with luasocket has quite a few issues the biggest of which is the inability to parse querystrings.\n\n### luaunit\nunit testing is done using [luaunit](https://github.com/bluebird75/luaunit)\n\n## TODO\n- Add remaining drivers\n- make a rockspec/post to luarocks\n- Document better\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flusis%2Flua-httpclient","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flusis%2Flua-httpclient","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flusis%2Flua-httpclient/lists"}