cosmopolitan/tool/net/help.txt

SYNOPSIS

  redbean.com [-hvduzmbagf] [-p PORT] [-- SCRIPTARGS...]

DESCRIPTION

  redbean - single-file distributable web server

OVERVIEW

  redbean makes it possible to share web applications that run offline
  as a single-file Actually Portable Executable PKZIP archive which
  contains your assets. All you need to do is download the redbean.com
  program below, change the filename to .zip, add your content in a zip
  editing tool, and then change the extension back to .com.

  redbean can serve 1 million+ gzip encoded responses per second on a
  cheap personal computer. That performance is thanks to zip and gzip
  using the same compression format, which enables kernelspace copies.
  Another reason redbean goes fast is that it's a tiny static binary,
  which makes fork memory paging nearly free.

  redbean is also easy to modify to suit your own needs. The program
  itself is written as a single .c file. It embeds the Lua programming
  language and SQLite which let you write dynamic pages.

FLAGS

  -h        help
  -d        daemonize
  -u        uniprocess
  -z        print port
  -m        log messages
  -b        log message bodies
  -a        log resource usage
  -g        log handler latency
  -e        run specified Lua command
  -j        enable ssl client verify
  -k        disable ssl fetch verify
  -f        log worker function calls
  -B        only use stronger cryptography
  -s        increase silence                  [repeatable]
  -v        increase verbosity                [repeatable]
  -V        increase ssl verbosity            [repeatable]
  -H K:V    sets http header globally         [repeatable]
  -D DIR    overlay assets in local directory [repeatable]
  -r /X=/Y  redirect X to Y                   [repeatable]
  -R /X=/Y  rewrites X to Y                   [repeatable]
  -K PATH   tls private key path              [repeatable]
  -C PATH   tls certificate(s) path           [repeatable]
  -A PATH   add assets with path (recursive)  [repeatable]
  -M INT    tunes max message payload size    [def. 65536]
  -t INT    timeout ms or keepalive sec if <0 [def. 60000]
  -p PORT   listen port                       [def. 8080; repeatable]
  -l ADDR   listen addr                       [def. 0.0.0.0; repeatable]
  -c SEC    configures static cache-control
  -L PATH   log file location
  -P PATH   pid file location
  -U INT    daemon set user id
  -G INT    daemon set group id

FEATURES

  - Lua v5.4
  - SQLite 3.35.5
  - TLS v1.2 / v1.1 / v1.0
  - HTTP v1.1 / v1.0 / v0.9
  - Chromium-Zlib Compression
  - Statusz Monitoring Statistics
  - Self-Modifying PKZIP Object Store
  - Linux + Windows + Mac + FreeBSD + OpenBSD + NetBSD

USAGE

  This executable is also a ZIP file that contains static assets.
  You can run redbean interactively in your terminal as follows:

    ./redbean.com -vvvmbag        # starts server verbosely
    open http://127.0.0.1:8080/   # shows zip listing page
    CTRL-C                        # 1x: graceful shutdown
    CTRL-C                        # 2x: forceful shutdown

  You can override the default listing page by adding:

    zip redbean.com index.lua     # lua server pages take priority
    zip redbean.com index.html    # default page for directory

  The listing page only applies to the root directory. However the
  default index page applies to subdirectories too. In order for it
  to work, there needs to be an empty directory entry in the zip.
  That should already be the default practice of your zip editor.

    wget                     \
      --mirror               \
      --convert-links        \
      --adjust-extension     \
      --page-requisites      \
      --no-parent            \
      --no-if-modified-since \
      http://a.example/index.html
    zip -r redbean.com a.example/  # default page for directory

  redbean normalizes the trailing slash for you automatically:

    $ printf 'GET /a.example HTTP/1.0\n\n' | nc 127.0.0.1 8080
    HTTP/1.0 307 Temporary Redirect
    Location: /a.example/

  Virtual hosting is accomplished this way too. The Host is simply
  prepended to the path, and if it doesn't exist, it gets removed.

    $ printf 'GET / HTTP/1.1\nHost:a.example\n\n' | nc 127.0.0.1 8080
    HTTP/1.1 200 OK
    Link: <http://127.0.0.1/a.example/index.html>; rel="canonical"

  If you mirror a lot of websites within your redbean then you can
  actually tell your browser that redbean is your proxy server, in
  which redbean will act as your private version of the Internet.

    $ printf 'GET http://a.example HTTP/1.0\n\n' | nc 127.0.0.1 8080
    HTTP/1.0 200 OK
    Link: <http://127.0.0.1/a.example/index.html>; rel="canonical"

  If you use a reverse proxy, then redbean recognizes the following
  provided that the proxy forwards requests over the local network:

    X-Forwarded-For: 203.0.113.42:31337
    X-Forwarded-Host: foo.example:80

  There's a text/plain statistics page called /statusz that makes
  it easy to track and monitor the health of your redbean:

    printf 'GET /statusz\n\n' | nc 127.0.0.1 8080

  redbean will display an error page using the /redbean.png logo
  by default, embedded as a bas64 data uri. You can override the
  custom page for various errors by adding files to the zip root.

    zip redbean.com 404.html      # custom not found page

  Audio video content should not be compressed in your ZIP files.
  Uncompressed assets enable browsers to send Range HTTP request.
  On the other hand compressed assets are best for gzip encoding.

    zip redbean.com index.html    # adds file
    zip -0 redbean.com video.mp4  # adds without compression

  You can have redbean run as a daemon by doing the following:

    sudo ./redbean.com -vvdp80 -p443 -L redbean.log -P redbean.pid
    kill -TERM $(cat redbean.pid) # 1x: graceful shutdown
    kill -TERM $(cat redbean.pid) # 2x: forceful shutdown

  redbean currently has a 32kb limit on request messages and 64kb
  including the payload. redbean will grow to whatever the system
  limits allow. Should fork() or accept() fail redbean will react
  by going into "meltdown mode" which closes lingering workers.
  You can trigger this at any time using:

    kill -USR2 $(cat redbean.pid)

  Another failure condition is running out of disk space in which
  case redbean reacts by truncating the log file. Lastly, redbean
  does the best job possible reporting on resource usage when the
  logger is in debug mode noting that NetBSD is the best at this.

  Your redbean is an actually portable executable, that's able to
  run on six different operating systems. To do that, it needs to
  overwrite its own MZ header at startup, with ELF or Mach-O, and
  then puts the original back once the program loads. If you want
  your redbean to follow the platform-local executable convention
  then delete the /.ape file from zip.

  redbean contains software licensed ISC, MIT, BSD-2, BSD-3, zlib
  which makes it a permissively licensed gift to anyone who might
  find it useful. The transitive closure of legalese can be found
  inside the binary. redbean also respects your privacy and won't
  phone home because your computer is its home.

