From 939340fe31587ae8296e1dae37a4363232f28531 Mon Sep 17 00:00:00 2001 From: tannevaled Date: Sun, 4 Oct 2026 21:14:49 +0200 Subject: [PATCH] docs: the embedding contract says nothing is shared between Runs; process state is The "Embedding it in a Go program" section promised, unqualified, that "nothing is shared between `Run`s" -- and then said, in the same sentence, that `require_relative` resolves against the **process** working directory. Both cannot be true, and the measurement says the second one is. Measured against origin/main through the public `Run` and nothing else, with a small Go embedder rather than the rbgo CLI: a script that assigns to `ENV` and calls `Dir.chdir` changes them for the host Go program and they stay changed after `Run` returns. A host whose PATH was 860 bytes and whose cwd was its build directory came back with a 13-byte PATH and a cwd of /private/tmp. Since `require_relative` anchors there, one `Run` can also plant a file a later `Run` loads. The narrow claim does hold and is kept: a global, a constant and a String monkey-patch set in one call really are gone in the next. So the sentence is now scoped to the Ruby heap instead of being dropped. Two further corrections in the same paragraph: `exit`, `exit!` and `abort` make `Run` return nil, so the "a Ruby exception comes back as a Go error" clause was describing the one case that works. Tracked upstream in go-embedded-ruby/ruby#773. And a warning admonition saying plainly that `Run` is not a sandbox. That is not a defect report -- MRI is not sandboxed either and conformance is the goal -- but MRI is normally a CLI a person runs on their own code, whereas `Run` is a function someone links into a server, and this page had no safety language at all. It also records the two things that are deliberately out of reach, because those are properties worth not losing by accident. The measurements live in the repository README rather than being duplicated here, and the admonition links to them. Its anchor resolves once go-embedded-ruby/ruby#770 merges, which adds that section. Co-Authored-By: Claude Opus 5 --- docs/index.md | 24 ++++++++++++++++++++---- 1 file changed, 20 insertions(+), 4 deletions(-) diff --git a/docs/index.md b/docs/index.md index d66f320..2cd2013 100644 --- a/docs/index.md +++ b/docs/index.md @@ -26,10 +26,26 @@ err := ruby.Run(`puts "hello from Ruby"`, &out) // out: "hello from Ruby\n" Everything else lives under `internal/`, so this is the whole embedding surface today. Measured behaviour worth knowing: there is **one writer, carrying both streams** (`$stderr` and `warn` land in `out` too); a Ruby exception comes back as a -Go `error` (`ArgumentError: bad`); **each call gets a fresh VM**, so nothing is -shared between `Run`s and there is no exported way to hold a VM open, call a Ruby -method from Go, or pass Go values in; and `require_relative` resolves against the -**process working directory**, since `Run` has no script to anchor to. +Go `error` (`ArgumentError: bad`), though `exit`, `exit!` and `abort` stop the +program and return **`nil`**, so a caller cannot tell “finished” from “stopped”; +**each call gets a fresh VM**, so the Ruby heap is not shared between `Run`s and +there is no exported way to hold a VM open, call a Ruby method from Go, or pass +Go values in; but **process state *is* shared** with the host and with every +other `Run` — `ENV`, the working directory, open files and signal handlers — which +is also why `require_relative` resolves against the **process working +directory**, since `Run` has no script to anchor to. + +!!! warning "`Run` is not a sandbox" + + Conformance is the goal and MRI is not sandboxed either, so neither is this. + Through that one function, Ruby source can spawn `/bin/sh`, read and write + the filesystem as the host's uid, open sockets, `require` any absolute path, + and change the host's `ENV` and working directory. **Do not pass untrusted + Ruby to it.** Two things are deliberately out of reach: there is no path from + Ruby to the host's Go state, and the host's standard descriptors are not + exposed, so a script cannot write outside the `out` you passed. The + [repository README](https://github.com/go-embedded-ruby/ruby#run-is-not-a-sandbox) + carries the measurements. go-embedded-ruby compiles Ruby source to bytecode and runs it on a stack VM in the **mruby/YARV lineage**. Because the front-end (lexer + parser + compiler)