ask-sandbox-providers 0.1.2 → 0.1.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: dc353cb8a3cc934284dea7ddbe8b57631404a3a88ab99fe577343c519fc23c57
-  data.tar.gz: 53319ce423b19e3a6c85d30f09a4caf526d2ce6c9a3c6198cfea24a8f1eb3c96
+  metadata.gz: bb95b1b00d2c4ed3bb7e3e9a98f77d9035b8c3cc5e990b47870e3edec87f4ea8
+  data.tar.gz: 64781ff4c3f4e8020d759cdef227a05b9f4a21f0b36a6bbb6776aca8849310f5
 SHA512:
-  metadata.gz: 9aca24be7433a28b77993c1f42631345c492c52231e3f11c5a0308a69e692dfaacdc67e1059bf5f4a5fb74ea330e9a583e9a12893f10c66c4be6ebd505818fda
-  data.tar.gz: 3e66b07e821f458ab19592aac2246cca303a3a26e5fa7e4244b419e64bb3b45270a5d9f8b960a3cbc6be57f8edf4037ab7c3bbfb9cbc0187f4e4e7bb5df6c9c1
+  metadata.gz: a14deb3e21c8ae4f73b65fd20d5f5eb6176ea871f6184fc18ecf826285ea1c150fa2f22fdf3a03d33e4602f817c7401f1e2da976a1b0fee6e451d880a39e5278
+  data.tar.gz: 3a1480416aa824fc853bdb6da60d278cad5699c6e8571d3d0bcd2bd5626f07a24b3664f884f7c7ac9166eaede264bfb954b2a8e1839a93bd9a566d819e9de9aa

data/README.md