SECURITY

  redbean uses a protocol polyglot for serving HTTP and HTTPS on
  the same port numbers. For example, both of these are valid:

    http://127.0.0.1:8080/
    https://127.0.0.1:8080/

  SSL verbosity is controlled as follows for troubleshooting:

    -V       log ssl errors
    -VV      log ssl state changes too
    -VVV     log ssl informational messages too
    -VVVV    log ssl verbose details too

  See https://redbean.dev for further details.

LUA SERVER PAGES

   Any files with the extension .lua will be dynamically served by redbean.
   Here's the simplest possible example:

     Write('<b>Hello World</b>')

   The Lua Server Page above should be able to perform at 700,000 responses
   per second on a Core i9, without any sort of caching. If you want a Lua
   handler that can do 1,000,000 responses per second, then try adding the
   following global handler to your /.init.lua file:

     function OnHttpRequest()
        Write('<b>Hello World</b>')
     end

   Here's an example of a more typical workflow for Lua Server Pages using
   the redbean API:

     SetStatus(200)
     SetHeader('Content-Type', 'text/plain; charset=utf-8')
     Write('<p>Hello ')
     Write(EscapeHtml(GetParam('name')))

   We didn't need the first two lines in the previous example, because
   they're implied by redbean automatically if you don't set them. Responses
   are also buffered until the script finishes executing. That enables
   redbean to make HTTP as easy as possible. In the future, API capabilities
   will be expanded to make possible things like websockets.

   redbean embeds the Lua standard library. You can use packages such as io
   to persist and share state across requests and connections, as well as the
   StoreAsset function, and the lsqlite3 module.

   Your Lua interpreter begins its life in the main process at startup in the
   .init.lua, which is likely where you'll want to perform all your expensive
   one-time operations like importing modules. Then, as requests roll in,
   isolated processes are cloned from the blueprint you created.

SPECIAL PATHS

   /
           redbean will generate a zip central directory listing for this
           page, and this page only, but only if there isn't an /index.lua or
           /index.html file defined.

   /.init.lua
           This script is run once in the main process at startup. This lets
           you modify the state of the Lua interpreter before connection
           processes are forked off. For example, it's a good idea to do
           expensive one-time computations here. You can also use this file
           to call the ProgramFOO() functions below. The init module load
           happens after redbean's arguments and zip assets have been parsed,
           but before calling functions like socket() and fork(). Note that
           this path is a hidden file so that it can't be unintentionally run
           by the network client.

   /.reload.lua
           This script is run from the main process when SIGHUP is received.
           This only applies to redbean when running in daemon mode. Any
           changes that are made to the Lua interpreter state will be
           inherited by future forked connection processes. Note that this
           path is a hidden file so that it can't be unintentionally run by
           the network client.

   /.lua/...
           Your Lua modules go in this directory. The way it works is redbean
           sets Lua's package.path to /zip/.lua/?.lua;/zip/.lua/?/init.lua by
           default. Cosmopolitan Libc lets system calls like open read from
           the ZIP structure, if the filename is prefixed with /zip/. So this
           works like magic.

   /redbean.png
           If it exists, it'll be used as the / listing page icon, embedded
           as a base64 URI.

   /usr/share/ssl/root
           This directory contains your root certificate authorities. It is
           needed so the Fetch() HTTPS client API can verify that a remote
           certificate was signed by a third party. You can add your own
           certificate files to this directory within the ZIP executable.
           If you enable HTTPS client verification then redbean will check
           that HTTPS clients (a) have a certificate and (b) it was signed.

GLOBALS

   argv: array[str]
           Array of command line arguments, excluding those parsed by
           getopt() in the C code, which stops parsing at the first
           non-hyphenated arg. In some cases you can use the magic --
           argument to delimit C from Lua arguments.

HOOKS

   OnHttpRequest()
           If this function is defined in the global scope by your /.init.lua
           then redbean will call it at the ealiest possible moment to
           hand over control for all messages (with the exception of OPTIONS
           *). See functions like Route which asks redbean to do its default
           thing from the handler.

   OnClientConnection(ip:int,port:int,serverip:int,serverport:int) → bool
           If this function is defined it'll be called from the main process
           each time redbean accepts a new client connection. If it returns
           true then redbean will close the connection without calling fork.

   OnProcessCreate(pid:int,ip:int,port:int,serverip:int,serverport:int)
           If this function is defined it'll be called from the main process
           each time redbean forks a connection handler worker process. The
           ip/port of the remote client is provided, along with the ip/port
           of the listening interface that accepted the connection. This may
           be used to create a server activity dashboard, in which case the
           data provider handler should set SetHeader('Connection','Close').
           This won't be called in uniprocess mode.

   OnProcessDestroy(pid:int)
           If this function is defined it'll be called from the main process
           each time redbean reaps a child connection process using wait4().
           This won't be called in uniprocess mode.

   OnServerStart()
           If this function is defined it'll be called from the main process
           right before the main event loop starts.

   OnServerStop()
           If this function is defined it'll be called from the main process
           after all the connection processes have been reaped and exit() is
           ready to be called.

   OnWorkerStart()
           If this function is defined it'll be called from the child worker
           process after it's been forked and before messages are handled.
           This won't be called in uniprocess mode.

   OnWorkerStop()
           If this function is defined it'll be called from the child worker
           process once _exit() is ready to be called. This won't be called
           in uniprocess mode.

