rails-wasm-author-constraints

Rails WASM Author Constraints

What works, what doesn't, and how to design lessons around the WASM environment.

Quick Reference: What Can I Teach?

Hard Limitations

These are impossible to work around in the WASM environment. Do not write lessons that depend on them:

No Outbound Networking

Socket operations (TCPSocket, UDPSocket, and all socket classes) fail because the underlying WASI syscalls are unimplemented. Net::HTTP and open-uri will raise errors when attempting connections. You cannot:

• Call external APIs from Ruby
• Download files from the internet
• Connect to external databases or services

Workaround for lessons: If you want to teach API consumption, focus on the controller/model patterns and mock the responses. Show the code structure without executing real HTTP calls.

No Process Spawning

system(), backticks, exec, fork, and Open3 are non-functional. The rails new generator works because it's been patched, but arbitrary shell commands from tutorial code will not work.

No Threading

Thread.new is shimmed to use Fiber.new (cooperative, single-threaded). Code that relies on parallel execution behaves differently. Background job processing and concurrent operations don't work as expected.

No IO.select

The poll_oneoff WASI syscall is unimplemented. This breaks gems like nio4r, Puma, and ActionCable's EventMachine adapter.

No chmod/fchmod

POSIX permission calls are stubbed. Avoid FileUtils.chmod in tutorial code. The rails new generator is pre-patched to handle this.

Gem Compatibility

Adding Gems

Authors can add gems to their tutorial by editing ruby-wasm/Gemfile and running bin/build-wasm to rebuild the WASM binary. This bakes all gems into the binary at build time.

Compatibility Tiers

Pre-Shimmed Gems

These gems are already handled by the WASM runtime:

Gem Build Workflow

# 1. Edit the Gemfile
vim ruby-wasm/Gemfile

# 2. Rebuild the WASM binary (takes several minutes)
bin/build-wasm

# 3. Test your tutorial locally
npm run dev

Database: PGLite

The database is PGLite — an in-browser PostgreSQL implementation compiled to WASM.

What Works

• Standard ActiveRecord operations: create, find, where, update, destroy
• Migrations: rails db:migrate, rails db:rollback
• Seeds: rails db:seed
• PostgreSQL-compatible SQL syntax
• Multiple databases (development, test)
• Associations, joins, aggregations
• Indexes and constraints

What to Know

Lesson Design Implications

• Always include ['node scripts/rails.js db:prepare', 'Prepare development database'] in prepareCommands for lessons that use the database
• Provide seeds in templates so users start with data
• Don't rely on data from a previous lesson persisting — each lesson should set up its own state via migrations + seeds

Boot Timing

The WASM runtime takes time to load. Set expectations for tutorial users:

Total first-load time: 15-40 seconds depending on network and browser.

Author Tips for Boot Experience

• Include a note in early lessons: "The Ruby runtime takes a moment to load — this is normal!"
• Use prepareCommands with descriptive labels so users see progress
• The ['output', 'Setup Logs'] terminal panel shows boot details
• Subsequent lesson navigation is faster if the WebContainer is already booted

Auto-Authentication

The runtime includes an auto-login patch: if tmp/authenticated-user.txt exists in the Rails app root, the first HTTP request auto-authenticates the user found by User.find_by(email_address: <file contents>). The file should contain a single email address (e.g., admin@example.com).

To use: Place workspace/tmp/authenticated-user.txt in _files/ or a template, containing the email of a seeded user. The first request calls start_new_session_for(user), creating a session cookie for all subsequent requests. Runs once per VM lifetime (the $__pre_authenticated global flag prevents repeat attempts).

This requires the Rails 8 Authentication concern and a User model with an email_address column.

Integration Testing

Rails integration tests work in the WASM runtime with important limitations.

What Works

• ActionDispatch::IntegrationTest with get, post, patch, delete
• assert_response, assert_redirected_to
• assert_difference, assert_no_difference
• Fixtures (fixtures :all) for test data
• Cookie-based session management for authentication

What Does NOT Work

Nokogiri-dependent assertions are unavailable. The Nokogiri gem is a minimal stub in WASM — CSS selectors return [] and HTML parsing is non-functional. This means these Rails test helpers will not work:

• assert_select — relies on Nokogiri CSS selectors
• css_select — same
• assert_dom — same
• Any assertion that parses response HTML into a DOM

Best Practices

Use response.body string matching instead of DOM assertions:

# BAD — uses Nokogiri under the hood
assert_select "h1", text: "Tickets"
assert_select ".alert--error", text: /blank/
assert_select "form"

# GOOD — plain string matching
assert_includes response.body, "Tickets"
assert_includes response.body, "blank"
assert_includes response.body, "<form"

Define an assert_text helper in test_helper.rb:

class ActionDispatch::IntegrationTest
  def assert_text(text)
    assert_includes response.body, text
  end
end

Use cookie-based sign_in without making HTTP requests:

class ActionDispatch::IntegrationTest
  private

  def sign_in(user)
    Current.session = user.sessions.create!

    ActionDispatch::TestRequest.create.cookie_jar.tap do |cookie_jar|
      cookie_jar.signed[:session_id] = Current.session.id
      cookies[:session_id] = cookie_jar[:session_id]
    end
  end
end

Disable test parallelization — we don't have threads or processes:

module ActiveSupport
  class TestCase
    # parallelize(workers: 1)
    fixtures :all
  end
end

Filesystem Boundaries

Ruby code can only access /workspace (the WASI preopen). Attempting to access paths outside this boundary raises Errno::ENOENT. Tutorial code should never navigate above /workspace with Dir.chdir("..") or absolute paths outside the preopen.

Conceptual vs. Real Operations

Some tutorial operations are conceptual — they teach the correct pattern but the actual execution requires something different in the WASM environment: