ruvoy 0.1.0-aarch64-linux

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 240c3296eb26fb27f1010ac292658b666b8d61e0e8e3b68468f07e9b4d0ca989
+  data.tar.gz: 72249773a9def101672c13f389ac5e8935003c6a854dd3c8710fe0e9b580fc1c
+SHA512:
+  metadata.gz: 944d5a8a115b5019806e824e40d21c187e2000a97cc56ed821d995bc3edbc707bf1bc8968ba1050f9b143f961678fa3381b5da3a9fdc5b316d4d16ce6d1b8deb
+  data.tar.gz: 974e24d42aa2c3d9c4fac85d876bde1bf9b71919ee19b679d9daf51d4107d589b31224e0912d360e833c722305c26ea2da5a39deb08ab28416f43f59afd432ad

data/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

data/README.md

@@ -0,0 +1,268 @@
+<p align="center">
+  <img src="assets/ruvoy-logo.png" alt="Ruvoy" width="360">
+</p>
+
+<p align="center"><strong>Ruby, carried by Envoy.</strong></p>
+
+<p align="center">
+  <img alt="Rust 2024" src="https://img.shields.io/badge/Rust-2024-000000?logo=rust&logoColor=white">
+  <img alt="Ruby 4.0.5" src="https://img.shields.io/badge/Ruby-4.0.5-CC342D?logo=ruby&logoColor=white">
+  <img alt="Envoy 1.39.1" src="https://img.shields.io/badge/Envoy-1.39.1-AC6199?logo=envoyproxy&logoColor=white">
+  <a href="LICENSE"><img alt="Apache License 2.0" src="https://img.shields.io/badge/License-Apache--2.0-blue.svg"></a>
+</p>
+
+<p align="center">English | <a href="README.zh-CN.md">简体中文</a> | <a href="README.ja.md">日本語</a></p>
+
+Ruvoy is a Ruby application runtime inside Envoy. Envoy speaks HTTP, Ruby
+speaks Rack, and owned Rust messages bridge the two.
+
+## Install
+
+```console
+$ gem install ruvoy
+```
+
+The gem carries the dynamic module and the Envoy binary, so there is nothing
+else to install and no version to match by hand.
+
+| | |
+|---|---|
+| Ruby | 4.0.x. The module links against the Ruby it was built for, so the gem is published per ABI. |
+| Platform | Linux `x86_64` and `aarch64`, matching the platforms Envoy publishes binaries for. |
+| Envoy | Bundled (1.39.1, dynamic module ABI 0.1.0). Not installed separately. |
+
+## Quickstart
+
+```console
+$ ruvoy examples/hello/config.ru
+$ curl localhost:8080/
+hello from ruby 4.0.5
+```
+
+`ruvoy` takes a rackup and serves it. It generates the Envoy configuration and
+replaces itself with Envoy, so signals and exit status belong to the proxy and
+a container needs no process supervisor.
+
+```console
+$ ruvoy --help
+Usage: ruvoy [options] [config.ru]
+    -p, --port PORT                  Listen on PORT (default 8080)
+    -a, --address ADDRESS            Bind to ADDRESS (default 127.0.0.1)
+        --admin-port PORT            Expose Envoy's admin interface on PORT
+        --print-config               Print the generated Envoy configuration and exit
+```
+
+To run it under an Envoy you configure yourself, `--print-config` prints the
+listener Ruvoy would have used; the module is `ruvoy_fiber` and its filter
+config is the path to the rackup.
+
+## Status
+
+The data path is implemented and covered by suites that run against a real
+Envoy in CI. Configuration reload has been driven through a running Envoy, and
+a one-hour soak of 1.8 million requests left the heap, file descriptors and
+threads flat. Interfaces may change.
+
+## Features
+
+- **Envoy-native HTTP** — HTTP/1.1, HTTP/2, connections, timeouts, and
+  downstream lifecycle remain under Envoy's control.
+- **Rack applications** — load an ordinary `config.ru` and receive a Rack
+  environment built from the Envoy request.
+- **Fiber concurrency** — scheduler-aware Ruby I/O overlaps on a dedicated
+  CRuby owner thread without entering Ruby from Envoy workers.
+- **Owned-data boundary** — only Rust-owned requests and responses cross
+  threads; Ruby objects never do.
+- **Streaming responses** — response bodies are delivered chunk by chunk as the
+  application produces them, with downstream backpressure applied to the Ruby
+  producer instead of buffering.
+- **Streaming requests** — the application is called as soon as the headers
+  arrive and reads the body as it lands, with a client the application cannot
+  keep up with slowed down instead of buffered.
+- **Bounded admission** — a request-count budget rejects excess work before it
+  reaches Ruby.
+- **No upstream HTTP hop** — Rack calls do not require a loopback connection to
+  a separate Ruby application server.
+
+## With and without Ruvoy
+
+| | Without Ruvoy | With Ruvoy |
+|---|---|---|
+| Request path | Envoy → upstream HTTP → Ruby server | Envoy → owned Rust message → Ruby |
+| Ruby host | Separate server process or processes | Dedicated CRuby owner thread inside Envoy |
+| Protocol handoff | Request is serialized onto another HTTP connection | Request crosses the worker boundary as owned data |
+| I/O concurrency | Server threads or workers | Async fibers on the Ruby owner thread |
+| Failure boundary | Envoy and Ruby are separate processes | Envoy and Ruby share one process |
+| CPU-bound Ruby | Multiple Ruby workers can use multiple cores | One CRuby VM remains limited by the GVL |
+
+Ruvoy is designed for scheduler-aware I/O and short CPU-light Rack work. It
+does not make CPU-bound Ruby execute in parallel.
+
+## Architecture
+
+```text
+client
+  → Envoy worker
+  → owned Rust request
+  → CRuby owner thread
+  → Async Fiber
+  → owned Rust response
+  → original Envoy worker
+  → client
+```
+
+Envoy workers never acquire a Ruby handle or enter the VM. The Ruby owner
+thread runs the Rack application, while the result is committed back onto the
+worker that owns the downstream stream.
+
+## Current scope
+
+Ruvoy constructs the Rack environment, provides binary `rack.input`, preserves
+repeated response headers, consumes enumerable response bodies, and calls
+`close` when the body supports it.
+
+Response bodies stream incrementally: headers are sent once and each chunk is
+forwarded as the application yields it, so the first bytes reach the client
+before the body is complete. A slow client applies backpressure to the Ruby
+producer rather than accumulating in memory, and a client that disconnects
+stops the enumeration and closes the body.
+
+Request bodies stream as well: the application is called once the headers
+arrive and reads through `rack.input` as the body lands, so uploading and
+processing overlap. What the application has not read yet waits in Envoy, which
+stops reading from the client until there is room again. Raw socket hijacking
+(`rack.hijack`) is not supported; the connection always belongs to Envoy.
+
+A response body that fails after its headers are already on the wire can only
+stop: a dynamic module cannot reset a stream it has started answering, so the
+client receives a short body rather than an error. Applications that can fail
+partway through should send their own length or checksum.
+
+## Scaling
+
+Each Ruvoy process runs exactly one CRuby VM, so Ruby work in one process is
+limited to one core by the GVL. Scaling out means more processes, not more
+threads: run one Ruvoy per replica and scale horizontally as with any
+single-VM Ruby server.
+
+## Benchmarks
+
+### Environment
+
+| Component | Configuration |
+|---|---|
+| Machine | 4 vCPU, 32 GiB memory, x86_64 |
+| System | Linux |
+| Envoy | `1.39.0`, concurrency `1` |
+| Ruby | `4.0.5` |
+| Rust | `1.97.1` |
+| Rack | `3.2.6` |
+| Load generator | oha `1.15.0` |
+
+### Mixed stress
+
+This run tested admission control, recovery, client cancellation, and resource
+stability. It used three complete cycles:
+
+- steady traffic: 45,000 HTTP/2 no-op requests, 6,000 HTTP/1.1 requests with a
+  200 ms wait, and 1,200 HTTP/1.1 requests with a 256 KiB body per cycle;
+- request-count overload: 15 seconds with at most 256 admitted requests;
+- aggregate-body overload: 15 seconds with a 64 MiB admitted-body budget;
+- client cancellation: 128 deliberately cancelled requests;
+- recovery: 20,000 no-op and 2,000 waiting requests per cycle.
+
+| Result | Value |
+|---|---:|
+| Total requests | `2,503,763` |
+| HTTP 200 | `251,400` |
+| Expected overload HTTP 503 | `2,252,363` |
+| Transport errors | `0` |
+| Steady and recovery failures | `0` |
+| Control-listener maximum latency | `35.615 ms` |
+| File descriptors after every cycle | `59` |
+| Ruby live-heap change, recovered cycle 1 → 3 | `+2 slots` |
+| Peak RSS during body overload | `489,332 KiB` |
+
+Every steady and recovery request returned HTTP 200. All HTTP 503 responses
+were generated during deliberate overload and are reported as rejected work,
+not successful throughput.
+
+The load generator ran on the same machine, and the server did not saturate
+the host CPU. This result therefore supports resilience and bounded-overload
+claims only; it is not a maximum-throughput measurement.
+
+### Server comparison
+
+A fixed-commit comparison of Ruvoy, direct Falcon `0.55.6`, direct Puma
+`7.2.0`, and Envoy → Puma, all serving the same Rack fixture:
+
+- oha ran on a separate 2 vCPU host over a local network (RTT ≈ 0.03 ms), so
+  the load generator never competed with the servers for CPU.
+- Each measurement is 10 s warm-up plus 30 s under load; 7 rounds per cell
+  with the architecture order rotated every round.
+- A round only counts if every request returned HTTP 200 with zero transport
+  errors. Reported values are medians with relative standard deviation.
+- Every architecture runs one Ruby execution context: Puma in single mode
+  with 100 threads, one Falcon instance, one Ruvoy owner thread, and Envoy
+  `concurrency 1`.
+- Judgement was fixed before the run: an advantage is claimed only when both
+  throughput and p99 improve by more than the larger of 5% and the observed
+  round-to-round variance.
+
+No-op Rack application, HTTP/1.1, 100 connections, plaintext:
+
+| Server | RPS median (RSD) | p50 ms | p99 ms | CPU | RSS MiB |
+|---|---:|---:|---:|---:|---:|
+| Ruvoy | `31,270` (1.9%) | `3.06` | `5.01` | 189% | 94 |
+| Falcon | `12,716` (0.5%) | `7.67` | `9.63` | 99% | 83 |
+| Puma | `10,410` (5.5%) | `8.84` | `20.96` | 87% | 127 |
+| Envoy → Puma | `9,754` (4.0%) | `9.92` | `17.63` | 159% | 185 |
+
+The same workload with TLS 1.3, terminated by Envoy for Ruvoy and
+Envoy → Puma and in-process by Falcon and Puma:
+
+| Server | RPS median (RSD) | p50 ms | p99 ms | CPU | RSS MiB |
+|---|---:|---:|---:|---:|---:|
+| Ruvoy | `32,065` (2.9%) | `2.98` | `4.85` | 192% | 95 |
+| Falcon | `11,401` (3.0%) | `8.73` | `10.61` | 99% | 91 |
+| Envoy → Puma | `9,674` (4.4%) | `9.97` | `17.44` | 162% | 191 |
+| Puma | `8,728` (6.7%) | `9.87` | `25.52` | 87% | 148 |
+
+Falcon is the comparison that isolates the architecture: both are
+fiber-per-request, so the difference is carrying requests as owned data
+inside one process instead of over a loopback HTTP hop. Against Falcon,
+Ruvoy holds `+146%` throughput with `−48%` p99 in plaintext and `+181%`
+with `−54%` under TLS — both past the pre-registered noise threshold.
+Against Envoy → Puma the margin is `+221%` and `+231%`.
+
+Four honest qualifications:
+
+- The no-op scenario measures per-request framework overhead, so these are
+  ceiling numbers. As real application time grows, the relative margin
+  shrinks: with a 200 ms simulated wait at 100 connections, all four servers
+  sit at the same ~495 RPS concurrency limit.
+- Ruvoy's CPU column includes the Envoy worker handling HTTP in the same
+  process (~1.9 cores versus Falcon's ~1.0). Per core the margin is roughly
+  `+29%`; the rest comes from pairing the Ruby thread with a proxy-grade
+  HTTP front end.
+- Every number here comes from an application that yields while it waits. A
+  driver written as a C extension releases the interpreter lock but not the
+  fiber, so a single such call stalls every other request on the thread. The
+  `wait50` and `block50` scenarios measure that difference directly; they are
+  not part of the campaign above.
+- A 1 MiB-response scenario was also run and produced no ranking: above
+  ~1,000 such responses per second all four architectures converged on the
+  network path's throughput limit with 59–96% variance, so that scenario
+  measures the link, not the servers.
+
+Not measured: CPU-bound Rack, real database or HTTP-client drivers, and
+multi-process deployment.
+
+Measurements were produced by `scripts/run-benchmark.sh`, which enforces the
+protocol above — remote load generation, rotation, warm-up, per-round
+validation, and the pre-registered judgement — and writes raw oha output,
+CPU and RSS samples, and the generated summary for every run.
+
+## License
+
+Apache License 2.0. See [LICENSE](LICENSE).

data/exe/ruvoy

@@ -0,0 +1,6 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "ruvoy/cli"
+
+exit Ruvoy::CLI.new(ARGV).run

data/lib/ruvoy/cli.rb

@@ -0,0 +1,112 @@
+# frozen_string_literal: true
+
+require "optparse"
+require "tempfile"
+require "ruvoy/envoy_config"
+require "ruvoy/paths"
+require "ruvoy/version"
+
+module Ruvoy
+  # Turns `ruvoy config.ru` into a running Envoy that serves it.
+  class CLI
+    DEFAULT_RACKUP = "config.ru"
+    DEFAULT_ADDRESS = "127.0.0.1"
+    DEFAULT_PORT = 8080
+
+    Options = Struct.new(:rackup, :address, :port, :admin_port, :print_config, keyword_init: true)
+
+    def initialize(argv, output: $stdout, error: $stderr)
+      @argv = argv
+      @output = output
+      @error = error
+    end
+
+    def run
+      options = catch(:finished) { parse }
+      return 0 unless options.is_a?(Options)
+
+      rackup = File.expand_path(options.rackup)
+      unless File.file?(rackup)
+        @error.puts("ruvoy: no such rackup: #{options.rackup}")
+        return 1
+      end
+
+      yaml = EnvoyConfig.to_yaml(
+        rackup: rackup,
+        address: options.address,
+        port: options.port,
+        admin_port: options.admin_port
+      )
+      if options.print_config
+        @output.puts(yaml)
+        return 0
+      end
+
+      launch(yaml)
+    rescue Paths::NotFound => error
+      @error.puts("ruvoy: #{error.message}")
+      1
+    end
+
+    private
+
+    def launch(yaml)
+      config = Tempfile.new([ "ruvoy", ".yaml" ])
+      config.write(yaml)
+      config.close
+      # Replacing this process rather than supervising a child keeps signals,
+      # exit status and container lifecycle in Envoy's hands.
+      Kernel.exec(environment, Paths.envoy_binary, "-c", config.path)
+    end
+
+    def environment
+      {
+        "ENVOY_DYNAMIC_MODULES_SEARCH_PATH" => Paths.module_directory,
+        # Envoy dlopens the module with no Ruby process to inherit a search
+        # path from, so libruby has to be findable here.
+        "LD_LIBRARY_PATH" => [ Paths.ruby_library_directory, ENV["LD_LIBRARY_PATH"] ]
+          .compact.reject(&:empty?).join(File::PATH_SEPARATOR)
+      }
+    end
+
+    def parse
+      options = Options.new(
+        rackup: DEFAULT_RACKUP,
+        address: DEFAULT_ADDRESS,
+        port: DEFAULT_PORT,
+        admin_port: nil,
+        print_config: false
+      )
+      parser = build_parser(options)
+      parser.parse!(@argv)
+      options.rackup = @argv.shift unless @argv.empty?
+      options
+    end
+
+    def build_parser(options)
+      OptionParser.new do |parser|
+        parser.banner = "Usage: ruvoy [options] [#{DEFAULT_RACKUP}]"
+        parser.on("-p", "--port PORT", Integer, "Listen on PORT (default #{DEFAULT_PORT})") do |port|
+          options.port = port
+        end
+        parser.on("-a", "--address ADDRESS", "Bind to ADDRESS (default #{DEFAULT_ADDRESS})") do |address|
+          options.address = address
+        end
+        parser.on("--admin-port PORT", Integer, "Expose Envoy's admin interface on PORT") do |port|
+          options.admin_port = port
+        end
+        parser.on("--print-config", "Print the generated Envoy configuration and exit") do
+          options.print_config = true
+        end
+        parser.on("-v", "--version", "Print the version and exit") do
+          @output.puts(VERSION)
+          throw :finished
+        end
+        parser.on("-h", "--help", "Print this message and exit") do
+          @output.puts(parser)
+          throw :finished
+        end
+      end
+    end
+  end
+end

data/lib/ruvoy/envoy_config.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+require "yaml"
+
+module Ruvoy
+  # Builds the Envoy bootstrap that serves one Rack application.
+  #
+  # The timeouts are not defaults worth inheriting: a Ruby fiber that never
+  # finishes writes nothing to the stream, so without an explicit bound the
+  # request would hang for Envoy's five-minute default.
+  module EnvoyConfig
+    STREAM_IDLE_TIMEOUT = "15s"
+    REQUEST_TIMEOUT = "30s"
+    CONNECTION_BUFFER_LIMIT_BYTES = 4_194_304
+
+    module_function
+
+    def build(rackup:, address:, port:, admin_port: nil)
+      config = { "static_resources" => { "listeners" => [ listener(rackup, address, port) ] } }
+      config["admin"] = admin(address, admin_port) if admin_port
+      config
+    end
+
+    def to_yaml(**options)
+      YAML.dump(build(**options))
+    end
+
+    def listener(rackup, address, port)
+      {
+        "name" => "ruvoy",
+        "per_connection_buffer_limit_bytes" => CONNECTION_BUFFER_LIMIT_BYTES,
+        "address" => { "socket_address" => { "address" => address, "port_value" => port } },
+        "filter_chains" => [ { "filters" => [ connection_manager(rackup) ] } ]
+      }
+    end
+
+    def connection_manager(rackup)
+      {
+        "name" => "envoy.filters.network.http_connection_manager",
+        "typed_config" => {
+          "@type" => "type.googleapis.com/envoy.extensions.filters.network." \
+                     "http_connection_manager.v3.HttpConnectionManager",
+          "stat_prefix" => "ruvoy",
+          "codec_type" => "AUTO",
+          "stream_idle_timeout" => STREAM_IDLE_TIMEOUT,
+          "request_timeout" => REQUEST_TIMEOUT,
+          "route_config" => {
+            "name" => "local_route",
+            "virtual_hosts" => [ { "name" => "local_service", "domains" => [ "*" ] } ]
+          },
+          "http_filters" => [ rack_filter(rackup) ]
+        }
+      }
+    end
+
+    # Terminal: the Rack application answers the request, so no router follows.
+    def rack_filter(rackup)
+      {
+        "name" => "envoy.extensions.filters.http.dynamic_modules",
+        "typed_config" => {
+          "@type" => "type.googleapis.com/envoy.extensions.filters.http." \
+                     "dynamic_modules.v3.DynamicModuleFilter",
+          "dynamic_module_config" => { "name" => "ruvoy_fiber", "do_not_close" => true },
+          "filter_name" => "fiber_rack",
+          "terminal_filter" => true,
+          "filter_config" => {
+            "@type" => "type.googleapis.com/google.protobuf.StringValue",
+            "value" => rackup
+          }
+        }
+      }
+    end
+
+    def admin(address, port)
+      {
+        "address" => { "socket_address" => { "address" => address, "port_value" => port } }
+      }
+    end
+  end
+end

data/lib/ruvoy/paths.rb

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+require "rbconfig"
+
+module Ruvoy
+  # Locates the three things a run needs: the Ruby the module was built
+  # against, the module itself, and Envoy.
+  #
+  # An installed gem carries the module and Envoy; a source checkout has
+  # neither in those places, so each lookup falls back to where a build leaves
+  # them. Both paths matter — the checkout is how this project tests itself.
+  module Paths
+    class NotFound < StandardError; end
+
+    ROOT = File.expand_path("../..", __dir__)
+    MODULE_BASENAME = "libruvoy_fiber.so"
+
+    class << self
+      # Envoy resolves a module by name against this directory.
+      def module_directory
+        from_env = ENV["RUVOY_MODULE_DIR"]
+        return require_directory(from_env, "RUVOY_MODULE_DIR") if from_env
+
+        candidates = [ packaged_module_directory, File.join(ROOT, "build", "modules") ]
+        found = candidates.find { |directory| File.exist?(File.join(directory, MODULE_BASENAME)) }
+        return found if found
+
+        raise NotFound, "no #{MODULE_BASENAME} in: #{candidates.join(", ")}"
+      end
+
+      def envoy_binary
+        from_env = ENV["RUVOY_ENVOY"]
+        return require_executable(from_env, "RUVOY_ENVOY") if from_env
+
+        packaged = packaged_envoy
+        return packaged if packaged
+
+        on_path = which("envoy")
+        return on_path if on_path
+
+        raise NotFound,
+              "no Envoy found: install the ruvoy-envoy gem, put one on PATH, " \
+              "or point RUVOY_ENVOY at it"
+      end
+
+      # Present only where the ruvoy-envoy gem is installed, which is optional:
+      # an Envoy the machine already has serves just as well.
+      def packaged_envoy
+        require "ruvoy/envoy"
+        Envoy::BINARY if File.executable?(Envoy::BINARY)
+      rescue LoadError
+        nil
+      end
+
+      # The module links against libruby, and Envoy loads it with no Ruby
+      # process to inherit a search path from.
+      def ruby_library_directory
+        RbConfig::CONFIG.fetch("libdir")
+      end
+
+      # Precompiled gems carry one module per Ruby ABI, since the module links
+      # against the libruby of the Ruby it was built for.
+      def packaged_module_directory
+        File.join(ROOT, "lib", "ruvoy", RbConfig::CONFIG.fetch("ruby_version"))
+      end
+
+      private
+
+      def require_directory(path, source)
+        return path if File.exist?(File.join(path, MODULE_BASENAME))
+
+        raise NotFound, "#{source} is #{path}, which holds no #{MODULE_BASENAME}"
+      end
+
+      def require_executable(path, source)
+        return path if File.executable?(path)
+
+        raise NotFound, "#{source} is #{path}, which is not executable"
+      end
+
+      def which(command)
+        ENV.fetch("PATH", "").split(File::PATH_SEPARATOR).filter_map do |directory|
+          candidate = File.join(directory, command)
+          candidate if File.executable?(candidate) && !File.directory?(candidate)
+        end.first
+      end
+    end
+  end
+end

data/lib/ruvoy/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Ruvoy
+  # Kept in step with the Cargo workspace version by scripts/test-cli.sh: the
+  # gem and the module it carries are the same release.
+  VERSION = "0.1.0"
+end

metadata

@@ -0,0 +1,87 @@
+--- !ruby/object:Gem::Specification
+name: ruvoy
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: aarch64-linux
+authors:
+- Zixin Zhou
+bindir: exe
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: async
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.45'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.45'
+- !ruby/object:Gem::Dependency
+  name: rack
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.2'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.2'
+description: |
+  Ruvoy is a Ruby application runtime inside Envoy. It loads an ordinary
+  rackup into a CRuby VM embedded in a dynamic module and answers requests as
+  a terminal HTTP filter, so a request reaches Rack as owned data rather than
+  over a second HTTP connection to a separate application server. HTTP/1.1,
+  HTTP/2, TLS, timeouts and the downstream connection lifecycle stay with
+  Envoy. Scheduler-aware Ruby I/O overlaps on fibers; CPU-bound Ruby does not
+  run in parallel, since the process holds one VM.
+email:
+- zhouzixin@apache.org
+executables:
+- ruvoy
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- exe/ruvoy
+- lib/ruvoy/4.0.0/libruvoy_fiber.so
+- lib/ruvoy/cli.rb
+- lib/ruvoy/envoy_config.rb
+- lib/ruvoy/paths.rb
+- lib/ruvoy/version.rb
+homepage: https://github.com/CodePrometheus/ruvoy
+licenses:
+- Apache-2.0
+metadata:
+  source_code_uri: https://github.com/CodePrometheus/ruvoy
+  bug_tracker_uri: https://github.com/CodePrometheus/ruvoy/issues
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 4.0.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.10
+specification_version: 4
+summary: A Rack application server that runs inside Envoy as a dynamic module
+test_files: []