pitchfork 0.12.0 → 0.14.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7bf3d38329b727807923b9d57bfa09f686e313e30b374542f703b9b27f8f6afb
-  data.tar.gz: b47932131e9873ac74617d9cabdd99d2d7c948dcd03564a544b51bd0449ad54c
+  metadata.gz: 9d3eb42c934de40ea4ae4e25e5d334af536a03f9818dfec8798319744d1629a5
+  data.tar.gz: 5ea480e75dabff8298cb419a9ca1ba159af04985f4e02df8fcb51c6eff65b996
 SHA512:
-  metadata.gz: d44f02f6db020cb66ccf17e7221bf86fbec3da47f2ddb9a3d00da5a857472e512f490b02e60f8394a95b595074ab86aa33f2d0822dab45f60090fc355a97bee9
-  data.tar.gz: 868ae5172e8bcee925528a12d3d332c40fb88fd2d6ca1394273ddb5cbe1fde92b0e17ace1abd3681620abffb325a381d6c6622885cdf21f965ade000180bc890
+  metadata.gz: c934f51445bc2b2904f9ecb84edfb0d454e87494fdb3a58210bf5e9b3e69887a6817be1d38f217696432ab40006448f97d22aa0eca866be4e09c6e80ca0499db
+  data.tar.gz: c2dfdf19c3a08aa91199b6289fef08add17281d60eaa3eefd361fb1de74aae0083ae2f10123293782d92b3c8a152b00c21676143c21b03487fecef2c8994d982

data/.github/workflows/ci.yml

@@ -4,13 +4,17 @@ on: [push, pull_request]
 
 jobs:
   ruby:
-    name: Ruby ${{ matrix.ruby }}
+    name: Ruby ${{ matrix.ruby }} ${{ matrix.rubyopt }}
     timeout-minutes: 15
     strategy:
       fail-fast: false
       matrix:
         os: ["ubuntu-latest"]
         ruby: ["ruby-head", "3.3", "3.2", "3.1", "3.0", "2.7", "2.6"]
+        rubyopt: [""]
+        include:
+          - ruby: "3.3"
+            rubyopt: "--enable-frozen-string-literal"
     runs-on: ubuntu-latest
     steps:
       - name: Check out code
@@ -25,5 +29,5 @@ jobs:
       - name: Install packages
         run: sudo apt-get install -y ragel socat netcat
 
-      - name: Tests
-        run: bundle exec rake
+      - name: Tests ${{ matrix.rubyopt }}
+        run: RUBYOPT="${{ matrix.rubyopt }}" bundle exec rake

data/.ruby-version

@@ -0,0 +1 @@
+3.3.1

data/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Unreleased
 
+# 0.14.0
+
+- Remove the dependency on `raindrops`.
+- Add `X-Request-Id` header in the workers proctitle if present.
+- Added experimental service workers.
+
+# 0.13.0
+
+- Fix compatibility with `--enable-frozen-string-literal` in preparation for Ruby 3.4.
+- Extend timed out workers deadline after sending signals to avoid flooding.
+- Fix compilation with Ruby 2.7 and older on macOS.
+
 # 0.12.0
 
 - Disable IO tracking on Rubies older than 3.2.3 to avoid running into https://bugs.ruby-lang.org/issues/19531.

data/Dockerfile

@@ -1,4 +1,4 @@
-FROM mcr.microsoft.com/devcontainers/ruby:1-3.2-bookworm
+FROM mcr.microsoft.com/devcontainers/ruby:3.3-bookworm
 RUN apt-get update -y && apt-get install -y ragel socat netcat-traditional smem apache2-utils
 WORKDIR /app
 CMD [ "bash" ]

data/Gemfile.lock

@@ -1,9 +1,8 @@
 PATH
   remote: .
   specs:
-    pitchfork (0.12.0)
+    pitchfork (0.14.0)
       rack (>= 2.0)
-      raindrops (~> 0.7)
 
 GEM
   remote: https://rubygems.org/
@@ -12,8 +11,7 @@ GEM
     nio4r (2.7.0)
     puma (6.4.2)
       nio4r (~> 2.0)
-    rack (3.0.9.1)
-    raindrops (0.20.1)
+    rack (3.0.11)
     rake (13.0.6)
     rake-compiler (1.2.1)
       rake
@@ -31,4 +29,4 @@ DEPENDENCIES
   rake-compiler
 
 BUNDLED WITH
-   2.3.22
+   2.3.27

data/benchmark/README.md

