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 lua-
115 http and require no effort on the developers part. For instance, an
116 HTTP server can be instantiated within any Lua main loop and run along‐
117 side application code without adversely affecting the main application
118 process. If other cqueue enabled components are integrated within a
119 cqueue loop, the application is entirely event driven through kernel
120 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://25thandclement.com/~will‐
129 iam/projects/cqueues.html) for more information about the cqueues li‐
130 brary.
131 • cqueues examples can be found with the cqueues source code available
133 through git or archives (http://www.25thandclement.com/~will‐
134 iam/projects/cqueues.html#download) or accessed online here
135 (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 re-
254 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_only,
483 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 lua-
523 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_secure,
555 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_headers, req_host,
583 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_secure, is_safe_method,
612 site_for_cookies, is_top_level, max_cookie_length)
613 Finds cookies visible to suitable for passing to an entity.
614 • domain is the domain that will be sent the cookie
616 • path is the path that will be sent the cookie
618 • is_http is a boolean flag indicating if the destination is a “non-
620 HTTP” API
621 • is_secure is a boolean flag indicating if the destination will be
623 communicated with over a “secure” protocol
624 • is_safe_method is a boolean flag indicating if the cookie will be
626 sent via a safe HTTP method (See also http.util.is_safe_method)
627 • site_for_cookies is a string containing the host that should be con‐
629 sidered as the “site for cookies” (See RFC 6265bis-02 Section 5.2
630 (https://tools.ietf.org/html/draft-ietf-httpbis-rfc6265bis-02#sec‐
631 tion-5.2)), can be nil if unknown.
632 • is_top_level is a boolean flag indicating if this request is a “top
634 level” request (See RFC 6265bis-02 Section 5.2
635 (https://tools.ietf.org/html/draft-ietf-httpbis-rfc6265bis-02#sec‐
636 tion-5.2))
637 • max_cookie_length is the maximum cookie length to allow (See also
639 store.max_cookie_length)
640 Returns a string suitable for use in a Cookie header.
642 store:lookup_for_request(headers, host, site_for_cookies, is_top_level,
644 max_cookie_length)
645 Finds cookies suitable for adding to a request.
646 • headers is the http.headers object for the outgoing request
648 • host is the host that your query was directed at (only used if head‐
650 ers is missing a Host header)
651 • site_for_cookies is a string containing the host that should be con‐
653 sidered as the “site for cookies” (See RFC 6265bis-02 Section 5.2
654 (https://tools.ietf.org/html/draft-ietf-httpbis-rfc6265bis-02#sec‐
655 tion-5.2)), can be nil if unknown.
656 • is_top_level is a boolean flag indicating if this request is a “top
658 level” request (See RFC 6265bis-02 Section 5.2
659 (https://tools.ietf.org/html/draft-ietf-httpbis-rfc6265bis-02#sec‐
660 tion-5.2))
661 • max_cookie_length is the maximum cookie length to allow (See also
663 store.max_cookie_length)
664 Returns a string suitable for use in a Cookie header.
666 store:clean_due()
668 Returns the number of seconds until the next cookie in the store ex‐
669 pires.
670 store:clean()
672 Remove all expired cookies from the store.
673 store:load_from_file(file)
675 Loads cookie data from the file object file into store. The file
676 should be in the Netscape Cookiejar format. Invalid lines in the file
677 are ignored.
678 Returns true on success or passes along nil, err, errno if a :read call
680 fails.
681 store:save_to_file(file)
683 Writes the cookie data from store into the file object file in the Net‐
684 scape Cookiejar format. file is not seek-ed or truncated before writ‐
685 ing.
686 Returns true on success or passes along nil, err, errno if a :write
688 call fails.
689 http.h1_connection
691 The h1_connection module adheres to the connection interface and pro‐
692 vides HTTP 1 and 1.1 specific operations.
693 new(socket, conn_type, version)
695 Constructor for a new connection. Takes a cqueues socket object, a
696 connection type string and a numeric HTTP version number. Valid values
697 for the connection type are "client" and "server". Valid values for
698 the version number are 1 and 1.1. Returns the newly initialized con‐
699 nection object.
700 h1_connection.version
702 Specifies the HTTP version used for the connection handshake. Valid
703 values are:
704 • 1.0
706 • 1.1
708 See connection.version
710 h1_connection:pollfd()
712 See connection:pollfd()
713 h1_connection:events()
715 See connection:events()
716 h1_connection:timeout()
718 See connection:timeout()
719 h1_connection:connect(timeout)
721 See connection:connect(timeout)
722 h1_connection:checktls()
724 See connection:checktls()
725 h1_connection:localname()
727 See connection:localname()
728 h1_connection:peername()
730 See connection:peername()
731 h1_connection:flush(timeout)
733 See connection:flush(timeout)
734 h1_connection:shutdown(dir)
736 Shut down is as graceful as possible: pipelined streams are shutdown,
737 then the underlying socket is shut down in the appropriate direc‐
738 tion(s).
739 dir is a string representing the direction of communication to shut
741 down communication in. If it contains "r" it will shut down reading,
742 if it contains "w" it will shut down writing. The default is "rw",
743 i.e. to shutdown communication in both directions.
744 See connection:shutdown()
746 h1_connection:close()
748 See connection:close()
749 h1_connection:new_stream()
751 In HTTP 1, only a client may initiate new streams with this function.
752 See connection:new_stream() for more information.
754 h1_connection:get_next_incoming_stream(timeout)
756 See connection:get_next_incoming_stream(timeout)
757 h1_connection:onidle(new_handler)
759 See connection:onidle(new_handler)
760 h1_connection:setmaxline(read_length)
762 Sets the maximum read buffer size (in bytes) to read_length. i.e. sets
763 the maximum length lines (such as headers).
764 The default comes from the underlying socket, which gets the
766 (changable) cqueues default at time of construction. The default
767 cqueues default is 4096 bytes.
768 h1_connection:clearerr(...)
770 Clears errors to allow for further read or write operations on the con‐
771 nection. Returns the error number of existing errors. This function
772 is used to recover from known errors.
773 h1_connection:error(...)
775 Returns the error number of existing errors.
776 h1_connection:take_socket()
778 Used to hand the reference of the connection socket to another object.
779 Resets the socket to defaults and returns the single existing reference
780 of the socket to the calling routine. This function can be used for
781 connection upgrades such as upgrading from HTTP 1 to a WebSocket.
782 h1_connection:read_request_line(timeout)
784 Reads a request line from the socket. Returns the request method, re‐
785 quested path and HTTP version for an incoming request. :read_re‐
786 quest_line() yields until a "\r\n" terminated chunk is received, or
787 timeout is exceeded. If the incoming chunk is not a valid HTTP request
788 line, nil is returned. On error, returns nil, an error message and an
789 error number.
790 h1_connection:read_status_line(timeout)
792 Reads a line of input from the socket. If the input is a valid status
793 line, the HTTP version (1 or 1.1), status code and reason description
794 (if applicable) is returned. :read_status_line() yields until a "\r\n"
795 terminated chunk is received, or timeout is exceeded. If the socket
796 could not be read, returns nil, an error message and an error number.
797 h1_connection:read_header(timeout)
799 Reads a CRLF terminated HTTP header from the socket and returns the
800 header key and value. This function will yield until a MIME compliant
801 header item is received or until timeout is exceeded. If the header
802 could not be read, the function returns nil an error and an error mes‐
803 sage.
804 h1_connection:read_headers_done(timeout)
806 Checks for an empty line, which indicates the end of the HTTP headers.
807 Returns true if an empty line is received. Any other value is pushed
808 back on the socket receive buffer (unget) and the function returns
809 false. This function will yield waiting for input from the socket or
810 until timeout is exceeded. Returns nil, an error and an error message
811 if the socket cannot be read.
812 h1_connection:read_body_by_length(len, timeout)
814 Get len number of bytes from the socket. Use a negative number for up
815 to that number of bytes. This function will yield and wait on the
816 socket if length of the buffered body is less than len. Asserts if len
817 is not a number.
818 h1_connection:read_body_till_close(timeout)
820 Reads the entire request body. This function will yield until the body
821 is complete or timeout is expired. If the read fails the function re‐
822 turns nil, an error message and an error number.
823 h1_connection:read_body_chunk(timeout)
825 Reads the next available line of data from the request and returns the
826 chunk and any chunk extensions. This function will yield until chunk
827 size is received or timeout is exceeded. If the chunk size is indicat‐
828 ed as 0 then false and any chunk extensions are returned. Returns nil,
829 an error message and an error number if there was an error reading
830 reading the chunk header or the socket.
831 h1_connection:write_request_line(method, path, httpversion, timeout)
833 Writes the opening HTTP 1.x request line for a new request to the sock‐
834 et buffer. Yields until success or timeout. If the write fails, re‐
835 turns nil, an error message and an error number.
836 Note the request line will not be flushed to the remote server until
838 write_headers_done is called.
839 h1_connection:write_status_line(httpversion, status_code, reason_phrase,
841 timeout)
842 Writes an HTTP status line to the socket buffer. Yields until success
843 or timeout. If the write fails, the function returns nil, an error
844 message and an error number.
845 Note the status line will not be flushed to the remote server until
847 write_headers_done is called.
848 h1_connection:write_header(k, v, timeout)
850 Writes a header item to the socket buffer as a key:value string.
851 Yields until success or timeout. Returns nil, an error message and an
852 error if the write fails.
853 Note the header item will not be flushed to the remote server until
855 write_headers_done is called.
856 h1_connection:write_headers_done(timeout)
858 Terminates a header block by writing a blank line ("\r\n") to the sock‐
859 et. This function will flush all outstanding data in the socket output
860 buffer. Yields until success or timeout. Returns nil, an error mes‐
861 sage and an error if the write fails.
862 h1_connection:write_body_chunk(chunk, chunk_ext, timeout)
864 Writes a chunk of data to the socket. chunk_ext must be nil as chunk
865 extensions are not supported. Will yield until complete or timeout is
866 exceeded. Returns true on success. Returns nil, an error message and
867 an error number if the write fails.
868 h1_connection:write_body_last_chunk(chunk_ext, timeout)
870 Writes the chunked body terminator "0\r\n" to the socket. chunk_ext
871 must be nil as chunk extensions are not supported. Will yield until
872 complete or timeout is exceeded. Returns nil, an error message and an
873 error number if the write fails.
874 Note that the connection will not be immediately flushed to the remote
876 server; normally this will occur when trailers are written.
877 h1_connection:write_body_plain(body, timeout)
879 Writes the contents of body to the socket and flushes the socket output
880 buffer immediately. Yields until success or timeout is exceeded. Re‐
881 turns nil, an error message and an error number if the write fails.
882 http.h1_reason_phrases
884 A table mapping from status codes (as strings) to reason phrases for
885 HTTP 1. Any unknown status codes return "Unassigned"
886 Example
888 local reason_phrases = require "http.h1_reason_phrases"
889 print(reason_phrases["200"]) --> "OK"
890 print(reason_phrases["342"]) --> "Unassigned"
891 http.h1_stream
893 The h1_stream module adheres to the stream interface and provides HTTP
894 1.x specific operations.
895 The gzip transfer encoding is supported transparently.
897 h1_stream.connection
899 See stream.connection
900 h1_stream.max_header_lines
902 The maximum number of header lines to read. Default is 100.
903 h1_stream:checktls()
905 See stream:checktls()
906 h1_stream:localname()
908 See stream:localname()
909 h1_stream:peername()
911 See stream:peername()
912 h1_stream:get_headers(timeout)
914 See stream:get_headers(timeout)
915 h1_stream:write_headers(headers, end_stream, timeout)
917 See stream:write_headers(headers, end_stream, timeout)
918 h1_stream:write_continue(timeout)
920 See stream:write_continue(timeout)
921 h1_stream:get_next_chunk(timeout)
923 See stream:get_next_chunk(timeout)
924 h1_stream:each_chunk()
926 See stream:each_chunk()
927 h1_stream:get_body_as_string(timeout)
929 See stream:get_body_as_string(timeout)
930 h1_stream:get_body_chars(n, timeout)
932 See stream:get_body_chars(n, timeout)
933 h1_stream:get_body_until(pattern, plain, include_pattern, timeout)
935 See stream:get_body_until(pattern, plain, include_pattern, timeout)
936 h1_stream:save_body_to_file(file, timeout)
938 See stream:save_body_to_file(file, timeout)
939 h1_stream:get_body_as_file(timeout)
941 See stream:get_body_as_file(timeout)
942 h1_stream:unget(str)
944 See stream:unget(str)
945 h1_stream:write_chunk(chunk, end_stream, timeout)
947 See stream:write_chunk(chunk, end_stream, timeout)
948 h1_stream:write_body_from_string(str, timeout)
950 See stream:write_body_from_string(str, timeout)
951 h1_stream:write_body_from_file(options|file, timeout)
953 See stream:write_body_from_file(options|file, timeout)
954 h1_stream:shutdown()
956 See stream:shutdown()
957 h1_stream:set_state(new)
959 Sets the state of the stream to new. new must be one of the following
960 valid states:
961 • "open": have sent or received headers; haven’t sent body yet
963 • "half closed (local)": have sent whole body
965 • "half closed (remote)": have received whole body
967 • "closed": complete
969 Not all state transitions are allowed.
971 h1_stream:read_headers(timeout)
973 Reads and returns a header block from the underlying connection. Does
974 not take into account buffered header blocks. On error, returns nil,
975 an error message and an error number.
976 This function should rarely be used, you’re probably looking for
978 :get_headers().
979 h1_stream:read_next_chunk(timeout)
981 Reads and returns the next chunk as a string from the underlying con‐
982 nection. Does not take into account buffered chunks. On error, re‐
983 turns nil, an error message and an error number.
984 This function should rarely be used, you’re probably looking for
986 :get_next_chunk().
987 http.h2_connection
989 The h2_connection module adheres to the connection interface and pro‐
990 vides HTTP 2 specific operations. An HTTP 2 connection can have multi‐
991 ple streams actively transmitting data at once, hence an http.h2_con‐
992 nection acts much like a scheduler.
993 new(socket, conn_type, settings)
995 Constructor for a new connection. Takes a cqueues socket object, a
996 connection type string and an optional table of HTTP 2 settings. Re‐
997 turns the newly initialized connection object in a non-connected state.
998 h2_connection.version
1000 Contains the HTTP connection version. Currently this will always be 2.
1001 See connection.version
1003 h2_connection:pollfd()
1005 See connection:pollfd()
1006 h2_connection:events()
1008 See connection:events()
1009 h2_connection:timeout()
1011 See connection:timeout()
1012 h2_connection:empty()
1014 h2_connection:step(timeout)
1015 h2_connection:loop(timeout)
1016 h2_connection:connect(timeout)
1017 See connection:connect(timeout)
1018 h2_connection:checktls()
1020 See connection:checktls()
1021 h2_connection:localname()
1023 See connection:localname()
1024 h2_connection:peername()
1026 See connection:peername()
1027 h2_connection:flush(timeout)
1029 See connection:flush(timeout)
1030 h2_connection:shutdown()
1032 See connection:shutdown()
1033 h2_connection:close()
1035 See connection:close()
1036 h2_connection:new_stream(id)
1038 Create and return a new h2_stream. id (optional) is the stream id to
1039 assign the new stream, if not specified for client initiated streams
1040 this will be the next free odd numbered stream, for server initiated
1041 streams this will be the next free even numbered stream.
1042 See connection:new_stream() for more information.
1044 h2_connection:get_next_incoming_stream(timeout)
1046 See connection:get_next_incoming_stream(timeout)
1047 h2_connection:onidle(new_handler)
1049 See connection:onidle(new_handler)
1050 h2_connection:read_http2_frame(timeout)
1052 h2_connection:write_http2_frame(typ, flags, streamid, payload, timeout,
1053 flush)
1054 h2_connection:ping(timeout)
1055 h2_connection:write_window_update(inc, timeout)
1056 h2_connection:write_goaway_frame(last_stream_id, err_code, debug_msg, time‐
1057 out)
1058 h2_connection:set_peer_settings(peer_settings)
1059 h2_connection:ack_settings()
1060 h2_connection:settings(tbl, timeout)
1061 http.h2_error
1062 A type of error object that encapsulates HTTP 2 error information. An
1063 http.h2_error object has fields:
1064 • name: The error name: a short identifier for this error
1066 • code: The error code
1068 • description: The description of the error code
1070 • message: An error message
1072 • traceback: A traceback taken at the point the error was thrown
1074 • stream_error: A boolean that indicates if this is a stream level or
1076 protocol level error
1077 errors
1079 A table containing errors as defined by the HTTP 2 specification
1080 (https://http2.github.io/http2-spec/#iana-errors). It can be indexed
1081 by error name (e.g. errors.PROTOCOL_ERROR) or numeric code (e.g. er‐
1082 rors[0x1]).
1083 is(ob)
1085 Returns a boolean indicating if the object ob is an http.h2_error ob‐
1086 ject
1087 h2_error:new(ob)
1089 Creates a new error object from the passed table. The table should
1090 have the form of an error object i.e. with fields name, code, message,
1091 traceback, etc.
1092 Fields name, code and description are inherited from the parent h2_er‐
1094 ror object if not specified.
1095 stream_error defaults to false.
1097 h2_error:new_traceback(message, stream_error, lvl)
1099 Creates a new error object, recording a traceback from the current
1100 thread.
1101 h2_error:error(message, stream_error, lvl)
1103 Creates and throws a new error.
1104 h2_error:assert(cond, ...)
1106 If cond is truthy, returns cond, ...
1107 If cond is falsy (i.e. false or nil), throws an error with the first
1109 element of ... as the message.
1110 http.h2_stream
1112 An h2_stream represents an HTTP 2 stream. The module follows the
1113 stream interface as well as HTTP 2 specific functions.
1114 h2_stream.connection
1116 See stream.connection
1117 h2_stream:checktls()
1119 See stream:checktls()
1120 h2_stream:localname()
1122 See stream:localname()
1123 h2_stream:peername()
1125 See stream:peername()
1126 h2_stream:get_headers(timeout)
1128 See stream:get_headers(timeout)
1129 h2_stream:write_headers(headers, end_stream, timeout)
1131 See stream:write_headers(headers, end_stream, timeout)
1132 h2_stream:write_continue(timeout)
1134 See stream:write_continue(timeout)
1135 h2_stream:get_next_chunk(timeout)
1137 See stream:get_next_chunk(timeout)
1138 h2_stream:each_chunk()
1140 See stream:each_chunk()
1141 h2_stream:get_body_as_string(timeout)
1143 See stream:get_body_as_string(timeout)
1144 h2_stream:get_body_chars(n, timeout)
1146 See stream:get_body_chars(n, timeout)
1147 h2_stream:get_body_until(pattern, plain, include_pattern, timeout)
1149 See stream:get_body_until(pattern, plain, include_pattern, timeout)
1150 h2_stream:save_body_to_file(file, timeout)
1152 See stream:save_body_to_file(file, timeout)
1153 h2_stream:get_body_as_file(timeout)
1155 See stream:get_body_as_file(timeout)
1156 h2_stream:unget(str)
1158 See stream:unget(str)
1159 h2_stream:write_chunk(chunk, end_stream, timeout)
1161 See stream:write_chunk(chunk, end_stream, timeout)
1162 h2_stream:write_body_from_string(str, timeout)
1164 See stream:write_body_from_string(str, timeout)
1165 h2_stream:write_body_from_file(options|file, timeout)
1167 See stream:write_body_from_file(options|file, timeout)
1168 h2_stream:shutdown()
1170 See stream:shutdown()
1171 h2_stream:pick_id(id)
1173 h2_stream:set_state(new)
1174 h2_stream:reprioritise(child, exclusive)
1175 h2_stream:write_http2_frame(typ, flags, payload, timeout, flush)
1176 Writes a frame with h2_stream’s stream id.
1177 See h2_connection:write_http2_frame(typ, flags, streamid, payload,
1179 timeout, flush)
1180 h2_stream:write_data_frame(payload, end_stream, padded, timeout, flush)
1182 h2_stream:write_headers_frame(payload, end_stream, end_headers, padded, ex‐
1183 clusive, stream_dep, weight, timeout, flush)
1184 h2_stream:write_priority_frame(exclusive, stream_dep, weight, timeout,
1185 flush)
1186 h2_stream:write_rst_stream_frame(err_code, timeout, flush)
1187 h2_stream:rst_stream(err, timeout)
1188 h2_stream:write_settings_frame(ACK, settings, timeout, flush)
1189 h2_stream:write_push_promise_frame(promised_stream_id, payload, end_head‐
1190 ers, padded, timeout, flush)
1191 h2_stream:push_promise(headers, timeout)
1192 Pushes a new promise to the client.
1193 Returns the new stream as a h2_stream.
1195 h2_stream:write_ping_frame(ACK, payload, timeout, flush)
1197 h2_stream:write_goaway_frame(last_streamid, err_code, debug_msg, timeout,
1198 flush)
1199 h2_stream:write_window_update_frame(inc, timeout, flush)
1200 h2_stream:write_window_update(inc, timeout)
1201 h2_stream:write_continuation_frame(payload, end_headers, timeout, flush)
1202 http.headers
1203 An ordered list of header fields. Each field has a name, a value and a
1204 never_index flag that indicates if the header field is potentially sen‐
1205 sitive data.
1206 Each headers object has an index by field name to efficiently retrieve
1208 values by key. Keep in mind that there can be multiple values for a
1209 given field name. (e.g. an HTTP server may send two Set-Cookie head‐
1210 ers).
1211 As noted in the Conventions section, HTTP 1 request and status line
1213 fields are passed around inside of headers objects under keys ":author‐
1214 ity", ":method", ":path", ":scheme" and ":status" as defined in HTTP 2.
1215 As such, they are all kept in string form (important to remember for
1216 the ":status" field).
1217 new()
1219 Creates and returns a new headers object.
1220 headers:len()
1222 Returns the number of headers.
1223 Also available as #headers in Lua 5.2+.
1225 headers:clone()
1227 Creates and returns a clone of the headers object.
1228 headers:append(name, value, never_index)
1230 Append a header.
1231 • name is the header field name. Lower case is the convention. It
1233 will not be validated at this time.
1234 • value is the header field value. It will not be validated at this
1236 time.
1237 • never_index is an optional boolean that indicates if the value should
1239 be considered secret. Defaults to true for header fields: authoriza‐
1240 tion, proxy-authorization, cookie and set-cookie.
1241 headers:each()
1243 An iterator over all headers that emits name, value, never_index.
1244 Example
1246 local http_headers = require "http.headers"
1247 local myheaders = http_headers.new()
1248 myheaders:append(":status", "200")
1249 myheaders:append("set-cookie", "foo=bar")
1250 myheaders:append("connection", "close")
1251 myheaders:append("set-cookie", "baz=qux")
1252 for name, value, never_index in myheaders:each() do
1253 print(name, value, never_index)
1254 end
1255 --[[ prints:
1256 ":status", "200", false
1257 "set-cookie", "foo=bar", true
1258 "connection", "close", false
1259 "set-cookie", "baz=qux", true
1260 ]]
1261 headers:has(name)
1263 Returns a boolean indicating if the headers object has a field with the
1264 given name.
1265 headers:delete(name)
1267 Removes all occurrences of a field name from the headers object.
1268 headers:geti(i)
1270 Return the i-th header as name, value, never_index
1271 headers:get_as_sequence(name)
1273 Returns all headers with the given name in a table. The table will
1274 contain a field .n with the number of elements.
1275 Example
1277 local http_headers = require "http.headers"
1278 local myheaders = http_headers.new()
1279 myheaders:append(":status", "200")
1280 myheaders:append("set-cookie", "foo=bar")
1281 myheaders:append("connection", "close")
1282 myheaders:append("set-cookie", "baz=qux")
1283 local mysequence = myheaders:get_as_sequence("set-cookie")
1284 --[[ mysequence will be:
1285 {n = 2; "foo=bar"; "baz=qux"}
1286 ]]
1287 headers:get(name)
1289 Returns all headers with the given name as multiple return values.
1290 headers:get_comma_separated(name)
1292 Returns all headers with the given name as items in a comma separated
1293 string.
1294 headers:modifyi(i, value, never_index)
1296 Change the i-th’s header to a new value and never_index.
1297 headers:upsert(name, value, never_index)
1299 If a header with the given name already exists, replace it. If not,
1300 append it to the list of headers.
1301 Cannot be used when a header name already has multiple values.
1303 headers:sort()
1305 Sort the list of headers by their field name, ordering those starting
1306 with : first. If names are equal then sort by value, then by never_in‐
1307 dex.
1308 headers:dump(file, prefix)
1310 Print the headers list to the given file, one per line. If file is not
1311 given, then print to stderr. prefix is prefixed to each line.
1312 http.hpack
1314 new(SETTINGS_HEADER_TABLE_SIZE)
1315 hpack_context:append_data(val)
1316 hpack_context:render_data()
1317 hpack_context:clear_data()
1318 hpack_context:evict_from_dynamic_table()
1319 hpack_context:dynamic_table_tostring()
1320 hpack_context:set_max_dynamic_table_size(SETTINGS_HEADER_TABLE_SIZE)
1321 hpack_context:encode_max_size(val)
1322 hpack_context:resize_dynamic_table(new_size)
1323 hpack_context:add_to_dynamic_table(name, value, k)
1324 hpack_context:dynamic_table_id_to_index(id)
1325 hpack_context:lookup_pair_index(k)
1326 hpack_context:lookup_name_index(name)
1327 hpack_context:lookup_index(index)
1328 hpack_context:add_header_indexed(name, value, huffman)
1329 hpack_context:add_header_never_indexed(name, value, huffman)
1330 hpack_context:encode_headers(headers)
1331 hpack_context:decode_headers(payload, header_list, pos)
1332 http.hsts
1333 Data structures useful for HSTS (HTTP Strict Transport Security)
1334 new_store()
1336 Creates and returns a new HSTS store.
1337 hsts_store.max_items
1339 The maximum number of items allowed in the store. Decreasing this val‐
1340 ue will only prevent new items from being added, it will not remove old
1341 items.
1342 Defaults to infinity (any number of items is allowed).
1344 hsts_store:clone()
1346 Creates and returns a copy of a store.
1347 hsts_store:store(host, directives)
1349 Add new directives to the store about the given host. directives
1350 should be a table of directives, which must include the key "max-age".
1351 Returns a boolean indicating if the item was accepted.
1353 hsts_store:remove(host)
1355 Removes the entry for host from the store (if it exists).
1356 hsts_store:check(host)
1358 Returns a boolean indicating if the given host is a known HSTS host.
1359 hsts_store:clean_due()
1361 Returns the number of seconds until the next item in the store expires.
1362 hsts_store:clean()
1364 Removes expired entries from the store.
1365 http.proxies
1367 new()
1368 Returns an empty `proxies' object
1369 proxies:update(getenv)
1371 getenv defaults to os.getenv (http://www.lua.org/manual/5.3/manu‐
1372 al.html#pdf-os.getenv)
1373 Reads environmental variables that are used to control if requests go
1375 through a proxy.
1376 • http_proxy (or CGI_HTTP_PROXY if running in a program with GATE‐
1378 WAY_INTERFACE set): the proxy to use for normal HTTP connections
1379 • https_proxy or HTTPS_PROXY: the proxy to use for HTTPS connections
1381 • all_proxy or ALL_PROXY: the proxy to use for all connections, over‐
1383 ridden by other options
1384 • no_proxy or NO_PROXY: a list of hosts to not use a proxy for
1386 Returns proxies.
1388 proxies:choose(scheme, host)
1390 Returns the proxy to use for the given scheme and host as a URI.
1391 http.request
1393 The http.request module encapsulates all the functionality required to
1394 retrieve an HTTP document from a server.
1395 new_from_uri(uri)
1397 Creates a new http.request object from the given URI.
1398 new_connect(uri, connect_authority)
1400 Creates a new http.request object from the given URI that will perform
1401 a CONNECT request.
1402 request.host
1404 The host this request should be sent to.
1405 request.port
1407 The port this request should be sent to.
1408 request.bind
1410 The local outgoing address and optionally port to bind in the form of
1411 "address[:port]". Default is to allow the kernel to choose an ad‐
1412 dress+port.
1413 IPv6 addresses may be specified via square bracket notation.
1415 e.g. "127.0.0.1", "127.0.0.1:50000", "[::1]:30000".
1416 This option is rarely needed. Supplying an address can be used to man‐
1418 ually select the network interface to make the request from, while sup‐
1419 plying a port is only really used to interoperate with firewalls or de‐
1420 vices that demand use of a certain port.
1421 request.tls
1423 A boolean indicating if TLS should be used.
1424 request.ctx
1426 An alternative SSL_CTX* to use. If not specified, uses the default TLS
1427 settings (see http.tls for information).
1428 request.sendname
1430 The TLS SNI host name used.
1431 request.version
1433 The HTTP version to use; leave as nil to auto-select.
1434 request.proxy
1436 Specifies the a proxy that the request will be made through. The value
1437 should be a URI or false to turn off proxying for the request.
1438 request.headers
1440 A http.headers object of headers that will be sent in the request.
1441 request.hsts
1443 The http.hsts store that will be used to enforce HTTP strict transport
1444 security. An attempt will be made to add strict transport headers from
1445 a response to the store.
1446 Defaults to a shared store.
1448 request.proxies
1450 The http.proxies object used to select a proxy for the request. Only
1451 consulted if request.proxy is nil.
1452 request.cookie_store
1454 The http.cookie.store that will be used to find cookies for the re‐
1455 quest. An attempt will be made to add cookies from a response to the
1456 store.
1457 Defaults to a shared store.
1459 request.is_top_level
1461 A boolean flag indicating if this request is a “top level” request (See
1462 RFC 6265bis-02 Section 5.2 (https://tools.ietf.org/html/draft-ietf-
1463 httpbis-rfc6265bis-02#section-5.2))
1464 Defaults to true
1466 request.site_for_cookies
1468 A string containing the host that should be considered as the “site for
1469 cookies” (See RFC 6265bis-02 Section 5.2
1470 (https://tools.ietf.org/html/draft-ietf-httpbis-rfc6265bis-02#sec‐
1471 tion-5.2)), can be nil if unknown.
1472 Defaults to nil.
1474 request.follow_redirects
1476 Boolean indicating if :go() should follow redirects. Defaults to true.
1477 request.expect_100_timeout
1479 Number of seconds to wait for a 100 Continue response before proceeding
1480 to send a request body. Defaults to 1.
1481 request.max_redirects
1483 Maximum number of redirects to follow before giving up. Defaults to 5.
1484 Set to math.huge to not give up.
1485 request.post301
1487 Respect RFC 2616 Section 10.3.2 and don’t convert POST requests into
1488 body-less GET requests when following a 301 redirect. The non-RFC be‐
1489 haviour is ubiquitous in web browsers and assumed by servers. Modern
1490 HTTP endpoints send status code 308 to indicate that they don’t want
1491 the method to be changed. Defaults to false.
1492 request.post302
1494 Respect RFC 2616 Section 10.3.3 and don’t convert POST requests into
1495 body-less GET requests when following a 302 redirect. The non-RFC be‐
1496 haviour is ubiquitous in web browsers and assumed by servers. Modern
1497 HTTP endpoints send status code 307 to indicate that they don’t want
1498 the method to be changed. Defaults to false.
1499 request:clone()
1501 Creates and returns a clone of the request.
1502 The clone has its own deep copies of the .headers and .h2_settings
1504 fields.
1505 The .tls and .body fields are shallow copied from the original request.
1507 request:handle_redirect(headers)
1509 Process a redirect.
1510 headers should be response headers for a redirect.
1512 Returns a new request object that will fetch from new location.
1514 request:to_uri(with_userinfo)
1516 Returns a URI for the request.
1517 If with_userinfo is true and the request has an authorization header
1519 (or proxy-authorization for a CONNECT request), the returned URI will
1520 contain a userinfo component.
1521 request:set_body(body)
1523 Allows setting a request body. body may be a string, function or lua
1524 file object.
1525 • If body is a string it will be sent as given.
1527 • If body is a function, it will be called repeatedly like an iterator.
1529 It should return chunks of the request body as a string or nil if
1530 done.
1531 • If body is a lua file object, it will be :seek’d
1533 (http://www.lua.org/manual/5.3/manual.html#pdf-file:seek) to the
1534 start, then sent as a body. Any errors encountered during file oper‐
1535 ations will be thrown.
1536 request:go(timeout)
1538 Performs the request.
1539 The request object is not invalidated; and can be reused for a new re‐
1541 quest. On success, returns the response headers and a stream.
1542 http.server
1544 http.server objects are used to encapsulate the accept() and dispatch
1545 of http clients. Each new client request will invoke the onstream
1546 callback in a new cqueues managed coroutine. In addition to construct‐
1547 ing and returning a HTTP response, an onstream handler may decide to
1548 take ownership of the connection for other purposes, e.g. upgrade from
1549 a HTTP 1.1 connection to a WebSocket connection.
1550 For examples of how to use the server library, please see the examples
1552 directory (https://github.com/daurnimator/lua-http/tree/master/exam‐
1553 ples) in the source tree.
1554 new(options)
1556 Creates a new instance of an HTTP server listening on the given socket.
1557 • .socket (cqueues.socket): the socket that accept() will be called on
1559 • .onerror (function): Function that will be called when an error oc‐
1561 curs (default handler throws an error). See server:onerror()
1562 • .onstream (function): Callback function for handling a new client re‐
1564 quest. The function receives the server and the new stream as param‐
1565 eters. If the callback throws an error it will be reported from
1566 :step() or :loop()
1567 • .tls (boolean): Specifies if the system should use Transport Layer
1569 Security. Values are:
1570 • nil: Allow both tls and non-tls connections
1572 • true: Allows tls connections only
1574 • false: Allows non-tls connections only
1576 • .ctx (context object): An openssl.ssl.context object to use for tls
1578 connections. If nil is passed, a self-signed context will be gener‐
1579 ated.
1580 • .connection_setup_timeout (number): Timeout (in seconds) to wait for
1582 client to send first bytes and/or complete TLS handshake. Default is
1583 10 seconds.
1584 • .intra_stream_timeout (number): Timeout (in seconds) to wait for a
1586 new stream on an idle connection before giving up and closing the
1587 connection
1588 • .version (number): The http version to allow to connect (default:
1590 any)
1591 • .cq (cqueue): A cqueues controller to use as a main loop. The de‐
1593 fault is a new controller for the server.
1594 • .max_concurrent (number): Maximum number of connections to allow live
1596 at a time. Default is infinity.
1597 listen(options)
1599 Creates a new socket and returns an HTTP server that will accept() from
1600 it. Parameters are the same as new(options) except instead of .socket
1601 you provide the following:
1602 • .host (string): Local IP address in dotted decimal or IPV6 notation.
1604 This value is required if .path is not specified.
1605 • .port (number): IP port for the local socket. Specify 0 for automat‐
1607 ic port selection. Ports 1-1024 require the application has root
1608 privilege to run. Maximum value is 65535. If .tls == nil then this
1609 value is required. Otherwise, the defaults are:
1610 • 80 if .tls == false
1612 • 443 if .tls == true
1614 • .path (string): Path to UNIX a socket. This value is required if
1616 .host is not specified.
1617 • .family (string): Protocol family. Default is "AF_INET"
1619 • .v6only (boolean): Specify true to limit all connections to ipv6 only
1621 (no ipv4-mapped-ipv6). Default is false.
1622 • .mode (string): fchmod or chmod socket after creating UNIX domain
1624 socket.
1625 • .mask (boolean): Set and restore umask when binding UNIX domain sock‐
1627 et.
1628 • .unlink (boolean): true means unlink socket path before binding.
1630 • .reuseaddr (boolean): Turn on SO_REUSEADDR flag.
1632 • .reuseport (boolean): Turn on SO_REUSEPORT flag.
1634 server:onerror(new_handler)
1636 If called with parameters, the function replaces the current error han‐
1637 dler function with new_handler and returns a reference to the old func‐
1638 tion. Calling the function with no parameters returns the current er‐
1639 ror handler. The default handler throws an error. The onerror func‐
1640 tion for the server can be set during instantiation through the options
1641 table passed to the server.listen(options) function.
1642 server:listen(timeout)
1644 Initializes the server socket and if required, resolves DNS. serv‐
1645 er:listen() is required if localname is called before step or loop. On
1646 error, returns nil, an error message and an error number.
1647 server:localname()
1649 Returns the connection information for the local socket. Returns ad‐
1650 dress family, IP address and port for an external socket. For Unix do‐
1651 main sockets, the function returns AF_UNIX and the path. If the con‐
1652 nection object is not connected, returns AF_UNSPEC (0). On error, re‐
1653 turns nil, an error message and an error number.
1654 server:pause()
1656 Cause the server loop to stop processing new clients until resume is
1657 called. Existing client connections will run until closed.
1658 server:resume()
1660 Resumes a paused server and processes new client requests.
1661 server:close()
1663 Shutdown the server and close the socket. A closed server cannot be
1664 reused.
1665 server:pollfd()
1667 Returns a file descriptor (as an integer) or nil.
1668 The file descriptor can be passed to a system API like select or kqueue
1670 to wait on anything this server object wants to do. This method is
1671 used for integrating with other main loops, and should be used in com‐
1672 bination with :events() and :timeout().
1673 server:events()
1675 Returns a string indicating the type of events the object is waiting
1676 on: the string will contain "r" if it wants to be steped when the file
1677 descriptor returned by pollfd() has had POLLIN indicated; "w" for POLL‐
1678 OUT or "p" for POLLPRI.
1679 This method is used for integrating with other main loops, and should
1681 be used in combination with :pollfd() and :timeout().
1682 server:timeout()
1684 The maximum time (in seconds) to wait before calling server:step().
1685 This method is used for integrating with other main loops, and should
1687 be used in combination with :pollfd() and :events().
1688 server:empty()
1690 Returns true if the master socket and all client connection have been
1691 closed, false otherwise.
1692 server:step(timeout)
1694 Step once through server’s main loop: any waiting clients will be ac‐
1695 cept()-ed, any pending streams will start getting processed, and each
1696 onstream handler will get be run at most once. This method will block
1697 for up to timeout seconds. On error, returns nil, an error message and
1698 an error number.
1699 This can be used for integration with external main loops.
1701 server:loop(timeout)
1703 Run the server as a blocking loop for up to timeout seconds. The serv‐
1704 er will continue to listen and accept client requests until either
1705 :pause() or :close() is called, or an error is experienced.
1706 server:add_socket(socket)
1708 Add a new connection socket to the server for processing. The server
1709 will use the current onstream request handler and all options currently
1710 specified through the server.listen(options) constructor. add_socket
1711 can be used to process connection sockets obtained from an external
1712 source such as:
1713 • Another cqueues thread with some other master socket.
1715 • From inetd for start on demand daemons.
1717 • A Unix socket with SCM_RIGHTS.
1719 server:add_stream(stream)
1721 Add an existing stream to the server for processing.
1722 http.socks
1724 Implements a subset of the SOCKS proxy protocol.
1725 connect(uri)
1727 uri is a string with the address of the SOCKS server. A scheme of
1728 "socks5" will resolve hosts locally, a scheme of "socks5h" will resolve
1729 hosts on the SOCKS server. If the URI has a userinfo component it will
1730 be sent to the SOCKS server as a username and password.
1731 Returns a http.socks object.
1733 fdopen(socket)
1735 This function takes an existing cqueues.socket as a parameter and re‐
1736 turns a http.socks object with socket as its base.
1737 socks.needs_resolve
1739 Specifies if the destination host should be resolved locally.
1740 socks:clone()
1742 Make a clone of a given socks object.
1743 socks:add_username_password_auth(username, password)
1745 Add username + password authorisation to the set of allowed authorisa‐
1746 tion methods with the given credentials.
1747 socks:negotiate(host, port, timeout)
1749 Complete the SOCKS connection.
1750 Negotiates a socks connection. host is a required string passed to the
1752 SOCKS server as the host address. The address will be resolved locally
1753 if .needs_resolve is true. port is a required number to pass to the
1754 SOCKS server as the connection port. On error, returns nil, an error
1755 message and an error number.
1756 socks:close()
1758 socks:take_socket()
1759 Take possession of the socket object managed by the http.socks object.
1760 Returns the socket (or nil if not available).
1761 http.tls
1763 has_alpn
1764 Boolean indicating if ALPN is available in the current environment.
1765 It may be disabled if OpenSSL was compiled without ALPN support, or is
1767 an old version.
1768 has_hostname_validation
1770 Boolean indicating if hostname validation (https://wiki.openssl.org/in‐
1771 dex.php/Hostname_validation) is available in the current environment.
1772 It may be disabled if OpenSSL is an old version.
1774 modern_cipher_list
1776 The Mozilla “Modern” cipher list (https://wiki.mozilla.org/Securi‐
1777 ty/Server_Side_TLS#Modern_compatibility) as a colon separated list,
1778 ready to pass to OpenSSL
1779 intermediate_cipher_list
1781 The Mozilla “Intermediate” cipher list (https://wiki.mozilla.org/Secu‐
1782 rity/Server_Side_TLS#Intermediate_compatibility_.28default.29) as a
1783 colon separated list, ready to pass to OpenSSL
1784 old_cipher_list
1786 The Mozilla “Old” cipher list (https://wiki.mozilla.org/Security/Serv‐
1787 er_Side_TLS#Old_backward_compatibility) as a colon separated list,
1788 ready to pass to OpenSSL
1789 banned_ciphers
1791 A set (table with string keys and values of true) of the ciphers banned
1792 in HTTP 2 (https://http2.github.io/http2-spec/#BadCipherSuites) where
1793 the keys are OpenSSL cipher names.
1794 Ciphers not known by OpenSSL are missing from the set.
1796 new_client_context()
1798 Create and return a new luaossl SSL context useful for HTTP client con‐
1799 nections.
1800 new_server_context()
1802 Create and return a new luaossl SSL context useful for HTTP server con‐
1803 nections.
1804 http.util
1806 encodeURI(str)
1807 encodeURIComponent(str)
1808 decodeURI(str)
1809 decodeURIComponent(str)
1810 query_args(str)
1811 Returns an iterator over the pairs in str
1812 Example
1814 local http_util = require "http.util"
1815 for name, value in http_util.query_args("foo=bar&baz=qux") do
1816 print(name, value)
1817 end
1818 --[[ prints:
1819 "foo", "bar"
1820 "baz", "qux"
1821 ]]
1822 dict_to_query(dict)
1824 Converts a dictionary (table with string keys) with string values to an
1825 encoded query string.
1826 Example
1828 local http_util = require "http.util"
1829 print(http_util.dict_to_query({foo = "bar"; baz = "qux"})) --> "baz=qux&foo=bar"
1830 resolve_relative_path(orig_path, relative_path)
1832 is_safe_method(method)
1833 Returns a boolean indicating if the passed string method is a “safe”
1834 method. See RFC 7231 section 4.2.1
1835 (https://tools.ietf.org/html/rfc7231#section-4.2.1) for more informa‐
1836 tion.
1837 is_ip(str)
1839 Returns a boolean indicating if the passed string str is a valid IP.
1840 scheme_to_port
1842 Map from schemes (as strings) to default ports (as integers).
1843 split_authority(authority, scheme)
1845 Splits an authority into host and port components. If the authority
1846 has no port component, will attempt to use the default for the scheme.
1847 Example
1849 local http_util = require "http.util"
1850 print(http_util.split_authority("localhost:8000", "http")) --> "localhost", 8000
1851 print(http_util.split_authority("example.com", "https")) --> "localhost", 443
1852 to_authority(host, port, scheme)
1854 Joins the host and port to create a valid authority component. Omits
1855 the port if it is the default for the scheme.
1856 imf_date(time)
1858 Returns the time in HTTP preferred date format (See RFC 7231 section
1859 7.1.1.1 (https://tools.ietf.org/html/rfc7231#section-7.1.1.1))
1860 time defaults to the current time
1862 maybe_quote(str)
1864 • If str is a valid token, return it as-is.
1865 • If str would be valid as a quoted-string, return the quoted version
1867 • Otherwise, returns nil
1869 http.version
1871 name
1872 "lua-http"
1873 version
1875 Current version of lua-http as a string.
1876 http.websocket
1878 new_from_uri(uri, protocols)
1879 Creates a new http.websocket object of type "client" from the given
1880 URI.
1881 • protocols (optional) should be a lua table containing a sequence of
1883 protocols to send to the server
1884 new_from_stream(stream, headers)
1886 Attempts to create a new http.websocket object of type "server" from
1887 the given request headers and stream.
1888 • stream should be a live HTTP 1 stream of the "server" type.
1890 • headers should be headers of a suspected websocket upgrade request
1892 from an HTTP 1 client.
1893 This function does not have side effects, and is hence okay to use ten‐
1895 tatively.
1896 websocket.close_timeout
1898 Amount of time (in seconds) to wait between sending a close frame and
1899 actually closing the connection. Defaults to 3 seconds.
1900 websocket:accept(options, timeout)
1902 Completes negotiation with a websocket client.
1903 • options is a table containing:
1905 • headers (optional) a headers object to use as a prototype for the
1907 response headers
1908 • protocols (optional) should be a lua table containing a sequence of
1910 protocols to allow from the client
1911 Usually called after a successful new_from_stream
1913 websocket:connect(timeout)
1915 Connect to a websocket server.
1916 Usually called after a successful new_from_uri
1918 websocket:receive(timeout)
1920 Reads and returns the next data frame plus its opcode. Any ping frames
1921 received while reading will be responded to.
1922 The opcode 0x1 will be returned as "text" and 0x2 will be returned as
1924 "binary".
1925 websocket:each()
1927 Iterator over websocket:receive().
1928 websocket:send_frame(frame, timeout)
1930 Low level function to send a raw frame.
1931 websocket:send(data, opcode, timeout)
1933 Send the given data as a data frame.
1934 • data should be a string
1936 • opcode can be a numeric opcode, "text" or "binary". If nil, defaults
1938 to a text frame. Note this opcode is the websocket frame opcode, not
1939 an application specific opcode. The opcode should be one from the
1940 IANA registry (https://www.iana.org/assignments/websocket/websock‐
1941 et.xhtml#opcode).
1942 websocket:send_ping(data, timeout)
1944 Sends a ping frame.
1945 • data is optional
1947 websocket:send_pong(data, timeout)
1949 Sends a pong frame. Works as a unidirectional keep-alive.
1950 • data is optional
1952 websocket:close(code, reason, timeout)
1954 Closes the websocket connection.
1955 • code defaults to 1000
1957 • reason is an optional string
1959 http.zlib
1961 An abstraction layer over the various lua zlib libraries.
1962 engine
1964 Currently either "lua-zlib" (https://github.com/brimworks/lua-zlib) or
1965 "lzlib" (https://github.com/LuaDist/lzlib)
1966 inflate()
1968 Returns a closure that inflates (uncompresses) a zlib stream.
1969 The closure takes a string of compressed data and an end of stream flag
1971 (boolean) as parameters and returns the inflated output as a string.
1972 The function will throw an error if the input is not a valid zlib
1973 stream.
1974 deflate()
1976 Returns a closure that deflates (compresses) a zlib stream.
1977 The closure takes a string of uncompressed data and an end of stream
1979 flag (boolean) as parameters and returns the deflated output as a
1980 string.
1981 Example
1983 local zlib = require "http.zlib"
1984 local original = "the racecar raced around the racecar track"
1985 local deflater = zlib.deflate()
1986 local compressed = deflater(original, true)
1987 print(#original, #compressed) -- compressed should be smaller
1988 local inflater = zlib.inflate()
1989 local uncompressed = inflater(compressed, true)
1990 assert(original == uncompressed)
1991 http.compat.prosody
1993 Provides usage similar to prosody’s net.http
1994 (https://prosody.im/doc/developers/net/http)
1995 request(url, ex, callback)
1997 A few key differences to the prosody net.http.request:
1998 • must be called from within a running cqueue
2000 • The callback may be called from a different thread in the cqueue
2002 • The returned object will be a http.request object
2004 • This object is passed to the callback on errors and as the fourth
2006 argument on success
2007 • The default user-agent will be from lua-http (rather than "Prosody
2009 XMPP Server")
2010 • lua-http features (such as HTTP2) will be used where possible
2012 Example
2014 local prosody_http = require "http.compat.prosody"
2015 local cqueues = require "cqueues"
2016 local cq = cqueues.new()
2017 cq:wrap(function()
2018 prosody_http.request("http://httpbin.org/ip", {}, function(b, c, r)
2019 print(c) --> 200
2020 print(b) --> {"origin": "123.123.123.123"}
2021 end)
2022 end)
2023 assert(cq:loop())
2024 http.compat.socket
2026 Provides compatibility with luasocket’s http.request module
2027 (http://w3.impa.br/~diego/software/luasocket/http.html).
2028 Differences:
2030 • Will automatically be non-blocking when run inside a cqueues managed
2032 coroutine
2033 • lua-http features (such as HTTP2) will be used where possible
2035 Example
2037 Using the `simple' interface as part of a normal script:
2038 local socket_http = require "http.compat.socket"
2040 local body, code = assert(socket_http.request("http://lua.org"))
2041 print(code, #body) --> 200, 2514
2042
2044 • Github (https://github.com/daurnimator/lua-http)
2045 • Issue tracker (https://github.com/daurnimator/lua-http/issues)
2047
2049 Daurnimator <quae@daurnimator.com>.
2050 lua-http()