passenger 6.1.8 → 6.2.1

data/build/support/general.rb

@@ -1,5 +1,5 @@
 #  Phusion Passenger - https://www.phusionpassenger.com/
-#  Copyright (c) 2010-2025 Asynchronous B.V.
+#  Copyright (c) 2010-2026 Asynchronous B.V.
 #
 #  "Passenger", "Phusion Passenger" and "Union Station" are registered
 #  trademarks of Asynchronous B.V.

data/build/support/vendor/cxx_hinted_parser/LICENSE.md

@@ -1,4 +1,4 @@
-Copyright (c) 2016-2025 Asynchronous B.V.
+Copyright (c) 2016-2026 Asynchronous B.V.
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

data/build/support/vendor/cxx_hinted_parser/lib/cxx_hinted_parser/parser.rb

@@ -1,6 +1,6 @@
 # encoding: binary
 
-#  Copyright (c) 2016-2025 Asynchronous B.V.
+#  Copyright (c) 2016-2026 Asynchronous B.V.
 #
 #  "Union Station" and "Passenger" are trademarks of Asynchronous B.V.
 #
@@ -25,6 +25,7 @@
 require 'strscan'
 
 module CxxHintedParser
+
   class Parser
     STRUCT_BEGIN_HINT = /- ?begin hinted parseable (struct|class) ?-/
     STRUCT_END_HINT = /- ?end hinted parseable (struct|class) ?-/
@@ -236,4 +237,5 @@ module CxxHintedParser
       @errors << Error.new(line, column, message)
     end
   end
+
 end

data/build/support/vendor/cxx_hinted_parser/lib/cxx_hinted_parser.rb

@@ -1,4 +1,4 @@
-#  Copyright (c) 2016-2025 Asynchronous B.V.
+#  Copyright (c) 2016-2026 Asynchronous B.V.
 #
 #  "Union Station" and "Passenger" are trademarks of Asynchronous B.V.
 #

data/build/support/vendor/cxxcodebuilder/LICENSE.md

@@ -1,4 +1,4 @@
-Copyright (c) 2016-2025 Asynchronous B.V.
+Copyright (c) 2016-2026 Asynchronous B.V.
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

data/build/support/vendor/cxxcodebuilder/lib/cxxcodebuilder/builder.rb

@@ -1,6 +1,6 @@
 # encoding: utf-8
 
-#  Copyright (c) 2016-2025 Asynchronous B.V.
+#  Copyright (c) 2016-2026 Asynchronous B.V.
 #
 #  "Union Station" and "Passenger" are trademarks of Asynchronous B.V.
 #
@@ -25,6 +25,7 @@
 require File.expand_path(File.dirname(__FILE__) + '/initializer_builder')
 
 module CxxCodeBuilder
+
   # Builds C/C++ code. Use it as follows:
   #
   #  1. Create a CxxCodeBuilder::Builder object.
@@ -627,4 +628,5 @@ module CxxCodeBuilder
       str
     end
   end
+
 end

data/build/support/vendor/cxxcodebuilder/lib/cxxcodebuilder/initializer_builder.rb

@@ -1,6 +1,6 @@
 # encoding: utf-8
 
-#  Copyright (c) 2016-2025 Asynchronous B.V.
+#  Copyright (c) 2016-2026 Asynchronous B.V.
 #
 #  "Union Station" and "Passenger" are trademarks of Asynchronous B.V.
 #
@@ -23,6 +23,7 @@
 #  THE SOFTWARE.
 
 module CxxCodeBuilder
+
   # Builds array and struct initialization code.
   class InitializerBuilder
     def initialize(builder, start_character, end_character)
@@ -163,4 +164,5 @@ module CxxCodeBuilder
       @builder.add_code_without_newline(@end_character)
     end
   end
+
 end

data/build/support/vendor/cxxcodebuilder/lib/cxxcodebuilder.rb

