Merge pull request #110 from nginx/release-1.32-rewrite

Release 1.32 rewrite news doc

Author: JTorreG

source/news/2024/unit-1.32.0-released.rst

@@ -4,82 +4,67 @@
 Unit 1.32.0 Released
 ####################
 
-Unit 1.31.0 introduced a Technology Preview of a WebAssembly language module
-and an SDK for C and Rust, helping developers build and run web applications
-compiled to Wasm. Although effective, we recognized that a custom low-level
-ABI on the host side and a developer SDK for server-side WebAssembly marked
-not the conclusion, but a significant milestone in our journey.
 
 Unit 1.32.0 comes with a new language module for WebAssembly that supports
 the WASI 0.2 HTTP world so that WebAssembly Components implementing this
-Interface can be hosted on Unit.
+interface can be hosted on Unit.
+
+This new language module improves upon the existing WebAssembly support. We
+recommend all users to use this new implementation for WebAssembly. We consider
+the old **unit-wasm** module deprecated now.
 
 Additionally, we are adding the following features:
 
-- Enhanced the NJS experience by making all Unit variables accessible
-  from JavaScript
+- Enhanced the :doc:`NJS (NGINX JavaScript) experience <../../scripting>` by making all Unit variables
+  accessible from JavaScript
 
-- Added support for conditional access logging
+- Added support for
+  :ref:`conditional access logging <conditional-access-logging-news>`, to help
+  you filter the requests that are logged
 
 - Added support for changing Unit's control socket permissions
 
-- Added a new variable **request_id**
+- Added a :ref:`new variable <configuration-variables>`, **request_id**
 
 ...and much more! Keep reading to learn more about what changed since 1.31.1.
 
-**********************
-Unit is now on GitHub!
-**********************
-
-This release is special! Special for us and the Community! As you may have
-noticed we have moved more and more of our development and planning workloads
-from our old systems to GitHub.
-
-GitHub is no longer just a read-only mirror. It now serves as the primary
-source for our source code and tests. We invite you to create issues,
-contribute through pull requests, or join our discussions. There are
-many ways to get involved with us.
-
-We've also fully transitioned the development and maintenance of unit.nginx.org
-to GitHub. We look forward to pull requests and issues that will improve our
-documentation.
-
 ************************************************************************
-WebAssembly next-level: Support for Wasm components and the WASI 0.2 API
+WebAssembly: Support for Wasm components and the WASI 0.2 API
 ************************************************************************
 
 Since the release of Unit 1.31.0 in August 2023 and the announcement of our
 technology preview for WebAssembly, a lot has changed an happened in the
 WebAssembly ecosystem.
 
 So we evolved and with 1.32.0, we are happy to announce the support for the
-WebAssembly Component Model using the WASI 0.2 APIs. This will open the
+WebAssembly Component Model using the WASI 0.2 APIs. This opens the
 possibilities to run Wasm Components compatible with the WASI 0.2 APIs on Unit
 without having a need to rebuild them. This is also the first Language Module
 for Unit that was driven by the Community. Special thanks to Alex Crichton
 for the contribution!
 
-You can find out more about this in our Blog post: WebAssembly Next-Level:
-Support for Wasm Components
+We are preparing a blog post where we will dive deeper into the details of the
+new WebAssembly language module. Stay tuned!
 
 *******************************************************************
 Enhanced scripting support - Use Unit-variables in NGINX JavaScript
 *******************************************************************
 
 Using JavaScript in Unit's configuration unlocks almost endless opportunities.
 A simple Unit configuration can be used to decide where a request should be
-routed or rewritten to by creating the values for pass and rewrite dynamically
-inside a JavaScript function.
+routed or rewritten to by creating the values for **pass** and **rewrite**
+dynamically inside a JavaScript function.
 
 Previously JavaScript modules had access to a
 :doc:`limited set of objects and scalars <../../scripting>`. Now JavaScript has
 access to all of :ref:`Unit's variables <configuration-variables>` through
 the vars object.
 