@@ -2,14 +2,7 @@
 
 [![Gem Version](https://badge.fury.io/rb/ask-sandbox-providers.svg)](https://badge.fury.io/rb/ask-sandbox-providers)
 
-Sandbox providers for the ask-rb ecosystem. Isolated code execution via four backends:
-
-| Provider | Isolation | Speed | Requirement |
-|---|---|---|---|
-| `Local` | Process + rlimits (CPU, memory, processes, file size) | Instant | None (stdlib) |
-| `Docker` | Full container (read-only rootfs, no network, no capabilities) | ~1s | Docker daemon |
-| `Daytona` | Remote container via Daytona API | ~2-5s | `daytona` gem, API key |
-| `Cloudflare` | Cloudflare Workers sandbox via proxy Worker | ~1-3s | Proxy Worker URL |
+Sandbox providers for the ask-rb ecosystem: isolated code execution with a single interface and four backends. The default Local provider needs nothing; Docker, Daytona, and Cloudflare add stronger or remote isolation.
 
 ## Installation
 
@@ -22,106 +15,42 @@ gem "ask-sandbox-providers"
 ```ruby
 require "ask-sandbox-providers"
 
-# Default: Local (subprocess + rlimits on macOS/Linux)
-result = Ask::Sandbox.provider.call(["ruby", "-e", "puts 1+1"])
-puts result.stdout  # => "1\n"
-puts result.exit_code  # => 0
-puts result.timed_out  # => false
+result = Ask::Sandbox.provider.call(["ruby", "-e", "puts 1 + 1"])
+result.stdout     # => "1\n"
+result.exit_code  # => 0
+result.success?   # => true
 ```
 
-### Configure a different provider
-
-```ruby
-# Docker (requires Docker daemon)
-Ask::Sandbox.provider = Ask::Sandbox::Docker.new(
-  image: "ruby:3.4-alpine",
-  memory: "256m",
-  network: false
-)
-
-# Daytona (requires `daytona` gem + API key)
-Ask::Sandbox.provider = Ask::Sandbox::Daytona.new(
-  api_key: Ask::Auth.lookup("DAYTONA_API_KEY"),
-  server_url: "https://api.daytona.io"
-)
-
-# Cloudflare (requires a deployed proxy Worker)
-Ask::Sandbox.provider = Ask::Sandbox::Cloudflare.new(
-  worker_url: "https://sandbox-proxy.my-worker.workers.dev",
-  auth_token: ENV["CLOUDFLARE_SANDBOX_TOKEN"]
-)
-```
+Commands can be an Array (executed directly, no shell) or a String (executed via `bash -c`). All providers accept `call(command, timeout: 30, workdir: nil, env: {}, stdin: nil)`.
 
-### String vs Array commands
+## Choosing a provider
 
 ```ruby
-# String → executed via shell (bash -c)
-Ask::Sandbox.provider.call("ls -la | head -5")
+Ask::Sandbox.provider = :docker   # symbol shortcuts: :local, :docker, :daytona, :cloudflare
 
-# Array → executed directly, no shell (safer for untrusted input)
-Ask::Sandbox.provider.call(["ruby", "-e", "puts ENV['HOME']"])
+Ask::Sandbox.provider = Ask::Sandbox::Docker.new(image: "ruby:3.4-alpine", memory: "256m", network: false)
 ```
 
-### Return value
-
-All providers return an `Ask::Sandbox::Result`:
-
-```ruby
-Result = Data.define(:stdout, :stderr, :exit_code, :timed_out)
-```
-
-## Provider Details
-
-### Local
-
-The default provider. Runs commands in a temp directory with:
+| Provider | Isolation | Requirement |
+|---|---|---|
+| `Ask::Sandbox::Local` (default) | Subprocess with rlimits (CPU, memory, processes, file size), temp directory, sanitized environment | None, stdlib only |
+| `Ask::Sandbox::Docker` | Container with read-only rootfs, no capabilities, no network | Docker daemon |
+| `Ask::Sandbox::Daytona` | Remote sandbox via the Daytona API | `daytona` gem, API key |
+| `Ask::Sandbox::Cloudflare` | Cloudflare Workers sandbox via a proxy Worker | Deployed proxy Worker URL |
 
-- **Process group isolation** — all child processes are killed on timeout
-- **`Process.setrlimit`** — CPU (10s), address space (2GB), processes (50), file size (10MB), FDs (200)
-- **Temp directory** — execution sandbox is auto-cleaned
-- **Environment sanitization** — Bundler/Ruby env vars stripped
+Daytona resolves its API key from `Ask::Auth.lookup("DAYTONA_API_KEY")` or `ENV["DAYTONA_API_KEY"]` when `api_key:` is not given. Cloudflare falls back to the `CLOUDFLARE_SANDBOX_WORKER_URL` and `CLOUDFLARE_SANDBOX_AUTH_TOKEN` env vars.
 
-Available on every platform where Ruby runs (macOS, Linux). Zero external dependencies.
+## Result
 
-### Docker
+Every provider returns `Ask::Sandbox::Result`, a `Data` object with `stdout`, `stderr`, `exit_code`, and `timed_out` fields, plus `#success?` (true when `exit_code == 0`).
 
-Runs commands in a Docker container with security hardening:
+## Full documentation
 
-- `--read-only` — read-only root filesystem
-- `--cap-drop ALL` — no Linux capabilities
-- `--security-opt no-new-privileges` — no privilege escalation
-- `--network none` — no network egress (configurable)
-- `--memory`, `--cpus`, `--pids-limit` — resource limits
-- `--rm` — auto-cleanup on exit
-
-### Daytona
-
-Runs commands in a Daytona sandbox via the official `daytona` gem. Daytona provides secure, elastic sandboxes with full isolation, dedicated kernel, filesystem, and network stack. See [daytona.io/docs](https://www.daytona.io/docs).
-
-### Cloudflare
-
-Runs commands in a Cloudflare Workers sandbox. Requires deploying a proxy Worker that wraps `@cloudflare/sandbox`. See the [Cloudflare Sandbox SDK docs](https://developers.cloudflare.com/sandbox/) for setup.
-
-## Migration from Direct Open3 Usage
-
-If you're upgrading from `ask-tools-shell` v0.1.0 where `Code` and `Bash` tools called
-`Open3.popen3` directly — no action needed. The default `Ask::Sandbox::Local` provider
-behaves identically. To enable stronger isolation, switch the provider:
-
-```ruby
-# Before: direct Open3 (implicit Local)
-Ask::Tools::Code.new.call(code: "puts 1")
-
-# After: configure Docker for stronger isolation
-Ask::Sandbox.provider = Ask::Sandbox::Docker.new
-# The Code tool now runs code inside a Docker container automatically
-```
+The full ask-rb documentation lives at https://ask-rb.github.io/ask-docs. [ask-sandbox-providers in depth](https://ask-rb.github.io/ask-docs/core/sandbox) covers each provider and the hardening details. API reference: https://ask-rb.github.io/ask-docs/reference/api.
 
 ## Development
 
-```bash
-git clone https://github.com/ask-rb/ask-sandbox-providers.git
-cd ask-sandbox-providers
+```
 bundle install
 bundle exec rake test
 ```

data/lib/ask/sandbox/local.rb

@@ -17,7 +17,11 @@ module Ask
 
       RLIMITS = {
         rlimit_cpu: [10, 30],
-        rlimit_nproc: [200, 200],
+        # nproc limits the *user's* total process count, not the sandbox's.
+        # 200 is easily exceeded on a busy dev machine, which makes every
+        # fork in the sandboxed command fail with EAGAIN. 1024 still guards
+        # against fork bombs without breaking normal use.
+        rlimit_nproc: [1024, 1024],
         rlimit_fsize: [10_485_760, 10_485_760],
         rlimit_nofile: [200, 200],
         rlimit_as: [2_147_483_648, 2_147_483_648]

data/lib/ask/sandbox/version.rb

@@ -2,6 +2,6 @@
 
 module Ask
   module Sandbox
-    VERSION = "0.1.2"
+    VERSION = "0.1.3"
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ask-sandbox-providers
 version: !ruby/object:Gem::Version
-  version: 0.1.2
+  version: 0.1.3
 platform: ruby
 authors:
 - Kaka Ruto