@@ -2,7 +2,7 @@
 
 ## Copy on Write Efficiency
 
-This benchmark aimed to compare real memory usage of differnet servers.
+This benchmark aimed to compare real memory usage of different servers.
 
 For instance, Puma 2 workers + 2 threads:
 

data/benchmark/cow_benchmark.rb

@@ -1,4 +1,5 @@
 #!/usr/bin/env ruby
+# frozen_string_literal: true
 require "net/http"
 
 app_path = File.expand_path('../examples/constant_caches.ru', __dir__)

data/docs/CONFIGURATION.md

@@ -188,7 +188,7 @@ The second "hard" timeout, is the sum of `timeout` and `cleanup`.
 Workers taking longer than this time period to be ready to handle a new
 request will be forcibly killed (via `SIGKILL`).
 
-Neither of these timeout mecanisms should be routinely relied on, and should
+Neither of these timeout mechanisms should be routinely relied on, and should
 instead be considered as a last line of defense in case you application
 is impacted by bugs causing unexpectedly slow response time, or fully stuck
 processes.
@@ -299,8 +299,13 @@ end
 ```ruby
 after_mold_fork do |server, mold|
   Database.disconnect!
+
+  # Ruby < 3.3
   3.times { GC.start } # promote surviving objects to oldgen
   GC.compact
+
+  # Ruby >= 3.3
+  Process.warmup
 end
 ```
 