FUNCTIONS

   Write(data:str)
           Appends data to HTTP response payload buffer. This is buffered
           independently of headers.

   SetStatus(code:int[,reason:str])
           Starts an HTTP response, specifying the parameters on its first
           line. reason is optional since redbean can fill in the appropriate
           text for well-known magic numbers, e.g. 200, 404, etc. This method
           will reset the response and is therefore mutually exclusive with
           ServeAsset and other Serve* functions. If this function isn't
           called, then the default behavior is to send 200 OK.

   SetHeader(name:str,value:str)
           Appends HTTP header to response header buffer. name is
           case-insensitive and restricted to non-space ASCII. value is a
           UTF-8 string that must be encodable as ISO-8859-1. Leading and
           trailing whitespace is trimmed automatically. Overlong characters
           are canonicalized. C0 and C1 control codes are forbidden, with the
           exception of tab. This function automatically calls SetStatus(200,
           "OK") if a status has not yet been set. As SetStatus and Serve*
           functions reset the response, SetHeader needs to be called after
           SetStatus and Serve* functions are called. The header buffer is
           independent of the payload buffer. Neither is written to the wire
           until the Lua Server Page has finished executing. This function
           disallows the setting of certain headers such as Content-Range and
           Date, which are abstracted by the transport layer. In such cases,
           consider calling ServeAsset.

   SetCookie(name:str,value:str[,options:table])
           Appends Set-Cookie HTTP header to the response header buffer.
           Several Set-Cookie headers can be added to the same response.
           __Host- and __Secure- prefixes are supported and may set or
           overwrite some of the options (for example, specifying __Host-
           prefix sets the Secure option to true, sets the path to "/", and
           removes the Domain option). The following options can be used (their
           lowercase equivalents are supported as well):
             - Expires: sets the maximum lifetime of the cookie as an HTTP-date
               timestamp. Can be specified as a Date in the RFC1123 (string)
               format or as a UNIX timestamp (number of seconds).
             - MaxAge: sets number of seconds until the cookie expires. A zero
               or negative number will expire the cookie immediately. If both
               Expires and MaxAge are set, MaxAge has precedence.
             - Domain: sets the host to which the cookie will be sent.
             - Path: sets the path that must be present in the request URL, or
               the client will not send the Cookie header.
             - Secure: (bool) requests the cookie to be only send to the
               server when a request is made with the https: scheme.
             - HttpOnly: (bool) forbids JavaScript from accessing the cookie.
             - SameSite: (Strict, Lax, or None) controls whether a cookie is
               sent with cross-origin requests, providing some protection
               against cross-site request forgery attacks.

   GetParam(name:str) → value:str
           Returns first value associated with name. name is handled in a
           case-sensitive manner. This function checks Request-URL parameters
           first. Then it checks application/x-www-form-urlencoded from the
           message body, if it exists, which is common for HTML forms sending
           POST requests. If a parameter is supplied matching name that has
           no value, e.g. foo in ?foo&bar=value, then the returned value will
           be nil, whereas for ?foo=&bar=value it would be "". To
           differentiate between no-equal and absent, use the HasParam
           function. The returned value is decoded from ISO-8859-1 (only in
           the case of Request-URL) and we assume that percent-encoded
           characters were supplied by the client as UTF-8 sequences, which
           are returned exactly as the client supplied them, and may
           therefore may contain overlong sequences, control codes, NUL
           characters, and even numbers which have been banned by the IETF.
           It is the responsibility of the caller to impose further
           restrictions on validity, if they're desired.

   EscapeHtml(str) → str
           Escapes HTML entities: The set of entities is &><"' which become
           &amp;&gt;&lt;&quot;&#39;. This function is charset agnostic and
           will not canonicalize overlong encodings. It is assumed that a
           UTF-8 string will be supplied. See escapehtml.c.

   LaunchBrowser([path:str])
           Launches web browser on local machine with URL to this redbean
           server. This function may be called from your /.init.lua.

   CategorizeIp(ip:uint32) → str
           Returns a string describing an IP address. This is currently Class
           A granular. It can tell you if traffic originated from private
           networks, ARIN, APNIC, DOD, etc.

   DecodeBase64(ascii:str) → binary:str
           Turns ASCII into binary, in a permissive way that ignores
           characters outside the base64 alphabet, such as whitespace. See
           decodebase64.c.

   DecodeLatin1(iso-8859-1:str) → utf-8:str
           Turns ISO-8859-1 string into UTF-8.

   EncodeBase64(binary:str) → ascii:str
           Turns binary into ASCII. This can be used to create HTML data:
           URIs that do things like embed a PNG file in a web page. See
           encodebase64.c.

   EncodeJson(value[,options:table]) → json:str
           Turns passed Lua value into a JSON string. Tables with non-zero
           length (as reported by `#`) are encoded as arrays with non-array
           elements ignored. Empty tables are encoded as empty arrays. All
           other tables are encoded as objects with numerical keys
           converted to strings (so `{[3]=1}` is encoded as `{"3":1}`).
           The following options can be used:
             - useoutput: (bool=false) encodes the result directly to the
               output buffer and returns `nil` value. This option is
               ignored if used outside of request handling code.
             - numformat: (string="%.14g") sets numeric format to be used.
             - maxdepth: (number=64) sets the max number of nested tables.

   EncodeLua(value[,options:table]) → json:str
           Turns passed Lua value into a Lua string. The following options
           can be used:
             - useoutput: (bool=false) encodes the result directly to the
               output buffer and returns `nil` value. This option is
               ignored if used outside of request handling code.
             - numformat: (string="%.14g") sets numeric format to be used.
             - maxdepth: (number=64) sets the max number of nested tables.

   EncodeLatin1(utf-8:str[,flags:int]) → iso-8859-1:str
           Turns UTF-8 into ISO-8859-1 string.

   EscapeFragment(str) → str
           Escapes URL #fragment. The allowed characters are
           -/?.~_@:!$&'()*+,;=0-9A-Za-z and everything else gets %XX encoded.
           Please note that '& can still break HTML and that '() can still
           break CSS URLs. This function is charset agnostic and will not
           canonicalize overlong encodings. It is assumed that a UTF-8 string
           will be supplied. See kescapefragment.c.

   EscapeHost(str) → str
           Escapes URL host. See kescapeauthority.c

   EscapeLiteral(str) → str
           Escapes JavaScript or JSON string literal content. The caller is
           responsible for adding the surrounding quotation marks. This
           implementation \uxxxx sequences for all non-ASCII sequences. HTML
           entities are also encoded, so the output doesn't need EscapeHtml.
           This function assumes UTF-8 input. Overlong encodings are
           canonicalized. Invalid input sequences are assumed to be
           ISO-8859-1. The output is UTF-16 since that's what JavaScript
           uses. For example, some individual codepoints such as emoji
           characters will encode as multiple \uxxxx sequences. Ints that are
           impossible to encode as UTF-16 are substituted with the \xFFFD
           replacement character. See escapejsstringliteral.c.

   EscapeParam(str) → str
           Escapes URL parameter name or value. The allowed characters are
           -.*_0-9A-Za-z and everything else gets %XX encoded. This function
           is charset agnostic and will not canonicalize overlong encodings.
           It is assumed that a UTF-8 string will be supplied. See
           kescapeparam.c.

   EscapePass(str) → str
           Escapes URL password. See kescapeauthority.c.

   EscapePath(str) → str
           Escapes URL path. This is the same as EscapeSegment except slash
           is allowed. The allowed characters are -.~_@:!$&'()*+,;=0-9A-Za-z/
           and everything else gets %XX encoded. Please note that '& can
           still break HTML, so the output may need EscapeHtml too. Also note
           that '() can still break CSS URLs. This function is charset
           agnostic and will not canonicalize overlong encodings. It is
           assumed that a UTF-8 string will be supplied. See kescapepath.c.

   EscapeSegment(str) → str
           Escapes URL path segment. This is the same as EscapePath except
           slash isn't allowed. The allowed characters are
           -.~_@:!$&'()*+,;=0-9A-Za-z and everything else gets %XX encoded.
           Please note that '& can still break HTML, so the output may need
           EscapeHtml too. Also note that '() can still break CSS URLs. This
           function is charset agnostic and will not canonicalize overlong
           encodings. It is assumed that a UTF-8 string will be supplied. See
           kescapesegment.c.

   EscapeUser(str) → str
           Escapes URL username. See kescapeauthority.c.

   Fetch(url:str[,body:str|{method=value:str,body=value:str,...}])
       → status:int,{header:str=value:str,...},body:str
           Sends an HTTP/HTTPS request to the specified URL. If only the URL is
           provided, then a GET request is sent. If both URL and body parameters
           are specified, then a POST request is sent. If any other method needs
           to be specified (for example, PUT or DELETE), then passing a table as
           the second value allows setting method and body values as well other
           options:
             - method (default = "GET"): sets the method to be used for the
               request. The specified method is converted to uppercase.
             - body (default = ""): sets the body value to be sent.
             - followredirect (default = true): forces temporary and permanent
               redirects to be followed. This behavior can be disabled by
               passing `false`.
             - maxredirects (default = 5): sets the number of allowed redirects
               to minimize looping due to misconfigured servers. When the number
               is exceeded, the result of the last redirect is returned.
           When the redirect is being followed, the same method and body values
           are being sent in all cases except when 303 status is returned. In
           that case the method is set to GET and the body is removed before the
           redirect is followed. Note that if these (method/body) values are
           provided as table fields, they will be modified in place.

   FormatHttpDateTime(seconds:int) → rfc1123:str
           Converts UNIX timestamp to an RFC1123 string that looks like this:
           Mon, 29 Mar 2021 15:37:13 GMT. See formathttpdatetime.c.

   FormatIp(uint32) → str
           Turns integer like 0x01020304 into a string like 1.2.3.4. See also
           ParseIp for the inverse operation.

   GetAssetComment(path:str) → str
           Returns comment text associated with asset in the ZIP central
           directory. Also available as GetComment (deprecated).

   GetAssetMode(path:str) → int
           Returns UNIX-style octal mode for ZIP asset (or local file if the
           -D flag is used)

   GetAssetSize(path:str) → int
           Returns byte size of uncompressed contents of ZIP asset (or local
           file if the -D flag is used)

   GetBody() → str
           Returns the request message body if present or an empty string.
           Also available as GetPayload (deprecated).

   GetCookie(name:str) → str
           Returns cookie value.

   GetCryptoHash(name:str,payload:str[,key:str]) → str
           Returns value of the specified cryptographic hash function. If the
           key is provided, then HMAC value of the same function is returned.
           The name can be one of the following strings: MD5, SHA1, SHA224,
           SHA256, SHA384, SHA512, and BLAKE2B256.

   GetRemoteAddr() → ip:uint32,port:uint16
           Returns client ip4 address and port, e.g. 0x01020304,31337 would
           represent 1.2.3.4:31337. This is the same as GetClientAddr except
           it will use the ip:port from the X-Forwarded-For header, only if
           IsPrivateIp or IsLoopbackIp return true. When multiple addresses
           are present in the header, the last/right-most address is used.

   GetClientAddr() → ip:uint32,port:uint16
           Returns client socket ip4 address and port, e.g. 0x01020304,31337
           would represent 1.2.3.4:31337. Please consider using GetRemoteAddr
           instead, since the latter takes into consideration reverse proxy
           scenarios.

   GetServerAddr() → ip:uint32,port:uint16
           Returns address to which listening server socket is bound, e.g.
           0x01020304,8080 would represent 1.2.3.4:8080. If -p 0 was supplied
           as the listening port, then the port in this string will be
           whatever number the operating system assigned.

   GetDate() → seconds:int
           Returns date associated with request that's used to generate the
           Date header, which is now, give or take a second. The returned
           value is a UNIX timestamp.

   GetHeader(name:str) → value:str
           Returns HTTP header. name is case-insensitive. The header value is
           returned as a canonical UTF-8 string, with leading and trailing
           whitespace trimmed, which was decoded from ISO-8859-1, which is
           guaranteed to not have C0/C1 control sequences, with the exception
           of the tab character. Leading and trailing whitespace is
           automatically removed. In the event that the client suplies raw
           UTF-8 in the HTTP message headers, the original UTF-8 sequence can
           be losslessly restored by counter-intuitively recoding the
           returned string back to Latin1. If the requested header is defined
           by the RFCs as storing comma-separated values (e.g. Allow,
           Accept-Encoding) and the field name occurs multiple times in the
           message, then this function will fold those multiple entries into
           a single string.

   GetHeaders() → {name:str=value:str,...}
           Returns HTTP headers as dictionary mapping header key strings to
           their UTF-8 decoded values. The ordering of headers from the
           request message is not preserved. Whether or not the same key can
           repeat depends on whether or not it's a standard header, and if
           so, if it's one of the ones that the RFCs define as repeatable.
           See khttprepeatable.c. Those headers will not be folded. Standard
           headers which aren't on that list, will be overwritten with the
           last-occurring one during parsing. Extended headers are always
           passed through exactly as they're received. Please consider using
           GetHeader API if possible since it does a better job abstracting
           these issues.

   GetLogLevel() → int
           Returns logger verbosity level. Likely return values are kLogDebug
           > kLogVerbose > kLogInfo > kLogWarn > kLogError > kLogFatal.

   GetHost() → str
           Returns host associated with request. This will be the Host
           header, if it's supplied. Otherwise it's the bind address.

   GetHostOs() → str
           Returns string that describes the host OS.

   GetMonospaceWidth(str|char) → int
           Returns monospace display width of string. This is useful for
           fixed-width formatting. For example, CJK characters typically take
           up two cells. This function takes into consideration combining
           characters, which are discounted, as well as control codes and
           ANSI escape sequences.

   GetMethod() → str
           Returns HTTP method. Normally this will be GET, HEAD, or POST in
           which case redbean normalizes this value to its uppercase form.
           Anything else that the RFC classifies as a "token" string is
           accepted too, which might contain characters like &".

   GetParams() → {{name:str[,value:str]},...}
           Returns name=value parameters from Request-URL and
           application/x-www-form-urlencoded message body in the order they
           were received. This may contain duplicates. The inner array will
           have either one or two items, depending on whether or not the
           equals sign was used.

   GetPath() → str
           Returns the Request-URL path. This is guaranteed to begin with
           "/". It is further guaranteed that no "//" or "/." exists in the
           path. The returned value is returned as a UTF-8 string which was
           decoded from ISO-8859-1. We assume that percent-encoded characters
           were supplied by the client as UTF-8 sequences, which are returned
           exactly as the client supplied them, and may therefore may contain
           overlong sequences, control codes, NUL characters, and even
           numbers which have been banned by the IETF. redbean takes those
           things into consideration when performing path safety checks. It
           is the responsibility of the caller to impose further restrictions
           on validity, if they're desired.

   GetEffectivePath() → str
           Returns path as it was resolved by the routing algorithms, which
           might contain the virtual host prepended if used.

   GetScheme() → str
           Returns scheme from Request-URL, if any.

   GetSslIdentity() → str
           Returns certificate subject or PSK identity from the current SSL
           session. `nil` is returned for regular (non-SSL) connections.

   GetStatus() → int
           Returns current status (as set by an earlier SetStatus call) or
           `nil` if the status hasn't been set yet.

   GetTime() → seconds:number
           Returns current time as a UNIX timestamp with 0.0001s precision.

   GetUrl() → str
           Returns the effective Request-URL as an ASCII string, where
           illegal characters or UTF-8 is guaranteed to be percent encoded,
           and has been normalized to include either the Host or
           X-Forwarded-Host headers, if they exist, and possibly a scheme too
           if redbean is being used as an HTTP proxy server. In the future
           this API might change to return an object instead.

   GetHttpVersion() → int
           Returns the request HTTP protocol version, which can be 9 for
           HTTP/0.9, 10 for HTTP/1.0, or 11 for HTTP/1.1. Also available
           as GetVersion (deprecated).

   GetRandomBytes([length:int]) → str
           Returns string with the specified number of random bytes (1..256).
           If no length is specified, then a string of length 16 is returned.

   GetRedbeanVersion() → int
           Returns the Redbean version in the format 0xMMmmpp, with major (MM),
           minor (mm), and patch (pp) versions encoded. The version value 1.4
           would be represented as 0x010400.

   GetZipPaths([prefix:str]) → {path:str,...}
           Returns paths of all assets in the zip central directory, prefixed
           by a slash. If prefix parameter is provided, then only paths that
           start with the prefix (case sensitive) are returned.

   HasParam(name:str) → bool
           Returns true if parameter with name was supplied in either the
           Request-URL or an application/x-www-form-urlencoded message body.

   HidePath(prefix:str)
           Programs redbean / listing page to not display any paths beginning
           with prefix. This function should only be called from /.init.lua.

   IsPublicIp(uint32) → bool
           Returns true if IP address is not a private network (10.0.0.0/8,
           172.16.0.0/12, 192.168.0.0/16) and is not localhost (127.0.0.0/8).
           Note: we intentionally regard TEST-NET IPs as public.

   IsPrivateIp(uint32) → bool
           Returns true if IP address is part of a private network
           (10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16).

   IsLoopbackClient() → bool
           Returns true if the client IP address (returned by GetRemoteAddr)
           is part of the localhost network (127.0.0.0/8).

   IsLoopbackIp(uint32) → bool
           Returns true if IP address is part of the localhost network
           (127.0.0.0/8).

   IsCompressed(path:str) → bool
           Returns true if ZIP artifact at path is stored on disk using
           DEFLATE compression.

   IndentLines(str[,int]) → str
           Adds spaces to beginnings of multiline string. If the int
           parameter is not supplied then 1 space will be added.

   LoadAsset(path:str) → str
           Returns contents of file as string. The asset may be sourced from
           either the zip (decompressed) or the local filesystem if the -D
           flag was used. If slurping large file into memory is a concern,
           then consider using ServeAsset which can serve directly off disk.

   StoreAsset(path:str,data:str[,mode:int])
           Stores asset to executable's ZIP central directory. This currently
           happens in an append-only fashion and is still largely in the
           proof-of-concept stages. Currently only supported on Linux, XNU,
           and FreeBSD.

   Log(level:int,message:str)
           Emits message string to log, if level is less than or equal to
           GetLogLevel. If redbean is running in interactive mode, then this
           will log to the console. If redbean is running as a daemon or the
           -L LOGFILE flag is passed, then this will log to the file.
           Reasonable values for level are kLogDebug > kLogVerbose > kLogInfo
           > kLogWarn > kLogError > kLogFatal. The logger emits timestamps in
           the local timezone with microsecond precision. If log entries are
           emitted more frequently than once per second, then the log entry
           will display a delta timestamp, showing how much time has elapsed
           since the previous log entry. This behavior is useful for quickly
           measuring how long various portions of your code take to execute.

   ParseHttpDateTime(rfc1123:str) → seconds:int
           Converts RFC1123 string that looks like this: Mon, 29 Mar 2021
           15:37:13 GMT to a UNIX timestamp. See parsehttpdatetime.c.

   ParseUrl(str) → URL
           Parses URL, returning object having the following fields: scheme,
           user, pass, host, port, path, params, fragment. This parser is
           charset agnostic. Percent encoded bytes are decoded for all
           fields. Returned values might contain things like NUL characters,
           spaces, control codes, and non-canonical encodings. Absent can be
           discerned from empty by checking if the pointer is set. There's no
           failure condition for this routine. This is a permissive parser.
           This doesn't normalize path segments like `.` or `..` so use
           IsAcceptablePath() to check for those. No restrictions are imposed
           beyond that which is strictly necessary for parsing. All the data
           that is provided will be consumed to the one of the fields. Strict
           conformance is enforced on some fields more than others, like
           scheme, since it's the most non-deterministically defined field of
           them all. Please note this is a URL parser, not a URI parser.
           Which means we support everything everything the URI spec says we
           should do except for the things we won't do, like tokenizing path
           segments into an array and then nesting another array beneath each
           of those for storing semicolon parameters. So this parser won't
           make SIP easy. What it can do is parse HTTP URLs and most URIs
           like data:opaque, better in fact than most things which claim to
           be URI parsers.

   EncodeUrl(URL) → str
           This function is the inverse of ParseUrl. The output will always
           be correctly formatted. The exception is if illegal characters are
           supplied in the scheme field, since there's no way of escaping
           those. Opaque parts are escaped as though they were paths, since
           many URI parsers won't understand things like an unescaped
           question mark in path.

   ParseIp(str) → int
           Converts IPv4 address string to integer, e.g. "1.2.3.4" →
           0x01020304, or returns -1 for invalid inputs. See also FormatIp
           for the inverse operation.

   ProgramAddr(str)
           Configures the address on which to listen. Can be used multiple
           times to set more than one address.

   ProgramBrand(str)
           Changes HTTP Server header, as well as the <h1> title on the /
           listing page. The brand string needs to be a UTF-8 value that's
           encodable as ISO-8859-1. If the brand is changed to something
           other than redbean, then the promotional links will be removed
           from the listing page too. This function should only be called
           from /.init.lua.

   ProgramCache(seconds:int)
           Configures Cache-Control and Expires header generation for static
           asset serving. A negative value will disable the headers. Zero
           means don't cache. Greater than zero asks public proxies and
           browsers to cache for a given number of seconds. This should only
           be called from /.init.lua.

   ProgramCertificate(pem:str)
           Same as the -C flag if called from .init.lua, e.g.
           ProgramCertificate(LoadAsset("/.sign.crt")) for zip loading or
           ProgramCertificate(Slurp("/etc/letsencrypt.lol/fullchain.pem")) for
           local file system only.

   ProgramHeader(name:str,value:str)
           Appends HTTP header to the header buffer for all responses (whereas
           SetHeader only appends a header to the current response buffer).
           name is case-insensitive and restricted to non-space ASCII. value
           is a UTF-8 string that must be encodable as ISO-8859-1. Leading and
           trailing whitespace is trimmed automatically. Overlong characters
           are canonicalized. C0 and C1 control codes are forbidden, with the
           exception of tab. The header buffer is independent of the payload
           buffer. This function disallows the setting of certain headers such
           as Content-Range and Date, which are abstracted by the transport
           layer.

   ProgramPort(uint16)
           Hard-codes the port number on which to listen, which can be any
           number in the range 1..65535, or alternatively 0 to ask the
           operating system to choose a port, which may be revealed later on
           by GetServerAddr or the -z flag to stdout.

   ProgramPrivateKey(pem:str)
           Same as the -K flag if called from .init.lua, e.g.
           ProgramPrivateKey(LoadAsset("/.sign.key")) for zip loading or
           ProgramPrivateKey(Slurp("/etc/letsencrypt/fullchain.pem")) for
           local file system only.

   ProgramRedirect(code:int,src:str,location:str)
           Configures fallback routing for paths which would otherwise return
           404 Not Found. If code is 0 then the path is rewritten internally
           as an accelerated redirect. If code is 301, 302, 307, or 308 then
           a redirect response will be sent to the client. This should only
           be called from /.init.lua.

   ProgramSslTicketLifetime(seconds:int)
           Defaults to 86400 (24 hours). This may be set to ≤0 to disable
           SSL tickets. It's a good idea to use these since it increases
           handshake performance 10x and eliminates a network round trip.

   EvadeDragnetSurveillance(bool)
           If this option is programmed then redbean will not transmit a
           Server Name Indicator (SNI) when performing Fetch() requests.

   ProgramSslPresharedKey(key:str,identity:str)
           This function can be used to enable the PSK ciphersuites
           which simplify SSL and enhance its performance in controlled
           environments. `key` may contain 1..32 bytes of random binary
           data and identity is usually a short plaintext string. The
           first time this function is called, the preshared key will
           be added to both the client and the server SSL configs. If
           it's called multiple times, then the remaining keys will be
           added to the server, which is useful if you want to assign
           separate keys to each client, each of which needs a separate
           identity too. If this function is called multiple times with
           the same identity string, then the latter call will overwrite
           the prior. If a preshared key is supplied and no certificates
           or key-signing-keys are programmed, then redbean won't bother
           auto-generating any serving certificates and will instead use
           only PSK ciphersuites.

   ProgramSslCiphersuite(name:str)
           See https://redbean.dev/ for further details.

   IsDaemon() → bool
           Returns true if -d flag was passed to redbean.

   ProgramUid(int)
           Same as the -U flag if called from .init.lua for setuid()

   ProgramGid(int)
           Same as the -G flag if called from .init.lua for setgid()

   ProgramDirectory(str)
           Same as the -D flag if called from .init.lua for overlaying local
           file system directories. This may be called multiple times. The
           first directory programmed is preferred. These currently do not
           show up in the index page listing.

   ProgramLogMessages(bool)
           Same as the -m flag if called from .init.lua for logging message
           headers only.

   ProgramLogBodies(bool)
           Same as the -b flag if called from .init.lua for logging message
           bodies as part of POST / PUT / etc. requests.

   ProgramLogPath(str)
           Same as the -L flag if called from .init.lua for setting the log
           file path on the local file system. It's created if it doesn't
           exist. This is called before de-escalating the uesr / group id.
           The file is opened in append only mode. If the disk runs out of
           space then redbean will truncate the log file if has access to
           change the log file after daemonizing.

   ProgramPidPath(str)
           Same as the -P flag if called from .init.lua for setting the pid
           file path on the local file system. It's useful for reloading
           daemonized redbean using `kill -HUP $(cat /var/run/redbean.pid)`
           or terminating redbean with `kill $(cat /var/run/redbean.pid)`
           which will gracefully terminate all clients. Sending the TERM
           signal twice will cause a forceful shutdown, which might make
           someone with a slow internet connection who's downloading big
           files unhappy.

   ProgramUniprocess([bool]) → bool
           Same as the -u flag if called from .init.lua. Can be used to
           configure the uniprocess mode. The current value is returned.

   Slurp(filename:str) → str
           Reads file data from local file system.

   Sleep(seconds:number)
           Sleeps the specified number of seconds (can be fractional). The
           smallest interval is a microsecond.

   Route([host:str,[path:str]])
           Instructs redbean to follow the normal HTTP serving path. This
           function is useful when writing an OnHttpRequest handler, since
           that overrides the serving path entirely. So if the handler
           decides it doesn't want to do anything, it can simply call this
           function, to hand over control back to the redbean core. By
           default, the host and path arguments are supplied from the
           resolved GetUrl value. This handler always resolves, since it will
           generate a 404 Not Found response if redbean couldn't find an
           appropriate endpoint.

   RouteHost([host:str,[path:str]]) → bool
           This is the same as Route, except it only implements the subset of
           request routing needed for serving virtual-hosted assets, where
           redbean tries to prefix the path with the hostname when looking up
           a file. This function returns true if the request was resolved. If
           it was resolved, then your OnHttpRequest request handler can still
           set additional headers.

   RoutePath([path:str]) → bool
           This is the same as Route, except it only implements the subset of
           request routing needed for serving assets. This function returns
           true if the request was resolved. If it was resolved, then your
           OnHttpRequest request handler can still set additional headers.
           Note that the asset needs to have "read other" permissions;
           otherwise this function logs a warning and returns 403 Forbidden.
           If this is undesirable, use GetAssetMode and ServeAsset to bypass
           the check.

   ServeAsset(path:str)
           Instructs redbean to serve static asset at path. This function
           causes what would normally happen outside a dynamic handler to
           happen. The asset can be sourced from either the zip or local
           filesystem if -D is used. This function is mutually exclusive with
           SetStatus and other Serve* functions.

   ServeError(code:int[,reason:str])
           Instructs redbean to serve a boilerplate error page. This takes
           care of logging the error, setting the reason phrase, and adding a
           payload. This function is mutually exclusive with SetStatus and
           other Serve* functions.

   ServeRedirect(code:int,location:str)
           Instructs redbean to return the specified redirect code along with
           the Location header set. This function is mutually exclusive with
           SetStatus and other Serve* functions.

   SetLogLevel(level:int)
           Sets logger verbosity. Reasonable values for level are kLogDebug >
           kLogVerbose > kLogInfo > kLogWarn > kLogError > kLogFatal. This is
           reset at the end of the http request, so it can be used to disable
           access log and message logging.

   VisualizeControlCodes(str) → str
           Replaces C0 control codes with their UNICODE pictures
           representation. This function also canonicalizes overlong
           encodings. C1 control codes are replaced with a JavaScript-like
           escape sequence.

   Underlong(str) → str
           Canonicalizes overlong encodings.

   Crc32(initial:int,data:str) → int
           Computes 32-bit CRC-32 used by zip/zlib/gzip/etc.

   Crc32c(initial:int,data:str) → int
           Computes 32-bit Castagnoli Cyclic Redundancy Check.

   Md5(str) → str
           Computes MD5 checksum, returning 16 bytes of binary.

   Sha1(str) → str
           Computes SHA1 checksum, returning 20 bytes of binary.

   Sha224(str) → str
           Computes SHA224 checksum, returning 28 bytes of binary.

   Sha256(str) → str
           Computes SHA256 checksum, returning 32 bytes of binary.

   Sha384(str) → str
           Computes SHA384 checksum, returning 48 bytes of binary.

   Sha512(str) → str
           Computes SHA512 checksum, returning 64 bytes of binary.

   Bsf(x:int) → int
           Returns position of first bit set. Passing 0 will raise an error.
           Same as the Intel x86 instruction BSF.

   Bsr(x:int) → int
           Returns binary logarithm of 𝑥. Passing 0 will raise an error. Same
           as the Intel x86 instruction BSR.

   Popcnt(x:int) → int
           Returns number of bits set in integer.

