passenger 6.0.14 → 6.0.27

data/build/support/general.rb

@@ -1,8 +1,8 @@
 #  Phusion Passenger - https://www.phusionpassenger.com/
-#  Copyright (c) 2010-2017 Phusion Holding B.V.
+#  Copyright (c) 2010-2025 Asynchronous B.V.
 #
 #  "Passenger", "Phusion Passenger" and "Union Station" are registered
-#  trademarks of Phusion Holding B.V.
+#  trademarks of 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/LICENSE.md

@@ -1,4 +1,4 @@
-Copyright (c) 2016 Phusion Holding B.V.
+Copyright (c) 2016-2025 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,8 +1,8 @@
 # encoding: binary
 
-#  Copyright (c) 2016 Phusion Holding B.V.
+#  Copyright (c) 2016-2025 Asynchronous B.V.
 #
-#  "Union Station" and "Passenger" are trademarks of Phusion Holding B.V.
+#  "Union Station" and "Passenger" are trademarks of 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.rb

@@ -1,6 +1,6 @@
-#  Copyright (c) 2016 Phusion Holding B.V.
+#  Copyright (c) 2016-2025 Asynchronous B.V.
 #
-#  "Union Station" and "Passenger" are trademarks of Phusion Holding B.V.
+#  "Union Station" and "Passenger" are trademarks of 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/LICENSE.md

@@ -1,4 +1,4 @@
-Copyright (c) 2016 Phusion Holding B.V.
+Copyright (c) 2016-2025 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,8 +1,8 @@
 # encoding: utf-8
 
-#  Copyright (c) 2016-2018 Phusion Holding B.V.
+#  Copyright (c) 2016-2025 Asynchronous B.V.
 #
-#  "Union Station" and "Passenger" are trademarks of Phusion Holding B.V.
+#  "Union Station" and "Passenger" are trademarks of 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/initializer_builder.rb

@@ -1,8 +1,8 @@
 # encoding: utf-8
 
-#  Copyright (c) 2016 Phusion Holding B.V.
+#  Copyright (c) 2016-2025 Asynchronous B.V.
 #
-#  "Union Station" and "Passenger" are trademarks of Phusion Holding B.V.
+#  "Union Station" and "Passenger" are trademarks of 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.rb

@@ -1,6 +1,6 @@
-#  Copyright (c) 2016 Phusion Holding B.V.
+#  Copyright (c) 2016-2025 Asynchronous B.V.
 #
-#  "Union Station" and "Passenger" are trademarks of Phusion Holding B.V.
+#  "Union Station" and "Passenger" are trademarks of 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/test_basics.rb

@@ -1,8 +1,8 @@
 #  Phusion Passenger - https://www.phusionpassenger.com/
-#  Copyright (c) 2010-2017 Phusion Holding B.V.
+#  Copyright (c) 2010-2025 Asynchronous B.V.
 #
 #  "Passenger", "Phusion Passenger" and "Union Station" are registered
-#  trademarks of Phusion Holding B.V.
+#  trademarks of 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
@@ -22,6 +22,8 @@
 #  OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
 #  THE SOFTWARE.
 
+require 'rubygems/version.rb'
+
 TEST_BOOST_OXT_LIBRARY = LIBBOOST_OXT
 TEST_COMMON_LIBRARY    = COMMON_LIBRARY
 TEST_COMMON_CFLAGS     = "-DTESTING_APPLICATION_POOL"