-In the following sample configuration, we set the Cache-Control header based on
-the HTTP method. We do this by accessing the method variable as **vars.method**.
-When the method starts with a "P" (POST, PUT, PATCH), we do not want to cache
-the response. For all other methods we set a **max-age** of 3600 seconds.
+In the following sample configuration, we set the **Cache-Control** header
+based on the HTTP method. We do this by accessing the method variable as
+**vars.method**. When the method starts with a "P" (POST, PUT, PATCH),
+we do not want to cache the response. For all other methods we set a **max-age**
+of 3600 seconds.
 
 .. code-block:: json
 
@@ -92,14 +77,60 @@ the response. For all other methods we set a **max-age** of 3600 seconds.
          }
     }
 
+
+.. _conditional-access-logging-news:
+**************************
+Conditional access logging
+**************************
+
+Access logs are a great way to monitor the traffic sent to Unit.
+However, you might find that certain requests, such as regular
+health checks and automated UI tests, aren't ones you want
+cluttering up your logs. While these checks are crucial for monitoring
+the health of your services or web applications, they can significantly
+increase the volume of data in your access logs, leading to unnecessary noise.
+
+With conditional access logging, you can define rules to decide if a request
+should be logged or not.
+
+.. code-block:: json
+
+    {
+        "access_log": {
+            "if": "`${uri == '/health' ? false : true}`",
+            "path": "/var/log/unit/access.log",
+            "format": "`${host + ': ' + uri}`"
+        }
+    }
+
+In this example we don't want to log any health checks sent to Unit.
+As shown in our example, to get the maximum out of the newly added **if**
+option, you can combine it with our JavaScript scripting feature, but this
+is not a must.
+
+The **if** option also supports simple string validation to check if a value
+is present in a request or not.
+
+.. code-block:: json
+
+    {
+        "access_log": {
+            "if": "$cookie_session",
+            "path": "…"
+        }
+    }
+
+In this example Unit will check the existence of a Cookie named session
+and only log requests when it exists.
+
 ****************
 CLI enhancements
 ****************
 
 The **unitc** command line tool is a convenient way of applying and editing Unit
 configuration without constructing lengthy **curl(1)** commands or knowing where
 the control socket is located. Unit 1.32.0 includes two useful enhancements to
-**unitc** that, included in the official packages.
+**unitc** that are included in the official packages.
 
 A Docker container ID can now be specified as the configuration target.
 To access the configuration of a local Unit container, use the **docker://**
@@ -135,59 +166,49 @@ statistics from a Docker container:
 Note that the `yq(1) <https://github.com/mikefarah/yq#install>`__ tool is required
 for YAML format conversion.
 
-**************************
-Conditional access logging
-**************************
-
-Access logs are a great way to monitor the traffic sent to Unit.
-However, you might find that certain requests, such as regular
-health checks and automated UI tests, aren't ones you want
-cluttering up your logs. While these checks are crucial for monitoring
-the health of your services or web applications, they can significantly
-increase the volume of data in your access logs, leading to unnecessary noise.
-
-With conditional access logging, you can define rules to decide if a request
-should be logged or not.
-
-.. code-block:: json
 
-    {
-        "access_log": {
-            "if": "`${uri == '/health' ? false : true}`",
-            "path": "/var/log/unit/access.log",
-            "format": "`${host + ': ' + uri}`"
-        }
-    }
+**********************
+Unit is now on GitHub!
+**********************
 
-In this example we don't want to log any health checks sent to Unit.
-Anything will be logged to the given file in the defined format as usual.
-As shown in our example, to get the maximum out of the newly added **if**
-option, you can combine it with our JavaScript scripting feature, but this
-is not a must.
+This release is special! Special for us and the Community! As you may have
+noticed we have moved more and more of our development and planning workloads
+from our old systems to `GitHub <https://github.com/nginx/unit/>`__.
 
