1lua-http()                                                          lua-http()
2
3
4

Introduction

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
9       • 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
13       • Provides both client and server APIs
14
15       • Fully asynchronous API that does not block the  current  thread  when
16         executing operations that typically block
17
18       • 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
22       • Transport  Layer Security (TLS) - lua-http supports HTTPS and WSS via
23         luaossl (https://github.com/wahern/luaossl).
24
25       • Easy integration into other event-loop or scripts
26
27   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
31       • Asynchronous and performant
32
33       • 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
37       • Can  be  used  at  a  very  high level without need to understand the
38         transportation of HTTP data (other than connection addresses).
39
40       • Provides a rich low level API, if desired, for creating powerful HTTP
41         based tools at the protocol level.
42
43       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
47       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
55   Portability
56       lua-http  is  pure Lua code with dependencies on the following external
57       libraries:
58
59       • cqueues (http://25thandclement.com/~william/projects/cqueues.html)  -
60         Posix API library for Lua
61
62       • luaossl  (http://25thandclement.com/~william/projects/luaossl.html) -
63         Lua bindings for TLS/SSL
64
65       • lua-zlib (https://github.com/brimworks/lua-zlib) - Optional Lua bind‐
66         ings for zlib
67
68       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
72   Common Use Cases
73       The following are two simple demonstrations of how the lua-http library
74       can be used:
75
76   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
81              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
89   WebSocket Communications
90       To request information from a WebSocket server, use the websocket  mod‐
91       ule to create a new WebSocket client.
92
93              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
101   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
114       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
122       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
128       • The       cqueues      website      (http://25thandclement.com/~will‐
129         iam/projects/cqueues.html) for more information about the cqueues li‐
130         brary.
131
132       • 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
137       • 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
142       • 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
146   Conventions
147       The following is a list of API conventions and general reference:
148
149   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
155       • Header fields should always be used with lower case keys.
156
157   Errors
158       • Invalid function parameters will throw a lua error (if validated).
159
160       • Errors are returned as nil, error, errno unless noted otherwise.
161
162       • Some HTTP 2 operations return/throw special http 2 error objects.
163
164   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
170   Terminology
171       Much lua-http terminology is borrowed from HTTP 2.
172
173       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
176       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

Interfaces

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
186       The  following  sections outline the interfaces exposed by the lua-http
187       library.
188
189   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
196       All connection types expose the following fields:
197
198   connection.type
199       The mode of use for the connection object.  Valid values are:
200
201       • "client": Acts as a client; this connection type is used by  entities
202         who want to make requests
203
204       • "server":  Acts as a server; this conenction type is used by entities
205         who want to respond to requests
206
207   connection.version
208       The HTTP version number of the connection as a number.
209
210   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
222   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
229   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
236   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
243       Note: If the client is using a proxy, the values  returned  :peername()
244       point to the proxy, not the remote server.
245
246   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
251   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
256   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
261   connection:new_stream()
262       Creates and returns a new stream on the connection.
263
264   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
268   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
274   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
279       All stream types expose the following fields and functions:
280
281   stream.connection
282       The underlying connection object.
283
284   stream:checktls()
285       Convenience wrapper equivalent to stream.connection:checktls()
286
287   stream:localname()
288       Convenience wrapper equivalent to stream.connection:localname()
289
290   stream:peername()
291       Convenience wrapper equivalent to stream.connection:peername()
292
293   stream:get_headers(timeout)
294       Retrieves  the next complete headers object (i.e. a block of headers or
295       trailers) from the stream.
296
297   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
303   stream:write_continue(timeout)
304       Sends a 100-continue header block.
305
306   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
311   stream:each_chunk()
312       Iterator over stream:get_next_chunk()
313
314   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
318   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
324   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
334   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
339   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
344   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
349   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
355   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
359   stream:write_body_from_file(options|file, timeout)
360       • options is a table containing:
361
362         • .file (file)
363
364         • .count (positive integer): number of bytes of file to write
365         defaults to infinity (the whole file will be written)
366
367       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
372   stream:shutdown()
373       Closes  the  stream.   The resources are released and the stream can no
374       longer be used.
375

Modules

377   http.bit
378       An abstraction layer over the various lua bit libraries.
379
380       Results are only consistent between underlying implementations when pa‐
381       rameters and results are in the range of 0 to 0x7fffffff.
382
383   band(a, b)
384       Bitwise And operation.
385
386   bor(a, b)
387       Bitwise Or operation.
388
389   bxor(a, b)
390       Bitwise XOr operation.
391
392   Example
393              local bit = require "http.bit"
394              print(bit.band(1, 3)) --> 1
395
396   http.client
397       Deals with obtaining a connection to an HTTP server.
398
399   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
404       • socket is a cqueues socket object
405
406       • options is a table containing:
407
408         • .tls (boolean, optional): Should TLS be used?
409         defaults to false
410
411         • .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
414         • .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
419           • true indicates to copy the .host field as long as it is not an IP
420
421           • false disables SNI
422
423         • .version (nil|1.0|1.1|2): HTTP version to use.
424
425           • nil: attempts HTTP 2 and falls back to HTTP 1.1
426
427           • 1.0
428
429           • 1.1
430
431           • 2
432
433         • .h2_settings  (table,  optional):  HTTP  2  settings  to  use.  See
434           http.h2_connection for details
435
436   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
442       • options  is  a table containing the options to http.client.negotiate,
443         plus the following:
444
445         • family (integer, optional): socket family to use.
446         defaults to AF_INET
447
448         • host (string): host to connect to.
449         may be either a hostname or an IP address
450
451         • port (string|integer): port to connect to in numeric form
452         e.g. "80" or 80
453
454         • path (string): path to connect to (UNIX sockets)
455
456         • v6only (boolean, optional): if the IPV6_V6ONLY flag should  be  set
457           on the underlying socket.
458
459         • 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
464       • 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
469   Example
470       Connect to a local HTTP server running on port 8000
471
472              local http_client = require "http.client"
473              local myconnection = http_client.connect {
474                  host = "localhost";
475                  port = 8000;
476                  tls = false;
477              }
478
479   http.cookie
480       A module for working with cookies.
481
482   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
487   parse_cookie(cookie)
488       Parses the Cookie header contents cookie.
489
490       Returns a table containing name and value pairs as strings.
491
492   parse_cookies(req_headers)
493       Parses all Cookie headers in the http.headers object req_headers.
494
495       Returns a table containing name and value pairs as strings.
496
497   parse_setcookie(setcookie)
498       Parses the Set-Cookie header contents setcookie.
499
500       Returns name, value and params where:
501
502       • name is a string containing the cookie name
503
504       • value is a string containing the cookie value
505
506       • params is the a table where the keys are cookie attribute  names  and
507         values are cookie attribute values
508
509   new_store()
510       Creates a new cookie store.
511
512       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
516   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
521       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
525   store.time()
526       A  function  used by the store to get the current time for expiries and
527       such.
528
529       Defaults to a  function  based  on  os.time  (https://www.lua.org/manu
530       al/5.3/manual.html#pdf-os.time).
531
532   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
538       Defaults to infinity (no maximum size).
539
540   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
545       Defaults to infinity (any number of cookies is allowed).
546
547   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
552       Defaults to infinity (any number of cookies is allowed).
553
554   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
558       • req_domain is the domain that the cookie was obtained from
559
560       • req_path is the path that the cookie was obtained from
561
562       • req_is_http  is  a boolean flag indicating if the cookie was obtained
563         from a “non-HTTP” API
564
565       • req_is_secure is a boolean flag indicating if the cookie was obtained
566         from a “secure” protocol
567
568       • 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
573       • name is a string containing the cookie name
574
575       • value is a string containing the cookie value
576
577       • params is the a table where the keys are cookie attribute  names  and
578         values are cookie attribute values
579
580       Returns a boolean indicating if a cookie was stored.
581
582   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
586       • req_headers is the http.headers object for the outgoing request
587
588       • resp_headers is the http.headers object received in response
589
590       • req_host is the host that your query was directed at  (only  used  if
591         req_headers is missing a Host header)
592
593       • 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
598   store:get(domain, path, name)
599       Returns the cookie value for the cookie stored for the  passed  domain,
600       path and name.
601
602   store:remove(domain, path, name)
603       Deletes the cookie stored for the passed domain, path and name.
604
605       If  name  is nil or not passed then all cookies for the domain and path
606       are removed.
607
608       If path is nil or not passed (in addition to name) then all cookies for
609       the domain are removed.
610
611   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
615       • domain is the domain that will be sent the cookie
616
617       • path is the path that will be sent the cookie
618
619       • is_http is a boolean flag indicating if the destination  is  a  “non-
620         HTTP” API
621
622       • is_secure  is  a  boolean  flag indicating if the destination will be
623         communicated with over a “secure” protocol
624
625       • 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
628       • 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
633       • 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
638       • max_cookie_length  is  the  maximum  cookie length to allow (See also
639         store.max_cookie_length)
640
641       Returns a string suitable for use in a Cookie header.
642
643   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
647       • headers is the http.headers object for the outgoing request
648
649       • host  is the host that your query was directed at (only used if head‐
650         ers is missing a Host header)
651
652       • 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
657       • 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
662       • max_cookie_length is the maximum cookie length  to  allow  (See  also
663         store.max_cookie_length)
664
665       Returns a string suitable for use in a Cookie header.
666
667   store:clean_due()
668       Returns  the  number  of seconds until the next cookie in the store ex‐
669       pires.
670
671   store:clean()
672       Remove all expired cookies from the store.
673
674   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
679       Returns true on success or passes along nil, err, errno if a :read call
680       fails.
681
682   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
687       Returns  true  on  success  or passes along nil, err, errno if a :write
688       call fails.
689
690   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
694   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
701   h1_connection.version
702       Specifies  the  HTTP  version used for the connection handshake.  Valid
703       values are:
704
705       • 1.0
706
707       • 1.1
708
709       See connection.version
710
711   h1_connection:pollfd()
712       See connection:pollfd()
713
714   h1_connection:events()
715       See connection:events()
716
717   h1_connection:timeout()
718       See connection:timeout()
719
720   h1_connection:connect(timeout)
721       See connection:connect(timeout)
722
723   h1_connection:checktls()
724       See connection:checktls()
725
726   h1_connection:localname()
727       See connection:localname()
728
729   h1_connection:peername()
730       See connection:peername()
731
732   h1_connection:flush(timeout)
733       See connection:flush(timeout)
734
735   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
740       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
745       See connection:shutdown()
746
747   h1_connection:close()
748       See connection:close()
749
750   h1_connection:new_stream()
751       In HTTP 1, only a client may initiate new streams with this function.
752
753       See connection:new_stream() for more information.
754
755   h1_connection:get_next_incoming_stream(timeout)
756       See connection:get_next_incoming_stream(timeout)
757
758   h1_connection:onidle(new_handler)
759       See connection:onidle(new_handler)
760
761   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
765       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
769   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
774   h1_connection:error(...)
775       Returns the error number of existing errors.
776
777   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
783   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
791   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
798   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
805   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
813   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
819   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
824   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
832   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
837       Note  the  request  line will not be flushed to the remote server until
838       write_headers_done is called.
839
840   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
846       Note  the  status  line  will not be flushed to the remote server until
847       write_headers_done is called.
848
849   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
854       Note the header item will not be flushed to  the  remote  server  until
855       write_headers_done is called.
856
857   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
863   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
869   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
875       Note that the connection will not be immediately flushed to the  remote
876       server; normally this will occur when trailers are written.
877
878   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
883   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
887   Example
888              local reason_phrases = require "http.h1_reason_phrases"
889              print(reason_phrases["200"]) --> "OK"
890              print(reason_phrases["342"]) --> "Unassigned"
891
892   http.h1_stream
893       The h1_stream module adheres to the stream interface and provides  HTTP
894       1.x specific operations.
895
896       The gzip transfer encoding is supported transparently.
897
898   h1_stream.connection
899       See stream.connection
900
901   h1_stream.max_header_lines
902       The maximum number of header lines to read.  Default is 100.
903
904   h1_stream:checktls()
905       See stream:checktls()
906
907   h1_stream:localname()
908       See stream:localname()
909
910   h1_stream:peername()
911       See stream:peername()
912
913   h1_stream:get_headers(timeout)
914       See stream:get_headers(timeout)
915
916   h1_stream:write_headers(headers, end_stream, timeout)
917       See stream:write_headers(headers, end_stream, timeout)
918
919   h1_stream:write_continue(timeout)
920       See stream:write_continue(timeout)
921
922   h1_stream:get_next_chunk(timeout)
923       See stream:get_next_chunk(timeout)
924
925   h1_stream:each_chunk()
926       See stream:each_chunk()
927
928   h1_stream:get_body_as_string(timeout)
929       See stream:get_body_as_string(timeout)
930
931   h1_stream:get_body_chars(n, timeout)
932       See stream:get_body_chars(n, timeout)
933
934   h1_stream:get_body_until(pattern, plain, include_pattern, timeout)
935       See stream:get_body_until(pattern, plain, include_pattern, timeout)
936
937   h1_stream:save_body_to_file(file, timeout)
938       See stream:save_body_to_file(file, timeout)
939
940   h1_stream:get_body_as_file(timeout)
941       See stream:get_body_as_file(timeout)
942
943   h1_stream:unget(str)
944       See stream:unget(str)
945
946   h1_stream:write_chunk(chunk, end_stream, timeout)
947       See stream:write_chunk(chunk, end_stream, timeout)
948
949   h1_stream:write_body_from_string(str, timeout)
950       See stream:write_body_from_string(str, timeout)
951
952   h1_stream:write_body_from_file(options|file, timeout)
953       See stream:write_body_from_file(options|file, timeout)
954
955   h1_stream:shutdown()
956       See stream:shutdown()
957
958   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
962       • "open": have sent or received headers; haven’t sent body yet
963
964       • "half closed (local)": have sent whole body
965
966       • "half closed (remote)": have received whole body
967
968       • "closed": complete
969
970       Not all state transitions are allowed.
971
972   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
977       This function should  rarely  be  used,  you’re  probably  looking  for
978       :get_headers().
979
980   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
985       This  function  should  rarely  be  used,  you’re  probably looking for
986       :get_next_chunk().
987
988   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
994   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
999   h2_connection.version
1000       Contains the HTTP connection version.  Currently this will always be 2.
1001
1002       See connection.version
1003
1004   h2_connection:pollfd()
1005       See connection:pollfd()
1006
1007   h2_connection:events()
1008       See connection:events()
1009
1010   h2_connection:timeout()
1011       See connection:timeout()
1012
1013   h2_connection:empty()
1014   h2_connection:step(timeout)
1015   h2_connection:loop(timeout)
1016   h2_connection:connect(timeout)
1017       See connection:connect(timeout)
1018
1019   h2_connection:checktls()
1020       See connection:checktls()
1021
1022   h2_connection:localname()
1023       See connection:localname()
1024
1025   h2_connection:peername()
1026       See connection:peername()
1027
1028   h2_connection:flush(timeout)
1029       See connection:flush(timeout)
1030
1031   h2_connection:shutdown()
1032       See connection:shutdown()
1033
1034   h2_connection:close()
1035       See connection:close()
1036
1037   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
1043       See connection:new_stream() for more information.
1044
1045   h2_connection:get_next_incoming_stream(timeout)
1046       See connection:get_next_incoming_stream(timeout)
1047
1048   h2_connection:onidle(new_handler)
1049       See connection:onidle(new_handler)
1050
1051   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
1065       • name: The error name: a short identifier for this error
1066
1067       • code: The error code
1068
1069       • description: The description of the error code
1070
1071       • message: An error message
1072
1073       • traceback: A traceback taken at the point the error was thrown
1074
1075       • stream_error:  A  boolean that indicates if this is a stream level or
1076         protocol level error
1077
1078   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
1084   is(ob)
1085       Returns  a  boolean indicating if the object ob is an http.h2_error ob‐
1086       ject
1087
1088   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
1093       Fields name, code and description are inherited from the parent  h2_er‐
1094       ror object if not specified.
1095
1096       stream_error defaults to false.
1097
1098   h2_error:new_traceback(message, stream_error, lvl)
1099       Creates  a  new  error  object,  recording a traceback from the current
1100       thread.
1101
1102   h2_error:error(message, stream_error, lvl)
1103       Creates and throws a new error.
1104
1105   h2_error:assert(cond, ...)
1106       If cond is truthy, returns cond, ...
1107
1108       If cond is falsy (i.e. false or nil), throws an error  with  the  first
1109       element of ... as the message.
1110
1111   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
1115   h2_stream.connection
1116       See stream.connection
1117
1118   h2_stream:checktls()
1119       See stream:checktls()
1120
1121   h2_stream:localname()
1122       See stream:localname()
1123
1124   h2_stream:peername()
1125       See stream:peername()
1126
1127   h2_stream:get_headers(timeout)
1128       See stream:get_headers(timeout)
1129
1130   h2_stream:write_headers(headers, end_stream, timeout)
1131       See stream:write_headers(headers, end_stream, timeout)
1132
1133   h2_stream:write_continue(timeout)
1134       See stream:write_continue(timeout)
1135
1136   h2_stream:get_next_chunk(timeout)
1137       See stream:get_next_chunk(timeout)
1138
1139   h2_stream:each_chunk()
1140       See stream:each_chunk()
1141
1142   h2_stream:get_body_as_string(timeout)
1143       See stream:get_body_as_string(timeout)
1144
1145   h2_stream:get_body_chars(n, timeout)
1146       See stream:get_body_chars(n, timeout)
1147
1148   h2_stream:get_body_until(pattern, plain, include_pattern, timeout)
1149       See stream:get_body_until(pattern, plain, include_pattern, timeout)
1150
1151   h2_stream:save_body_to_file(file, timeout)
1152       See stream:save_body_to_file(file, timeout)
1153
1154   h2_stream:get_body_as_file(timeout)
1155       See stream:get_body_as_file(timeout)
1156
1157   h2_stream:unget(str)
1158       See stream:unget(str)
1159
1160   h2_stream:write_chunk(chunk, end_stream, timeout)
1161       See stream:write_chunk(chunk, end_stream, timeout)
1162
1163   h2_stream:write_body_from_string(str, timeout)
1164       See stream:write_body_from_string(str, timeout)
1165
1166   h2_stream:write_body_from_file(options|file, timeout)
1167       See stream:write_body_from_file(options|file, timeout)
1168
1169   h2_stream:shutdown()
1170       See stream:shutdown()
1171
1172   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
1178       See  h2_connection:write_http2_frame(typ,  flags,  streamid,   payload,
1179       timeout, flush)
1180
1181   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
1194       Returns the new stream as a h2_stream.
1195
1196   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
1207       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
1212       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
1218   new()
1219       Creates and returns a new headers object.
1220
1221   headers:len()
1222       Returns the number of headers.
1223
1224       Also available as #headers in Lua 5.2+.
1225
1226   headers:clone()
1227       Creates and returns a clone of the headers object.
1228
1229   headers:append(name, value, never_index)
1230       Append a header.
1231
1232       • name is the header field name.  Lower case  is  the  convention.   It
1233         will not be validated at this time.
1234
1235       • value  is  the  header field value.  It will not be validated at this
1236         time.
1237
1238       • 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
1242   headers:each()
1243       An iterator over all headers that emits name, value, never_index.
1244
1245   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
1262   headers:has(name)
1263       Returns a boolean indicating if the headers object has a field with the
1264       given name.
1265
1266   headers:delete(name)
1267       Removes all occurrences of a field name from the headers object.
1268
1269   headers:geti(i)
1270       Return the i-th header as name, value, never_index
1271
1272   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
1276   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
1288   headers:get(name)
1289       Returns all headers with the given name as multiple return values.
1290
1291   headers:get_comma_separated(name)
1292       Returns all headers with the given name as items in a  comma  separated
1293       string.
1294
1295   headers:modifyi(i, value, never_index)
1296       Change the i-th’s header to a new value and never_index.
1297
1298   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
1302       Cannot be used when a header name already has multiple values.
1303
1304   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
1309   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
1313   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
1335   new_store()
1336       Creates and returns a new HSTS store.
1337
1338   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
1343       Defaults to infinity (any number of items is allowed).
1344
1345   hsts_store:clone()
1346       Creates and returns a copy of a store.
1347
1348   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
1352       Returns a boolean indicating if the item was accepted.
1353
1354   hsts_store:remove(host)
1355       Removes the entry for host from the store (if it exists).
1356
1357   hsts_store:check(host)
1358       Returns a boolean indicating if the given host is a known HSTS host.
1359
1360   hsts_store:clean_due()
1361       Returns the number of seconds until the next item in the store expires.
1362
1363   hsts_store:clean()
1364       Removes expired entries from the store.
1365
1366   http.proxies
1367   new()
1368       Returns an empty `proxies' object
1369
1370   proxies:update(getenv)
1371       getenv  defaults  to   os.getenv   (http://www.lua.org/manual/5.3/manu
1372       al.html#pdf-os.getenv)
1373
1374       Reads  environmental  variables that are used to control if requests go
1375       through a proxy.
1376
1377       • 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
1380       • https_proxy or HTTPS_PROXY: the proxy to use for HTTPS connections
1381
1382       • all_proxy  or  ALL_PROXY: the proxy to use for all connections, over‐
1383         ridden by other options
1384
1385       • no_proxy or NO_PROXY: a list of hosts to not use a proxy for
1386
1387       Returns proxies.
1388
1389   proxies:choose(scheme, host)
1390       Returns the proxy to use for the given scheme and host as a URI.
1391
1392   http.request
1393       The http.request module encapsulates all the functionality required  to
1394       retrieve an HTTP document from a server.
1395
1396   new_from_uri(uri)
1397       Creates a new http.request object from the given URI.
1398
1399   new_connect(uri, connect_authority)
1400       Creates  a new http.request object from the given URI that will perform
1401       a CONNECT request.
1402
1403   request.host
1404       The host this request should be sent to.
1405
1406   request.port
1407       The port this request should be sent to.
1408
1409   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
1414       IPv6  addresses  may  be  specified  via   square   bracket   notation.
1415       e.g. "127.0.0.1", "127.0.0.1:50000", "[::1]:30000".
1416
1417       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
1422   request.tls
1423       A boolean indicating if TLS should be used.
1424
1425   request.ctx
1426       An alternative SSL_CTX* to use.  If not specified, uses the default TLS
1427       settings (see http.tls for information).
1428
1429   request.sendname
1430       The TLS SNI host name used.
1431
1432   request.version
1433       The HTTP version to use; leave as nil to auto-select.
1434
1435   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
1439   request.headers
1440       A http.headers object of headers that will be sent in the request.
1441
1442   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
1447       Defaults to a shared store.
1448
1449   request.proxies
1450       The http.proxies object used to select a proxy for the  request.   Only
1451       consulted if request.proxy is nil.
1452
1453   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
1458       Defaults to a shared store.
1459
1460   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
1465       Defaults to true
1466
1467   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
1473       Defaults to nil.
1474
1475   request.follow_redirects
1476       Boolean indicating if :go() should follow redirects.  Defaults to true.
1477
1478   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
1482   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
1486   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
1493   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
1500   request:clone()
1501       Creates and returns a clone of the request.
1502
1503       The clone has its own deep copies  of  the  .headers  and  .h2_settings
1504       fields.
1505
1506       The .tls and .body fields are shallow copied from the original request.
1507
1508   request:handle_redirect(headers)
1509       Process a redirect.
1510
1511       headers should be response headers for a redirect.
1512
1513       Returns a new request object that will fetch from new location.
1514
1515   request:to_uri(with_userinfo)
1516       Returns a URI for the request.
1517
1518       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
1522   request:set_body(body)
1523       Allows  setting  a request body.  body may be a string, function or lua
1524       file object.
1525
1526       • If body is a string it will be sent as given.
1527
1528       • 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
1532       • 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
1537   request:go(timeout)
1538       Performs the request.
1539
1540       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
1543   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
1551       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
1555   new(options)
1556       Creates a new instance of an HTTP server listening on the given socket.
1557
1558       • .socket (cqueues.socket): the socket that accept() will be called on
1559
1560       • .onerror  (function):  Function that will be called when an error oc‐
1561         curs (default handler throws an error).  See server:onerror()
1562
1563       • .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
1568       • .tls  (boolean):  Specifies  if the system should use Transport Layer
1569         Security.  Values are:
1570
1571         • nil: Allow both tls and non-tls connections
1572
1573         • true: Allows tls connections only
1574
1575         • false: Allows non-tls connections only
1576
1577       • .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
1581       • .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
1585       • .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
1589       • .version (number): The http version to  allow  to  connect  (default:
1590         any)
1591
1592       • .cq  (cqueue):  A  cqueues controller to use as a main loop.  The de‐
1593         fault is a new controller for the server.
1594
1595       • .max_concurrent (number): Maximum number of connections to allow live
1596         at a time.  Default is infinity.
1597
1598   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
1603       • .host  (string): Local IP address in dotted decimal or IPV6 notation.
1604         This value is required if .path is not specified.
1605
1606       • .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
1611         • 80 if .tls == false
1612
1613         • 443 if .tls == true
1614
1615       • .path  (string):  Path  to  UNIX a socket.  This value is required if
1616         .host is not specified.
1617
1618       • .family (string): Protocol family.  Default is "AF_INET"
1619
1620       • .v6only (boolean): Specify true to limit all connections to ipv6 only
1621         (no ipv4-mapped-ipv6).  Default is false.
1622
1623       • .mode  (string):  fchmod  or  chmod socket after creating UNIX domain
1624         socket.
1625
1626       • .mask (boolean): Set and restore umask when binding UNIX domain sock‐
1627         et.
1628
1629       • .unlink (boolean): true means unlink socket path before binding.
1630
1631       • .reuseaddr (boolean): Turn on SO_REUSEADDR flag.
1632
1633       • .reuseport (boolean): Turn on SO_REUSEPORT flag.
1634
1635   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
1643   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
1648   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
1655   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
1659   server:resume()
1660       Resumes a paused server and processes new client requests.
1661
1662   server:close()
1663       Shutdown  the  server  and close the socket.  A closed server cannot be
1664       reused.
1665
1666   server:pollfd()
1667       Returns a file descriptor (as an integer) or nil.
1668
1669       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
1674   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
1680       This method is used for integrating with other main loops,  and  should
1681       be used in combination with :pollfd() and :timeout().
1682
1683   server:timeout()
1684       The maximum time (in seconds) to wait before calling server:step().
1685
1686       This  method  is used for integrating with other main loops, and should
1687       be used in combination with :pollfd() and :events().
1688
1689   server:empty()
1690       Returns true if the master socket and all client connection  have  been
1691       closed, false otherwise.
1692
1693   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
1700       This can be used for integration with external main loops.
1701
1702   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
1707   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
1714       • Another cqueues thread with some other master socket.
1715
1716       • From inetd for start on demand daemons.
1717
1718       • A Unix socket with SCM_RIGHTS.
1719
1720   server:add_stream(stream)
1721       Add an existing stream to the server for processing.
1722
1723   http.socks
1724       Implements a subset of the SOCKS proxy protocol.
1725
1726   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
1732       Returns a http.socks object.
1733
1734   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
1738   socks.needs_resolve
1739       Specifies if the destination host should be resolved locally.
1740
1741   socks:clone()
1742       Make a clone of a given socks object.
1743
1744   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
1748   socks:negotiate(host, port, timeout)
1749       Complete the SOCKS connection.
1750
1751       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
1757   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
1762   http.tls
1763   has_alpn
1764       Boolean indicating if ALPN is available in the current environment.
1765
1766       It  may be disabled if OpenSSL was compiled without ALPN support, or is
1767       an old version.
1768
1769   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
1773       It may be disabled if OpenSSL is an old version.
1774
1775   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
1780   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
1785   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
1790   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
1795       Ciphers not known by OpenSSL are missing from the set.
1796
1797   new_client_context()
1798       Create and return a new luaossl SSL context useful for HTTP client con‐
1799       nections.
1800
1801   new_server_context()
1802       Create and return a new luaossl SSL context useful for HTTP server con‐
1803       nections.
1804
1805   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
1813   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
1823   dict_to_query(dict)
1824       Converts a dictionary (table with string keys) with string values to an
1825       encoded query string.
1826
1827   Example
1828              local http_util = require "http.util"
1829              print(http_util.dict_to_query({foo = "bar"; baz = "qux"})) --> "baz=qux&foo=bar"
1830
1831   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
1838   is_ip(str)
1839       Returns a boolean indicating if the passed string str is a valid IP.
1840
1841   scheme_to_port
1842       Map from schemes (as strings) to default ports (as integers).
1843
1844   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
1848   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
1853   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
1857   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
1861       time defaults to the current time
1862
1863   maybe_quote(str)
1864       • If str is a valid token, return it as-is.
1865
1866       • If str would be valid as a quoted-string, return the quoted version
1867
1868       • Otherwise, returns nil
1869
1870   http.version
1871   name
1872       "lua-http"
1873
1874   version
1875       Current version of lua-http as a string.
1876
1877   http.websocket
1878   new_from_uri(uri, protocols)
1879       Creates a new http.websocket object of type  "client"  from  the  given
1880       URI.
1881
1882       • protocols  (optional)  should be a lua table containing a sequence of
1883         protocols to send to the server
1884
1885   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
1889       • stream should be a live HTTP 1 stream of the "server" type.
1890
1891       • headers  should  be  headers of a suspected websocket upgrade request
1892         from an HTTP 1 client.
1893
1894       This function does not have side effects, and is hence okay to use ten‐
1895       tatively.
1896
1897   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
1901   websocket:accept(options, timeout)
1902       Completes negotiation with a websocket client.
1903
1904       • options is a table containing:
1905
1906         • headers (optional) a headers object to use as a prototype  for  the
1907           response headers
1908
1909         • protocols (optional) should be a lua table containing a sequence of
1910           protocols to allow from the client
1911
1912       Usually called after a successful new_from_stream
1913
1914   websocket:connect(timeout)
1915       Connect to a websocket server.
1916
1917       Usually called after a successful new_from_uri
1918
1919   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
1923       The  opcode  0x1 will be returned as "text" and 0x2 will be returned as
1924       "binary".
1925
1926   websocket:each()
1927       Iterator over websocket:receive().
1928
1929   websocket:send_frame(frame, timeout)
1930       Low level function to send a raw frame.
1931
1932   websocket:send(data, opcode, timeout)
1933       Send the given data as a data frame.
1934
1935       • data should be a string
1936
1937       • 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
1943   websocket:send_ping(data, timeout)
1944       Sends a ping frame.
1945
1946       • data is optional
1947
1948   websocket:send_pong(data, timeout)
1949       Sends a pong frame.  Works as a unidirectional keep-alive.
1950
1951       • data is optional
1952
1953   websocket:close(code, reason, timeout)
1954       Closes the websocket connection.
1955
1956       • code defaults to 1000
1957
1958       • reason is an optional string
1959
1960   http.zlib
1961       An abstraction layer over the various lua zlib libraries.
1962
1963   engine
1964       Currently either "lua-zlib" (https://github.com/brimworks/lua-zlib)  or
1965       "lzlib" (https://github.com/LuaDist/lzlib)
1966
1967   inflate()
1968       Returns a closure that inflates (uncompresses) a zlib stream.
1969
1970       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
1975   deflate()
1976       Returns a closure that deflates (compresses) a zlib stream.
1977
1978       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
1982   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
1992   http.compat.prosody
1993       Provides      usage      similar      to       prosody’s       net.http
1994       (https://prosody.im/doc/developers/net/http)
1995
1996   request(url, ex, callback)
1997       A few key differences to the prosody net.http.request:
1998
1999       • must be called from within a running cqueue
2000
2001       • The callback may be called from a different thread in the cqueue
2002
2003       • The returned object will be a http.request object
2004
2005         • This  object  is passed to the callback on errors and as the fourth
2006           argument on success
2007
2008       • The default user-agent will be from lua-http  (rather  than  "Prosody
2009         XMPP Server")
2010
2011       • lua-http features (such as HTTP2) will be used where possible
2012
2013   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
2025   http.compat.socket
2026       Provides    compatibility    with   luasocket’s   http.request   module
2027       (http://w3.impa.br/~diego/software/luasocket/http.html).
2028
2029       Differences:
2030
2031       • Will automatically be non-blocking when run inside a cqueues  managed
2032         coroutine
2033
2034       • lua-http features (such as HTTP2) will be used where possible
2035
2036   Example
2037       Using the `simple' interface as part of a normal script:
2038
2039              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
2046       • Issue tracker (https://github.com/daurnimator/lua-http/issues)
2047

AUTHORS

2049       Daurnimator <quae@daurnimator.com>.
2050
2051
2052
2053                                                                    lua-http()
Impressum