collab 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: d67b7d2a30faff8c19e2ef8ebbacf175bc716c8eec5b4a3672bc088554067759
+  data.tar.gz: 413ba76d5f6d46f390ff213b85369be667801a140151d91b166c5bc4dd1b0eff
+SHA512:
+  metadata.gz: e11fada08ea6e80d32d3d02ead738495ad0c89d044065563c543fbd68c4c0425c4e04f7475306dd69751de6f081637f99e6919b9d42b35ffd021882c3dc4d814
+  data.tar.gz: e7dab34c2530ba90fe8dee20e10cca6db76bea46d37205c703186c40c93cd6c7d9d0b92ef1a149e85060c1057f61f3a08d055d8b2f0389bdcd6f60445b646f01

data/Rakefile

@@ -0,0 +1,27 @@
+begin
+  require 'bundler/setup'
+rescue LoadError
+  puts 'You must `gem install bundler` and `bundle install` to run rake tasks'
+end
+
+require 'rdoc/task'
+
+RDoc::Task.new(:rdoc) do |rdoc|
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title    = 'Collab'
+  rdoc.options << '--line-numbers'
+  rdoc.rdoc_files.include('README.md')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end
+
+require 'bundler/gem_tasks'
+
+require 'rake/testtask'
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << 'test'
+  t.pattern = 'test/**/*_test.rb'
+  t.verbose = false
+end
+
+task default: :test

data/app/channels/collab/document_channel.rb

@@ -0,0 +1,28 @@
+class Collab::DocumentChannel < ApplicationCable::Channel
+  def subscribed
+    @document = instance_exec(::Collab.config.find_document_for_subscribe)
+
+    starting_version = params[:startingVersion]&.to_i
+    raise "missing startingVersion" if starting_version.nil?
+
+    stream_for @document
+    
+    transactions = @document.transactions
+                            .where("document_version > ?", starting_version)
+                            .order(document_version: :asc)
+                            .load
+            
+    raise "invalid version" unless transactions.first.document_version == (starting_version + 1) unless transactions.empty?
+
+    transactions.lazy.map(&:as_json).each(method(:transmit))
+  end
+
+  def submit(data)
+    instance_exec(@document, data, &::Collab.config.authorize_update_document)
+    @document.perform_transaction_later(data)
+  end
+
+  def unsubscribed
+    stop_all_streams # this may not be needed
+  end
+end

data/app/jobs/collab/document_transaction_job.rb

@@ -0,0 +1,7 @@
+class Collab::DocumentTransactionJob < ::Collab.config.application_job.constantize
+  queue_as ::Collab.config.queue_document_transaction_job_as
+
+  def perform(document, data)
+    document.apply_transaction_now(data)
+  end
+end

data/lib/collab.rb

@@ -0,0 +1,19 @@
+require "collab/config"
+require "collab/railtie"
+
+module Collab
+  def config
+    @config ||= Collab::Config.new
+    return @config unless block_given?
+    yield @config
+  end
+
+  autoload "Bridge", "collab/bridge"
+  autoload "HasCollaborativeDocument", "collab/has_collaborative_document"
+  
+  module Models
+    autoload "Base", "collab/models/base"
+    autoload "Document", "collab/models/document"
+    autoload "DocumentTransaction", "collab/models/document_transaction"
+  end
+end

data/lib/collab/bridge.rb

@@ -0,0 +1,54 @@
+require "collab/config"
+require "json"
+
+module Collab
+  class Bridge
+    class JSRuntimeError < StandardError
+      def initialize(data)
+        @js_backtrace = data["stack"].split("\n").map{|f| "JavaScript #{f.strip}"} if data["stack"]
+
+        super(data["name"] + ": " + data["message"])
+      end
+
+      def backtrace
+        return unless  val = super
+        
+        if @js_backtrace
+          @js_backtrace + val
+        else
+          val
+        end
+      end
+    end
+    
+    def initialize
+      @node = Dir.chdir(Rails.root) do
+        IO.popen(["node", "-e", %q{"require('rails-collab-server')"}], "r+")
+      end
+    end
+
+    def self.current
+      @current ||= new
+    end
+
+    def call(name, data = nil, schemaName:)
+      req = {name: name, data: data, schemaPackage: ::Collab.config.schema_package, schemaName: schemaName}
+      @node.puts(JSON.generate(req))
+      res = JSON.parse(@node.gets)
+      raise ::Collab::Bridge::JSRuntimeError.new(res["error"]) if res["error"]
+      res["result"]
+    end
+    
+    def apply_transaction(document, transaction, schemaName:)
+      call("applyTransaction", {doc: document, data: transaction}, schemaName: schemaName)
+    end
+
+    def html_to_document(html, schemaName:)
+      call("htmlToDoc", html, schemaName: schemaName)
+    end
+
+    def document_to_html(document, schemaName:)
+      call("docToHtml", document, schemaName: schemaName)
+    end
+  end
+end

data/lib/collab/config.rb