@@ -1,4 +1,4 @@
-#  Copyright (c) 2016-2025 Asynchronous B.V.
+#  Copyright (c) 2016-2026 Asynchronous B.V.
 #
 #  "Union Station" and "Passenger" are trademarks of Asynchronous B.V.
 #

data/build/test_basics.rb

@@ -1,5 +1,5 @@
 #  Phusion Passenger - https://www.phusionpassenger.com/
-#  Copyright (c) 2010-2025 Asynchronous B.V.
+#  Copyright (c) 2010-2026 Asynchronous B.V.
 #
 #  "Passenger", "Phusion Passenger" and "Union Station" are registered
 #  trademarks of Asynchronous B.V.

data/dev/copy_boost_headers

@@ -1,6 +1,6 @@
 #!/usr/bin/env ruby
 #  Phusion Passenger - https://www.phusionpassenger.com/
-#  Copyright (c) 2010-2025 Asynchronous B.V.
+#  Copyright (c) 2010-2026 Asynchronous B.V.
 #
 #  "Passenger", "Phusion Passenger" and "Union Station" are registered
 #  trademarks of Asynchronous B.V.

data/dev/index_cxx_dependencies.rb

@@ -1,5 +1,6 @@
 #!/usr/bin/env ruby
 require 'pp'
