resty.http资源

# lua-resty-http Lua HTTP client cosocket driver for [OpenResty](http://openresty.org/) / [ngx\_lua](https://github.com/openresty/lua-nginx-module). ## Status Production ready. [](https://github.com/ledgetech/lua-resty-http/actions) ## Features * HTTP 1.0 and 1.1 * SSL * Streaming interface to the response body, for predictable memory usage * Alternative simple interface for single-shot requests without a manual connection step * Chunked and non-chunked transfer encodings * Connection keepalives * Request pipelining * Trailers * HTTP proxy connections ## API * [new](#new) * [connect](#connect) * [set\_proxy\_options](#set_proxy_options) * [set\_timeout](#set_timeout) * [set\_timeouts](#set_timeouts) * [set\_keepalive](#set_keepalive) * [get\_reused\_times](#get_reused_times) * [close](#close) * [request](#request) * [request\_uri](#request_uri) * [request\_pipeline](#request_pipeline) * [parse\_uri](#parse_uri) * [get\_client\_body\_reader](#get_client_body_reader) * [Response](#response) * [body\_reader](#resbody_reader) * [read\_body](#resread_body) * [read\_trailers](#resread_trailers) ### Deprecated These methods may be removed in future versions. * [connect\_proxy](#connect_proxy) * [ssl\_handshake](#ssl_handshake) * [proxy\_request](#proxy_request) * [proxy\_response](#proxy_response) ## Usage There are two basic modes of operation: 1. **Simple single-shot requests** which require no manual connection management but which buffer the entire response and leave the connection either closed or back in the connection pool. 2. **Streamed requests** where the connection is established separately, then the request is sent, the body stream read in chunks, and finally the connection is manually closed or kept alive. This technique requires a little more code but provides the ability to discard potentially large response bodies on the Lua side, as well as pipelining multiple requests over a single connection. ### Single-shot request ```lua local httpc = require("resty.http").new() -- Single-shot requests use the `request_uri` interface. local res, err = httpc:request_uri("http://example.com/helloworld", { method = "POST", body = "a=1&b=2", headers = { ["Content-Type"] = "application/x-www-form-urlencoded", }, }) if not res then ngx.log(ngx.ERR, "request failed: ", err) return end -- At this point, the entire request / response is complete and the connection -- will be closed or back on the connection pool. -- The `res` table contains the expeected `status`, `headers` and `body` fields. local status = res.status local length = res.headers["Content-Length"] local body = res.body ``` ### Streamed request ```lua local httpc = require("resty.http").new() -- First establish a connection local ok, err, ssl_session = httpc:connect({ scheme = "https", host = "127.0.0.1", port = 8080, }) if not ok then ngx.log(ngx.ERR, "connection failed: ", err) return end -- Then send using `request`, supplying a path and `Host` header instead of a -- full URI. local res, err = httpc:request({ path = "/helloworld", headers = { ["Host"] = "example.com", }, }) if not res then ngx.log(ngx.ERR, "request failed: ", err) return end -- At this point, the status and headers will be available to use in the `res` -- table, but the body and any trailers will still be on the wire. -- We can use the `body_reader` iterator, to stream the body according to our -- desired buffer size. local reader = res.body_reader local buffer_size = 8192 repeat local buffer, err = reader(buffer_size) if err then ngx.log(ngx.ERR, err) break end if buffer then -- process end until not buffer local ok, err = httpc:set_keepalive() if not ok then ngx.say("failed to set keepalive: ", err) return end -- At this point, the connection will either be safely back in the pool, or closed. ```` # Connection ## new `syntax: httpc, err = http.new()` Creates the HTTP connection object. In case of failures, returns `nil` and a string describing the error. ## connect `syntax: ok, err, ssl_session = httpc:connect(options)` Attempts to connect to the web server while incorporating the following activities: - TCP connection - SSL handshake - HTTP proxy configuration In doing so it will create a distinct connection pool name that is safe to use with SSL and / or proxy based connections, and as such this syntax is strongly recommended over the original (now deprecated) [TCP only connection syntax](#TCP-only-connect). The options table has the following fields: * `scheme`: scheme to use, or nil for unix domain socket * `host`: target host, or path to a unix domain socket * `port`: port on target host, will default to `80` or `443` based on the scheme * `pool`: custom connection pool name. Option as per [OpenResty docs](https://github.com/openresty/lua-nginx-module#tcpsockconnect), except that the default will become a pool name constructed using the SSL / proxy properties, which is important for safe connection reuse. When in doubt, leave it blank! * `pool_size`: option as per [OpenResty docs](https://github.com/openresty/lua-nginx-module#tcpsockconnect) * `backlog`: option as per [OpenResty docs](https://github.com/openresty/lua-nginx-module#tcpsockconnect) * `proxy_opts`: sub-table, defaults to the global proxy options set, see [set\_proxy\_options](#set_proxy_options). * `ssl_reused_session`: option as per [OpenResty docs](https://github.com/openresty/lua-nginx-module#tcpsocksslhandshake) * `ssl_verify`: option as per [OpenResty docs](https://github.com/openresty/lua-nginx-module#tcpsocksslhandshake), except that it defaults to `true`. * `ssl_server_name`: option as per [OpenResty docs](https://github.com/openresty/lua-nginx-module#tcpsocksslhandshake) * `ssl_send_status_req`: option as per [OpenResty docs](https://github.com/openresty/lua-nginx-module#tcpsocksslhandshake) ## set\_timeout `syntax: httpc:set_timeout(time)` Sets the socket timeout (in ms) for subsequent operations. See [set\_timeouts](#set_timeouts) below for a more declarative approach. ## set\_timeouts `syntax: httpc:set_timeouts(connect_timeout, send_timeout, read_timeout)` Sets the connect timeout threshold, send timeout threshold, and read timeout threshold, respectively, in milliseconds, for subsequent socket operations (connect, send, receive, and iterators returned from receiveuntil). ## set\_keepalive `syntax: ok, err = httpc:set_keepalive(max_idle_timeout, pool_size)` Either places the current connection into the pool for future reuse, or closes the connection. Calling this instead of [close](#close) is "safe" in that it will conditionally close depending on the type of request. Specifically, a `1.0` request without `Connection: Keep-Alive` will be closed, as will a `1.1` request with `Connection: Close`. In case of success, returns `1`. In case of errors, returns `nil, err`. In the case where the connection is conditionally closed as described above, returns `2` and the error string `connection must be closed`, so as to distinguish from unexpected errors. See [OpenResty docs](https://github.com/openresty/lua-nginx-module#tcpsocksetkeepalive) for parameter documentation. ## set\_proxy\_options `syntax: httpc:set_proxy_options(opts)` Configure an HTTP proxy to be used with this client instance. The `opts` table expects the following fields: * `http_proxy`: an URI to a proxy server to be used with HTTP requests * `http_proxy_authorization`: a default `Proxy-Authorization` header value to be used with `http_proxy`, e.g. `Basic ZGVtbzp0ZXN0`, which will be overriden if the `Proxy-Authorization` request header is present. * `https_proxy`: an URI to a proxy server to be used with HTTPS requests * `https_proxy_authorization`: as `http_proxy_authorization` but for use with `htt