1lua-http() lua-http()
2
6 lua-http is an performant, capable HTTP and WebSocket library for Lua
7 5.1, 5.2, 5.3 and LuaJIT. Some of the features of the library include:
8 · Support for HTTP versions 1, 1.1 and 2 as specified by RFC 7230
10 (https://tools.ietf.org/html/rfc7230) and RFC 7540
11 (https://tools.ietf.org/html/rfc7540)
12 · Provides both client and server APIs
14 · Fully asynchronous API that does not block the current thread when
16 executing operations that typically block
17 · Support for WebSockets as specified by RFC 6455
19 (https://tools.ietf.org/html/rfc6455) including ping/pong, binary da‐
20 ta transfer and TLS encryption
21 · Transport Layer Security (TLS) - lua-http supports HTTPS and WSS via
23 luaossl (https://github.com/wahern/luaossl).
24 · Easy integration into other event-loop or scripts
26 Why lua-http?
28 The lua-http library was written to fill a gap in the Lua ecosystem by
29 providing an HTTP and WebSocket library with the following traits:
30 · Asynchronous and performant
32 · Can be used without forcing the developer to follow a specific pat‐
34 tern. Conversely, the library can be adapted to many common pat‐
35 terns.
36 · Can be used at a very high level without need to understand the
38 transportation of HTTP data (other than connection addresses).
39 · Provides a rich low level API, if desired, for creating powerful HTTP
41 based tools at the protocol level.
42 As a result of these design goals, the library is simple and unobtru‐
44 sive and can accommodate tens of thousands of connections on commodity
45 hardware.
46 lua-http is a flexible HTTP and WebSocket library that allows develop‐
48 ers to concentrate on line-of-business features when building Internet
49 enabled applications. If you are looking for a way to streamline de‐
50 velopment of an internet enabled application, enable HTTP networking in
51 your game, create a new Internet Of Things (IoT) system, or write a
52 performant custom web server for a specific use case, lua-http has the
53 tools you need.
54 Portability
56 lua-http is pure Lua code with dependencies on the following external
57 libraries:
58 · cqueues (http://25thandclement.com/~william/projects/cqueues.html) -
60 Posix API library for Lua
61 · luaossl (http://25thandclement.com/~william/projects/luaossl.html) -
63 Lua bindings for TLS/SSL
64 · lua-zlib (https://github.com/brimworks/lua-zlib) - Optional Lua bind‐
66 ings for zlib
67 lua-http can run on any operating system supported by cqueues and
69 openssl, which at the time of writing is GNU/Linux, FreeBSD, NetBSD,
70 OpenBSD, OSX and Solaris.
71 Common Use Cases
73 The following are two simple demonstrations of how the lua-http library
74 can be used:
75 Retrieving a Document
77 The highest level interface for clients is http.request. By construct‐
78 ing a request object from a URI using new_from_uri and immediately
79 evaluating it, you can easily fetch an HTTP resource.
80 local http_request = require "http.request"
82 local headers, stream = assert(http_request.new_from_uri("http://example.com"):go())
83 local body = assert(stream:get_body_as_string())
84 if headers:get ":status" ~= "200" then
85 error(body)
86 end
87 print(body)
88 WebSocket Communications
90 To request information from a WebSocket server, use the websocket mod‐
91 ule to create a new WebSocket client.
92 local websocket = require "http.websocket"
94 local ws = websocket.new_from_uri("wss://echo.websocket.org")
95 assert(ws:connect())
96 assert(ws:send("koo-eee!"))
97 local data = assert(ws:receive())
98 assert(data == "koo-eee!")
99 assert(ws:close())
100 Asynchronous Operation
102 lua-http has been written to perform asynchronously so that it can be
103 used in your application, server or game without blocking your main
104 loop. Asynchronous operations are achieved by utilizing cqueues, a
105 Lua/C library that incorporates Lua yielding and kernel level APIs to
106 reduce CPU usage. All lua-http operations including DNS lookup, TLS
107 negotiation and read/write operations will not block the main applica‐
108 tion thread when run from inside a cqueue or cqueue enabled “contain‐
109 er”. While sometimes it is necessary to block a routine (yield) and
110 wait for external data, any blocking API calls take an optional timeout
111 to ensure good behaviour of networked applications and avoid unrespon‐
112 sive or “dead” routines.
113 Asynchronous operations are one of the most powerful features of
115 lua-http and require no effort on the developers part. For instance,
116 an HTTP server can be instantiated within any Lua main loop and run
117 alongside application code without adversely affecting the main appli‐
118 cation process. If other cqueue enabled components are integrated
119 within a cqueue loop, the application is entirely event driven through
120 kernel level polling APIs.
121 cqueues can be used in conjunction with lua-http to integrate other
123 features into your lua application and create powerful, performant, web
124 enabled applications. Some of the examples in this guide will use
125 cqueues for simple demonstrations. For more resources about cqueues,
126 please see:
127 · The cqueues website (http://25thand‐
129 clement.com/~william/projects/cqueues.html) for more information
130 about the cqueues library.
131 · cqueues examples can be found with the cqueues source code available
133 through git or archives (http://www.25thand‐
134 clement.com/~william/projects/cqueues.html#download) or accessed on‐
135 line here (https://github.com/wahern/cqueues/tree/master/examples).
136 · For more information on integrating cqueues with other event loop li‐
138 braries please see integration with other event loops
139 (https://github.com/wahern/cqueues/wiki/Integrations-with-other-main-
140 loops).
141 · For other libraries that use cqueues such as asynchronous APIs for
143 Redis and PostgreSQL, please see the cqueues wiki entry here
144 (https://github.com/wahern/cqueues/wiki/Libraries-that-use-cqueues).
145 Conventions
147 The following is a list of API conventions and general reference:
148 HTTP
150 · HTTP 1 request and status line fields are passed around inside of
151 headers objects under keys ":authority", ":method", ":path",
152 ":scheme" and ":status" as defined in HTTP 2. As such, they are all
153 kept in string form (important to remember for the :status field).
154 · Header fields should always be used with lower case keys.
156 Errors
158 · Invalid function parameters will throw a lua error (if validated).
159 · Errors are returned as nil, error, errno unless noted otherwise.
161 · Some HTTP 2 operations return/throw special http 2 error objects.
163 Timeouts
165 All operations that may block the current thread take a timeout argu‐
166 ment. This argument is always the number of seconds to allow before
167 returning nil, err_msg, ETIMEDOUT where err_msg is a localised error
168 message such as "connection timed out".
169 Terminology
171 Much lua-http terminology is borrowed from HTTP 2.
172 Connection - An abstraction over an underlying TCP/IP socket. lua-http
174 currently has two connection types: one for HTTP 1, one for HTTP 2.
175 Stream - A request/response on a connection object. lua-http has two
177 stream types: one for HTTP 1 streams, and one for HTTP 2 streams. The
178 common interfaces is described in stream.
179
181 lua-http has separate modules for HTTP 1 vs HTTP 2 protocols, yet the
182 different versions share many common concepts. lua-http provides a
183 common interface for operations that make sense for both protocol ver‐
184 sions (as well as any future developments).
185 The following sections outline the interfaces exposed by the lua-http
187 library.
188 connection
190 A connection encapsulates a socket and provides protocol specific oper‐
191 ations. A connection may have streams which encapsulate the re‐
192 quests/responses happening over a conenction. Alternatively, you can
193 ignore streams entirely and use low level protocol specific operations
194 to read and write to the socket.
195 All connection types expose the following fields:
197 connection.type
199 The mode of use for the connection object. Valid values are:
200 · "client": Acts as a client; this connection type is used by entities
202 who want to make requests
203 · "server": Acts as a server; this conenction type is used by entities
205 who want to respond to requests
206 connection.version
208 The HTTP version number of the connection as a number.
209 connection:pollfd()
211 connection:events()
212 connection:timeout()
213 connection:connect(timeout)
214 Completes the connection to the remote server using the address speci‐
215 fied, HTTP version and any options specified in the connection.new con‐
216 structor. The connect function will yield until the connection attempt
217 finishes (success or failure) or until timeout is exceeded. Connecting
218 may include DNS lookups, TLS negotiation and HTTP2 settings exchange.
219 Returns true on success. On error, returns nil, an error message and
220 an error number.
221 connection:checktls()
223 Checks the socket for a valid Transport Layer Security connection. Re‐
224 turns the luaossl ssl object if the connection is secured. Returns nil
225 and an error message if there is no active TLS session. Please see the
226 luaossl website (http://25thandclement.com/~william/projects/lu‐
227 aossl.html) for more information about the ssl object.
228 connection:localname()
230 Returns the connection information for the local socket. Returns ad‐
231 dress family, IP address and port for an external socket. For Unix do‐
232 main sockets, the function returns AF_UNIX and the path. If the con‐
233 nection object is not connected, returns AF_UNSPEC (0). On error, re‐
234 turns nil, an error message and an error number.
235 connection:peername()
237 Returns the connection information for the socket peer (as in, the next
238 hop). Returns address family, IP address and port for an external
239 socket. For unix sockets, the function returns AF_UNIX and the path.
240 If the connection object is not connected, returns AF_UNSPEC (0). On
241 error, returns nil, an error message and an error number.
242 Note: If the client is using a proxy, the values returned :peername()
244 point to the proxy, not the remote server.
245 connection:flush(timeout)
247 Flushes buffered outgoing data on the socket to the operating system.
248 Returns true on success. On error, returns nil, an error message and
249 an error number.
250 connection:shutdown()
252 Performs an orderly shutdown of the connection by closing all streams
253 and calls :shutdown() on the socket. The connection cannot be
254 re-opened.
255 connection:close()
257 Closes a connection and releases operating systems resources. Note
258 that :close() performs a connection:shutdown() prior to releasing re‐
259 sources.
260 connection:new_stream()
262 Creates and returns a new stream on the connection.
263 connection:get_next_incoming_stream(timeout)
265 Returns the next peer initiated stream on the connection. This func‐
266 tion can be used to yield and “listen” for incoming HTTP streams.
267 connection:onidle(new_handler)
269 Provide a callback to get called when the connection becomes idle
270 i.e. when there is no request in progress and no pipelined streams
271 waiting. When called it will receive the connection as the first argu‐
272 ment. Returns the previous handler.
273 stream
275 An HTTP stream is an abstraction of a request/response within a HTTP
276 connection. Within a stream there may be a number of “header” blocks
277 as well as data known as the “body”.
278 All stream types expose the following fields and functions:
280 stream.connection
282 The underlying connection object.
283 stream:checktls()
285 Convenience wrapper equivalent to stream.connection:checktls()
286 stream:localname()
288 Convenience wrapper equivalent to stream.connection:localname()
289 stream:peername()
291 Convenience wrapper equivalent to stream.connection:peername()
292 stream:get_headers(timeout)
294 Retrieves the next complete headers object (i.e. a block of headers or
295 trailers) from the stream.
296 stream:write_headers(headers, end_stream, timeout)
298 Write the given headers object to the stream. The function takes a
299 flag indicating if this is the last chunk in the stream, if true the
300 stream will be closed. If timeout is specified, the stream will wait
301 for the send to complete until timeout is exceeded.
302 stream:write_continue(timeout)
304 Sends a 100-continue header block.
305 stream:get_next_chunk(timeout)
307 Returns the next chunk of the http body from the socket, potentially
308 yielding for up to timeout seconds. On error, returns nil, an error
309 message and an error number.
310 stream:each_chunk()
312 Iterator over stream:get_next_chunk()
313 stream:get_body_as_string(timeout)
315 Reads the entire body from the stream and return it as a string. On
316 error, returns nil, an error message and an error number.
317 stream:get_body_chars(n, timeout)
319 Reads n characters (bytes) of body from the stream and return them as a
320 string. If the stream ends before n characters are read then returns
321 the partial result. On error, returns nil, an error message and an er‐
322 ror number.
323 stream:get_body_until(pattern, plain, include_pattern, timeout)
325 Reads in body data from the stream until the lua pattern
326 (http://www.lua.org/manual/5.3/manual.html#6.4.1) pattern is found and
327 returns the data as a string. plain is a boolean that indicates that
328 pattern matching facilities should be turned off so that function does
329 a plain “find substring” operation, with no characters in pattern being
330 considered magic. include_patterns specifies if the pattern itself
331 should be included in the returned string. On error, returns nil, an
332 error message and an error number.
333 stream:save_body_to_file(file, timeout)
335 Reads the body from the stream and saves it to the lua file handle
336 (http://www.lua.org/manual/5.3/manual.html#6.8) file. On error, re‐
337 turns nil, an error message and an error number.
338 stream:get_body_as_file(timeout)
340 Reads the body from the stream into a temporary file and returns a lua
341 file handle (http://www.lua.org/manual/5.3/manual.html#6.8). On error,
342 returns nil, an error message and an error number.
343 stream:unget(str)
345 Places str back on the incoming data buffer, allowing it to be returned
346 again on a subsequent command (“un-gets” the data). Returns true on
347 success. On error, returns nil, an error message and an error number.
348 stream:write_chunk(chunk, end_stream, timeout)
350 Writes the string chunk to the stream. If end_stream is true, the body
351 will be finalized and the stream will be closed. write_chunk yields
352 indefinitely, or until timeout is exceeded. On error, returns nil, an
353 error message and an error number.
354 stream:write_body_from_string(str, timeout)
356 Writes the string str to the stream and ends the stream. On error, re‐
357 turns nil, an error message and an error number.
358 stream:write_body_from_file(options|file, timeout)
360 · options is a table containing:
361 · .file (file)
363 · .count (positive integer): number of bytes of file to write
365 defaults to infinity (the whole file will be written)
366 Writes the contents of file file to the stream and ends the stream.
368 file will not be automatically seeked, so ensure it is at the correct
369 offset before calling. On error, returns nil, an error message and an
370 error number.
371 stream:shutdown()
373 Closes the stream. The resources are released and the stream can no
374 longer be used.
375
377 http.bit
378 An abstraction layer over the various lua bit libraries.
379 Results are only consistent between underlying implementations when pa‐
381 rameters and results are in the range of 0 to 0x7fffffff.
382 band(a, b)
384 Bitwise And operation.
385 bor(a, b)
387 Bitwise Or operation.
388 bxor(a, b)
390 Bitwise XOr operation.
391 Example
393 local bit = require "http.bit"
394 print(bit.band(1, 3)) --> 1
395 http.client
397 Deals with obtaining a connection to an HTTP server.
398 negotiate(socket, options, timeout)
400 Negotiates the HTTP settings with the remote server. If TLS has been
401 specified, this function instantiates the encryption tunnel. Parame‐
402 ters are as follows:
403 · socket is a cqueues socket object
405 · options is a table containing:
407 · .tls (boolean, optional): Should TLS be used?
409 defaults to false
410 · .ctx (userdata, optional): the SSL_CTX* to use if .tls is true.
412 If .ctx is nil then a default context will be used.
413 · .sendname (string|boolean, optional): the TLS SNI
415 (https://en.wikipedia.org/wiki/Server_Name_Indication) host to
416 send.
417 defaults to true
418 · true indicates to copy the .host field as long as it is not an IP
420 · false disables SNI
422 · .version (nil|1.0|1.1|2): HTTP version to use.
424 · nil: attempts HTTP 2 and falls back to HTTP 1.1
426 · 1.0
428 · 1.1
430 · 2
432 · .h2_settings (table, optional): HTTP 2 settings to use. See
434 http.h2_connection for details
435 connect(options, timeout)
437 This function returns a new connection to an HTTP server. Once a con‐
438 nection has been opened, a stream can be created to start a request/re‐
439 sponse exchange. Please see h1_stream.new_stream and
440 h2_stream.new_stream for more information about creating streams.
441 · options is a table containing the options to http.client.negotiate,
443 plus the following:
444 · family (integer, optional): socket family to use.
446 defaults to AF_INET
447 · host (string): host to connect to.
449 may be either a hostname or an IP address
450 · port (string|integer): port to connect to in numeric form
452 e.g. "80" or 80
453 · path (string): path to connect to (UNIX sockets)
455 · v6only (boolean, optional): if the IPV6_V6ONLY flag should be set
457 on the underlying socket.
458 · bind (string, optional): the local outgoing address and optionally
460 port to bind in the form of "address[:port]", IPv6 addresses may be
461 specified via square bracket notation. e.g. "127.0.0.1",
462 "127.0.0.1:50000", "[::1]:30000".
463 · timeout (optional) is the maximum amount of time (in seconds) to al‐
465 low for connection to be established.
466 This includes time for DNS lookup, connection, TLS negotiation (if TLS
467 enabled) and in the case of HTTP 2: settings exchange.
468 Example
470 Connect to a local HTTP server running on port 8000
471 local http_client = require "http.client"
473 local myconnection = http_client.connect {
474 host = "localhost";
475 port = 8000;
476 tls = false;
477 }
478 http.cookie
480 A module for working with cookies.
481 bake(name, value, expiry_time, domain, path, secure_only, http_on‐
483 ly, same_site)
484 Returns a string suitable for use in a Set-Cookie header with the
485 passed parameters.
486 parse_cookie(cookie)
488 Parses the Cookie header contents cookie.
489 Returns a table containing name and value pairs as strings.
491 parse_cookies(req_headers)
493 Parses all Cookie headers in the http.headers object req_headers.
494 Returns a table containing name and value pairs as strings.
496 parse_setcookie(setcookie)
498 Parses the Set-Cookie header contents setcookie.
499 Returns name, value and params where:
501 · name is a string containing the cookie name
503 · value is a string containing the cookie value
505 · params is the a table where the keys are cookie attribute names and
507 values are cookie attribute values
508 new_store()
510 Creates a new cookie store.
511 Cookies are unique for a tuple of domain, path and name; although mul‐
513 tiple cookies with the same name may exist in a request due to overlap‐
514 ping paths or domains.
515 store.psl
517 A lua-psl (https://github.com/daurnimator/lua-psl) object to use for
518 checking against the Public Suffix List. Set the field to false to
519 skip checking the suffix list.
520 Defaults to the latest (https://rockdaboot.github.io/libpsl/libpsl-Pub‐
522 lic-Suffix-List-functions.html#psl-latest) PSL on the system. If
523 lua-psl is not installed then it will be nil.
524 store.time()
526 A function used by the store to get the current time for expiries and
527 such.
528 Defaults to a function based on os.time (https://www.lua.org/manu‐
530 al/5.3/manual.html#pdf-os.time).
531 store.max_cookie_length
533 The maximum length (in bytes) of cookies in the store; this value is
534 also used as default maximum cookie length for :lookup(). Decreasing
535 this value will only prevent new cookies from being added, it will not
536 remove old cookies.
537 Defaults to infinity (no maximum size).
539 store.max_cookies
541 The maximum number of cookies allowed in the store. Decreasing this
542 value will only prevent new cookies from being added, it will not re‐
543 move old cookies.
544 Defaults to infinity (any number of cookies is allowed).
546 store.max_cookies_per_domain
548 The maximum number of cookies allowed in the store per domain. De‐
549 creasing this value will only prevent new cookies from being added, it
550 will not remove old cookies.
551 Defaults to infinity (any number of cookies is allowed).
553 store:store(req_domain, req_path, req_is_http, req_is_se‐
555 cure, req_site_for_cookies, name, value, params)
556 Attempts to add a cookie to the store.
557 · req_domain is the domain that the cookie was obtained from
559 · req_path is the path that the cookie was obtained from
561 · req_is_http is a boolean flag indicating if the cookie was obtained
563 from a “non-HTTP” API
564 · req_is_secure is a boolean flag indicating if the cookie was obtained
566 from a “secure” protocol
567 · req_site_for_cookies is a string containing the host that should be
569 considered as the “site for cookies” (See RFC 6265bis-02 Section 5.2
570 (https://tools.ietf.org/html/draft-ietf-httpbis-rfc6265bis-02#sec‐
571 tion-5.2)), can be nil if unknown.
572 · name is a string containing the cookie name
574 · value is a string containing the cookie value
576 · params is the a table where the keys are cookie attribute names and
578 values are cookie attribute values
579 Returns a boolean indicating if a cookie was stored.
581 store:store_from_request(req_headers, resp_head‐
583 ers, req_host, req_site_for_cookies)
584 Attempt to store any cookies found in the response headers.
585 · req_headers is the http.headers object for the outgoing request
587 · resp_headers is the http.headers object received in response
589 · req_host is the host that your query was directed at (only used if
591 req_headers is missing a Host header)
592 · req_site_for_cookies is a string containing the host that should be
594 considered as the “site for cookies” (See RFC 6265bis-02 Section 5.2
595 (https://tools.ietf.org/html/draft-ietf-httpbis-rfc6265bis-02#sec‐
596 tion-5.2)), can be nil if unknown.
597 store:get(domain, path, name)
599 Returns the cookie value for the cookie stored for the passed domain,
600 path and name.
601 store:remove(domain, path, name)
603 Deletes the cookie stored for the passed domain, path and name.
604 If name is nil or not passed then all cookies for the domain and path
606 are removed.
607 If path is nil or not passed (in addition to name) then all cookies for
609 the domain are removed.
610 store:lookup(domain, path, is_http, is_se‐
612 cure, is_safe_method, site_for_cookies, is_top_level, max_cook‐
613 ie_length)
614 Finds cookies visible to suitable for passing to an entity.
615 · domain is the domain that will be sent the cookie
617 · path is the path that will be sent the cookie
619 · is_http is a boolean flag indicating if the destination is a
621 “non-HTTP” API
622 · is_secure is a boolean flag indicating if the destination will be
624 communicated with over a “secure” protocol
625 · is_safe_method is a boolean flag indicating if the cookie will be
627 sent via a safe HTTP method (See also http.util.is_safe_method)
628 · site_for_cookies is a string containing the host that should be con‐
630 sidered as the “site for cookies” (See RFC 6265bis-02 Section 5.2
631 (https://tools.ietf.org/html/draft-ietf-httpbis-rfc6265bis-02#sec‐
632 tion-5.2)), can be nil if unknown.
633 · is_top_level is a boolean flag indicating if this request is a “top
635 level” request (See RFC 6265bis-02 Section 5.2
636 (https://tools.ietf.org/html/draft-ietf-httpbis-rfc6265bis-02#sec‐
637 tion-5.2))
638 · max_cookie_length is the maximum cookie length to allow (See also
640 store.max_cookie_length)
641 Returns a string suitable for use in a Cookie header.
643 store:lookup_for_request(headers, host, site_for_cookies, is_top_lev‐
645 el, max_cookie_length)
646 Finds cookies suitable for adding to a request.
647 · headers is the http.headers object for the outgoing request
649 · host is the host that your query was directed at (only used if head‐
651 ers is missing a Host header)
652 · site_for_cookies is a string containing the host that should be con‐
654 sidered as the “site for cookies” (See RFC 6265bis-02 Section 5.2
655 (https://tools.ietf.org/html/draft-ietf-httpbis-rfc6265bis-02#sec‐
656 tion-5.2)), can be nil if unknown.
657 · is_top_level is a boolean flag indicating if this request is a “top
659 level” request (See RFC 6265bis-02 Section 5.2
660 (https://tools.ietf.org/html/draft-ietf-httpbis-rfc6265bis-02#sec‐
661 tion-5.2))
662 · max_cookie_length is the maximum cookie length to allow (See also
664 store.max_cookie_length)
665 Returns a string suitable for use in a Cookie header.
667 store:clean_due()
669 Returns the number of seconds until the next cookie in the store ex‐
670 pires.
671 store:clean()
673 Remove all expired cookies from the store.
674 store:load_from_file(file)
676 Loads cookie data from the file object file into store. The file
677 should be in the Netscape Cookiejar format. Invalid lines in the file
678 are ignored.
679 Returns true on success or passes along nil, err, errno if a :read call
681 fails.
682 store:save_to_file(file)
684 Writes the cookie data from store into the file object file in the Net‐
685 scape Cookiejar format. file is not seek-ed or truncated before writ‐
686 ing.
687 Returns true on success or passes along nil, err, errno if a :write
689 call fails.
690 http.h1_connection
692 The h1_connection module adheres to the connection interface and pro‐
693 vides HTTP 1 and 1.1 specific operations.
694 new(socket, conn_type, version)
696 Constructor for a new connection. Takes a cqueues socket object, a
697 connection type string and a numeric HTTP version number. Valid values
698 for the connection type are "client" and "server". Valid values for
699 the version number are 1 and 1.1. Returns the newly initialized con‐
700 nection object.
701 h1_connection.version
703 Specifies the HTTP version used for the connection handshake. Valid
704 values are:
705 · 1.0
707 · 1.1
709 See connection.version
711 h1_connection:pollfd()
713 See connection:pollfd()
714 h1_connection:events()
716 See connection:events()
717 h1_connection:timeout()
719 See connection:timeout()
720 h1_connection:connect(timeout)
722 See connection:connect(timeout)
723 h1_connection:checktls()
725 See connection:checktls()
726 h1_connection:localname()
728 See connection:localname()
729 h1_connection:peername()
731 See connection:peername()
732 h1_connection:flush(timeout)
734 See connection:flush(timeout)
735 h1_connection:shutdown(dir)
737 Shut down is as graceful as possible: pipelined streams are shutdown,
738 then the underlying socket is shut down in the appropriate direc‐
739 tion(s).
740 dir is a string representing the direction of communication to shut
742 down communication in. If it contains "r" it will shut down reading,
743 if it contains "w" it will shut down writing. The default is "rw",
744 i.e. to shutdown communication in both directions.
745 See connection:shutdown()
747 h1_connection:close()
749 See connection:close()
750 h1_connection:new_stream()
752 In HTTP 1, only a client may initiate new streams with this function.
753 See connection:new_stream() for more information.
755 h1_connection:get_next_incoming_stream(timeout)
757 See connection:get_next_incoming_stream(timeout)
758 h1_connection:onidle(new_handler)
760 See connection:onidle(new_handler)
761 h1_connection:setmaxline(read_length)
763 Sets the maximum read buffer size (in bytes) to read_length. i.e. sets
764 the maximum length lines (such as headers).
765 The default comes from the underlying socket, which gets the
767 (changable) cqueues default at time of construction. The default
768 cqueues default is 4096 bytes.
769 h1_connection:clearerr(...)
771 Clears errors to allow for further read or write operations on the con‐
772 nection. Returns the error number of existing errors. This function
773 is used to recover from known errors.
774 h1_connection:error(...)
776 Returns the error number of existing errors.
777 h1_connection:take_socket()
779 Used to hand the reference of the connection socket to another object.
780 Resets the socket to defaults and returns the single existing reference
781 of the socket to the calling routine. This function can be used for
782 connection upgrades such as upgrading from HTTP 1 to a WebSocket.
783 h1_connection:read_request_line(timeout)
785 Reads a request line from the socket. Returns the request method, re‐
786 quested path and HTTP version for an incoming request. :read_re‐
787 quest_line() yields until a "\r\n" terminated chunk is received, or
788 timeout is exceeded. If the incoming chunk is not a valid HTTP request
789 line, nil is returned. On error, returns nil, an error message and an
790 error number.
791 h1_connection:read_status_line(timeout)
793 Reads a line of input from the socket. If the input is a valid status
794 line, the HTTP version (1 or 1.1), status code and reason description
795 (if applicable) is returned. :read_status_line() yields until a "\r\n"
796 terminated chunk is received, or timeout is exceeded. If the socket
797 could not be read, returns nil, an error message and an error number.
798 h1_connection:read_header(timeout)
800 Reads a CRLF terminated HTTP header from the socket and returns the
801 header key and value. This function will yield until a MIME compliant
802 header item is received or until timeout is exceeded. If the header
803 could not be read, the function returns nil an error and an error mes‐
804 sage.
805 h1_connection:read_headers_done(timeout)
807 Checks for an empty line, which indicates the end of the HTTP headers.
808 Returns true if an empty line is received. Any other value is pushed
809 back on the socket receive buffer (unget) and the function returns
810 false. This function will yield waiting for input from the socket or
811 until timeout is exceeded. Returns nil, an error and an error message
812 if the socket cannot be read.
813 h1_connection:read_body_by_length(len, timeout)
815 Get len number of bytes from the socket. Use a negative number for up
816 to that number of bytes. This function will yield and wait on the
817 socket if length of the buffered body is less than len. Asserts if len
818 is not a number.
819 h1_connection:read_body_till_close(timeout)
821 Reads the entire request body. This function will yield until the body
822 is complete or timeout is expired. If the read fails the function re‐
823 turns nil, an error message and an error number.
824 h1_connection:read_body_chunk(timeout)
826 Reads the next available line of data from the request and returns the
827 chunk and any chunk extensions. This function will yield until chunk
828 size is received or timeout is exceeded. If the chunk size is indicat‐
829 ed as 0 then false and any chunk extensions are returned. Returns nil,
830 an error message and an error number if there was an error reading
831 reading the chunk header or the socket.
832 h1_connection:write_request_line(method, path, httpversion, timeout)
834 Writes the opening HTTP 1.x request line for a new request to the sock‐
835 et buffer. Yields until success or timeout. If the write fails, re‐
836 turns nil, an error message and an error number.
837 Note the request line will not be flushed to the remote server until
839 write_headers_done is called.
840 h1_connection:write_status_line(httpversion, status_code, rea‐
842 son_phrase, timeout)
843 Writes an HTTP status line to the socket buffer. Yields until success
844 or timeout. If the write fails, the function returns nil, an error
845 message and an error number.
846 Note the status line will not be flushed to the remote server until
848 write_headers_done is called.
849 h1_connection:write_header(k, v, timeout)
851 Writes a header item to the socket buffer as a key:value string.
852 Yields until success or timeout. Returns nil, an error message and an
853 error if the write fails.
854 Note the header item will not be flushed to the remote server until
856 write_headers_done is called.
857 h1_connection:write_headers_done(timeout)
859 Terminates a header block by writing a blank line ("\r\n") to the sock‐
860 et. This function will flush all outstanding data in the socket output
861 buffer. Yields until success or timeout. Returns nil, an error mes‐
862 sage and an error if the write fails.
863 h1_connection:write_body_chunk(chunk, chunk_ext, timeout)
865 Writes a chunk of data to the socket. chunk_ext must be nil as chunk
866 extensions are not supported. Will yield until complete or timeout is
867 exceeded. Returns true on success. Returns nil, an error message and
868 an error number if the write fails.
869 h1_connection:write_body_last_chunk(chunk_ext, timeout)
871 Writes the chunked body terminator "0\r\n" to the socket. chunk_ext
872 must be nil as chunk extensions are not supported. Will yield until
873 complete or timeout is exceeded. Returns nil, an error message and an
874 error number if the write fails.
875 Note that the connection will not be immediately flushed to the remote
877 server; normally this will occur when trailers are written.
878 h1_connection:write_body_plain(body, timeout)
880 Writes the contents of body to the socket and flushes the socket output
881 buffer immediately. Yields until success or timeout is exceeded. Re‐
882 turns nil, an error message and an error number if the write fails.
883 http.h1_reason_phrases
885 A table mapping from status codes (as strings) to reason phrases for
886 HTTP 1. Any unknown status codes return "Unassigned"
887 Example
889 local reason_phrases = require "http.h1_reason_phrases"
890 print(reason_phrases["200"]) --> "OK"
891 print(reason_phrases["342"]) --> "Unassigned"
892 http.h1_stream
894 The h1_stream module adheres to the stream interface and provides HTTP
895 1.x specific operations.
896 The gzip transfer encoding is supported transparently.
898 h1_stream.connection
900 See stream.connection
901 h1_stream.max_header_lines
903 The maximum number of header lines to read. Default is 100.
904 h1_stream:checktls()
906 See stream:checktls()
907 h1_stream:localname()
909 See stream:localname()
910 h1_stream:peername()
912 See stream:peername()
913 h1_stream:get_headers(timeout)
915 See stream:get_headers(timeout)
916 h1_stream:write_headers(headers, end_stream, timeout)
918 See stream:write_headers(headers, end_stream, timeout)
919 h1_stream:write_continue(timeout)
921 See stream:write_continue(timeout)
922 h1_stream:get_next_chunk(timeout)
924 See stream:get_next_chunk(timeout)
925 h1_stream:each_chunk()
927 See stream:each_chunk()
928 h1_stream:get_body_as_string(timeout)
930 See stream:get_body_as_string(timeout)
931 h1_stream:get_body_chars(n, timeout)
933 See stream:get_body_chars(n, timeout)
934 h1_stream:get_body_until(pattern, plain, include_pattern, timeout)
936 See stream:get_body_until(pattern, plain, include_pattern, timeout)
937 h1_stream:save_body_to_file(file, timeout)
939 See stream:save_body_to_file(file, timeout)
940 h1_stream:get_body_as_file(timeout)
942 See stream:get_body_as_file(timeout)
943 h1_stream:unget(str)
945 See stream:unget(str)
946 h1_stream:write_chunk(chunk, end_stream, timeout)
948 See stream:write_chunk(chunk, end_stream, timeout)
949 h1_stream:write_body_from_string(str, timeout)
951 See stream:write_body_from_string(str, timeout)
952 h1_stream:write_body_from_file(options|file, timeout)
954 See stream:write_body_from_file(options|file, timeout)
955 h1_stream:shutdown()
957 See stream:shutdown()
958 h1_stream:set_state(new)
960 Sets the state of the stream to new. new must be one of the following
961 valid states:
962 · "open": have sent or received headers; haven't sent body yet
964 · "half closed (local)": have sent whole body
966 · "half closed (remote)": have received whole body
968 · "closed": complete
970 Not all state transitions are allowed.
972 h1_stream:read_headers(timeout)
974 Reads and returns a header block from the underlying connection. Does
975 not take into account buffered header blocks. On error, returns nil,
976 an error message and an error number.
977 This function should rarely be used, you're probably looking for
979 :get_headers().
980 h1_stream:read_next_chunk(timeout)
982 Reads and returns the next chunk as a string from the underlying con‐
983 nection. Does not take into account buffered chunks. On error, re‐
984 turns nil, an error message and an error number.
985 This function should rarely be used, you're probably looking for
987 :get_next_chunk().
988 http.h2_connection
990 The h2_connection module adheres to the connection interface and pro‐
991 vides HTTP 2 specific operations. An HTTP 2 connection can have multi‐
992 ple streams actively transmitting data at once, hence an http.h2_con‐
993 nection acts much like a scheduler.
994 new(socket, conn_type, settings)
996 Constructor for a new connection. Takes a cqueues socket object, a
997 connection type string and an optional table of HTTP 2 settings. Re‐
998 turns the newly initialized connection object in a non-connected state.
999 h2_connection.version
1001 Contains the HTTP connection version. Currently this will always be 2.
1002 See connection.version
1004 h2_connection:pollfd()
1006 See connection:pollfd()
1007 h2_connection:events()
1009 See connection:events()
1010 h2_connection:timeout()
1012 See connection:timeout()
1013 h2_connection:empty()
1015 h2_connection:step(timeout)
1016 h2_connection:loop(timeout)
1017 h2_connection:connect(timeout)
1018 See connection:connect(timeout)
1019 h2_connection:checktls()
1021 See connection:checktls()
1022 h2_connection:localname()
1024 See connection:localname()
1025 h2_connection:peername()
1027 See connection:peername()
1028 h2_connection:flush(timeout)
1030 See connection:flush(timeout)
1031 h2_connection:shutdown()
1033 See connection:shutdown()
1034 h2_connection:close()
1036 See connection:close()
1037 h2_connection:new_stream(id)
1039 Create and return a new h2_stream. id (optional) is the stream id to
1040 assign the new stream, if not specified for client initiated streams
1041 this will be the next free odd numbered stream, for server initiated
1042 streams this will be the next free even numbered stream.
1043 See connection:new_stream() for more information.
1045 h2_connection:get_next_incoming_stream(timeout)
1047 See connection:get_next_incoming_stream(timeout)
1048 h2_connection:onidle(new_handler)
1050 See connection:onidle(new_handler)
1051 h2_connection:read_http2_frame(timeout)
1053 h2_connection:write_http2_frame(typ, flags, streamid, payload, time‐
1054 out, flush)
1055 h2_connection:ping(timeout)
1056 h2_connection:write_window_update(inc, timeout)
1057 h2_connection:write_goaway_frame(last_stream_id, err_code, debug_msg, time‐
1058 out)
1059 h2_connection:set_peer_settings(peer_settings)
1060 h2_connection:ack_settings()
1061 h2_connection:settings(tbl, timeout)
1062 http.h2_error
1063 A type of error object that encapsulates HTTP 2 error information. An
1064 http.h2_error object has fields:
1065 · name: The error name: a short identifier for this error
1067 · code: The error code
1069 · description: The description of the error code
1071 · message: An error message
1073 · traceback: A traceback taken at the point the error was thrown
1075 · stream_error: A boolean that indicates if this is a stream level or
1077 protocol level error
1078 errors
1080 A table containing errors as defined by the HTTP 2 specification
1081 (https://http2.github.io/http2-spec/#iana-errors). It can be indexed
1082 by error name (e.g. errors.PROTOCOL_ERROR) or numeric code (e.g. er‐
1083 rors[0x1]).
1084 is(ob)
1086 Returns a boolean indicating if the object ob is an http.h2_error ob‐
1087 ject
1088 h2_error:new(ob)
1090 Creates a new error object from the passed table. The table should
1091 have the form of an error object i.e. with fields name, code, message,
1092 traceback, etc.
1093 Fields name, code and description are inherited from the parent h2_er‐
1095 ror object if not specified.
1096 stream_error defaults to false.
1098 h2_error:new_traceback(message, stream_error, lvl)
1100 Creates a new error object, recording a traceback from the current
1101 thread.
1102 h2_error:error(message, stream_error, lvl)
1104 Creates and throws a new error.
1105 h2_error:assert(cond, ...)
1107 If cond is truthy, returns cond, ...
1108 If cond is falsy (i.e. false or nil), throws an error with the first
1110 element of ... as the message.
1111 http.h2_stream
1113 An h2_stream represents an HTTP 2 stream. The module follows the
1114 stream interface as well as HTTP 2 specific functions.
1115 h2_stream.connection
1117 See stream.connection
1118 h2_stream:checktls()
1120 See stream:checktls()
1121 h2_stream:localname()
1123 See stream:localname()
1124 h2_stream:peername()
1126 See stream:peername()
1127 h2_stream:get_headers(timeout)
1129 See stream:get_headers(timeout)
1130 h2_stream:write_headers(headers, end_stream, timeout)
1132 See stream:write_headers(headers, end_stream, timeout)
1133 h2_stream:write_continue(timeout)
1135 See stream:write_continue(timeout)
1136 h2_stream:get_next_chunk(timeout)
1138 See stream:get_next_chunk(timeout)
1139 h2_stream:each_chunk()
1141 See stream:each_chunk()
1142 h2_stream:get_body_as_string(timeout)
1144 See stream:get_body_as_string(timeout)
1145 h2_stream:get_body_chars(n, timeout)
1147 See stream:get_body_chars(n, timeout)
1148 h2_stream:get_body_until(pattern, plain, include_pattern, timeout)
1150 See stream:get_body_until(pattern, plain, include_pattern, timeout)
1151 h2_stream:save_body_to_file(file, timeout)
1153 See stream:save_body_to_file(file, timeout)
1154 h2_stream:get_body_as_file(timeout)
1156 See stream:get_body_as_file(timeout)
1157 h2_stream:unget(str)
1159 See stream:unget(str)
1160 h2_stream:write_chunk(chunk, end_stream, timeout)
1162 See stream:write_chunk(chunk, end_stream, timeout)
1163 h2_stream:write_body_from_string(str, timeout)
1165 See stream:write_body_from_string(str, timeout)
1166 h2_stream:write_body_from_file(options|file, timeout)
1168 See stream:write_body_from_file(options|file, timeout)
1169 h2_stream:shutdown()
1171 See stream:shutdown()
1172 h2_stream:pick_id(id)
1174 h2_stream:set_state(new)
1175 h2_stream:reprioritise(child, exclusive)
1176 h2_stream:write_http2_frame(typ, flags, payload, timeout, flush)
1177 Writes a frame with h2_stream's stream id.
1178 See h2_connection:write_http2_frame(typ, flags, streamid, pay‐
1180 load, timeout, flush)
1181 h2_stream:write_data_frame(payload, end_stream, padded, timeout, flush)
1183 h2_stream:write_headers_frame(payload, end_stream, end_headers, padded, ex‐
1184 clusive, stream_dep, weight, timeout, flush)
1185 h2_stream:write_priority_frame(exclusive, stream_dep, weight, time‐
1186 out, flush)
1187 h2_stream:write_rst_stream_frame(err_code, timeout, flush)
1188 h2_stream:rst_stream(err, timeout)
1189 h2_stream:write_settings_frame(ACK, settings, timeout, flush)
1190 h2_stream:write_push_promise_frame(promised_stream_id, payload, end_head‐
1191 ers, padded, timeout, flush)
1192 h2_stream:push_promise(headers, timeout)
1193 Pushes a new promise to the client.
1194 Returns the new stream as a h2_stream.
1196 h2_stream:write_ping_frame(ACK, payload, timeout, flush)
1198 h2_stream:write_goaway_frame(last_streamid, err_code, debug_msg, time‐
1199 out, flush)
1200 h2_stream:write_window_update_frame(inc, timeout, flush)
1201 h2_stream:write_window_update(inc, timeout)
1202 h2_stream:write_continuation_frame(payload, end_headers, timeout, flush)
1203 http.headers
1204 An ordered list of header fields. Each field has a name, a value and a
1205 never_index flag that indicates if the header field is potentially sen‐
1206 sitive data.
1207 Each headers object has an index by field name to efficiently retrieve
1209 values by key. Keep in mind that there can be multiple values for a
1210 given field name. (e.g. an HTTP server may send two Set-Cookie head‐
1211 ers).
1212 As noted in the Conventions section, HTTP 1 request and status line
1214 fields are passed around inside of headers objects under keys ":author‐
1215 ity", ":method", ":path", ":scheme" and ":status" as defined in HTTP 2.
1216 As such, they are all kept in string form (important to remember for
1217 the ":status" field).
1218 new()
1220 Creates and returns a new headers object.
1221 headers:len()
1223 Returns the number of headers.
1224 Also available as #headers in Lua 5.2+.
1226 headers:clone()
1228 Creates and returns a clone of the headers object.
1229 headers:append(name, value, never_index)
1231 Append a header.
1232 · name is the header field name. Lower case is the convention. It
1234 will not be validated at this time.
1235 · value is the header field value. It will not be validated at this
1237 time.
1238 · never_index is an optional boolean that indicates if the value should
1240 be considered secret. Defaults to true for header fields: authoriza‐
1241 tion, proxy-authorization, cookie and set-cookie.
1242 headers:each()
1244 An iterator over all headers that emits name, value, never_index.
1245 Example
1247 local http_headers = require "http.headers"
1248 local myheaders = http_headers.new()
1249 myheaders:append(":status", "200")
1250 myheaders:append("set-cookie", "foo=bar")
1251 myheaders:append("connection", "close")
1252 myheaders:append("set-cookie", "baz=qux")
1253 for name, value, never_index in myheaders:each() do
1254 print(name, value, never_index)
1255 end
1256 --[[ prints:
1257 ":status", "200", false
1258 "set-cookie", "foo=bar", true
1259 "connection", "close", false
1260 "set-cookie", "baz=qux", true
1261 ]]
1262 headers:has(name)
1264 Returns a boolean indicating if the headers object has a field with the
1265 given name.
1266 headers:delete(name)
1268 Removes all occurrences of a field name from the headers object.
1269 headers:geti(i)
1271 Return the i-th header as name, value, never_index
1272 headers:get_as_sequence(name)
1274 Returns all headers with the given name in a table. The table will
1275 contain a field .n with the number of elements.
1276 Example
1278 local http_headers = require "http.headers"
1279 local myheaders = http_headers.new()
1280 myheaders:append(":status", "200")
1281 myheaders:append("set-cookie", "foo=bar")
1282 myheaders:append("connection", "close")
1283 myheaders:append("set-cookie", "baz=qux")
1284 local mysequence = myheaders:get_as_sequence("set-cookie")
1285 --[[ mysequence will be:
1286 {n = 2; "foo=bar"; "baz=qux"}
1287 ]]
1288 headers:get(name)
1290 Returns all headers with the given name as multiple return values.
1291 headers:get_comma_separated(name)
1293 Returns all headers with the given name as items in a comma separated
1294 string.
1295 headers:modifyi(i, value, never_index)
1297 Change the i-th's header to a new value and never_index.
1298 headers:upsert(name, value, never_index)
1300 If a header with the given name already exists, replace it. If not,
1301 append it to the list of headers.
1302 Cannot be used when a header name already has multiple values.
1304 headers:sort()
1306 Sort the list of headers by their field name, ordering those starting
1307 with : first. If names are equal then sort by value, then by never_in‐
1308 dex.
1309 headers:dump(file, prefix)
1311 Print the headers list to the given file, one per line. If file is not
1312 given, then print to stderr. prefix is prefixed to each line.
1313 http.hpack
1315 new(SETTINGS_HEADER_TABLE_SIZE)
1316 hpack_context:append_data(val)
1317 hpack_context:render_data()
1318 hpack_context:clear_data()
1319 hpack_context:evict_from_dynamic_table()
1320 hpack_context:dynamic_table_tostring()
1321 hpack_context:set_max_dynamic_table_size(SETTINGS_HEADER_TABLE_SIZE)
1322 hpack_context:encode_max_size(val)
1323 hpack_context:resize_dynamic_table(new_size)
1324 hpack_context:add_to_dynamic_table(name, value, k)
1325 hpack_context:dynamic_table_id_to_index(id)
1326 hpack_context:lookup_pair_index(k)
1327 hpack_context:lookup_name_index(name)
1328 hpack_context:lookup_index(index)
1329 hpack_context:add_header_indexed(name, value, huffman)
1330 hpack_context:add_header_never_indexed(name, value, huffman)
1331 hpack_context:encode_headers(headers)
1332 hpack_context:decode_headers(payload, header_list, pos)
1333 http.hsts
1334 Data structures useful for HSTS (HTTP Strict Transport Security)
1335 new_store()
1337 Creates and returns a new HSTS store.
1338 hsts_store.max_items
1340 The maximum number of items allowed in the store. Decreasing this val‐
1341 ue will only prevent new items from being added, it will not remove old
1342 items.
1343 Defaults to infinity (any number of items is allowed).
1345 hsts_store:clone()
1347 Creates and returns a copy of a store.
1348 hsts_store:store(host, directives)
1350 Add new directives to the store about the given host. directives
1351 should be a table of directives, which must include the key "max-age".
1352 Returns a boolean indicating if the item was accepted.
1354 hsts_store:remove(host)
1356 Removes the entry for host from the store (if it exists).
1357 hsts_store:check(host)
1359 Returns a boolean indicating if the given host is a known HSTS host.
1360 hsts_store:clean_due()
1362 Returns the number of seconds until the next item in the store expires.
1363 hsts_store:clean()
1365 Removes expired entries from the store.
1366 http.proxies
1368 new()
1369 Returns an empty `proxies' object
1370 proxies:update(getenv)
1372 getenv defaults to os.getenv (http://www.lua.org/manual/5.3/manu‐
1373 al.html#pdf-os.getenv)
1374 Reads environmental variables that are used to control if requests go
1376 through a proxy.
1377 · http_proxy (or CGI_HTTP_PROXY if running in a program with GATE‐
1379 WAY_INTERFACE set): the proxy to use for normal HTTP connections
1380 · https_proxy or HTTPS_PROXY: the proxy to use for HTTPS connections
1382 · all_proxy or ALL_PROXY: the proxy to use for all connections, over‐
1384 ridden by other options
1385 · no_proxy or NO_PROXY: a list of hosts to not use a proxy for
1387 Returns proxies.
1389 proxies:choose(scheme, host)
1391 Returns the proxy to use for the given scheme and host as a URI.
1392 http.request
1394 The http.request module encapsulates all the functionality required to
1395 retrieve an HTTP document from a server.
1396 new_from_uri(uri)
1398 Creates a new http.request object from the given URI.
1399 new_connect(uri, connect_authority)
1401 Creates a new http.request object from the given URI that will perform
1402 a CONNECT request.
1403 request.host
1405 The host this request should be sent to.
1406 request.port
1408 The port this request should be sent to.
1409 request.bind
1411 The local outgoing address and optionally port to bind in the form of
1412 "address[:port]". Default is to allow the kernel to choose an ad‐
1413 dress+port.
1414 IPv6 addresses may be specified via square bracket notation. e.g.
1416 "127.0.0.1", "127.0.0.1:50000", "[::1]:30000".
1417 This option is rarely needed. Supplying an address can be used to man‐
1419 ually select the network interface to make the request from, while sup‐
1420 plying a port is only really used to interoperate with firewalls or de‐
1421 vices that demand use of a certain port.
1422 request.tls
1424 A boolean indicating if TLS should be used.
1425 request.ctx
1427 An alternative SSL_CTX* to use. If not specified, uses the default TLS
1428 settings (see http.tls for information).
1429 request.sendname
1431 The TLS SNI host name used.
1432 request.version
1434 The HTTP version to use; leave as nil to auto-select.
1435 request.proxy
1437 Specifies the a proxy that the request will be made through. The value
1438 should be a URI or false to turn off proxying for the request.
1439 request.headers
1441 A http.headers object of headers that will be sent in the request.
1442 request.hsts
1444 The http.hsts store that will be used to enforce HTTP strict transport
1445 security. An attempt will be made to add strict transport headers from
1446 a response to the store.
1447 Defaults to a shared store.
1449 request.proxies
1451 The http.proxies object used to select a proxy for the request. Only
1452 consulted if request.proxy is nil.
1453 request.cookie_store
1455 The http.cookie.store that will be used to find cookies for the re‐
1456 quest. An attempt will be made to add cookies from a response to the
1457 store.
1458 Defaults to a shared store.
1460 request.is_top_level
1462 A boolean flag indicating if this request is a “top level” request (See
1463 RFC 6265bis-02 Section 5.2 (https://tools.ietf.org/html/draft-ietf-
1464 httpbis-rfc6265bis-02#section-5.2))
1465 Defaults to true
1467 request.site_for_cookies
1469 A string containing the host that should be considered as the “site for
1470 cookies” (See RFC 6265bis-02 Section 5.2
1471 (https://tools.ietf.org/html/draft-ietf-httpbis-rfc6265bis-02#sec‐
1472 tion-5.2)), can be nil if unknown.
1473 Defaults to nil.
1475 request.follow_redirects
1477 Boolean indicating if :go() should follow redirects. Defaults to true.
1478 request.expect_100_timeout
1480 Number of seconds to wait for a 100 Continue response before proceeding
1481 to send a request body. Defaults to 1.
1482 request.max_redirects
1484 Maximum number of redirects to follow before giving up. Defaults to 5.
1485 Set to math.huge to not give up.
1486 request.post301
1488 Respect RFC 2616 Section 10.3.2 and don't convert POST requests into
1489 body-less GET requests when following a 301 redirect. The non-RFC be‐
1490 haviour is ubiquitous in web browsers and assumed by servers. Modern
1491 HTTP endpoints send status code 308 to indicate that they don't want
1492 the method to be changed. Defaults to false.
1493 request.post302
1495 Respect RFC 2616 Section 10.3.3 and don't convert POST requests into
1496 body-less GET requests when following a 302 redirect. The non-RFC be‐
1497 haviour is ubiquitous in web browsers and assumed by servers. Modern
1498 HTTP endpoints send status code 307 to indicate that they don't want
1499 the method to be changed. Defaults to false.
1500 request:clone()
1502 Creates and returns a clone of the request.
1503 The clone has its own deep copies of the .headers and .h2_settings
1505 fields.
1506 The .tls and .body fields are shallow copied from the original request.
1508 request:handle_redirect(headers)
1510 Process a redirect.
1511 headers should be response headers for a redirect.
1513 Returns a new request object that will fetch from new location.
1515 request:to_uri(with_userinfo)
1517 Returns a URI for the request.
1518 If with_userinfo is true and the request has an authorization header
1520 (or proxy-authorization for a CONNECT request), the returned URI will
1521 contain a userinfo component.
1522 request:set_body(body)
1524 Allows setting a request body. body may be a string, function or lua
1525 file object.
1526 · If body is a string it will be sent as given.
1528 · If body is a function, it will be called repeatedly like an iterator.
1530 It should return chunks of the request body as a string or nil if
1531 done.
1532 · If body is a lua file object, it will be :seek'd
1534 (http://www.lua.org/manual/5.3/manual.html#pdf-file:seek) to the
1535 start, then sent as a body. Any errors encountered during file oper‐
1536 ations will be thrown.
1537 request:go(timeout)
1539 Performs the request.
1540 The request object is not invalidated; and can be reused for a new re‐
1542 quest. On success, returns the response headers and a stream.
1543 http.server
1545 http.server objects are used to encapsulate the accept() and dispatch
1546 of http clients. Each new client request will invoke the onstream
1547 callback in a new cqueues managed coroutine. In addition to construct‐
1548 ing and returning a HTTP response, an onstream handler may decide to
1549 take ownership of the connection for other purposes, e.g. upgrade from
1550 a HTTP 1.1 connection to a WebSocket connection.
1551 For examples of how to use the server library, please see the examples
1553 directory (https://github.com/daurnimator/lua-http/tree/master/exam‐
1554 ples) in the source tree.
1555 new(options)
1557 Creates a new instance of an HTTP server listening on the given socket.
1558 · .socket (cqueues.socket): the socket that accept() will be called on
1560 · .onerror (function): Function that will be called when an error oc‐
1562 curs (default handler throws an error). See server:onerror()
1563 · .onstream (function): Callback function for handling a new client re‐
1565 quest. The function receives the server and the new stream as param‐
1566 eters. If the callback throws an error it will be reported from
1567 :step() or :loop()
1568 · .tls (boolean): Specifies if the system should use Transport Layer
1570 Security. Values are:
1571 · nil: Allow both tls and non-tls connections
1573 · true: Allows tls connections only
1575 · false: Allows non-tls connections only
1577 · .ctx (context object): An openssl.ssl.context object to use for tls
1579 connections. If nil is passed, a self-signed context will be gener‐
1580 ated.
1581 · .connection_setup_timeout (number): Timeout (in seconds) to wait for
1583 client to send first bytes and/or complete TLS handshake. Default is
1584 10 seconds.
1585 · .intra_stream_timeout (number): Timeout (in seconds) to wait for a
1587 new stream on an idle connection before giving up and closing the
1588 connection
1589 · .version (number): The http version to allow to connect (default:
1591 any)
1592 · .cq (cqueue): A cqueues controller to use as a main loop. The de‐
1594 fault is a new controller for the server.
1595 · .max_concurrent (number): Maximum number of connections to allow live
1597 at a time. Default is infinity.
1598 listen(options)
1600 Creates a new socket and returns an HTTP server that will accept() from
1601 it. Parameters are the same as new(options) except instead of .socket
1602 you provide the following:
1603 · .host (string): Local IP address in dotted decimal or IPV6 notation.
1605 This value is required if .path is not specified.
1606 · .port (number): IP port for the local socket. Specify 0 for automat‐
1608 ic port selection. Ports 1-1024 require the application has root
1609 privilege to run. Maximum value is 65535. If .tls == nil then this
1610 value is required. Otherwise, the defaults are:
1611 · 80 if .tls == false
1613 · 443 if .tls == true
1615 · .path (string): Path to UNIX a socket. This value is required if
1617 .host is not specified.
1618 · .family (string): Protocol family. Default is "AF_INET"
1620 · .v6only (boolean): Specify true to limit all connections to ipv6 only
1622 (no ipv4-mapped-ipv6). Default is false.
1623 · .mode (string): fchmod or chmod socket after creating UNIX domain
1625 socket.
1626 · .mask (boolean): Set and restore umask when binding UNIX domain sock‐
1628 et.
1629 · .unlink (boolean): true means unlink socket path before binding.
1631 · .reuseaddr (boolean): Turn on SO_REUSEADDR flag.
1633 · .reuseport (boolean): Turn on SO_REUSEPORT flag.
1635 server:onerror(new_handler)
1637 If called with parameters, the function replaces the current error han‐
1638 dler function with new_handler and returns a reference to the old func‐
1639 tion. Calling the function with no parameters returns the current er‐
1640 ror handler. The default handler throws an error. The onerror func‐
1641 tion for the server can be set during instantiation through the options
1642 table passed to the server.listen(options) function.
1643 server:listen(timeout)
1645 Initializes the server socket and if required, resolves DNS. serv‐
1646 er:listen() is required if localname is called before step or loop. On
1647 error, returns nil, an error message and an error number.
1648 server:localname()
1650 Returns the connection information for the local socket. Returns ad‐
1651 dress family, IP address and port for an external socket. For Unix do‐
1652 main sockets, the function returns AF_UNIX and the path. If the con‐
1653 nection object is not connected, returns AF_UNSPEC (0). On error, re‐
1654 turns nil, an error message and an error number.
1655 server:pause()
1657 Cause the server loop to stop processing new clients until resume is
1658 called. Existing client connections will run until closed.
1659 server:resume()
1661 Resumes a paused server and processes new client requests.
1662 server:close()
1664 Shutdown the server and close the socket. A closed server cannot be
1665 reused.
1666 server:pollfd()
1668 Returns a file descriptor (as an integer) or nil.
1669 The file descriptor can be passed to a system API like select or kqueue
1671 to wait on anything this server object wants to do. This method is
1672 used for integrating with other main loops, and should be used in com‐
1673 bination with :events() and :timeout().
1674 server:events()
1676 Returns a string indicating the type of events the object is waiting
1677 on: the string will contain "r" if it wants to be steped when the file
1678 descriptor returned by pollfd() has had POLLIN indicated; "w" for POLL‐
1679 OUT or "p" for POLLPRI.
1680 This method is used for integrating with other main loops, and should
1682 be used in combination with :pollfd() and :timeout().
1683 server:timeout()
1685 The maximum time (in seconds) to wait before calling server:step().
1686 This method is used for integrating with other main loops, and should
1688 be used in combination with :pollfd() and :events().
1689 server:empty()
1691 Returns true if the master socket and all client connection have been
1692 closed, false otherwise.
1693 server:step(timeout)
1695 Step once through server's main loop: any waiting clients will be ac‐
1696 cept()-ed, any pending streams will start getting processed, and each
1697 onstream handler will get be run at most once. This method will block
1698 for up to timeout seconds. On error, returns nil, an error message and
1699 an error number.
1700 This can be used for integration with external main loops.
1702 server:loop(timeout)
1704 Run the server as a blocking loop for up to timeout seconds. The serv‐
1705 er will continue to listen and accept client requests until either
1706 :pause() or :close() is called, or an error is experienced.
1707 server:add_socket(socket)
1709 Add a new connection socket to the server for processing. The server
1710 will use the current onstream request handler and all options currently
1711 specified through the server.listen(options) constructor. add_socket
1712 can be used to process connection sockets obtained from an external
1713 source such as:
1714 · Another cqueues thread with some other master socket.
1716 · From inetd for start on demand daemons.
1718 · A Unix socket with SCM_RIGHTS.
1720 server:add_stream(stream)
1722 Add an existing stream to the server for processing.
1723 http.socks
1725 Implements a subset of the SOCKS proxy protocol.
1726 connect(uri)
1728 uri is a string with the address of the SOCKS server. A scheme of
1729 "socks5" will resolve hosts locally, a scheme of "socks5h" will resolve
1730 hosts on the SOCKS server. If the URI has a userinfo component it will
1731 be sent to the SOCKS server as a username and password.
1732 Returns a http.socks object.
1734 fdopen(socket)
1736 This function takes an existing cqueues.socket as a parameter and re‐
1737 turns a http.socks object with socket as its base.
1738 socks.needs_resolve
1740 Specifies if the destination host should be resolved locally.
1741 socks:clone()
1743 Make a clone of a given socks object.
1744 socks:add_username_password_auth(username, password)
1746 Add username + password authorisation to the set of allowed authorisa‐
1747 tion methods with the given credentials.
1748 socks:negotiate(host, port, timeout)
1750 Complete the SOCKS connection.
1751 Negotiates a socks connection. host is a required string passed to the
1753 SOCKS server as the host address. The address will be resolved locally
1754 if .needs_resolve is true. port is a required number to pass to the
1755 SOCKS server as the connection port. On error, returns nil, an error
1756 message and an error number.
1757 socks:close()
1759 socks:take_socket()
1760 Take possession of the socket object managed by the http.socks object.
1761 Returns the socket (or nil if not available).
1762 http.tls
1764 has_alpn
1765 Boolean indicating if ALPN is available in the current environment.
1766 It may be disabled if OpenSSL was compiled without ALPN support, or is
1768 an old version.
1769 has_hostname_validation
1771 Boolean indicating if hostname validation (https://wiki.openssl.org/in‐
1772 dex.php/Hostname_validation) is available in the current environment.
1773 It may be disabled if OpenSSL is an old version.
1775 modern_cipher_list
1777 The Mozilla “Modern” cipher list (https://wiki.mozilla.org/Securi‐
1778 ty/Server_Side_TLS#Modern_compatibility) as a colon separated list,
1779 ready to pass to OpenSSL
1780 intermediate_cipher_list
1782 The Mozilla “Intermediate” cipher list (https://wiki.mozilla.org/Secu‐
1783 rity/Server_Side_TLS#Intermediate_compatibility_.28default.29) as a
1784 colon separated list, ready to pass to OpenSSL
1785 old_cipher_list
1787 The Mozilla “Old” cipher list (https://wiki.mozilla.org/Security/Serv‐
1788 er_Side_TLS#Old_backward_compatibility) as a colon separated list,
1789 ready to pass to OpenSSL
1790 banned_ciphers
1792 A set (table with string keys and values of true) of the ciphers banned
1793 in HTTP 2 (https://http2.github.io/http2-spec/#BadCipherSuites) where
1794 the keys are OpenSSL cipher names.
1795 Ciphers not known by OpenSSL are missing from the set.
1797 new_client_context()
1799 Create and return a new luaossl SSL context useful for HTTP client con‐
1800 nections.
1801 new_server_context()
1803 Create and return a new luaossl SSL context useful for HTTP server con‐
1804 nections.
1805 http.util
1807 encodeURI(str)
1808 encodeURIComponent(str)
1809 decodeURI(str)
1810 decodeURIComponent(str)
1811 query_args(str)
1812 Returns an iterator over the pairs in str
1813 Example
1815 local http_util = require "http.util"
1816 for name, value in http_util.query_args("foo=bar&baz=qux") do
1817 print(name, value)
1818 end
1819 --[[ prints:
1820 "foo", "bar"
1821 "baz", "qux"
1822 ]]
1823 dict_to_query(dict)
1825 Converts a dictionary (table with string keys) with string values to an
1826 encoded query string.
1827 Example
1829 local http_util = require "http.util"
1830 print(http_util.dict_to_query({foo = "bar"; baz = "qux"})) --> "baz=qux&foo=bar"
1831 resolve_relative_path(orig_path, relative_path)
1833 is_safe_method(method)
1834 Returns a boolean indicating if the passed string method is a “safe”
1835 method. See RFC 7231 section 4.2.1
1836 (https://tools.ietf.org/html/rfc7231#section-4.2.1) for more informa‐
1837 tion.
1838 is_ip(str)
1840 Returns a boolean indicating if the passed string str is a valid IP.
1841 scheme_to_port
1843 Map from schemes (as strings) to default ports (as integers).
1844 split_authority(authority, scheme)
1846 Splits an authority into host and port components. If the authority
1847 has no port component, will attempt to use the default for the scheme.
1848 Example
1850 local http_util = require "http.util"
1851 print(http_util.split_authority("localhost:8000", "http")) --> "localhost", 8000
1852 print(http_util.split_authority("example.com", "https")) --> "localhost", 443
1853 to_authority(host, port, scheme)
1855 Joins the host and port to create a valid authority component. Omits
1856 the port if it is the default for the scheme.
1857 imf_date(time)
1859 Returns the time in HTTP preferred date format (See RFC 7231 section
1860 7.1.1.1 (https://tools.ietf.org/html/rfc7231#section-7.1.1.1))
1861 time defaults to the current time
1863 maybe_quote(str)
1865 · If str is a valid token, return it as-is.
1866 · If str would be valid as a quoted-string, return the quoted version
1868 · Otherwise, returns nil
1870 http.version
1872 name
1873 "lua-http"
1874 version
1876 Current version of lua-http as a string.
1877 http.websocket
1879 new_from_uri(uri, protocols)
1880 Creates a new http.websocket object of type "client" from the given
1881 URI.
1882 · protocols (optional) should be a lua table containing a sequence of
1884 protocols to send to the server
1885 new_from_stream(stream, headers)
1887 Attempts to create a new http.websocket object of type "server" from
1888 the given request headers and stream.
1889 · stream should be a live HTTP 1 stream of the "server" type.
1891 · headers should be headers of a suspected websocket upgrade request
1893 from an HTTP 1 client.
1894 This function does not have side effects, and is hence okay to use ten‐
1896 tatively.
1897 websocket.close_timeout
1899 Amount of time (in seconds) to wait between sending a close frame and
1900 actually closing the connection. Defaults to 3 seconds.
1901 websocket:accept(options, timeout)
1903 Completes negotiation with a websocket client.
1904 · options is a table containing:
1906 · headers (optional) a headers object to use as a prototype for the
1908 response headers
1909 · protocols (optional) should be a lua table containing a sequence of
1911 protocols to allow from the client
1912 Usually called after a successful new_from_stream
1914 websocket:connect(timeout)
1916 Connect to a websocket server.
1917 Usually called after a successful new_from_uri
1919 websocket:receive(timeout)
1921 Reads and returns the next data frame plus its opcode. Any ping frames
1922 received while reading will be responded to.
1923 The opcode 0x1 will be returned as "text" and 0x2 will be returned as
1925 "binary".
1926 websocket:each()
1928 Iterator over websocket:receive().
1929 websocket:send_frame(frame, timeout)
1931 Low level function to send a raw frame.
1932 websocket:send(data, opcode, timeout)
1934 Send the given data as a data frame.
1935 · data should be a string
1937 · opcode can be a numeric opcode, "text" or "binary". If nil, defaults
1939 to a text frame. Note this opcode is the websocket frame opcode, not
1940 an application specific opcode. The opcode should be one from the
1941 IANA registry (https://www.iana.org/assignments/websocket/websock‐
1942 et.xhtml#opcode).
1943 websocket:send_ping(data, timeout)
1945 Sends a ping frame.
1946 · data is optional
1948 websocket:send_pong(data, timeout)
1950 Sends a pong frame. Works as a unidirectional keep-alive.
1951 · data is optional
1953 websocket:close(code, reason, timeout)
1955 Closes the websocket connection.
1956 · code defaults to 1000
1958 · reason is an optional string
1960 http.zlib
1962 An abstraction layer over the various lua zlib libraries.
1963 engine
1965 Currently either "lua-zlib" (https://github.com/brimworks/lua-zlib) or
1966 "lzlib" (https://github.com/LuaDist/lzlib)
1967 inflate()
1969 Returns a closure that inflates (uncompresses) a zlib stream.
1970 The closure takes a string of compressed data and an end of stream flag
1972 (boolean) as parameters and returns the inflated output as a string.
1973 The function will throw an error if the input is not a valid zlib
1974 stream.
1975 deflate()
1977 Returns a closure that deflates (compresses) a zlib stream.
1978 The closure takes a string of uncompressed data and an end of stream
1980 flag (boolean) as parameters and returns the deflated output as a
1981 string.
1982 Example
1984 local zlib = require "http.zlib"
1985 local original = "the racecar raced around the racecar track"
1986 local deflater = zlib.deflate()
1987 local compressed = deflater(original, true)
1988 print(#original, #compressed) -- compressed should be smaller
1989 local inflater = zlib.inflate()
1990 local uncompressed = inflater(compressed, true)
1991 assert(original == uncompressed)
1992 http.compat.prosody
1994 Provides usage similar to prosody's net.http
1995 (https://prosody.im/doc/developers/net/http)
1996 request(url, ex, callback)
1998 A few key differences to the prosody net.http.request:
1999 · must be called from within a running cqueue
2001 · The callback may be called from a different thread in the cqueue
2003 · The returned object will be a http.request object
2005 · This object is passed to the callback on errors and as the fourth
2007 argument on success
2008 · The default user-agent will be from lua-http (rather than
2010 "Prosody XMPP Server")
2011 · lua-http features (such as HTTP2) will be used where possible
2013 Example
2015 local prosody_http = require "http.compat.prosody"
2016 local cqueues = require "cqueues"
2017 local cq = cqueues.new()
2018 cq:wrap(function()
2019 prosody_http.request("http://httpbin.org/ip", {}, function(b, c, r)
2020 print(c) --> 200
2021 print(b) --> {"origin": "123.123.123.123"}
2022 end)
2023 end)
2024 assert(cq:loop())
2025 http.compat.socket
2027 Provides compatibility with luasocket's http.request module
2028 (http://w3.impa.br/~diego/software/luasocket/http.html).
2029 Differences:
2031 · Will automatically be non-blocking when run inside a cqueues managed
2033 coroutine
2034 · lua-http features (such as HTTP2) will be used where possible
2036 Example
2038 Using the `simple' interface as part of a normal script:
2039 local socket_http = require "http.compat.socket"
2041 local body, code = assert(socket_http.request("http://lua.org"))
2042 print(code, #body) --> 200, 2514
2043
2045 · Github (https://github.com/daurnimator/lua-http)
2046 · Issue tracker (https://github.com/daurnimator/lua-http/issues)
2048
2050 Daurnimator <quae@daurnimator.com>.
2051 lua-http()