@@ -0,0 +1,15 @@
+module Collab
+  class Config
+    attr_accessor :max_transactions, :application_job, :queue_document_transaction_job_as, :schema_package, :application_record, :document_transaction_model, :document_model
+    
+    def find_document_for_subscribe(&block)
+      @find_document_for_subscribe unless block
+      @find_document_for_subscribe = block
+    end
+
+    def authorize_update_document(&block)
+      @authorize_update_document unless block
+      @authorize_update_document = block
+    end
+  end
+end

data/lib/collab/has_collaborative_document.rb

@@ -0,0 +1,19 @@
+module Collab
+  module HasCollaborativeDocument
+    extend ActiveSupport::Concern
+    
+    class_methods do
+      def has_collaborative_document(attach_as, schema:, blank_document:)
+        has_one attach_as, -> { where(attached_as: attach_as) }, class_name: ::Collab.config.document_model, as: :attached
+
+        define_method attach_as do
+          super() || begin
+            document = self.__send__("build_#{attach_as}", schema_name: schema, document: blank_document.dup)
+            document.save!
+            document
+          end
+        end
+      end
+    end
+  end
+end

data/lib/collab/models/base.rb

@@ -0,0 +1,6 @@
+module Collab
+  class Models::Base < ::Collab.config.application_record.constantize
+    self.abstract_class = true
+    self.table_name_prefix = 'collab_'
+  end
+end

data/lib/collab/models/document.rb

@@ -0,0 +1,75 @@
+module Collab
+  class Models::Document < ::Collab::Models::Base
+    belongs_to :attached, polymorphic: true
+    has_many :transactions, class_name: ::Collab.config.document_transaction_model, foreign_key: :document_id
+
+    validates :document, presence: true
+    validates :document_version, presence: true, numericality: {only_integer: true, greater_than_or_equal_to: 0}
+    validates :schema_name, presence: true
+
+    before_save :nullify_serialized_html, unless: :serialized_html_fresh?
+    after_save :delete_old_transactions
+
+    # The already-serialized html version of this document
+    def serialized_html
+      return super if serialized_html_fresh?
+    end
+
+    def serialized_html_fresh?
+      serialized_html_version == document_version
+    end
+
+    # Serialize the document to html - will be cached if possible (somewhat expensive)
+    def to_html
+      return serialized_html if serialized_html
+
+      serialized_html = ::Collab::Bridge.current.document_to_html(self.document, schema_name: schema_name)
+      self.update! serialized_html: serialized_html, serialized_html_version: document_version
+      serialized_html
+    end
+
+    def from_html(html)
+      raise "cannot override a persisted document" if self.persisted?
+      
+      self.document = ::Collab::Bridge.current.html_to_document(html, schema_name: schema_name)
+    end
+
+    def perform_transaction_later(data)
+      ::Collab::DocumentTransactionJob.perform_later(@document, data)
+    end
+
+    def apply_transaction_now(data)
+      return unless data["v"].is_a?(Integer)
+
+      return if (data["v"] - 1) != self.document_version # if expired between queue and perform, there is no need to aquire a lock. this is an optimization - not a guarantee
+      with_lock do
+        return if (data["v"] - 1) != self.document_version # now that we've aquired a lock to the record, ensure that we're still accessing the correct version
+        
+        transaction_result = ::Collab::Bridge.current.apply_transaction(self.document, data, schema_name: self.schema_name)
+        return unless transaction_result # check to make sure the transaction succeeded
+        
+        self.document = transaction_result["doc"]
+        self.document_version = data["v"]
+        save!
+
+        transactions.create! document_version: self.document_version, steps: data["steps"], ref: data["ref"]
+      end
+    end
+
+    def as_json
+      {id: id, document: document, version: self.document_version}
+    end
+
+    private
+
+    def nullify_serialized_html
+      self.serialized_html = nil
+    end
+
+    def delete_old_transactions
+      cutoff = document_version - ::Collab.config.max_transactions
+      return if cutoff <= 0
+      transactions.where("document_version < ?", cutoff).delete_all
+    end
+  end
+end

data/lib/collab/models/document_transaction.rb

@@ -0,0 +1,22 @@
+module Collab
+  class Models::DocumentTransaction < ::Collab::Models::Base
+    belongs_to :document, class_name: ::Collab.config.document_model
+
+    validates :steps, presence: true
+    validates :document_version, presence: true
+
+    after_create_commit :broadcast
+
+    def as_json
+      {
+        v: document_version,
+        steps: steps,
+        ref: ref
+      }
+    end
+
+    def broadcast
+      ::Collab::DocumentChannel.broadcast_to(document, as_json)
+    end
+  end
+end

data/lib/collab/railtie.rb

@@ -0,0 +1,4 @@
+module Collab
+  class Railtie < ::Rails::Railtie
+  end
+end

data/lib/collab/version.rb

@@ -0,0 +1,3 @@
+module Collab
+  VERSION = '0.1.0'
+end

data/lib/generators/collab/install/install_generator.rb