+require 'stringio'
 
 SEARCH_PATHS = [
   "src",
@@ -221,6 +222,9 @@ def generate_full_map(basic_map)
 end
 
 result = generate_full_map(generate_basic_map)
-puts "# Autogenerated by dev/index_cxx_dependencies.rb"
+puts "# Autogenerated by dev/index_cxx_dependencies.rb (update with `rake dependency_map`)"
 puts "CXX_DEPENDENCY_MAP ="
-PP.pp(result, STDOUT, 1)
+
+output = StringIO.new
+PP.pp(result, output, 1)
+puts output.string.gsub(/ =>\n/m, "=>\n")

data/dev/libev-changes.patch

@@ -0,0 +1,108 @@
+From 4fb0fa52b2ad4d5cc1263c15d41f272ec142864b Mon Sep 17 00:00:00 2001
+From: Camden Narzt <c.narzt@me.com>
+Date: Sun, 23 Aug 2026 16:27:02 -0600
+Subject: [PATCH] changes
+
+---
+ ev++.h |  4 ++--
+ ev.c   | 18 +++++++++++++++++-
+ ev.h   |  9 ++++++---
+ 3 files changed, 25 insertions(+), 6 deletions(-)
+
+diff --git a/ev++.h b/ev++.h
+index 22dfcf5..f445fbc 100644
+--- a/ev++.h
++++ b/ev++.h
+@@ -570,12 +570,12 @@ namespace ev {
+     return ev_embeddable_backends ();
+   }
+ 
+-  inline void set_allocator (void *(*cb)(void *ptr, long size) EV_NOEXCEPT) EV_NOEXCEPT
++  inline void set_allocator (void *(*cb)(void *ptr, long size)) EV_NOEXCEPT
+   {
+     ev_set_allocator (cb);
+   }
+ 
+-  inline void set_syserr_cb (void (*cb)(const char *msg) EV_NOEXCEPT) EV_NOEXCEPT
++  inline void set_syserr_cb (void (*cb)(const char *msg)) EV_NOEXCEPT
+   {
+     ev_set_syserr_cb (cb);
+   }
+diff --git a/ev.c b/ev.c
+index ec212a1..9c697cb 100644
+--- a/ev.c
++++ b/ev.c
+@@ -507,7 +507,11 @@
+ #endif
+ 
+ #if EV_USE_INOTIFY
+-# include <sys/statfs.h>
++# ifdef __FreeBSD__
++#  include <sys/mount.h>
++# else
++#  include <sys/statfs.h>
++# endif
+ # include <sys/inotify.h>
+ /* some very old inotify.h headers don't have IN_DONT_FOLLOW */
+ # ifndef IN_DONT_FOLLOW
+@@ -3196,6 +3200,18 @@ ev_backend (EV_P) EV_NOEXCEPT
+   return backend;
+ }
+ 
++int
++ev_backend_fd (EV_P) EV_THROW
++{
++  return backend_fd;
++}
++
++int
++ev_loop_get_pipe (EV_P_ unsigned int index) EV_THROW
++{
++  return evpipe[index];
++}
++
+ #if EV_FEATURE_API
+ unsigned int
+ ev_iteration (EV_P) EV_NOEXCEPT
+diff --git a/ev.h b/ev.h
+index 4669c39..2384093 100644
+--- a/ev.h
++++ b/ev.h
+@@ -545,13 +545,13 @@ EV_API_DECL void ev_sleep (ev_tstamp delay) EV_NOEXCEPT; /* sleep for a while */
+  * or take some potentially destructive action.
+  * The default is your system realloc function.
+  */
+-EV_API_DECL void ev_set_allocator (void *(*cb)(void *ptr, long size) EV_NOEXCEPT) EV_NOEXCEPT;
++EV_API_DECL void ev_set_allocator (void *(*cb)(void *ptr, long size)) EV_NOEXCEPT;
+ 
+ /* set the callback function to call on a
+  * retryable syscall error
+  * (such as failed select, poll, epoll_wait)
+  */
+-EV_API_DECL void ev_set_syserr_cb (void (*cb)(const char *msg) EV_NOEXCEPT) EV_NOEXCEPT;
++EV_API_DECL void ev_set_syserr_cb (void (*cb)(const char *msg)) EV_NOEXCEPT;
+ 
+ #if EV_MULTIPLICITY
+ 
+@@ -616,6 +616,9 @@ EV_API_DECL unsigned int ev_backend (EV_P) EV_NOEXCEPT; /* backend in use by loo
+ 
+ EV_API_DECL void ev_now_update (EV_P) EV_NOEXCEPT; /* update event loop time */
+ 
++EV_API_DECL int ev_backend_fd (EV_P) EV_THROW;
++EV_API_DECL int ev_loop_get_pipe (EV_P_ unsigned int index) EV_THROW;
++
+ #if EV_WALK_ENABLE
+ /* walk (almost) all watchers in the loop of a given type, invoking the */
+ /* callback on every such watcher. The callback might stop the watcher, */
+@@ -672,7 +675,7 @@ EV_API_DECL void *ev_userdata (EV_P) EV_NOEXCEPT;
+ typedef void (*ev_loop_callback)(EV_P);
+ EV_API_DECL void ev_set_invoke_pending_cb (EV_P_ ev_loop_callback invoke_pending_cb) EV_NOEXCEPT;
+ /* C++ doesn't allow the use of the ev_loop_callback typedef here, so we need to spell it out */
+-EV_API_DECL void ev_set_loop_release_cb (EV_P_ void (*release)(EV_P) EV_NOEXCEPT, void (*acquire)(EV_P) EV_NOEXCEPT) EV_NOEXCEPT;
++EV_API_DECL void ev_set_loop_release_cb (EV_P_ void (*release)(EV_P), void (*acquire)(EV_P)) EV_NOEXCEPT;
+ 
+ EV_API_DECL unsigned int ev_pending_count (EV_P) EV_NOEXCEPT; /* number of pending events, if any */
+ 
+-- 
+2.50.1 (Apple Git-155)
+

data/dev/nginx_version_sha256

@@ -1,6 +1,6 @@
 #!/usr/bin/env ruby
 #  Phusion Passenger - https://www.phusionpassenger.com/
-#  Copyright (c) 2024-2025 Asynchronous B.V.
+#  Copyright (c) 2024-2026 Asynchronous B.V.
 #
 #  "Passenger", "Phusion Passenger" and "Union Station" are registered
 #  trademarks of Asynchronous B.V.

data/dev/ruby_server.rb

@@ -135,12 +135,7 @@ private
   def handle_next_client(forward_connection)
     client = @server.accept
     begin