LSQLITE3 MODULE

   Please refer to the LuaSQLite3 Documentation.

   For example, you could put the following in your /.init.lua file:

     sqlite3 = require "lsqlite3"
     db = sqlite3.open_memory()
     db:exec[[
       CREATE TABLE test (
         id INTEGER PRIMARY KEY,
         content TEXT
       );
       INSERT INTO test (content) VALUES ('Hello World');
       INSERT INTO test (content) VALUES ('Hello Lua');
       INSERT INTO test (content) VALUES ('Hello Sqlite3');
     ]]

   Then, your Lua server pages or OnHttpRequest handler may perform SQL
   queries by accessing the db global. The performance is good too, at about
   400k qps.

     for row in db:nrows("SELECT * FROM test") do
        Write(row.id.." "..row.content.."<br>")
     end

   redbean supports a subset of what's defined in the upstream LuaSQLite3
   project. Most of the unsupported APIs relate to pointers and database
   notification hooks.

   redbean also currently disables SQLite features which don't make sense for
   production serving, such as ALTER, VACUUM, ANALYZE, etc. For that reason
   we provide an APE build of the SQLite shell which you can use to
   administrate your redbean database. See the sqlite3.com download above.

RE MODULE

   This module exposes an API for POSIX regular expressions which enable you
   to validate input, search for substrings, extract pieces of strings, etc.
   Here's a usage example:

     # Example IPv4 Address Regular Expression (see also ParseIP)
     p = re.compile([[^([0-9]{1,3})\.([0-9]{1,3})\.([0-9]{1,3})\.([0-9]{1,3})$]])
     m,a,b,c,d = p:search(𝑠)
     if m then
       print("ok", tonumber(a), tonumber(b), tonumber(c), tonumber(d))
     else
       print("not ok")
     end

   re.search(regex:str,text:str[,flags:int]) → [match[,group_1,...]]
           Shortcut for re.compile plus regex_t*:search.

   re.compile(regex:str[,flags:int]) → regex_t*
           Compiles regular expression, using the POSIX extended syntax. This
           has an O(2^𝑛) cost, so it's a good idea to do this from your
           /.init.lua file. Flags may contain re.BASIC, re.ICASE, re.NOSUB,
           and/or re.NEWLINE. See also regcomp() from libc.

   regex_t*:search(text:str[,flags:int]) → [match[,group_1,...]]
           Executes regular expression. This has an O(𝑛) cost. This returns
           nothing (nil) if the pattern doesn't match anything. Otherwise it
           pushes the matched substring and any parenthesis-captured values
           too. Flags may contain re.NOTBOL or re.NOTEOL to indicate whether
           or not text should be considered at the start and/or end of a
           line.

   re.BASIC
           Use this flag if you prefer the default POSIX regex syntax. We use
           extended regex notation by default. For example, an extended
           regular expression for matching an IP address might look like
           ([0-9]*)\.([0-9]*)\.([0-9]*)\.([0-9]*) whereas with basic syntax
           it would look like \([0-9]*\)\.\([0-9]*\)\.\([0-9]*\)\.\([0-9]*\).
           This flag may only be used with re.compile and re.search.

   re.ICASE
           Use this flag to make your pattern case ASCII case-insensitive.
           This means [a-z] will mean the same thing as [A-Za-z]. This flag
           may only be used with re.compile and re.search.

   re.NEWLINE
           Use this flag to change the handling of NEWLINE (\x0a) characters.
           When this flag is set, (1) a NEWLINE shall not be matched by a "."
           or any form of a non-matching list, (2) a "^" shall match the
           zero-length string immediately after a NEWLINE (regardless of
           re.NOTBOL), and (3) a "$" shall match the zero-length string
           immediately before a NEWLINE (regardless of re.NOTEOL).

   re.NOSUB
           Causes re.search to only report success and failure. This is
           reported via the API by returning empty string for success. This
           flag may only be used with re.compile and re.search.

   re.NOTBOL
           The first character of the string pointed to by string is not the
           beginning of the line. This flag may only be used with re.search
           and regex_t*:search.

   re.NOTEOL
           The last character of the string pointed to by string is not the
           end of the line. This flag may only be used with re.search and
           regex_t*:search.

MAXMIND MODULE

   This module may be used to get city/country/asn/etc from IPs, e.g.

       -- .init.lua
       maxmind = require "maxmind"
       asndb = maxmind.open('/usr/local/share/maxmind/GeoLite2-ASN.mmdb')

       -- request handler
       as = asndb:lookup(GetRemoteAddr())
       if as then
           asnum = as:get("autonomous_system_number")
           asorg = as:get("autonomous_system_organization")
           Write(EscapeHtml(asnum))
           Write(' ')
           Write(EscapeHtml(asorg))
       end

   For further details, please see maxmind.lua in redbean-demo.com.

CONSTANTS

   kLogDebug
           Integer for debug logging level. See Log.

   kLogVerbose
           Integer for verbose logging level, which is less than kLogDebug.

   kLogInfo
           Integer for info logging level, which is less than kLogVerbose.

   kLogWarn
           Integer for warn logging level, which is less than kLogVerbose.

   kLogError
           Integer for error logging level, which is less than kLogWarn.

   kLogFatal
           Integer for fatal logging level, which is less than kLogError.
           Logging anything at this level will result in a backtrace and
           process exit.

SEE ALSO

  https://justine.lol/redbean/index.html
  https://news.ycombinator.com/item?id=26271117