ruvoy 0.1.0-aarch64-linux → 0.2.1-aarch64-linux

checksums.yaml

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

data/README.md

@@ -19,17 +19,18 @@ speaks Rack, and owned Rust messages bridge the two.
 ## Install
 
 ```console
-$ gem install ruvoy
+$ gem install ruvoy ruvoy-envoy
 ```
 
-The gem carries the dynamic module and the Envoy binary, so there is nothing
-else to install and no version to match by hand.
+The `ruvoy` gem carries the dynamic module. Envoy comes from the `ruvoy-envoy`
+gem or the machine: ruvoy looks for `RUVOY_ENVOY`, then `ruvoy-envoy`, then
+`envoy` on `PATH`.
 
 | | |
 |---|---|
 | 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. |
+| Envoy | 1.39 (dynamic module ABI 0.1.0), from the `ruvoy-envoy` gem or the machine. |
 
 ## Quickstart
 
@@ -54,7 +55,8 @@ Usage: ruvoy [options] [config.ru]
 
 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.
+config is the path to the rackup, or a JSON object naming it (see
+[Envoy context and upstream calls](#envoy-context-and-upstream-calls)).
 
 ## Status
 
@@ -83,6 +85,9 @@ threads flat. Interfaces may change.
   reaches Ruby.
 - **No upstream HTTP hop** — Rack calls do not require a loopback connection to
   a separate Ruby application server.
+- **Envoy context and upstream calls** — optionally, the application sees the
+  route, connection, TLS and metadata Envoy has for the request, and calls
+  Envoy's clusters from inside it.
 
 ## With and without Ruvoy
 
@@ -130,13 +135,172 @@ 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
+stops reading from the client until there is room again. What it has read is
+kept, in memory up to 128 KiB and in a temporary file beyond that, so
+`rack.input` can be rewound and read again, as frameworks written for earlier
+Rack versions expect. 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.
+A response body that fails after its headers are already on the wire resets
+the stream, so the client sees an error rather than a short body that looks
+complete.
+
+## Blocking calls
+
+A fiber waits without holding the runtime thread only when the call it waits
+on cooperates with Ruby's fiber scheduler: Ruby's own sockets and IO, `sleep`,
+and the asynchronous APIs many drivers offer do. A C extension call that
+blocks in the kernel instead holds the one thread every request shares, so
+requests queue behind it: fifty-millisecond calls of that kind serve about
+twenty requests a second however many clients wait.
+
+`Ruvoy.offload` runs such a call on its own Ruby thread while the calling
+fiber waits:
+
+```ruby
+rows = Ruvoy.offload { connection.sync_exec(sql) }
+
+# At most 16 in flight; callers beyond that wait their turn.
+DATABASE = Ruvoy::Offload.new(limit: 16)
+rows = DATABASE.call { connection.sync_exec(sql) }
+```
+
+- It helps extensions that release the GVL while they block, which is how
+  blocking C calls are normally written. One that holds the GVL stalls every
+  thread, and nothing on the Ruby side helps.
+- A call cannot be cut short. When the caller is interrupted, because its
+  client went away or a timeout fired, it still waits for the call to finish
+  before it unwinds, so a connection the call is using is not handed back
+  while in use.
+- The block runs on another thread, so thread-local state, such as a
+  per-thread connection, belongs to that thread rather than to the caller.
+- Prefer a driver's scheduler-aware API where it has one. `offload` costs a
+  thread per call and bounds nothing unless given a limit.
+
+## Rails
+
+Rails applications run unchanged, with one setting every fiber server needs:
+
+```ruby
+config.active_support.isolation_level = :fiber
+```
+
+Active Record hands out connections per thread by default, and every
+request's fiber runs on the one runtime thread, so without it concurrent
+requests share a single connection. With it, each request in flight holds a
+connection of its own.
+
+- Action Cable is not supported: it needs `rack.hijack`.
+- Requests reach Rails through Envoy, which adds `X-Forwarded-Proto` to what
+  it passes on.
+- Envoy serves static files ahead of the application, so
+  `config.public_file_server.enabled = false` spares Rails a filesystem lookup
+  on every request: about a fifth more throughput on small responses here.
+- `test/e2e/rails_app_test.rb` runs a production Rails 8.1 application on
+  Ruvoy and on a reference server, compares every answer, and checks
+  connections under concurrency and when a client leaves mid-transaction.
+
+## Envoy context and upstream calls
+
+Two optional capabilities give the application more of Envoy than a Rack
+request carries. Both stay off unless the filter configuration asks for them,
+and both are available on the fiber runtime only. The configuration is then a
+JSON object:
+
+```json
+{
+  "rackup": "/srv/app/config.ru",
+  "context": { "metadata_namespaces": ["acme.tenant"] },
+  "upstream": { "clusters": ["users"], "timeout_ms": 15000, "max_response_bytes": 1048576 }
+}
+```
+
+### `ruvoy.context`
+
+Envoy's view of the request, copied on the worker when the headers arrive.
+Ruby values are only built when the application reads them.
+
+```ruby
+context = env["ruvoy.context"]
+context.route_name        # => "api", or nil for an unnamed route
+context.connection        # => {"id"=>7, "source_address"=>"10.0.0.7", "source_port"=>51234, ...}
+context.tls               # => nil on plaintext, else {"version"=>"TLSv1.3", "server_name"=>..., "peer_certificate"=>...}
+context.dynamic_metadata  # => {"acme.tenant"=>{"id"=>"t-42"}}, from filters ahead of Ruvoy
+context.route_metadata    # => the same namespaces, from the matched route
+context.to_h              # => all of the above
+```
+
+What Envoy's module interface can report sets some limits:
+
+- A route has a name only if the route configuration gives it one. A terminal
+  filter still needs a route entry to be named: give it
+  `non_forwarding_action: {}`.
+- `server_name` is the SNI the client sent, which Envoy records only when the
+  listener has the TLS inspector listener filter.
+- `peer_certificate` means the client presented a certificate. It identifies
+  the client only on a listener that requires client certificates signed by a
+  trusted CA.
+- Only the first URI and the first DNS subject alternative name are reported.
+- Metadata values are strings, numbers (always Float), booleans and lists of
+  those. Nested structures are left out.
+
+### `ruvoy.upstream`
+
+Calls a cluster Envoy was configured with and returns a Rack-style triple:
+
+```ruby
+status, headers, body = env["ruvoy.upstream"].call(
+  "users", "GET", "/users/42",
+  headers: { "accept" => "application/json" }, timeout: 2
+)
+```
+
+The request's worker sends the call through the cluster, so the cluster's
+connection pool, TLS settings and circuit breakers apply, and headers such as
+`x-envoy-retry-on` ask Envoy to retry. The calling fiber waits without holding
+the runtime thread, so other requests keep being served and calls made from
+one request overlap. A repeated response header arrives as an Array.
+
+- Only the clusters in `upstream.clusters` can be called; any other raises
+  `ArgumentError`.
+- Answers Envoy produces while the call is under way arrive as ordinary
+  responses: 504 when it timed out, 503 when the upstream could not be reached
+  or hung up.
+- `Ruvoy::UpstreamError` is raised when the call could not be sent: the cluster
+  does not exist, or turned the call away at once because it has no healthy
+  host or a circuit breaker is open. It is also raised when the request finished
+  before the call did.
+- A response body over `max_response_bytes`, or over Envoy's own buffer limit,
+  raises `Ruvoy::UpstreamResponseTooLarge`, a subclass of `Ruvoy::UpstreamError`,
+  so a caller can tell asking for less apart from trying again later.
+- `call` buffers the response whole, so `max_response_bytes` bounds what one
+  call can hold in memory.
+
+`stream` takes the same arguments and returns once the response head is in.
+The body yields the response as it arrives and can be returned as the Rack
+response, so a proxy is one line:
+
+```ruby
+run ->(env) { env["ruvoy.upstream"].stream("api", env["REQUEST_METHOD"], env["PATH_INFO"], body: env["rack.input"]) }
+```
+
+- The request body may be a String or anything that responds to `read`, such
+  as `rack.input`. One that ends within its first 64 KiB goes with its length,
+  an empty one as none, and a longer one chunked while the response comes down.
+- `idle_timeout:` bounds the wait for the head and between chunks, `timeout_ms`
+  by default, and raises `Ruvoy::UpstreamTimeout`. `timeout:` bounds the whole
+  exchange and is unset by default: Envoy answers 504 before the head, and
+  resets the stream after it.
+- Envoy applies no flow control to a stream a module starts, so at most
+  `upstream.stream_buffer_bytes` (default 1 MiB) of the response waits for a
+  slow reader. Past that the stream is reset and the reader gets
+  `Ruvoy::UpstreamOverflow`. The request body is held to the same budget until
+  Envoy takes it; what Envoy buffers after that is not bounded by Ruvoy.
+- Closing the body before its end, or finishing the request, resets the
+  stream. `body.trailers` holds the upstream's trailers once the body has ended.
+
+[`examples/extensions`](examples/extensions) runs both against a stand-in
+service, including two calls from one request overlapping.
 
 ## Scaling
 
@@ -258,7 +422,7 @@ Four honest qualifications:
 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
+Measurements were produced by `bench/run.rb`, 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.

data/lib/ruvoy/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ruvoy
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.1
 platform: aarch64-linux
 authors:
 - Zixin Zhou