-      if Gem::Version.new(RUBY_VERSION) >= Gem::Version.new('2.3.0')
-        buffer = String.new(encoding: Encoding::BINARY)
-      else
-        buffer = ""
-        buffer.force_encoding('binary') if buffer.respond_to?(:force_encoding)
-      end
+      buffer = "".b
       while true
         begin
           read_header(client, buffer)

data/dev/runner

@@ -29,5 +29,7 @@ while true
 end
 
 module PhusionPassenger
+
   p eval(ARGV.join(" "))
+
 end

data/dev/upgrading_libuv.sh

@@ -0,0 +1,16 @@
+#!/usr/bin/env bash
+set -x
+VERSION=1.49.2
+#apt update && apt install -y build-essential curl libtool autoconf
+rm -rf src/cxx_supportlib/vendor-copy/libuv
+curl -sSL "https://dist.libuv.org/dist/v${VERSION}/libuv-v${VERSION}.tar.gz" | tar -C src/cxx_supportlib/vendor-copy/ -xz
+mv src/cxx_supportlib/vendor-copy/libuv-* src/cxx_supportlib/vendor-copy/libuv
+cd src/cxx_supportlib/vendor-copy/libuv || exit 1
+if [ "$(uname)" = Darwin ]; then
+sed -e 's/AC_CONFIG_LINKS(\[test/# &/g' -i '' configure.ac
+else
+sed -e 's/AC_CONFIG_LINKS(\[test/# &/g' -i'' configure.ac
+fi
+./autogen.sh
+rm -rf test docs img tools .github CMakeLists.txt cmake-toolchains src/win autogen.sh .readthedocs.yaml .mailmap
+find . \( -name '*.md' -o -name '.git*' \) -delete

data/doc/BasicArchitectureOverview.md