-The **if** option also supports simple string validation to check if a value
-is present in a request or not.
+GitHub is no longer just a read-only mirror. It now serves as the primary
+source for our source code and tests. We invite you to create
+`issues <https://github.com/nginx/unit/issues>`__, contribute through
+`pull requests <https://github.com/nginx/unit/pulls>`__, or join our
+`discussions <https://github.com/nginx/unit/discussions>`__. There are many
+ways to get involved with us.
 
-.. code-block:: json
+We've also fully transitioned the development and maintenance of unit.nginx.org
+to the `Github unit-docs <https://github.com/nginx/unit-docs/>`__ repository.
+We look forward to pull requests and issues that will improve our documentation.
 
-    {
-        "access_log": {
-            "if": "$cookie_session",
-            "path": "…"
-        }
-    }
+*************************************
+Changes in behavior and other updates
+*************************************
 
-In this example Unit will check the existence of a Cookie named session
-and only log request including this cookie.
+==========================================================================
+Docker image uses **stderr**, so now you can send **access_log** to stdout
+==========================================================================
 
+With 1.32.0 the **unit.log** file is symlinked to the container's
+**/dev/stderr** instead of **/dev/stdout**. This leaves room for the
+*access_log* to be redirected to **/dev/stdout** and will not populate
+the Unit log messages to **stdout** which might be scraped by log collectors.
 
+=======================================================
+unit.nginx.org/download/ is now sources.nginx.org/unit/
+=======================================================
 
-*************************************
-Changes in behavior and other updates
-*************************************
+We have moved the location of the Unit tarballs from "unit.nginx.org/download/"
+to a new, central source archive for NGINX:
+`sources.nginx.org/unit/ <https://sources.nginx.org/unit/>`__.
 
-- Docker image uses **stderr** (was **stdout**) so now you can send **access_log** to stdout.
-- Node JS Language Module enhancements
+The old link is currently proxying to the new location, but officially
+deprecated now! Please update to the new location "sources.nginx.org/unit/".
 
 ************
 Wall of fame
@@ -204,4 +225,62 @@ making Unit better! With 1.32.0 we would like to send a shout out to:
 - Dean Coakley
 - rustedsword
 - Hippolyte Pello
-- Javier Evans
+- Javier Evans
+
+**************
+Full Changelog
+**************
+
+.. code-block:: none
+
+  Changes with Unit 1.32.0                                         27 Feb 2024
+
+    *) Feature: WebAssembly Components using WASI interfaces defined in
+       wasi:http/proxy@0.2.0.
+
+    *) Feature: conditional access logging.
+
+    *) Feature: NJS variables access.
+
+    *) Feature: $request_id variable contains a string that is formed using
+       random data and can be used as a unique request identifier.
+
+    *) Feature: options to set control socket permissions.
+
+    *) Feature: Ruby arrays in response headers, improving compatibility
+       with Rack v3.0.
+
+    *) Feature: Python bytearray response bodies for ASGI applications.
+
+    *) Bugfix: router could crash while sending large files. Thanks to
+       rustedsword.
+
+    *) Bugfix: serving static files from a network filesystem could lead to
+       error.
+
+    *) Bugfix: "uidmap" and "gidmap" isolation options validation.
+
+    *) Bugfix: abstract UNIX socket name could be corrupted during
+       configuration validation. Thanks to Alejandro Colomar.
+
+    *) Bugfix: HTTP header field value encoding could be misinterpreted in
+       Python module.
+
+    *) Bugfix: Node.js http.createServer() accepts and ignores the "options"
+       argument, improving compatibility with strapi applications, among
+       others.
+
+    *) Bugfix: ServerRequest.flushHeaders() implemented in Node.js module to
+       make it compatible with Next.js.
+
+    *) Bugfix: ServerRequest.httpVersion variable format in Node.js module.
+
+    *) Bugfix: Node.js module handles standard library imports prefixed with
+       "node:", making it possible to run newer Nuxt applications, among
+       others.
+
+    *) Bugfix: Node.js tarball location changed to avoid build/install
+       errors.
+
+    *) Bugfix: Go module sets environment variables necessary for building
+       on macOS/arm64 systems.