@@ -32,7 +34,7 @@ task :test => ['test:oxt', 'test:cxx', 'test:ruby', 'test:node', 'test:integrati
 desc "Clean all compiled test files"
 task 'test:clean' do
   sh("rm -rf #{TEST_OUTPUT_DIR}")
-  sh("rm -f test/cxx/*.gch")
+  sh("rm -f test/cxx/*.#{PlatformInfo.precompiled_header_extension} test/cxx/*.gch test/cxx/*.pch")
 end
 
 task :clean => 'test:clean'
@@ -49,10 +51,13 @@ task 'test:install_deps' do
   default = boolean_option('DEVDEPS_DEFAULT', true)
   install_base_deps = boolean_option('BASE_DEPS', default)
 
+  bundle_args = []
   if deps_target = string_option('DEPS_TARGET')
-    bundle_args = "--path #{shesc deps_target} #{ENV['BUNDLE_ARGS']}".strip
-  else
-    bundle_args = ENV['BUNDLE_ARGS'].to_s
+    if bundler_too_new?
+      sh "bundle config set --local path #{shesc deps_target}"
+    else
+      bundle_args.concat(["--path", shesc(deps_target)])
+    end
   end
 
   npm_args = ENV['NPM_ARGS'].to_s
@@ -61,20 +66,29 @@ task 'test:install_deps' do
     sh "#{gem_install} bundler"
   end
 
-  if install_base_deps
-    sh "bundle install #{bundle_args} --without="
-  else
-    sh "bundle install #{bundle_args} --without base"
+  if !install_base_deps
+    if bundler_too_new?
+      sh "bundle config set --local without 'base'"
+    else
+      bundle_args.concat(["--without", "base"])
+    end
   end
+  sh "bundle install #{bundle_args.join(' ')} #{ENV['BUNDLE_ARGS']}"
 
   if boolean_option('NODE_MODULES', default)
     sh "npm install #{npm_args}"
   end
 end
 
+def bundler_version
+  `bundle --version` =~ /version (.+)/
+  Gem::Version.new($1)
+end
 
 def bundler_too_old?
-  `bundle --version` =~ /version (.+)/
-  version = $1.split('.').map { |x| x.to_i }
-  version[0] < 1 || version[0] == 1 && version[1] < 10
+  Gem::Version.new(bundler_version) < Gem::Version.new("1.1.10")
+end
+
+def bundler_too_new?
+  Gem::Version.new(bundler_version) >= Gem::Version.new("2.1.0")
 end

data/dev/copy_boost_headers

@@ -1,9 +1,9 @@
 #!/usr/bin/env ruby
 #  Phusion Passenger - https://www.phusionpassenger.com/
-#  Copyright (c) 2010-2017 Phusion Holding B.V.
+#  Copyright (c) 2010-2025 Asynchronous B.V.
 #
 #  "Passenger", "Phusion Passenger" and "Union Station" are registered
-#  trademarks of Phusion Holding B.V.
+#  trademarks of 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
@@ -24,56 +24,55 @@
 #  THE SOFTWARE.
 
 ESSENTIALS = [
-  "boost/detail/{limits,endian}.hpp",
-  "boost/config*",
-  "boost/mpl",
-  "boost/preprocessor/stringize.hpp",
-  "boost/smart_ptr/detail/sp_counted_*",
-  "boost/smart_ptr/detail/atomic_count*",
-  "boost/smart_ptr/detail/spinlock*",
+  "boost/*regex*",
+  "boost/algorithm/string",
   "boost/atomic",
-  "boost/pool",
-  "boost/unordered*",
-  "boost/thread",
-  "boost/intrusive",
+  "boost/bind",
+  "boost/chrono*",
+  "boost/config*",
   "boost/container",
-  "boost/predef",
-  "boost/move",
   "boost/core",
-  "boost/bind",
+  "boost/cstdint.hpp",
+  "boost/date_time",
+  "boost/date_time/date_formatting_limited.hpp",
+  "boost/date_time/gregorian/formatters_limited.hpp",
+  "boost/detail/fenv.hpp",
+  "boost/detail/reference_content.hpp",
+  "boost/foreach.hpp",
   "boost/function",
-  "boost/ratio*",
   "boost/integer*",
-  "boost/chrono*",
-  "boost/random*",
-  "boost/asio*",
-  "boost/optional.hpp",
+  "boost/intrusive",
+  "boost/move",
+  "boost/mpl",
+  "boost/non_type.hpp",
+  "boost/none*",
   "boost/optional",
-  "boost/utility",
-  "libs/thread/src",
-  "libs/system/src",
-  "libs/regex/src",
-  "libs/chrono/src",
-  "libs/random/src",
-  "boost/preprocessor",
+  "boost/optional.hpp",
   "boost/parameter",
-  "boost/date_time/gregorian/formatters_limited.hpp",
-  "boost/date_time/date_formatting_limited.hpp",
-  "boost/type_traits/make_signed.hpp",
+  "boost/pool",
+  "boost/predef",
+  "boost/predef/other/endian.h",
+  "boost/preprocessor",
+  "boost/preprocessor/stringize.hpp",
+  "boost/random*",
+  "boost/ratio*",
+  "boost/smart_ptr/detail/atomic_count*",
+  "boost/smart_ptr/detail/sp_counted_*",
+  "boost/smart_ptr/detail/spinlock*",
+  "boost/system/config.hpp",
+  "boost/system/detail/error_code.ipp",
+  "boost/thread",
+  "boost/type_traits",
   "boost/type_traits/detail/*",
+  "boost/type_traits/make_signed.hpp",
   "boost/typeof",
-  "boost/date_time",
-  "boost/type_traits",
-  "boost/cstdint.hpp",
-  "boost/*regex*",
-  "boost/non_type.hpp",
-  "boost/detail/fenv.hpp",
-  "boost/foreach.hpp",
-  "boost/none*",
-  "boost/system/detail/error_code.ipp",
-  "boost/system/config.hpp",
-  "boost/detail/reference_content.hpp",
-  "boost/algorithm/string"
+  "boost/unordered*",
+  "boost/utility",
+  "libs/chrono/src",
+  "libs/random/src",
+  "libs/regex/src",
+  "libs/system/src",
+  "libs/thread/src",
 ]
 EXCLUDE = [
   "libs/thread/src/win32/*",
@@ -83,50 +82,60 @@ EXCLUDE = [
   "libs/regex/src/usinstances.cpp",
   "boost/atomic/detail/windows.hpp",
   "boost/regex/icu.hpp",
-  "boost/asio/detail/win*",
-  "boost/asio/detail/impl/win*"
 ]
 PROGRAM_SOURCE = %q{
-  #include <boost/shared_ptr.hpp>
-  #include <boost/shared_array.hpp>
-  #include <boost/weak_ptr.hpp>
-  #include <boost/make_shared.hpp>
-  #include <boost/enable_shared_from_this.hpp>
-  #include <boost/intrusive_ptr.hpp>
-  #include <boost/smart_ptr/intrusive_ref_counter.hpp>
-  #include <boost/thread.hpp>
-  #include <boost/noncopyable.hpp>
-  #include <boost/function.hpp>
-  #include <boost/bind/bind.hpp>
-  #include <boost/container/vector.hpp>
-  #include <boost/date_time/posix_time/posix_time.hpp>
-  #include <boost/foreach.hpp>
-  #include <boost/unordered_map.hpp>
-  #include <boost/regex.hpp>
-  #include <boost/pool/object_pool.hpp>
-  #include <boost/move/core.hpp>
-  #include <boost/move/utility.hpp>
+  #include <boost/aligned_storage.hpp>
   #include <boost/atomic.hpp>
-  #include <boost/typeof/typeof.hpp>
+  #include <boost/bind/bind.hpp>
+  #include <boost/chrono.hpp>
   #include <boost/circular_buffer.hpp>
   #include <boost/config.hpp>
   #include <boost/container/small_vector.hpp>
+  #include <boost/container/vector.hpp>
   #include <boost/core/noncopyable.hpp>
   #include <boost/cstdint.hpp>
   #include <boost/current_function.hpp>
+  #include <boost/date_time/posix_time/posix_time.hpp>
   #include <boost/date_time/posix_time/posix_time_types.hpp>
+  #include <boost/enable_shared_from_this.hpp>
+  #include <boost/foreach.hpp>
+  #include <boost/function.hpp>
+  #include <boost/intrusive_ptr.hpp>
+  #include <boost/make_shared.hpp>
+  #include <boost/move/core.hpp>
   #include <boost/move/move.hpp>
+  #include <boost/move/utility.hpp>
+  #include <boost/noncopyable.hpp>
+  #include <boost/nondet_random.hpp>
+  #include <boost/pointer_cast.hpp>
+  #include <boost/pool/object_pool.hpp>
   #include <boost/predef.h>
+  #include <boost/predef/other/endian.h>
+  #include <boost/preprocessor/stringize.hpp>
+  #include <boost/random/random_device.hpp>
+  #include <boost/random/uniform_int_distribution.hpp>
   #include <boost/ref.hpp>
+  #include <boost/regex.hpp>
   #include <boost/scoped_array.hpp>
   #include <boost/scoped_ptr.hpp>
+  #include <boost/shared_array.hpp>
+  #include <boost/shared_ptr.hpp>
+  #include <boost/smart_ptr/intrusive_ref_counter.hpp>
   #include <boost/static_assert.hpp>
+  #include <boost/system/error_code.hpp>
+  #include <boost/system/system_error.hpp>
+  #include <boost/thread.hpp>
+  #include <boost/thread/condition_variable.hpp>
   #include <boost/thread/mutex.hpp>
+  #include <boost/thread/once.hpp>
   #include <boost/thread/tss.hpp>
+  #include <boost/typeof/typeof.hpp>
+  #include <boost/version.hpp>
+  #include <boost/weak_ptr.hpp>
 // Included despite not used in Passenger
+  #include <boost/thread/thread_time.hpp>
   #include <boost/cregex.hpp>
   #include <boost/pointer_cast.hpp>
-  #include <boost/asio.hpp>
 }
 
 require 'fileutils'
@@ -173,9 +182,8 @@ def copy_boost_files(patterns, exclude = nil)
 end
 
 def copy_essential_files
-  exclude = []
-  EXCLUDE.each do |pattern|
-    exclude.concat(Dir["#{BOOST_DIR}/#{pattern}"])
+  exclude = EXCLUDE.flat_map do |pattern|
+    Dir["#{BOOST_DIR}/#{pattern}"]
   end
   copy_boost_files(ESSENTIALS, exclude)
 end
@@ -187,28 +195,39 @@ def prepare
 end
 
 def cleanup
-  FileUtils.rm_rf("boost/thread/win32")
-  FileUtils.rm_rf("boost/src/win32")
-  FileUtils.rm_rf("boost/asio/win32")
   FileUtils.rm_rf("boost/atomic/detail/caps_windows.hpp")
+  FileUtils.rm_rf("boost/atomic/detail/core_ops_windows.hpp")
+  FileUtils.rm_rf("boost/atomic/detail/fence_ops_windows.hpp")
   FileUtils.rm_rf("boost/atomic/detail/ops_windows.hpp")
-  FileUtils.rm_rf("boost/smart_ptr/detail/spinlock_w32.hpp")
-  FileUtils.rm_rf("boost/smart_ptr/detail/sp_counted_base_w32.hpp")
-  FileUtils.rm_rf("boost/smart_ptr/detail/atomic_count_win32.hpp")
-  FileUtils.rm_rf("boost/config/platform/win32.hpp")
+  FileUtils.rm_rf("boost/atomic/detail/wait_caps_windows.hpp")
+  FileUtils.rm_rf("boost/atomic/detail/wait_ops_windows.hpp")
   FileUtils.rm_rf("boost/chrono/detail/inlined/win")
+  FileUtils.rm_rf("boost/config/platform/cygwin.hpp")
+  FileUtils.rm_rf("boost/config/platform/win32.hpp")
+  FileUtils.rm_rf("boost/core/detail/sp_win32_sleep.hpp")
+  FileUtils.rm_rf("boost/smart_ptr/detail/atomic_count_win32.hpp")
+  FileUtils.rm_rf("boost/smart_ptr/detail/sp_counted_base_w32.hpp")
+  FileUtils.rm_rf("boost/smart_ptr/detail/spinlock_w32.hpp")
+  FileUtils.rm_rf("boost/src/win32")
+  FileUtils.rm_rf("boost/thread/win32")
   File.unlink("test.cpp") rescue nil
 end
 
 # Compile PROGRAM_SOURCE and copy whatever missing header files the compiler needs.
 def copy_dependencies(cflags)
+  if RUBY_PLATFORM =~ /darwin/
+    openssl_path = `brew --prefix openssl`.strip
+  else
+    openssl_path = '/usr/include/openssl'
+  end
   done = false
   while !done
-    compiler_output = `c++ test.cpp -c -I. -I.. #{cflags.join(" ")} 2>&1`
+    compiler_output = `c++ test.cpp -c -I#{openssl_path}/include -I. -I.. #{cflags.join(" ")} 2>&1`
     File.unlink('test.o') if File.exist?('test.o')
     missing_headers = compiler_output.
                         split("\n").
                         grep(/(error: .*: No such file|fatal error: '.*' file not found)/).
+                        reject{|s| s =~ /\/usr\/include\// }.
                         map do |line|
       if line =~ /error: (.*): No such file/
         file = $1

data/dev/index_cxx_dependencies.rb

@@ -6,7 +6,6 @@ SEARCH_PATHS = [
   "src/agent",
   "src/cxx_supportlib",
   "src/cxx_supportlib/vendor-copy",
-  "src/cxx_supportlib/vendor-modified/websocketpp",
   "src/cxx_supportlib/vendor-modified",
   "test/cxx"
 ]
@@ -52,6 +51,7 @@ EXCLUDE_NAMES = %w{
   cstdlib
   cstddef
   cstdarg
+  cstdint
   cstring
   ctime
   csignal

data/dev/nginx_version_sha256

@@ -0,0 +1,72 @@
+#!/usr/bin/env ruby
+#  Phusion Passenger - https://www.phusionpassenger.com/
+#  Copyright (c) 2024-2025 Asynchronous B.V.
+#
+#  "Passenger", "Phusion Passenger" and "Union Station" are registered
+#  trademarks of 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
+#  in the Software without restriction, including without limitation the rights
+#  to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+#  copies of the Software, and to permit persons to whom the Software is
+#  furnished to do so, subject to the following conditions:
+#
+#  The above copyright notice and this permission notice shall be included in
+#  all copies or substantial portions of the Software.
+#
+#  THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+#  IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+#  FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+#  AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+#  LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+#  OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+#  THE SOFTWARE.
+
+require 'openssl'
+require 'open-uri'
+require 'gpgme'
+require 'rubygems/version.rb'
+
+VERSION = ARGV[0]
+debug = !ENV["VERBOSE"].nil?
+if Gem::Version.new(VERSION).segments[1].odd?
+  puts "Only use LTS Nginx versions (even numbered minor versions, eg: 1.26.3)"
+  exit 1
+end
+DL_URL = "https://nginx.org/download/nginx-#{VERSION}.tar.gz"
+SIG_URL = "#{DL_URL}.asc"
+KEY_URLS = [
+  # https://nginx.org/en/pgp_keys.html
+  "https://nginx.org/keys/nginx_signing.key",
+  "https://nginx.org/keys/thresh.key",
+  "https://nginx.org/keys/sb.key",
+  "https://nginx.org/keys/pluknet.key",
+  "https://nginx.org/keys/arut.key",
+  "https://nginx.org/keys/maxim.key",
+]
+
+puts DL_URL if debug
+data = URI.open(DL_URL) do |f| f.read end
+File.write("./dl.tar.gz",data) if debug
+puts SIG_URL if debug
+sig = URI.open(SIG_URL) do |f| f.read end
+
+KEY_URLS.each do |key_url|
+  puts key_url if debug
+  key = URI.open(key_url) do |f| f.read end
+  GPGME::Key.import(key) #only needed if the key has not been imported previously
+end
+
+crypto = GPGME::Crypto.new
+valid = false
+crypto.verify(sig, signed_text: data) do |signature|
+  valid = signature.valid?
+end
+
+if valid
+  puts Digest::SHA256.hexdigest(data)
+else
+  puts "invalid sig, maybe you need to add a new key to the list?"
+  exit 1
+end

data/doc/AiInstructions.md

@@ -0,0 +1,112 @@
+This is codebase of the Passenger application server.
+
+## Architecture summary
+
+### 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.
+- Passenger Watchdog Agent: spawns and supervises Passenger Core Agent and a bunch of other periodic helper tasks.
+- Passenger Core Agent. 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 routing path
+
+1. Requests are commonly first received by the web server, which forwards request to Passenger Core. 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 socket 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.
+
+### Application spawning
+
+- Main logic in SpawningKit (src/agent/Core/SpawningKit)
+- Creates subprocess, sets up appropriate environment:
+  - Basic things like working directory and UID.
+  - But also a temporary directory for subprocesses to communicate its spawning progress with the parent process.
+- Once generic subprocess environment setup is done, exec()s a language-specific "loader" which handles further language-specific spawning. For example for Ruby apps, rack-preloader.rb and rack-loader.rb are applicable.
+- Two spawning modes:
+  - "direct" is a normal execution of the app without fancy tricks. Uses "loaders".
+  - "smart" uses preforking. Preforking server is started through a "preloader". SpawningKit communicates with preforking server to perform further actual spawning.
+
+## C++ tech stack
+
+- Agent written in C++
+- C++11
+- Boost. But prefer C++11
+
+### 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/helper-scripts: various helper scripts, including SpawningKit language-specific (pre)loaders.
+
+## Build system
+
+- Building agents: `drake -j4 nginx` (for concurrent building) or `rake nginx`
+- Building C++ test suite: `drake -j4 test:cxx:build` (for concurrent building) or `rake test:cxx:build`
+
+## Special files
+
+*.cxxcodebuilder: a Ruby DSL for generating C/C++ code: https://github.com/phusion/cxxcodebuilder/blob/master/README.md
+Similar in philosophy as Rails's Jbuilder.
+Convention: AutoGeneratedFoo.c.cxxcodebuilder generates AutoGeneratedFoo.c
+
+## Config handling
+
+Apache/Nginx:
+- Config flows from the web server to the Core to the app.
+- There are three levels of configs: global, per-application, per-request. They're centrally registered:
+  - src/ruby_supportlib/phusion_passenger/apache2/config_options.rb
+  - src/ruby_supportlib/phusion_passenger/nginx/config_options.rb
+- Module C/C++ code for managing these configs are autogenerated by build system from config_options.rb.
+
+Passenger Standalone:
+- Config flows from the Passenger Standalone CLI tool, either to Nginx ("nginx" engine mode) or directly to Core ("builtin" engine mode).
+- Config options are centrally registrered in src/ruby_supportlib/phusion_passenger/standalone/config_options_list.rb.
+- Nginx engine: config to pass from CLI to Nginx, are registered in the Nginx config templates in resources/templates/standalone.
+- Builtin engine: config to pass from CLI to Core (via Watchdog) through src/ruby_supportlib/phusion_passenger/standalone/start_command/builtin_engine.rb build_daemon_controller_options.
+
+In the Core Controller there are also three levels of configs: global (via ConfigKit), per-application and per-request. Per-application and per-request configs are fetched from HTTP headers. Per-application configs are passed to ApplicationPool options. Per-request configs are sometimes (but usually not) passed to ApplicationPool.
+
+Keep config option naming between the different integration modes consistent, yet adhering to naming conventions for that integration mode. Example: Apache=PassengerStartTimeout, Nginx=passenger_start_timeout, Standalone=start_timeout (config file) or --start-timeout (CLI arg).
+
+## Coding guidelines
+
+### General
+
+- Make the smallest changes to existing interfaces as possible. Be averse to rewriting things.
+- Keep code readable and focused by splitting smaller or side concerns into functions.
+- Unless the code is trivial and small, prefer not to duplicate code: prefer splitting to common functions.
+- When appropriate, consult design aspects documentation in doc/DesignAspects.
+
+### For C++
+
+- Don't introduce direct libev/libuv dependency in components that don't already use libev/libuv/ServerKit.
+- Prefer using internal utility library.
+  - Prefer oxt/system_calls.hpp wrappers (e.g. oxt::open) over direct syscalls. If no wrapper available, loop until no EINTR.
+  - Consult Utils.h (general utils), IOUtils.h (I/O), FileTools/*.h (file operations).
+  - Prefer FileDescriptor or safelyClose() over close().
+- Mind security: see TempFileHandling.md; prefer safeReadFile() for reading files.
+- Before modifying .cpp files, research corresponding header files.
+- Be careful about object lifetimes. For example, if an object must live longer than the scope, consider storing it as a class field.
+
+#### When working on a ServerKit server (including Core Controller)
+
+- Working objects whose lifecycle are scoped by the request, are to be stored in the corresponding Request struct.
+- When adding stuff to the Request struct, mind proper initialization and deinitialization. Update the initializeRequest and deinitializeRequest methods.
+- When performing an async operation that's not cancellable, use refRequest to keep the Request object alive until the async callback is called. In the callback, check for req->ended().

data/doc/CxxMockingStrategy.md

@@ -0,0 +1,42 @@
+# C++ mocking strategy
+
+- We don't use any mocking library.
+- We implement mocking by splitting mockable code to protected virtual methods. Inside test suites, we create a subclass in which we override the methods we want to mock.
+- Best practices for the override:
+   - Opt-in for mocking on a per-test basis.
+   - When not opted-in, call the parent class's method instead of duplicating its code.
+
+Example:
+
+```c++
+class Greeter {
+protected:
+    virtual const char *name() {
+        return "john";
+    }
+
+public:
+    void greet() {
+        std::cout << "hello " << name() << std::endl;
+    }
+};
+
+// In the test suite:
+class TestGreeter: public Greeter {
+protected:
+    virtual const char *name() override {
+        if (mockName != nullptr) {
+            return mockName;
+        } else {
+            return Greeter::name();
+        }
+    }
+
+public:
+    const char *mockName; // Set to non-nullptr to mock the name
+
+    TestGreeter()
+        : mockName(nullptr)
+        { }
+};
+```