Site icon 지락문화예술공작단

Introduction to nginScript

KENNETH

Introduction to nginScript

<!–

table, th, td {
border: 1px solid black;
}
th {
background-color: #d3d3d3;
align: left;
padding-left: 5px;
padding-bottom: 2px;
padding-top: 2px;
line-height: 120%;
}
td {
padding-left: 5px;
padding-bottom: 5px;
padding-top: 5px;
line-height: 120%;
}
td.center {
text-align: center;
padding-bottom: 5px;
padding-top: 5px;
line-height: 120%;
}

–>

Harnessing the Power and Convenience of JavaScript for Each Request

Since nginScript launched in September 2015 it has been remained an experimental module while additional capabilities and core language support were added. With NGINX Plus R12 we are pleased to announce that nginScript is now generally available as a stable module for NGINX and NGINX Plus.

nginScript is a unique JavaScript implementation for NGINX and NGINX Plus, designed specifically for server‑side use cases and per‑request processing. It extends NGINX configuration syntax with JavaScript code in order to implement sophisticated configuration solutions.

The use cases are extensive, especially as nginScript is available for both HTTP and TCP/UDP protocols. Example use cases for nginScript include:

There are of course many more possibilities for nginScript, and more still that have yet to be implemented. Although we are pleased to announce general availability of nginScript and be able to recommend it for production use, there is a roadmap of planned improvements that will enable yet more use cases, such as:

Before discussing nginScript in more detail, let’s first address two common misconceptions.

nginScript Is Not Lua

The NGINX community has created several programmatic extensions over the years. At the time of writing, Lua is the most popular of these; it’s available as a module for NGINX and a certified third‑party module for NGINX Plus. The Lua module and add‑on libraries provide deep integration with the NGINX core and a rich set of functionality, including a driver for Redis.

Whilst Lua is a powerful scripting language, it has a steep learning curve, unusual syntax, and some challenging idiosyncrasies. It remains fairly niche in terms of adoption and is not typically found in the “skillset toolbox” of the frontend developer or DevOps engineer.

nginScript does not seek to replace Lua and it will be some time before nginScript has a comparable level of functionality. The goal of nginScript is to provide programmatic configuration solutions to the widest possible community by using a popular programming language.

nginScript Is Not Node.js

nginScript does not aim to turn NGINX or NGINX Plus into an application server. In simple terms, the use cases for nginScript are akin to middleware, as the code execution happens between the client and the content. Technically speaking, while Node.js shares two things with the combination of nginScript and NGINX or NGINX Plus – an event‑driven architecture and the JavaScript programming language – the similarities end there.

Node.js uses the Google V8 JavaScript engine, whereas nginScript is a bespoke implementation of the ECMAScript standards, designed specifically for NGINX and NGINX Plus. Node.js has a persistent JavaScript virtual machine in memory and performs routine garbage collection for memory management, whereas nginScript initializes a new JavaScript virtual machine and the necessary memory for each request and frees the memory when the request is completed.

JavaScript as a Server-Side Language

As mentioned above, nginScript is a bespoke implementation of the JavaScript language. All other existing JavaScript runtime engines are designed to be executed within a web browser. The nature of client‑side code execution is different from server‑side code execution in many ways – from the availability of system resources to the possible number of concurrent runtimes.

We decided to implement our own JavaScript runtime in order to meet the requirements of server‑side code execution and fit elegantly with NGINX’s request‑processing architecture. Our design principles for nginScript are these:

Getting Started with nginScript – A Real‑World Example

nginScript is implemented as a module that you can compile into an open source NGINX binary or dynamically load into NGINX or NGINX Plus. Instructions for enabling nginScript with NGINX and NGINX Plus appear at the end of this article.

In this example we use NGINX or NGINX Plus as a simple reverse proxy and use nginScript to construct access log entries in a specialized format, that:

The NGINX configuration for this example is extremely simple.

<!–
[config]js_include conf.d/header_logging.js; # Load JavaScript code from here
js_set $access_log_with_headers kvAccessLog; # Fill variable from JS function
log_format kvpairs $access_log_with_headers; # Define special log format

