wasmify-rails 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 442a1c699d7e906546d63b1d5c6c451652d65ecd651bd16fa72d98841a845acf
+  data.tar.gz: d8dac2abf684945cc8c9fbd10d3ed6c6236c9535c3f7c3974501638b7be6f607
+SHA512:
+  metadata.gz: 14b9d7c161e577b80d5d9b92d6cb6a7294203f535f938423b194e4adf204541f0d93c4efa466847d2546bf8a919aa96c82037613fb31c7114f3fe1c4debaa5ee
+  data.tar.gz: 61c8ee0c9f26376f53e22bff246bba40c9d038094d846c17cc7b022f600344c70142777901d28d60eb41a5c8471c4dacbf6c188166a0aa76e1b88554c52900e9

data/CHANGELOG.md

@@ -0,0 +1,7 @@
+# Change log
+
+## master
+
+## 0.1.0
+
+- Initial release

data/LICENSE.txt

@@ -0,0 +1,23 @@
+Copyright (c) 2024 Vladimir Dementyev
+
+MIT License
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+

data/README.md

@@ -0,0 +1,168 @@
+[![Gem Version](https://badge.fury.io/rb/wasmify-rails.svg)](https://rubygems.org/gems/wasmify-rails)
+
+# Wasmify Rails
+
+This gem provides tools and extensions to compile Rails applications to WebAssembly.
+
+## Installation
+
+Adding to your Gemfile:
+
+```ruby
+# Gemfile
+gem "wasmify-rails", group: [:development, :wasm]
+```
+
+## Usage
+
+This gem comes with a few commands (Rake tasks) to help you get started with packing your Rails app into a Wasm module.
+
+### Step 1: `bin/rails wasmify:install`
+
+Run the following command to preconfigure your project for _wasmification_:
+
+```sh
+bin/rails wasmify:install
+```
+
+The script will tweak you configuration files and create a couple of new ones:
+
+- `config/environments/wasm.rb` — a dedicated Rails environment based on the `production` environment to be used in Wasm builds.
+
+- `config/wasmify.yml` — this is a configuration file for different _wasmify_ commands (see below).
+
+### Step 2: `bin/rails wasmify:build:core`
+
+Now, it's time to build a ruby.wasm with all your project dependencies (from the Gemfile). This is gonna be a base Wasm module
+for your project but not including the project files.
+
+Prior to running the build command, you MUST update your Gemfile to mark the gems that you need in the Wasm environment
+with the `:wasm` group. For example:
+
+```ruby
+# Rails is required.
+# NOTE: don't forget about the default group — you need it for the regular Rails environments.
+gem "rails", group: [:default, :wasm]
+
+# We don't need Puma though
+gem "puma"
+
+# You can also use group ... do ... end syntax
+group :default, :wasm do
+  gem "propshaft"
+  gem "importmap-rails"
+  gem "turbo-rails"
+  gem "stimulus-rails"
+end
+...
+```
+
+**NOTE:** If you use `ruby file: ".ruby-version"` in your Gemfile, you should probably configure the Ruby version for Wasm platform
+a bit differently (since patch versions might not match). For example:
+
+```ruby
+if RUBY_PLATFORM =~ /wasm/
+  ruby "3.3.3"
+else
+  ruby file: ".ruby-version"
+end
+```
+
+Now, try to run the following command:
+
+```sh
+$ bin/rails wasmify:build:core
+
+...
+INFO: Packaging gem: rails-7.2.1
+...
+INFO: Size: 77.92 MB
+```
+
+If it succeeds then you're good to go further. However, 99% that it will fail with some compilation error.
+You must identify the gem that caused the problem (usually, it happens when we failed to compile a C extension to Wasm—not every C extension is Wasm-compilable).
+Then, you can either update your Gemfile to exclude the problematic gem from the Wasm group or you can update your `config/wasmify.yml` and
+add the gem to the `exclude_gems` list.
+
+Repeat until the `bin/rails wasmify:build:core` succeeds.
+
+You can also verify that the resulting Wasm module works by running:
+
+```sh
+$ bin/rails wasmify:build:core:verify
+
+Your Rails version is: 7.2.1 [wasm32-wasi]
+```
+
+If this command fails, try to iterate on gem exclusions and rebuild the core module.
+
+### Step 3: `bin/rails wasmify:pack:core`
+
+Now, we're ready to pack the whole application into a single Wasm module.
+For that, run the following command:
+
+```sh
+$ bin/rails wasmify:pack:core
+
+Packed the application to tmp/wasmify/app-core.wasm
+Size: 103 MB
+```
+
+That should succeeds given that the previous step was successful.
+
+Now, let's try to boot the application and see if it works:
+
+```sh
+$ bin/rails wasmify:pack:core:verify
+
+Initializing Rails application...
+Rails application initialized!
+```
+
+If the verification passes, you can proceed to the final step — building the Wasm module to be used on the web.
+If it fails, check out the error message and try to fix the issues (usually, configuration related).
+
+### Step 4: `bin/rails wasmify:pwa`
+
+We're ready to launch our Rails application fully within a browser!
+
+For that, you can use our starter Vite PWA application that can be generated via the following command:
+
+```sh
+bin/rails wasmify:pwa
+```
+
+Then, update your `config/wasmify.yml` to specify the path to the PWA app as the output:
+
+```yml
+output_dir: "pwa"
+# ...
+```
+
+Now, create the final Wasm module:
+
+```sh
+bin/rails wasmify:pack
+```
+
+And go to the `pwa` for the instructions on how to launch the application.
+
+## Roadmap
+
+- PGLite support (see [this example](https://github.com/kateinoigakukun/mastodon/blob/fff2e4a626a20a616c546ddf4f91766abaf1133a/pwa/dist/pglite.rb#L1))
+- Active Storage OPFS service
+- File uploads support (multipart/form-data)
+- Background jobs support
+- WASI Preview 2 support (also [this](https://github.com/kateinoigakukun/mastodon/tree/katei/wasmify))
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at [https://github.com/](https://github.com/).
+
+## Credits
+
+The `nulldb` adapter for Active Record (used for tests) is adopted from [this project](https://github.com/nulldb/nulldb).
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](http://opensource.org/licenses/MIT).

data/lib/active_record/connection_adapters/nulldb_adapter/checkpoint.rb

@@ -0,0 +1,13 @@
+class ActiveRecord::ConnectionAdapters::NullDBAdapter
+
+  class Checkpoint < Statement
+    def initialize
+      super(:checkpoint, "")
+    end
+
+    def ==(other)
+      self.class == other.class
+    end
+  end
+
+end

data/lib/active_record/connection_adapters/nulldb_adapter/column.rb

@@ -0,0 +1,4 @@
+class ActiveRecord::ConnectionAdapters::NullDBAdapter
+  class Column < ::ActiveRecord::ConnectionAdapters::Column
+  end
+end

data/lib/active_record/connection_adapters/nulldb_adapter/configuration.rb

@@ -0,0 +1,5 @@
+class ActiveRecord::ConnectionAdapters::NullDBAdapter
+
+  class Configuration < Struct.new(:project_root); end
+
+end

data/lib/active_record/connection_adapters/nulldb_adapter/core.rb

@@ -0,0 +1,391 @@
+class ActiveRecord::ConnectionAdapters::NullDBAdapter < ActiveRecord::ConnectionAdapters::AbstractAdapter
+
+  # A convenience method for integratinginto RSpec.  See README for example of
+  # use.
+  def self.insinuate_into_spec(config)
+    config.before :all do
+      ActiveRecord::Base.establish_connection(:adapter => :nulldb)
+    end
+
+    config.after :all do
+      ActiveRecord::Base.establish_connection(:test)
+    end
+  end
+
+  # Recognized options:
+  #
+  # [+:schema+] path to the schema file, relative to Rails.root
+  # [+:table_definition_class_name+] table definition class
+  # (e.g. ActiveRecord::ConnectionAdapters::PostgreSQL::TableDefinition for Postgres) or nil.
+  def initialize(config={})
+    @log            = StringIO.new
+    @logger         = Logger.new(@log)
+    @last_unique_id = 0
+    @tables         = {'schema_info' => new_table_definition(nil)}
+    @indexes        = Hash.new { |hash, key| hash[key] = [] }
+    @schema_path    = config.fetch(:schema){ "db/schema.rb" }
+    @config         = config.merge(:adapter => :nulldb)
+    super *initialize_args
+    @visitor ||= Arel::Visitors::ToSql.new self if defined?(Arel::Visitors::ToSql)
+
+    if config[:table_definition_class_name]
+      ActiveRecord::ConnectionAdapters::NullDBAdapter.send(:remove_const, 'TableDefinition')
+      ActiveRecord::ConnectionAdapters::NullDBAdapter.const_set('TableDefinition',
+        self.class.const_get(config[:table_definition_class_name]))
+    end
+
+    register_types
+  end
+
+  # A log of every statement that has been "executed" by this connection adapter
+  # instance.
+  def execution_log
+    (@execution_log ||= [])
+  end
+
+  # A log of every statement that has been "executed" since the last time
+  # #checkpoint! was called, or since the connection was created.
+  def execution_log_since_checkpoint
+    checkpoint_index = @execution_log.rindex(Checkpoint.new)
+    checkpoint_index = checkpoint_index ? checkpoint_index + 1 : 0
+    @execution_log[(checkpoint_index..-1)]
+  end
+
+  # Inserts a checkpoint in the log.  See also #execution_log_since_checkpoint.
+  def checkpoint!
+    self.execution_log << Checkpoint.new
+  end
+
+  def adapter_name
+    "NullDB"
+  end
+
+  def supports_migrations?
+    true
+  end
+
+  def connect
+  end
+
+  def reconnect
+  end
+
+  def create_table(table_name, options = {})
+    table_definition = new_table_definition(self, table_name, options.delete(:temporary), options)
+
+    unless options[:id] == false
+      table_definition.primary_key(options[:primary_key] || "id")
+    end
+
+    yield table_definition if block_given?
+
+    @tables[table_name.to_s] = table_definition
+  end
+
+  def rename_table(table_name, new_name)
+    table_definition = @tables.delete(table_name.to_s)
+
+    table_definition.name = new_name.to_s
+    @tables[new_name.to_s] = table_definition
+  end
+
+  def add_index(table_name, column_names, **options)
+    options[:unique] = false unless options.key?(:unique)
+    column_names = Array.wrap(column_names).map(&:to_s)
+
+    index, index_type, ignore = add_index_options(table_name, column_names, **options)
+
+    if index.is_a?(ActiveRecord::ConnectionAdapters::IndexDefinition)
+      @indexes[table_name] << index
+    else
+      # Rails < 6.1
+      @indexes[table_name] << IndexDefinition.new(table_name, index, (index_type == 'UNIQUE'), column_names, [], [])
+    end
+  end
+
+  # Rails 6.1+
+  if ActiveRecord::VERSION::MAJOR >= 7 || (ActiveRecord::VERSION::MAJOR >= 6 and ActiveRecord::VERSION::MINOR > 0)
+    def remove_index(table_name, column_name = nil, **options )
+      index_name = index_name_for_remove(table_name, column_name, options)
+      index = @indexes[table_name].reject! { |index| index.name == index_name }
+    end
+  else
+    def remove_index(table_name,  options = {} )
+      index_name = index_name_for_remove(table_name, options)
+      index = @indexes[table_name].reject! { |index| index.name == index_name }
+    end
+  end
+
+  def add_fk_constraint(*args)
+    # NOOP
+  end
+
+  def add_pk_constraint(*args)
+    # NOOP
+  end
+
+  def enable_extension(*)
+    # NOOP
+  end
+
+  # Retrieve the table names defined by the schema
+  def tables
+    @tables.keys.map(&:to_s)
+  end
+
+  def views
+    [] # TODO: Implement properly if needed - This is new method in rails
+  end
+
+  # Retrieve table columns as defined by the schema
+  def columns(table_name, name = nil)
+    if @tables.size <= 1
+      ActiveRecord::Migration.verbose = false
+      schema_path = if Pathname(@schema_path).absolute?
+                      @schema_path
+                    else
+                      File.join(NullDB.configuration.project_root, @schema_path)
+                    end
+      Kernel.load(schema_path)
+    end
+
+    if table = @tables[table_name]
+      table.columns.map do |col_def|
+        col_args = default_column_arguments(col_def)
+        ActiveRecord::ConnectionAdapters::NullDBAdapter::Column.new(*col_args)
+      end
+    else
+      []
+    end
+  end
+
+  # Retrieve table indexes as defined by the schema
+  def indexes(table_name, name = nil)
+    @indexes[table_name]
+  end
+
+  def execute(statement, name = nil)
+    self.execution_log << Statement.new(entry_point, statement)
+    NullObject.new
+  end
+
+  def exec_query(statement, name = 'SQL', binds = [], options = {})
+    internal_exec_query(statement, name, binds, **options)
+  end
+
+  def internal_exec_query(statement, name = 'SQL', binds = [], prepare: false, async: false)
+    self.execution_log << Statement.new(entry_point, statement)
+    EmptyResult.new
+  end
+
+  def select_rows(statement, name = nil, binds = [], async: false)
+    [].tap do
+      self.execution_log << Statement.new(entry_point, statement)
+    end
+  end
+
+  def insert(statement, name = nil, primary_key = nil, object_id = nil, sequence_name = nil, binds = [], returning: nil)
+    with_entry_point(:insert) do
+      super(statement, name, primary_key, object_id, sequence_name)
+    end
+
+    result = object_id || next_unique_id
+
+    returning ? [result] : result
+  end
+  alias :create :insert
+
+  def update(statement, name=nil, binds = [])
+    with_entry_point(:update) do
+      super(statement, name)
+    end
+  end
+
+  def delete(statement, name=nil, binds = [])
+    with_entry_point(:delete) do
+      super(statement, name).size
+    end
+  end
+
+  def select_all(statement, name=nil, binds = [], options = {})
+    with_entry_point(:select_all) do
+      super(statement, name)
+    end
+  end
+
+  def select_one(statement, name=nil, binds = [])
+    with_entry_point(:select_one) do
+      super(statement, name)
+    end
+  end
+
+  def select_value(statement, name=nil, binds = [])
+    with_entry_point(:select_value) do
+      super(statement, name)
+    end
+  end
+
+  def select_values(statement, name=nil)
+    with_entry_point(:select_values) do
+      super(statement, name)
+    end
+  end
+
+  def primary_key(table_name)
+    columns(table_name).detect { |col| col.type == :primary_key }.try(:name)
+  end
+
+  def add_column(table_name, column_name, type, **options)
+    super
+
+    table_meta = @tables[table_name.to_s]
+    return unless table_meta
+
+    table_meta.column column_name, type, **options
+  end
+
+  def change_column(table_name, column_name, type, options = {})
+    table_meta = @tables[table_name.to_s]
+    column = table_meta.columns.find { |column| column.name == column_name.to_s }
+    return unless column
+
+    column.type = type
+    column.options = options if options
+  end
+
+  def rename_column(table_name, column_name, new_column_name)
+    table_meta = @tables[table_name.to_s]
+    column = table_meta.columns.find { |column| column.name == column_name.to_s }
+    return unless column
+
+    column.name = new_column_name
+  end
+
+  def change_column_default(table_name, column_name, default_or_changes)
+    table_meta = @tables[table_name.to_s]
+    column = table_meta.columns.find { |column| column.name == column_name.to_s }
+
+    return unless column
+
+    if default_or_changes.kind_of? Hash
+      column.default = default_or_changes[:to]
+    else
+      column.default = default_or_changes
+    end
+  end
+
+  protected
+
+  def select(statement, name = nil, binds = [], prepare: nil, async: nil, **)
+    EmptyResult.new.tap do |r|
+      r.bind_column_meta(columns_for(name))
+      self.execution_log << Statement.new(entry_point, statement)
+    end
+  end
+
+  private
+
+  def columns_for(table_name)
+    table_meta = @tables[table_name]
+    return [] unless table_meta
+    table_meta.columns
+  end
+
+  def next_unique_id
+    @last_unique_id += 1
+  end
+
+  def with_entry_point(method)
+    if entry_point.nil?
+      with_thread_local_variable(:entry_point, method) do
+        yield
+      end
+    else
+      yield
+    end
+  end
+
+  def entry_point
+    Thread.current[:entry_point]
+  end
+
+  def with_thread_local_variable(name, value)
+    old_value = Thread.current[name]
+    Thread.current[name] = value
+    begin
+      yield
+    ensure
+      Thread.current[name] = old_value
+    end
+  end
+
+  def includes_column?
+    false
+  end
+
+  def new_table_definition(adapter = nil, table_name = nil, is_temporary = nil, options = {})
+    case ::ActiveRecord::VERSION::MAJOR
+    when 6, 7
+      TableDefinition.new(self, table_name, temporary: is_temporary, options: options.except(:id))
+    when 5
+      TableDefinition.new(table_name, is_temporary, options.except(:id), nil)
+    else
+      raise "Unsupported ActiveRecord version #{::ActiveRecord::VERSION::STRING}"
+    end
+  end
+
+  def default_column_arguments(col_def)
+    [
+      col_def.name.to_s,
+      col_def.default.present? ? col_def.default.to_s : nil,
+      sql_type_definition(col_def),
+      col_def.null.nil? || col_def.null
+    ]
+  end
+
+  def sql_type_definition(col_def)
+    ActiveRecord::ConnectionAdapters::SqlTypeMetadata.new(
+      type: col_def.type,
+      sql_type: col_def.type.to_s,
+      limit: col_def.limit
+    )
+  end
+
+  def initialize_args
+    [nil, @logger, @config]
+  end
+
+  # Register types only once to avoid ActiveRecord::TypeConflictError
+  # in ActiveRecord::Type::Registration#<=>
+  REGISTRATION_MUTEX = Mutex.new
+
+  def register_types
+    REGISTRATION_MUTEX.synchronize do
+      return if self.class.types_registered
+
+      self.class.types_registered = true
+    end
+
+    ActiveRecord::Type.register(
+      :primary_key,
+      ActiveModel::Type::Integer,
+      adapter: adapter_name,
+      override: true
+    )
+
+    ActiveRecord::Type.add_modifier({ array: true }, DummyOID, adapter: :nulldb)
+    ActiveRecord::Type.add_modifier({ range: true }, DummyOID, adapter: :nulldb)
+  end
+
+  class << self
+    attr_accessor :types_registered
+  end
+
+  class DummyOID < ActiveModel::Type::Value
+    attr_reader :subtype
+
+    def initialize(*args)
+      @subtype = args.first
+    end
+  end
+end

data/lib/active_record/connection_adapters/nulldb_adapter/empty_result.rb

@@ -0,0 +1,41 @@
+class ActiveRecord::ConnectionAdapters::NullDBAdapter
+
+  class EmptyResult < Array
+    attr_reader :column_types
+    
+    def bind_column_meta(columns)
+      @columns = columns
+      return if columns.empty?
+
+      @column_types = columns.reduce({}) do |ctypes, col|
+        ctypes[col.name] = ActiveRecord::Type.lookup(col.type)
+        ctypes
+      end      
+    end
+
+    def columns
+      @columns ||= []
+    end
+
+    def column_types
+      @column_types ||= {}
+    end
+
+    def cast_values(type_overrides = nil)
+      rows
+    end
+
+    def rows
+      []
+    end
+
+    def >(num)
+      rows.size > num
+    end
+
+    def includes_column?(name)
+      false
+    end
+  end
+
+end

data/lib/active_record/connection_adapters/nulldb_adapter/index_definition.rb

@@ -0,0 +1,5 @@
+class ActiveRecord::ConnectionAdapters::NullDBAdapter
+
+  class IndexDefinition < Struct.new(:table, :name, :unique, :columns, :lengths, :orders); end
+
+end

data/lib/active_record/connection_adapters/nulldb_adapter/null_object.rb

@@ -0,0 +1,13 @@
+class ActiveRecord::ConnectionAdapters::NullDBAdapter
+
+  class NullObject
+    def method_missing(*args, &block)
+      nil
+    end
+
+    def to_a
+      []
+    end
+  end
+
+end

data/lib/active_record/connection_adapters/nulldb_adapter/quoting.rb

@@ -0,0 +1,3 @@
+class ActiveRecord::ConnectionAdapters::NullDBAdapter
+  def self.quote_column_name(name) = %Q("#{name.to_s.gsub('"', '""')}")
+end