@@ -0,0 +1,55 @@
+# Basic architecture overview
+
+## Multi-process
+
+- Web server (Apache or Nginx, both with the Passenger module loaded). Only simple I/O processing and lifecycle management of the Passenger Watchdog Agent.
+- PassengerAgent: single binary w/ multiple personalities. Most important:
+  - Watchdog: spawns and supervises Core Agent and a bunch of other periodic helper tasks.
+  - Core: most logic happens here. Main request processing (Controller), spawns (SpawningKit) and supervises (ApplicationPool) application processes, keeps track of various statistics. Has an API server (separate socket) for management operations (used by e.g. `passenger-status`).
+
+### HTTP request flow
+
+1. Requests are commonly first received by the web server, which forwards request to Passenger Core (via its Unix domain socket in the instance directory). Core's Controller subsystem then processes it.
+2. Requests may also be directly received by Passenger Core (Passenger Standalone + "builtin" engine).
+3. Passenger Core's Controller subsystem uses ApplicationPool to determine whether to spawn an application process or which process to route request to. Connects to the app's Unix domain socket (also located in the instance directory) or reuses keepalive socket.
+4. Response from app forwarded back to the connecting client (could be a real client or the web server).
+
+### Applcation processes lifecycle management and request routing
+
+- Main logic in ApplicationPool (src/agent/Core/ApplicationPool). Keeps track of which application Processes exist. Contains logic for routing a request to best Process.
+- Pool has many Groups. Group has many Processes (for application processes). Process has many Sockets (of which one is the "main socket" for receiving requests).
+- Spawning logic outsourced to SpawningKit.
+
+## C++ tech stack
+
+- Agent written in C++
+- C++14
+- Boost. But prefer C++14
+
+### HTTP and non-blocking I/O handling
+
+- ServerKit (src/cxx_supportlib/ServerKit)
+- libev
+- Some parts use libuv. Integrates with libev via SafeLibev.h
+
+## Important directories
+
+- src: most source code
+- src/agent: various agents
+- src/agent/Core
+- src/agent/Watchdog
+- src/nginx_module
+- src/apache2_module
+- src/cxx_supportlib: C++ support library
+- src/ruby_supportlib: Ruby parts of passenger: Passenger Standalone, Passenger Config, admin tool helpers, shared Ruby app loading code, generic utilities
+- src/helper-scripts: various helper scripts, including SpawningKit language-specific (pre)loaders.
+- bin: user-invocable executables (CLI tools)
+- build: build system
+- test: unit and integration tests
+- dev: scripts used during development and CI, not used during runtime
+- resources: non-executable resources, used during runtime
+- packaging: Debian/RPM/Homebrew packaging automation
+
+## See also
+
+An older [Design & Architecture](https://www.phusionpassenger.com/documentation/Design%20and%20Architecture.html) document.

data/doc/BuildCaching.md

@@ -0,0 +1,23 @@
+## Build caching (ccache)
+
+Set this environment variable to make our build system prefix all compiler invocations with [ccache](https://ccache.dev/):
+
+```bash
+export USE_CCACHE=1
+```
+
+You also need:
+
+```bash
+# Required for caching test files (involves precompiled headers)
+export CCACHE_SLOPPINESS=pch_defines,time_macros
+```
+
+When using multiple worktrees, configure cache sharing:
+
+```bash
+export CCACHE_BASEDIR=<full path to common parent directory of the worktrees>
+# Prevent debug info from distinguishing between worktrees
+export EXTRA_CFLAGS=-fdebug-prefix-map="$PWD"=.
+export EXTRA_CXXFLAGS=-fdebug-prefix-map="$PWD"=.
+```

data/doc/BuildSystem.md

@@ -0,0 +1,49 @@
+# Build system
+
+Our build system is [Rake](https://github.com/ruby/rake). Its functionality is similar to Make, but its DSL is in Ruby. `passenger-install-apache2-module` and `passenger-install-nginx-module` call Rake to compile things.
+
+## Key Rake targets
+
+- `rake apache2` — compiles the Apache 2 module, and other parts needed by the Apache integration mode (e.g., the Passenger agent binary).
+- `rake nginx` — compiles parts needed by the Nginx integration mode (e.g., agent binary). Does *not* compile the Nginx module.
+- For test suite targets, see [Running tests](RunningTests.md).
+
+See more with `rake -T`.
+
+## Concurrent compilation
+
+Run `rake -m -j<NUMBER>` for concurrent compilation. `<NUMBER>` should equal the number of CPU cores.
+
+## Environment variables
+
+You can pass environment variables via CLI arguments. These are equivalent:
+
+```bash
+rake something FOO=123
+
+export FOO=123 && rake something
+```
+
+You can persist environment variables in `config.rb`. This file is automatically loaded by Rake.
+
+```ruby
+# config.rb
+ENV['FOO'] = '123'
+```
+
+## Customization
+
+Customize the build system with environment variables. Boolean options can be set to true, false, 0 or 1.
+
+- `OUTPUT_DIR`: where build output is placed. Default: `buildout/`
+- `EXTRA_PRE_CFLAGS` and `EXTRA_CFLAGS`: insert additional flags to C compiler invocations. One for before our own flags, one for after. Does not cover linking invocations.
+- `EXTRA_PRE_CXXFLAGS` and `EXTRA_CXXFLAGS`: ditto, but for C++ compiler invocations.
+- `EXTRA_PRE_LDFLAGS` and `EXTRA_LDFLAGS`: insert additional flags to C/C++ compiler linking invocations. One for before our own flags, one for after.
+- `EXTRA_PRE_C_LDFLAGS` and `EXTRA_C_LDFLAGS`: ditto, but only applies to C compiler linking invocations.
+- `EXTRA_PRE_CXX_LDFLAGS` and `EXTRA_CXX_LDFLAGS`: ditto, but only applies to C++ compiler linking invocations.
+- `USE_CCACHE=<bool>` (default: false): wrap compiler invocations in ccache. See also [ccache setup instructions](DevEnvironmentSetup.md#build-caching).
+- `USE_ASAN=<bool>` (default: false): compile with AddressSanitizer.
+- `USE_UBSAN=<bool>` (default: false): compile with UndefinedBehaviorSanitizer.
+- `OPTIMIZE=<bool>` (default: false): compile with optimizations.
+- `USE_VENDORED_LIBEV=<bool>` (default: true): set to false to compile with system-provided libev instead of our vendored one.
+- `USE_VENDORED_LIBUV=<bool>` (default: true): set to false to compile with system-provided libuv instead of our vendored one.

data/doc/DebuggingAndStressTesting.md

@@ -45,6 +45,8 @@ Increase PassengerLogLevel to print more debugging messages.
 
 Recompile Phusion Passenger with the environment variable `USE_ASAN=1` to enable support for AddressSanitizer.
 
+On GCC, you should set the environment variable `ASAN_OPTIONS=detect_stack_use_after_return=1` too when running binaries.
+
 ## Simulating system call failures
 
 Error conditions are sometimes hard to test. Things like network errors are usually hard to simulate using real equipment. In order to facilitate with error testing, we've developed a system call failure simulation framework, inspired by sqlite's failure test suite. You specify which system call errors should be simulated, and with what probability they should occur. By running normal tests multiple times you can see how Phusion Passenger behaves under these simulated error conditions.

data/doc/DesignAspects/LimitedGemDependencies.md

@@ -40,6 +40,7 @@ We pick strategy 1.
 - **Code with broad version compatibility**: Since we can't rely on specific gem versions, we must use gems in a way that's compatible with a wide number of gem versions.
 - **Development code can YOLO with gem dependencies**: Development-related Passenger Ruby code can depend on any gem, since development code is not included in native packages.
   - All such dependencies must be specified in the Passenger Gemfile.
+  - Note: the build system (Rakefile) does not count as "development-related Ruby code" because it's used outside just development. For example `passenger-install-XXX-module` calls Rake to compile things.
 
 ## See also
 

data/doc/DevEnvironmentSetup.md

@@ -0,0 +1,46 @@
+# Development environment setup
+
+## Basic requirements
+
+- A C/C++ compiler toolchain
+  - Ubuntu: `apt install build-essential`
+- Ruby, including development headers
+  - Ubuntu: `apt install ruby ruby-dev`
+- For working on Node.js support: Node.js and NPM
+  - Ubuntu: `apt install nodejs`
+- For working on the Apache module: Apache and its development headers
+  - Ubuntu: `apt install apache2 apache2-dev`
+- For working on the Nginx module: Nginx and its source code
+  - Ubuntu: `apt install nginx-dev` (sources end up in /usr/share/nginx/src)
+
+## Setup test suites
+
+Install the testing dependencies:
+
+- `bundle install`
+- To run the Node.js test suite: `npm install`
+
+Configure the C++ unit test suite:
+
+- Create `test/config.json` (see the `.example` file)
+
+## C++ development tooling recommendations
+
+## Clangd support
+
+[Clangd](https://clangd.llvm.org/) is great for IDE/editor auto-complete and symbol navigation.
+
+Use [bear](https://github.com/rizsotto/bear) to generate `compile_commands.json` once:
+
+```bash
+bear -- rake -m -j4 nginx apache2 test:cxx:build buildout/test/oxt/main
+```
+
+## Build caching (ccache)
+
+See [separate document](BuildCaching.md).
+
+## C++ debugging
+
+- If using gdb to debug the C++ test suite: create `test/.gdbinit` (see `test/gdbinit.example`).
+- When using Visual Studio Code, we recommend the [CodeLLDB](https://marketplace.visualstudio.com/items?itemName=vadimcn.vscode-lldb) extension.

data/doc/DevHandbook.md

@@ -0,0 +1,28 @@
+# Passenger development handbook
+
+## Fundamentals
+
+- [Basic architecture overview](BasicArchitectureOverview.md)
+- [Development environment setup](DevEnvironmentSetup.md) — Prerequisites for C++, Ruby, Node.js, Apache, and Nginx work; test setup; clangd, ccache, and debugger configuration.
+- [Build system](BuildSystem.md) — How it works, how to compile various parts of Passenger. Rake targets for Apache and Nginx integration, output and compiler/linker settings, sanitizers, optimization, and vendored libev/libuv controls. Recommended Rake flags for concurrent building. Instructions for persisting dev-time environment variables (loaded by Rake).
+  - [Build caching](BuildCaching.md) — ccache setup.
+- [Running tests](RunningTests.md) — Ruby, Node.js, C++/oxt, integration, and packaging test suites; selecting C++ groups or test numbers; debugger and Valgrind support; and root-only tests; safely running test suites directly (bypassing Rake); example test suite outputs.
+- [Writing C++ tests](WritingCxxTests.md) — How C++ tests are structured; how our testing framework (forked tut) works; available assertions.
+  - [C++ mocking strategy](CxxMockingStrategy.md)
+
+## Best practices
+
+- [Coding tips and common pitfalls](CodingTipsAndPitfalls.md) — C++ object-lifetime and event-loop hazards involving `shared_ptr`, callbacks, exceptions, and thread-interruption-safe RAII destructors.
+- [Secure handling of temp files](SecureTempFileHandling.md) — Preventing symlink, file-squatting, and TOCTOU attacks through unpredictable names, atomic reservation, restrictive permissions, `mkstemp()`, and `mkdtemp()`.
+
+## Design decisions & aspects
+
+- [Limited gem dependencies](DesignAspects/LimitedGemDependencies.md) — Runtime Ruby dependency policy for gem and native-package installs, multiple Ruby versions, execution with or without Bundler, OS repository availability, and gemspec versus Gemfile placement.
+- [No gem activation during Ruby loader initialization](DesignAspects/NoGemActivationDuringRubyLoaderInitialization.md) — No-activation rule for code called before Bundler by the Ruby loaders, including gemified standard-library code and Ruby/C++ reimplementation strategies.
+
+## Subsystems in C++
+
+- [ConfigKit](../src/cxx_supportlib/ConfigKit/README.md) — Core JSON configuration API covering runtime-introspectable schemas and stores, defaults, nested schemas, validation, normalization, updates, inspection, and secret filtering.
+    - [ConfigKit practical usage & design patterns](../src/cxx_supportlib/ConfigKit/IN_PRACTICE.md) — Configurable-component patterns covering config realizations, subclassing and composition, translators, atomic prepare/commit with infallible commit, asynchronous event-loop wrappers, and concurrency serialization.
+- [SpawningKit](../src/agent/Core/SpawningKit/README.md) — Reliably starting web application worker/preloader processes: spawn methods (direct/smart), wrappers/start commands, process environment and privilege setup, startup handshakes/readiness checks, timeouts, and detailed spawn-failure diagnostics.
+- [Wrapper registry](../src/cxx_supportlib/WrapperRegistry/README.md) — Registry of supported application types and language wrappers: maps app type names/aliases to wrapper loader, interpreter, process title, and startup-file signatures used by application autodetection and spawning.

data/doc/Packaging.md

@@ -50,7 +50,7 @@ version).
 In this configuration, files can be scattered anywhere throughout the filesystem. This
 way Phusion Passenger can be packaged in an FHS-compliant way. The exact locations
 of the different types of files can be specified through a
-_location configuration file_. The existance and usage of a location configuration
+_location configuration file_. The existence and usage of a location configuration
 file does not automatically imply that Phusion Passenger is natively packaged.
 
 If Phusion Passenger needs to have a new Ruby extension compiled, then it will

data/doc/RunningTests.md

@@ -0,0 +1,88 @@
+# Running tests
+
+All Rake commands also compile whatever is necessary.
+
+Common test suites:
+
+- `rake test:ruby` — Ruby support unit tests
+- `rake test:node` — Node.js support unit tests
+- `rake test:cxx` and `rake test:oxt` — C++ unit tests (requires `test/config.json`, see [Development environment setup](DevEnvironmentSetup.md)). See also [Advanced C++ test suite usage](#advanced-c-test-suite-usage).
+- `rake test:integration:apache2` — Apache 2 integration tests
+- `rake test:integration:nginx` — Nginx integration tests
+- `rake test:integration:standalone` — Passenger Standalone integration tests
+
+Packaging-specific test suites:
+
+- `rake test:integration:native_packaging` — run from Debian and RPM packaging automation.
+- `rake test:source_packaging` — run from gem and source tarball packaging automation.
+
+> [!NOTE]
+> Some tests, such as the ones about privilege lowering, require root. Those will only be run if Rake is run as root. For running `test:cxx` in root specifically, use `SUDO=1` (see below).
+
+> [!NOTE]
+> When choosing to bypass Rake, ensure running tests from `test/`.
+
+## Apache 2 integration test suite usage
+
+To run specific tests, use either the `E` or `LOC` environment variables:
+
+```bash
+# Match on test name. Passed to `rspec -e`
+rake test:integration:apache2 E="doesn't use page caching if the HTTP request is not GET"
+
+# Match on file name and line numbers. Passed to `rspec`. Note: filename is relative to `test/`
+rake test:integration:apache2 "./integration_tests/apache2_tests.rb[1:3:5]"
+```
+
+## Advanced C++ test suite usage
+
+The `test:cxx` unit test suite contains many different test groups. To run a specific one, set the environment variable `GROUPS` to a comma-delimited list of group names:
+
+```bash
+rake test:cxx GROUPS='ApplicationPool2_PoolTest,UtilsTest'
+```
+
+To run specific tests within a suite., pass the relevant test number(s):
+
+```bash
+rake test:cxx GROUPS='ApplicationPool2_PoolTest:82,83'
+```
+
+To run them in GDB, LLDB or Valgrind:
+
+```bash
+rake test:cxx GDB=1
+rake test:cxx LLDB=1
+rake test:cxx VALGRIND=1
+```
+
+> [!TIP]
+> See [Development environment setup](DevEnvironmentSetup.md) for setting up our recommended GDB config file.
+
+Some tests, such as the ones about privilege lowering, require root. To run compilation commands as a normal user, and only the test suite as root:
+
+```bash
+rake test:cxx SUDO=1
+```
+
+## Example `test:cxx` output
+
+Output format is modified from the original Tut test framework.
+
+```
+SystemTools_ProcessMetricsCollectorTest:
+  1... ✔
+  2... ✔
+  3... ✗
+  4... skipped
+
+VariantMapTest:
+  1... ✔
+  8... skipped
+
+---> group: SystemTools_ProcessMetricsCollectorTest, test: test<3>
+     problem: assertion failed
+     failed assertion: "PSS is correct"
+
+tests summary: failures:1 ok:851
+```

data/doc/{TempFileHandling.md → SecureTempFileHandling.md}

@@ -1,4 +1,4 @@
-# Handling of temp files
+# Secure handling of temp files
 
 Always use unpredictable filenames for temp files. Failing to do so makes us vulnerable to symlink attacks, TOCTOU race conditions, file squatting, or even information disclosure and privilege escalation.
 

data/doc/{CxxTestingGuide.md → WritingCxxTests.md}

@@ -1,4 +1,4 @@
-# C++ testing guide
+# Writing C++ tests
 
 C++ tests use a modified version of the [Tut test framework](https://mrzechonek.github.io/tut-framework/).
 
@@ -89,22 +89,3 @@ namespace tut {
 ## Mocking
 
 See [C++ mocking strategy](CxxMockingStrategy.md).
-
-## Running tests
-
-Prerequisite: ensure `test/config.json` exists. Refer to its `.example` file.
-
-```bash
-# Run all test suites
-rake test:cxx GROUPS=SomethingTest
-
-# Run specific test suites
-rake test:cxx GROUPS=SomethingTest,AnotherTest
-
-# Run specific tests by number
-rake test:cxx GROUPS=SomethingTest:1,3
-
-# Attach to GDB or LLDB
-rake test:cxx GROUPS=SomethingTest GDB=1
-rake test:cxx GROUPS=SomethingTest LLDB=1
-```