server {
listen 80;
access_log /var/log/nginx/access_headers.log kvpairs;
location / {
proxy_pass http://www.example.com;
}
}[/config] –>As you can see, the nginScript code does not sit inline with the configuration syntax. We use the js_include directive to specify the file that contains all of our JavaScript code. The js_set directive defines a new NGINX variable, $access_log_with_headers, and the JavaScript function that populates it. The log_format directive defines a new format called kvpairs which writes each log line with the value of $access_log_with_headers.

The server block defines a simple HTTP reverse proxy that forwards all requests to http://www.example.com. The access_log directive specifies that all requests will be logged with the kvpairs format.

Let’s now look at the JavaScript code that prepares the log line. We have two functions:

As can be seen in the kvAccessLog function, it is the return value that is passed to the js_set configuration directive. Bear in mind that NGINX variables are evaluated on demand and this in turn means that the JavaScript function defined by js_set is executed when the value of the variable is required. In this example, $access_log_with_headers is used in the log_format directive and so kvAccessLog() is executed at log time. Variables used as part of map or rewrite directives trigger the corresponding JavaScript execution at an earlier processing phase.

We can see this nginScript‑enhanced logging solution in action by passing a request through our reverse proxy and observing the resulting log file entry.

$ curl http://127.0.0.1/

$ tail --lines=1 /var/log/nginx/access_headers.log

2017-03-14T14:36:53+00:00 client=127.0.0.1 method=GET uri=/ status=200 req.Host=127.0.0.1 req.User-Agent=curl/7.47.0 req.Accept=*/* res.Cache-Control=max-age=604800 res.Etag=x22359670651+identx22 res.Expires='Tue, 21 Mar 2017 14:36:53 GMT' res.Last-Modified='Fri, 09 Aug 2013 23:54:35 GMT' res.Vary=Accept-Encoding res.X-Cache=HIT

Much of the utility of nginScript is a result of its access to NGINX internals. This example utilizes several properties of the request and response objects. The Stream nginScript module for TCP and UDP applications utilizes a single session object with its own set of properties. See our blog for other examples of nginScript solutions:

We’d love to hear about the use cases that you come up with for nginScript – please tell us about them in the comments section below.

Enabling nginScript for NGINX and NGINX Plus

Loading nginScript for NGINX Plus

nginScript is available as a free dynamic module for NGINX Plus subscribers (for open source NGINX, see Loading nginScript for Open Source NGINX below).

  1. Obtain the module itself by installing it from the NGINX Plus repository.

    • For Ubuntu and Debian systems:

      $ sudo apt‑get install nginx-plus-module-njs

      • For RedHat, CentOS, and Oracle Linux systems:

    $ sudo yum install nginx-plus-module-njs

  2. Enable the module by including a load_module directive for it in the top‑level (“main”) context of the nginx.conf configuration file (not in the http or stream context). This example loads the nginScript module for HTTP traffic.

    load_module modules/ngx_http_js_module.so;

  3. Reload NGINX Plus to load the nginScript module into the running instance.

    $ sudo nginx -s reload

Loading nginScript for Open Source NGINX

If your system is configured to use the official pre‑built packages for open source NGINX and your installed version is 1.9.11 or later, then you can install nginScript as a pre‑built package for your platform.

  1. Install the pre‑built package.

    • For Ubuntu and Debian systems:

      $ sudo apt-get install nginx-module-njs

    • For RedHat, CentOS, and Oracle Linux systems:

      $ sudo yum install nginx-module-njs

  2. Enable the module by including a load_module directive for it in the top‑level (“main”) context of the nginx.conf configuration file (not in the http or stream context). This example loads the nginScript module for HTTP traffic.

    load_module modules/ngx_http_js_module.so;

  3. Reload NGINX Plus to load the nginScript module into the running instance.

    $ sudo nginx -s reload

Compiling nginScript as a Dynamic Module for Open Source NGINX

Compile the nginScript module from source at the open source repository. Copy the module binary ngx_http_js_module.so to the modules subdirectory of the NGINX root (usually /etc/nginx/modules). Follow the instructions above to configure NGINX and reload.

The post Introduction to nginScript appeared first on NGINX.

Source: Introduction to nginScript

Exit mobile version