NGHTTP2 Module

Daniel-Constantin Mierla

   <miconda@gmail.com>

Edited by

Daniel-Constantin Mierla

   <miconda@gmail.com>

   Copyright © 2024 asipto.com
     __________________________________________________________________

   Table of Contents

   1. Admin Guide

        1. Overview
        2. Dependencies

              2.1. Kamailio Modules
              2.2. External Libraries or Applications

        3. Parameters

              3.1. listen_addr (str)
              3.2. listen_port (str)
              3.3. event_callback (str)

        4. Functions

              4.1. nghttp2_reply(code, body)
              4.2. nghttp2_reply_header(name, value)

        5. Event Routes

              5.1. nghttp2:request

   List of Examples

   1.1. Set listen_addr parameter
   1.2. Set listen_port parameter
   1.3. Set event_callback parameter
   1.4. nghttp2_reply usage
   1.5. nghttp2_reply usage

Chapter 1. Admin Guide

   Table of Contents

   1. Overview
   2. Dependencies

        2.1. Kamailio Modules
        2.2. External Libraries or Applications

   3. Parameters

        3.1. listen_addr (str)
        3.2. listen_port (str)
        3.3. event_callback (str)

   4. Functions

        4.1. nghttp2_reply(code, body)
        4.2. nghttp2_reply_header(name, value)

   5. Event Routes

        5.1. nghttp2:request

1. Overview

   This module implements an embedded HTTP/2 server using nghttpd2
   library.

2. Dependencies

   2.1. Kamailio Modules
   2.2. External Libraries or Applications

2.1. Kamailio Modules

   The following modules must be loaded before this module:
     * none.

2.2. External Libraries or Applications

   The following libraries or applications must be installed before
   running Kamailio with this module loaded:
     * libnghttp2 - libnghttpd library (v1.43.0+)

3. Parameters

   3.1. listen_addr (str)
   3.2. listen_port (str)
   3.3. event_callback (str)

3.1. listen_addr (str)

   IPv4 address to listen for HTTP2 connection. If not set, then it
   listens on all local addresses (port has to be specified by listen_port
   parameter).

   Default value is "" (empty - not set).

   Example 1.1. Set listen_addr parameter
...
modparam("nghttp2", "listen_addr", "127.0.0.1")
...

3.2. listen_port (str)

   Port or service name to listen for HTTP2 connection.

   Default value is "8282".

   Example 1.2. Set listen_port parameter
...
modparam("nghttp2", "listen_port", "8284")
...

3.3. event_callback (str)

   The name of the function in the kemi configuration file (embedded
   scripting language such as Lua, Python, ...) to be executed instead of
   event_route[nghttp2:request] block.

   The function has one string parameter with the value "nghttp2:request".

   Default value is 'empty' (no function is executed for events).

   Example 1.3. Set event_callback parameter
...
modparam("nghttp2", "event_callback", "ksr_nghttp2_event")
...
-- event callback function implemented in Lua
function ksr_nghttp2_event(evname)
        KSR.info("===== nghttp2 module triggered event: " .. evname .. "\n");
        return 1;
end
...

4. Functions

   4.1. nghttp2_reply(code, body)
   4.2. nghttp2_reply_header(name, value)

4.1.  nghttp2_reply(code, body)

   Send back a reply with body. The body can be empty string. Both
   parameters can contain variables.

   Example 1.4. nghttp2_reply usage
...
event_route[nghttp2:request] {
    nghttp2_reply("200",
        "<html><body>OK</body></html>");
}
...

4.2.  nghttp2_reply_header(name, value)

   Set a header to be added to reply. There can be up to 15 headers.

   Example 1.5. nghttp2_reply usage
...
event_route[nghttp2:request] {
    nghttp2_reply_header("Content-Type", "text/html");
    nghttp2_reply_header("My-Header", "xyz");
    nghttp2_reply("200",
        "<html><body>OK</body></html>");
}
...

5. Event Routes

   5.1. nghttp2:request

5.1.  nghttp2:request

   The event route is executed when a new HTTP request is received.

   Inside it, the $nghttp2(...) group of variables is available, giving
   access to several attributes of the HTTP request, such as method, URL
   path, data (body) or headers.
...
...
loadmodule "nghttp2.so
...
event_route[nghttp2:request] {
    xinfo("request: $nghttp2(method) - url: $nghttp2(path) - data: [$nghttp2(dat
a)]\n");
    nghttp2_reply("200", "OK", "text/html",
        "<html><body>OK</body></html>");
}
...