@@ -0,0 +1,21 @@
+require "rails/generators"
+require "rails/generators/active_record"
+
+module Collab
+  class Install < Rails::Generators::NamedBase
+    include ::Rails::Generators::Migration
+
+    desc "Creates the necessary migrations and initializer for the gem"
+
+    source_root File.expand_path('templates', __dir__)
+  
+    def copy_initializer_file
+      migration_template(
+        "create_collab_tables.rb",
+        "db/migrate/create_collab_tables.rb",
+      )
+      
+      copy_file "initializer.rb", "config/initializers/collab.rb"
+    end
+  end
+end

data/lib/generators/collab/install/templates/create_collab_tables.rb

@@ -0,0 +1,32 @@
+class CreateCollabTables < ActiveRecord::Migration[6.0]
+  def change
+    create_table :collab_documents, id: :uuid do |t|
+      t.references :attached, null: false, index: false, type: :uuid, polymorphic: true
+      t.string :attached_as
+      t.index [:attached_type, :attached_id, :attached_as], name: "index_collaborative_documents_on_attached"
+
+      t.string :schema_name, null: false
+
+      t.jsonb :document, null: false
+      t.integer :document_version, null: false, default: 0
+
+      t.text :serialized_html
+      t.integer :serialized_html_version
+
+      t.timestamps
+    end
+
+    create_table :collab_document_transactions, id: false do |t|
+      t.references :document, null: false, foreign_key: {to_table: :collaborative_documents}, type: :uuid, index: false
+
+      t.jsonb :steps, array: true, null: false
+      t.integer :document_version, null: false
+
+      t.string :ref
+
+      t.index [:document_id, :document_version], unique: true, order: {document_version: :asc}, name: "index_collaborative_document_transactions"
+
+      t.timestamps
+    end
+  end
+end

data/lib/generators/collab/install/templates/initializer.rb

@@ -0,0 +1,39 @@
+# Configuration for the collab gem
+Collab.config do |c|
+  # The NPM package containing the document schema. This will be require()d from your Rails directory
+  # To use a Git repo, see https://docs.npmjs.com/files/package.json#git-urls-as-dependencies
+  c.schema_package = "prosemirror-schema-basic"
+  # How many old transactions to keep per document
+  c.max_transactions = 250
+
+  # Handlers
+  # ========
+  # Find a the document to subscribe to based on the params passed to the channel
+  # Authorization may also be performed here (raise an error)
+  # The block is executed in the scope of the ActionCable channel within #subscribe
+  c.find_document_for_subscribe do
+    Collab::Models::Document.find params[:document_id]
+  end
+  # Called when a client submits a transaction in order to update a document
+  # You should throw an error if unauthorized
+  # The block is executed in the instance of the channel
+  c.authorize_update_document do |document, transaction_data|
+    # raise "authorization failed"
+  end
+
+  # ActionJob settings
+  # ==================
+  # The base job class to use
+  c.application_job = "::ApplicationJob"
+  # The job queue to use for DocumentTransaction jobs
+  c.queue_document_transaction_job_as = :default
+
+
+  # ActiveRecord settings
+  # =====================
+  # The class which models in the gem should inherit from
+  c.application_record = "::ApplicationRecord"
+  # If you want to use your own document model or document transaction model, 
+  c.document_model = "::Collab::Models::Document"
+  c.document_transaction_model = "::Collab::Models::DocumentTransaction"
+end

data/lib/tasks/collab_tasks.rake

@@ -0,0 +1,4 @@
+# desc "Explaining what the task does"
+# task :collab do
+#   # Task goes here
+# end

metadata

@@ -0,0 +1,96 @@
+--- !ruby/object:Gem::Specification
+name: collab
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Ben Aubin
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2020-07-30 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 6.0.3
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 6.0.3.1
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 6.0.3
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 6.0.3.1
+- !ruby/object:Gem::Dependency
+  name: sqlite3
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description:
+email:
+- ben@benaubin.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- Rakefile
+- app/channels/collab/document_channel.rb
+- app/jobs/collab/document_transaction_job.rb
+- lib/collab.rb
+- lib/collab/bridge.rb
+- lib/collab/config.rb
+- lib/collab/has_collaborative_document.rb
+- lib/collab/models/base.rb
+- lib/collab/models/document.rb
+- lib/collab/models/document_transaction.rb
+- lib/collab/railtie.rb
+- lib/collab/version.rb
+- lib/generators/collab/install/install_generator.rb
+- lib/generators/collab/install/templates/create_collab_tables.rb
+- lib/generators/collab/install/templates/initializer.rb
+- lib/tasks/collab_tasks.rake
+homepage: https://github.com/benaubin/rails-collab
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/benaubin/rails-collab
+  source_code_uri: https://github.com/benaubin/rails-collab
+  changelog_uri: https://github.com/benaubin/rails-collab/blob/master/CHANGELOG.md
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.3.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.1.4
+signing_key:
+specification_version: 4
+summary: Collaborative editing on Rails.
+test_files: []