@@ -417,6 +422,39 @@ after_request_complete do |server, worker, env|
 end
 ```
 
+### `before_service_worker_ready` (experimental)
+
+Experimental and may change at any point.
+
+If defined, Pitchfork will spawn one extra worker, called a service worker
+which doesn't accept incoming requests, but allows to perform service tasks
+such as warming node local caches or emitting metrics.
+
+Service workers are never promoted to molds, so it is safe to use threads and
+other fork unsafe APIs.
+
+This callback MUST not block. It should start one or multiple background threads
+to perform tasks at regular intervals.
+
+```ruby
+before_service_worker_ready do |server, service_worker|
+  Thread.new do
+    loop do
+      MyApp.emit_utilization_metrics
+      sleep 1
+    end
+  end
+end
+```
+
+### `before_service_worker_exit` (experimental)
+
+Experimental and may change at any point.
+
+Optional.
+
+Called whenever the service worker is exiting. This allow to do a clean shutdown.
+
 ## Reforking
 
 ### `refork_after`

data/docs/MIGRATING_FROM_UNICORN.md

@@ -0,0 +1,34 @@
+# Unicorn Migration Guide
+
+While Pitchfork started out as a patch on top of Unicorn, many Unicorn features
+that don't make sense in containerized environments were removed to simplify the codebase.
+
+This guide is intended to cover the most common changes you need to make to your configuration
+in order to make the switch.
+
+> [!NOTE]
+> This document doesn't contain every incompatibility with Unicorn. If you encounter
+additional incompatibilities, please open an Issue or a Pull Request to add your findings.
+
+* The configurations `user`, `working_directory`, `stderr_path`, `stdout_path`, and `pid`
+have been removed without replacement. Pitchfork is designed for modern deployment strategies
+like Docker and Systemd, as such the responsibility for this functionality is delegated to
+these systems.
+
+* The configuration `preload_app` has been removed without replacement. Pitchfork will always behave
+as if it is set to `true`.
+
+* The Signal `USR2` has been repurposed for reforking. Remove `ExecReload` from your Sytemd unit
+file, if it contains it. Reloading is not a supported feature of Pitchfork.
+
+* The configuration `after_fork` has been split between `after_worker_fork` and `after_mold_fork`.
+
+* If you use `unicorn-worker-killer` or similar gems, you will need to implement this functionally yourself since
+there is no `pitchfork-worker-killer`. Changes to Pitchfork internals make this a pretty painless
+ordeal, you can check out the following GitHub issue to get started: https://github.com/Shopify/pitchfork/issues/92
+
+## Reforking
+
+[Reforking](REFORKING.md) is Pitchfork's main selling point. Give [Refork Safety](FORK_SAFETY.md#refork-safety) a read to understand
+if your application may be compatible. [Enabling reforking](CONFIGURATION.md#refork_after) will give you memory savings above what Unicorn
+is able to offer with its forking model.

data/docs/WHY_MIGRATE.md

@@ -39,6 +39,11 @@ pid file management, hot reload have been stripped.
 
 Pitchfork only kept features that makes sense in a containerized world.
 
+### Migration Guide
+
+If the above points convinced you to make the switch, take a look at the [migration guide](MIGRATING_FROM_UNICORN.md).
+It will go over the most common changes you will need to make to use Pitchfork.
+
 ## Coming from Puma
 
 Generally speaking, compared to (threaded) Puma, Pitchfork *may* offer better latency and isolation at the expense of throughput.

data/examples/constant_caches.ru

@@ -1,3 +1,4 @@
+# frozen_string_literal: true
 require_relative "../lib/pitchfork/mem_info"
 
 module App

data/examples/echo.ru

@@ -1,3 +1,4 @@
+# frozen_string_literal: true
 # Example application that echoes read data back to the HTTP client.
 # This emulates the old echo protocol people used to run.
 #

data/examples/hello.ru

@@ -1,3 +1,4 @@
+# frozen_string_literal: true
 run lambda { |env|
   /\A100-continue\z/i =~ env['HTTP_EXPECT'] and return [100, {}, []]
   body = "Hello World!\n"

data/examples/pitchfork.conf.minimal.rb

@@ -1,3 +1,4 @@
+# frozen_string_literal: true
 # Minimal sample configuration file for Pitchfork
 
 # listen 2007 # by default Pitchfork listens on port 8080

data/examples/pitchfork.conf.rb

@@ -1,3 +1,4 @@
+# frozen_string_literal: true
 # Sample verbose configuration file for Pitchfork
 
 # Use at least one worker per core if you're on a dedicated server,

data/examples/pitchfork.conf.service.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+# Minimal sample configuration file for Pitchfork
+
+# listen 2007 # by default Pitchfork listens on port 8080
+worker_processes 4 # this should be >= nr_cpus
+refork_after [50, 100, 1000]
+
+service_thread = nil
+service_shutdown = false
+
+before_service_worker_ready do |server, service|
+  service_thread = Thread.new do
+    server.logger.info "Service: start"
+    count = 1
+    until service_shutdown
+      server.logger.info "Service: ping count=#{count}"
+      count += 1
+      sleep 1
+    end
+  end
+end
+
+before_service_worker_exit do |server, service|
+  server.logger.info "Service: shutting down"
+  service_shutdown = true
+  service_thread&.join(2)
+end

data/exe/pitchfork

@@ -1,4 +1,5 @@
 #!/usr/bin/env ruby
+# frozen_string_literal: true
 # -*- encoding: binary -*-
 require 'pitchfork/launcher'
 require 'optparse'
@@ -63,7 +64,7 @@ op = OptionParser.new("", 24, '  ') do |opts|
     warn "-s/--server only exists for compatibility with rackup"
   end
 
-  # Unicorn-specific stuff
+  # Pitchfork-specific stuff
   opts.on("-l", "--listen {HOST:PORT|PATH}",
           "listen on HOST:PORT or PATH",
           "this may be specified multiple times",
@@ -71,11 +72,11 @@ op = OptionParser.new("", 24, '  ') do |opts|
     options[:listeners] << address
   end
 
-  opts.on("-c", "--config-file FILE", "Unicorn-specific config file") do |f|
+  opts.on("-c", "--config-file FILE", "Pitchfork-specific config file") do |f|
     options[:config_file] = f
   end
 
-  # I'm avoiding Unicorn-specific config options on the command-line.
+  # I'm avoiding Pitchfork-specific config options on the command-line.
   # IMNSHO, config options on the command-line are redundant given
   # config files and make things unnecessarily complicated with multiple
   # places to look for a config option.
@@ -88,7 +89,7 @@ op = OptionParser.new("", 24, '  ') do |opts|
   end
 
   opts.on_tail("-v", "--version", "Show version") do
-    puts "#{cmd} v#{Pitchfork::Const::UNICORN_VERSION}"
+    puts "#{cmd} v#{Pitchfork::VERSION} (based on Unicorn v#{Pitchfork::Const::UNICORN_VERSION})"
     exit
   end
 

data/ext/pitchfork_http/epollexclusive.h

@@ -11,10 +11,11 @@
 #if defined(HAVE_EPOLL_CREATE1)
 #  include <sys/epoll.h>
 #  include <errno.h>
-#  include <ruby/io.h>
 #  include <ruby/thread.h>
 #endif /* __linux__ */
 
+#include <ruby/io.h>
+
 #if defined(EPOLLEXCLUSIVE) && defined(HAVE_EPOLL_CREATE1)
 #  define USE_EPOLL (1)
 #else
@@ -50,7 +51,6 @@ static VALUE prep_readers(VALUE cls, VALUE readers)
 	for (i = 0; i < RARRAY_LEN(readers); i++) {
 		int rc;
 		struct epoll_event e;
-		rb_io_t *fptr;
 		VALUE io = rb_ary_entry(readers, i);
 
 		e.data.u64 = i; /* the reason readers shouldn't change */

data/ext/pitchfork_http/extconf.rb

@@ -1,9 +1,12 @@
 # -*- encoding: binary -*-
+# frozen_string_literal: true
 require 'mkmf'
 
+append_cflags("-fvisibility=hidden")
 have_const("PR_SET_CHILD_SUBREAPER", "sys/prctl.h")
 have_func("rb_enc_interned_str", "ruby.h") # Ruby 3.0+
 have_func("rb_io_descriptor", "ruby.h") # Ruby 3.1+
+have_func("getpagesize", "unistd.h")
 
 if RUBY_VERSION.start_with?('3.0.')
   # https://bugs.ruby-lang.org/issues/18772

data/ext/pitchfork_http/memory_page.c

@@ -0,0 +1,223 @@
+/* Note: A large part of this code has been borrowed/stolen/adapted from raindrops. */
+
+#include <ruby.h>
+#include <unistd.h>
+#include <sys/mman.h>
+#include <errno.h>
+#include <stddef.h>
+#include <string.h>
+#include <assert.h>
+
+#define PAGE_MASK               (~(page_size - 1))
+#define PAGE_ALIGN(addr)        (((addr) + page_size - 1) & PAGE_MASK)
+
+static size_t slot_size = 128;
+
+static void init_slot_size(void)
+{
+    long tmp = 2;
+
+#ifdef _SC_NPROCESSORS_CONF
+    tmp = sysconf(_SC_NPROCESSORS_CONF);
+#endif
+    /* no point in padding on single CPU machines */
+    if (tmp == 1) {
+        slot_size = sizeof(unsigned long);
+    }
+#ifdef _SC_LEVEL1_DCACHE_LINESIZE
+    if (tmp != 1) {
+        tmp = sysconf(_SC_LEVEL1_DCACHE_LINESIZE);
+        if (tmp > 0) {
+            slot_size = (size_t)tmp;
+        }
+    }
+#endif
+}
+
+static size_t page_size = (size_t)-1;
+
+static void init_page_size(void)
+{
+#if defined(_SC_PAGE_SIZE)
+    page_size = (size_t)sysconf(_SC_PAGE_SIZE);
+#elif defined(_SC_PAGESIZE)
+    page_size = (size_t)sysconf(_SC_PAGESIZE);
+#elif defined(HAVE_GETPAGESIZE)
+    page_size = (size_t)getpagesize();
+#elif defined(PAGE_SIZE)
+    page_size = (size_t)PAGE_SIZE;
+#elif defined(PAGESIZE)
+    page_size = (size_t)PAGESIZE;
+#else
+#  error unable to detect page size for mmap()
+#endif
+    if ((page_size == (size_t)-1) || (page_size < slot_size)) {
+        rb_raise(rb_eRuntimeError, "system page size invalid: %llu", (unsigned long long)page_size);
+    }
+}
+
+/* each slot is a counter */
+struct slot {
+    unsigned long counter;
+} __attribute__((packed));
+
+/* allow mmap-ed regions to store more than one counter */
+struct memory_page {
+    size_t size;
+    size_t capa;
+    struct slot *slots;
+};
+
+static void memory_page_free(void *ptr)
+{
+    struct memory_page *page = (struct memory_page *)ptr;
+
+    if (page->slots != MAP_FAILED) {
+        int rv = munmap(page->slots, slot_size * page->capa);
+        if (rv != 0) {
+            rb_bug("Pitchfork::MemoryPage munmap failed in gc: %s", strerror(errno));
+        }
+    }
+
+    xfree(ptr);
+}
+
+static size_t memory_page_memsize(const void *ptr)
+{
+    const struct memory_page *page = (const struct memory_page *)ptr;
+    size_t memsize = sizeof(struct memory_page);
+    if (page->slots != MAP_FAILED) {
+        memsize += slot_size * page->capa;
+    }
+    return memsize;
+}
+
+static const rb_data_type_t memory_page_type = {
+    .wrap_struct_name = "Pitchfork::MemoryPage",
+    .function = {
+        .dmark = NULL,
+        .dfree = memory_page_free,
+        .dsize = memory_page_memsize,
+    },
+    .flags = RUBY_TYPED_WB_PROTECTED,
+};
+
+static VALUE memory_page_alloc(VALUE klass)
+{
+    struct memory_page *page;
+    VALUE obj = TypedData_Make_Struct(klass, struct memory_page, &memory_page_type, page);
+
+    page->slots = MAP_FAILED;
+    return obj;
+}
+
+static struct memory_page *memory_page_get(VALUE self)
+{
+    struct memory_page *page;
+
+    TypedData_Get_Struct(self, struct memory_page, &memory_page_type, page);
+
+    if (page->slots == MAP_FAILED) {
+        rb_raise(rb_eStandardError, "invalid or freed Pitchfork::MemoryPage");
+    }
+
+    return page;
+}
+
+static unsigned long *memory_page_address(VALUE self, VALUE index)
+{
+    struct memory_page *page = memory_page_get(self);
+    unsigned long off = FIX2ULONG(index) * slot_size;
+
+    if (off >= slot_size * page->size) {
+        rb_raise(rb_eArgError, "offset overrun");
+    }
+
+    return (unsigned long *)((unsigned long)page->slots + off);
+}
+
+
+static VALUE memory_page_aref(VALUE self, VALUE index)
+{
+    return ULONG2NUM(*memory_page_address(self, index));
+}
+
+static VALUE memory_page_aset(VALUE self, VALUE index, VALUE value)
+{
+    unsigned long *addr = memory_page_address(self, index);
+    *addr = NUM2ULONG(value);
+    return value;
+}
+
+static VALUE memory_page_initialize(VALUE self, VALUE size)
+{
+    struct memory_page *page;
+    TypedData_Get_Struct(self, struct memory_page, &memory_page_type, page);
+
+    int tries = 1;
+
+    if (page->slots != MAP_FAILED) {
+        rb_raise(rb_eRuntimeError, "already initialized");
+    }
+
+    page->size = NUM2SIZET(size);
+    if (page->size < 1) {
+        rb_raise(rb_eArgError, "size must be >= 1");
+    }
+
+    size_t tmp = PAGE_ALIGN(slot_size * page->size);
+    page->capa = tmp / slot_size;
+    assert(PAGE_ALIGN(slot_size * page->capa) == tmp && "not aligned");
+
+retry:
+    page->slots = mmap(NULL, tmp, PROT_READ|PROT_WRITE, MAP_ANON|MAP_SHARED, -1, 0);
+
+    if (page->slots == MAP_FAILED) {
+        int err = errno;
+
+        if ((err == EAGAIN || err == ENOMEM) && tries-- > 0) {
+            rb_gc();
+            goto retry;
+        }
+        rb_sys_fail("mmap");
+    }
+
+    memset(page->slots, 0, tmp);
+
+    return self;
+}
+
+void init_pitchfork_memory_page(VALUE mPitchfork)
+{
+    init_slot_size();
+    init_page_size();
+
+    VALUE rb_cMemoryPage = rb_define_class_under(mPitchfork, "MemoryPage", rb_cObject);
+
+    /*
+     * The size of one page of memory for a mmap()-ed MemoryPage region.
+     * Typically 4096 bytes under Linux.
+     */
+    rb_define_const(rb_cMemoryPage, "PAGE_SIZE", SIZET2NUM(page_size));
+
+    /*
+     * The size (in bytes) of a slot in a MemoryPage object.
+     * This is the size of a word on single CPU systems and
+     * the size of the L1 cache line size if detectable.
+     *
+     * Defaults to 128 bytes if undetectable.
+     */
+    rb_define_const(rb_cMemoryPage, "SLOT_SIZE", SIZET2NUM(slot_size));
+
+    rb_define_const(rb_cMemoryPage, "SLOTS", SIZET2NUM(page_size / slot_size));
+
+    /*
+     * The maximum value a slot counter can hold
+     */
+    rb_define_const(rb_cMemoryPage, "SLOT_MAX", ULONG2NUM((unsigned long)-1));
+
+    rb_define_alloc_func(rb_cMemoryPage, memory_page_alloc);
+    rb_define_private_method(rb_cMemoryPage, "initialize", memory_page_initialize, 1);
+    rb_define_method(rb_cMemoryPage, "[]", memory_page_aref, 1);
+    rb_define_method(rb_cMemoryPage, "[]=", memory_page_aset, 2);
+}