clearwater-hot_loader 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 62c2fa540fc31b83554e87857a0fa030fb28fd5f
+  data.tar.gz: 48acf0cb240586d81b00f681810731c149eaf75a
+SHA512:
+  metadata.gz: 5eb6383c99d0897ba6f5dc9cd910c5657866d7bae1c9672b1e2d7b6091802b22eda30004d3fd22411e0da6b2c332c63bbf5c8f093fe311682c7946c5f25c088d
+  data.tar.gz: 549ef88113da09433a95cdc7b6a0cd0d2402550994dde6ab4d70ee39c14b3c18e26b6c4b139bbee7764755a6c93514ffe3134e751de2ea292ce85c612ae8cfaa

data/.gitignore

@@ -0,0 +1,9 @@
+/.bundle/
+/.yardoc
+/Gemfile.lock
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/

data/.rspec

@@ -0,0 +1,2 @@
+--format documentation
+--color

data/.travis.yml

@@ -0,0 +1,4 @@
+language: ruby
+rvm:
+  - 2.2.3
+before_install: gem install bundler -v 1.10.6

data/CODE_OF_CONDUCT.md

@@ -0,0 +1,13 @@
+# Contributor Code of Conduct
+
+As contributors and maintainers of this project, we pledge to respect all people who contribute through reporting issues, posting feature requests, updating documentation, submitting pull requests or patches, and other activities.
+
+We are committed to making participation in this project a harassment-free experience for everyone, regardless of level of experience, gender, gender identity and expression, sexual orientation, disability, personal appearance, body size, race, ethnicity, age, or religion.
+
+Examples of unacceptable behavior by participants include the use of sexual language or imagery, derogatory comments or personal attacks, trolling, public or private harassment, insults, or other unprofessional conduct.
+
+Project maintainers have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that are not aligned to this Code of Conduct. Project maintainers who do not follow the Code of Conduct may be removed from the project team.
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be reported by opening an issue or contacting one or more of the project maintainers.
+
+This Code of Conduct is adapted from the [Contributor Covenant](http://contributor-covenant.org), version 1.0.0, available at [http://contributor-covenant.org/version/1/0/0/](http://contributor-covenant.org/version/1/0/0/)

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in clearwater-hot_loader.gemspec
+gemspec

data/README.md

@@ -0,0 +1,85 @@
+# Clearwater::HotLoader
+
+A complete solution for re-rendering a Clearwater app in development without a full-page reload.
+
+## Installation
+
+In your `Gemfile`:
+
+```ruby
+# This gem is only useful in the development environment
+gem 'clearwater-hot_loader', group: :development
+```
+
+Then run `bundle` to get it installed.
+
+## Usage
+
+In order to get hot-loading working, we need to connect three parts:
+
+1. The filesystem monitor to trigger changes
+2. WebSocket server to notify the client about changes
+3. WebSocket client to receive the push from the server
+
+The examples in this README will have examples for Rails, but we only rely on Rack.
+
+### Filesystem Monitor
+
+You kick off the filesystem monitor by running `Clearwater::HotLoader.start`.
+
+For a Rails app, simply add that command to the end of your `config/environments/development.rb` file to ensure it only gets run in development.
+
+For Rack apps that aren't based on Rails, you can add this to your `config.ru` file (above the line beginning with `run`):
+
+```ruby
+if ENV['RACK_ENV'] == 'development'
+  Clearwater::HotLoader.start
+end
+```
+
+### WebSocket Server
+
+The client needs to know what to connect to in order to listen for changes, so we need to add an endpoint to our web app to make this happen. How you do this depends entirely on which back-end framework you're using, but most Rack-based frameworks (including Rails) have a way to mount another Rack app as the handler for an endpoint.
+
+_Note: You want to ensure you're only mounting it in development._
+
+In Rails, add this to your `config/routes.rb` file:
+
+```ruby
+mount Clearwater::HotLoader, at: '/clearwater_hot_loader' if Rails.env.development?
+```
+
+The `Clearwater::HotLoader` module contains a Rack server which will handle a WebSocket connection. The filesystem monitor notifies the WebSocket server when files have changed.
+
+### WebSocket Client
+
+The WebSocket client listens for updates from the server and executes them, updating the Ruby environment running inside the browser, and then re-renders your Clearwater app. If you have multiple Clearwater apps running on the page, it will re-render all of them.
+
+To connect to the server, simply add this to the top of your Clearwater app:
+
+```ruby
+require 'clearwater/hot_loader'
+Clearwater::HotLoader.connect port
+```
+
+Simply replace `port` with the port number on which your app is running. It will be the same port on which your web app is running. For example, if you usually open `localhost:3000` to load your web app in the browser, you'll want to connect to port 3000.
+
+## Caveats
+
+- Hot loading involves patching classes and objects that are already loaded. If your code is executing as if being run for the first time, existing app state may be clobbered with fresh state.
+- `require` statements are ignored for various reasons:
+  - Reloading all dependencies is nearly always unnecessary
+  - The Opal environment is not designed to be idempotent. Reloading it may clobber the one already loaded.
+- Because of that, if you add an outside dependency, you will likely need to refresh the page.
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+
+To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+
+## Contributing
+
+Bug reports and pull requests are welcome on [GitHub](https://github.com/clearwater-rb/clearwater-hot_loader).
+
+This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [Contributor Covenant](contributor-covenant.org) code of conduct.

data/Rakefile

@@ -0,0 +1,6 @@
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+task :default => :spec

data/bin/console

@@ -0,0 +1,14 @@
+#!/usr/bin/env ruby
+
+require "bundler/setup"
+require "clearwater/hot_loader"
+
+# You can add fixtures and/or initialization code here to make experimenting
+# with your gem easier. You can also use a different console, if you like.
+
+# (If you use this, don't forget to add pry to your Gemfile!)
+# require "pry"
+# Pry.start
+
+require "irb"
+IRB.start

data/bin/setup

@@ -0,0 +1,7 @@
+#!/bin/bash
+set -euo pipefail
+IFS=$'\n\t'
+
+bundle install
+
+# Do any other automated setup that you need to do here

data/clearwater-hot_loader.gemspec

@@ -0,0 +1,27 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'clearwater/hot_loader/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = "clearwater-hot_loader"
+  spec.version       = Clearwater::HotLoader::VERSION
+  spec.authors       = ["Jamie Gaskins"]
+  spec.email         = ["jgaskins@gmail.com"]
+
+  spec.summary       = %q{Reload your Clearwater app without refreshing the browser}
+  spec.homepage      = "https://github.com/clearwater-rb/clearwater-hot_loader"
+
+  spec.files         = `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|spec|features)/}) }
+  spec.bindir        = "exe"
+  spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
+  spec.require_paths = ["lib"]
+
+  spec.add_runtime_dependency 'clearwater'
+  spec.add_runtime_dependency 'listen'
+  spec.add_runtime_dependency 'faye-websocket'
+
+  spec.add_development_dependency "bundler", "~> 1.10"
+  spec.add_development_dependency "rake", "~> 10.0"
+  spec.add_development_dependency "rspec"
+end

data/lib/clearwater/hot_loader/configuration.rb

@@ -0,0 +1,29 @@
+module Clearwater
+  module HotLoader
+    class Configuration
+      attr_reader :directories
+
+      def initialize attributes={}
+        candidate_directories = Dir[
+          *%w(
+            app/assets/javascripts
+            app/assets/javascripts/**/*
+            assets
+            assets/**/*
+          )
+        ]
+        self.directories = candidate_directories
+
+        attributes.each do |attr, value|
+          public_send "#{attr}=", value
+        end
+      end
+
+      def directories= directories
+        @directories = Array(directories).select { |f|
+          File.directory?(f)
+        }
+      end
+    end
+  end
+end

data/lib/clearwater/hot_loader/file_listener.rb

@@ -0,0 +1,21 @@
+require 'listen'
+
+module Clearwater
+  module HotLoader
+    class FileListener
+      def initialize directory, &block
+        @directory = directory
+
+        @listener = Listen.to(directory) do |modified, added, removed|
+          (modified + added).each do |file|
+            block.call(file)
+          end
+        end
+      end
+
+      def start
+        @listener.start
+      end
+    end
+  end
+end

data/lib/clearwater/hot_loader/server.rb

@@ -0,0 +1,46 @@
+require 'opal'
+require 'faye/websocket'
+
+module Clearwater
+  module HotLoader
+    class Server
+      include Faye
+
+      attr_reader :hot_loader
+
+      def initialize hot_loader=HotLoader
+        @hot_loader = hot_loader
+      end
+
+      def call env
+        if WebSocket.websocket? env
+          ws = WebSocket.new(env)
+
+          ws.on :close do
+            hot_loader.remove_socket ws
+          end
+
+          hot_loader.add_socket ws
+
+          ws.rack_response
+        else
+          [200, { 'Content-Type' => 'text/plain' }, ['Websockets only, please.']]
+        end
+      end
+
+      def compile_file filename
+        code = File.read(filename)
+
+        if filename.end_with? '.rb'
+          Opal.compile(code)
+        elsif filename.end_with? '.js'
+          code
+        else
+          ''
+        end
+      rescue => e
+        ''
+      end
+    end
+  end
+end

data/lib/clearwater/hot_loader/version.rb

@@ -0,0 +1,5 @@
+module Clearwater
+  module HotLoader
+    VERSION = "0.1.0"
+  end
+end

data/lib/clearwater/hot_loader.rb

@@ -0,0 +1,64 @@
+require 'opal'
+require 'clearwater/hot_loader/server'
+require 'clearwater/hot_loader/file_listener'
+require 'clearwater/hot_loader/configuration'
+require 'set'
+
+module Clearwater
+  module HotLoader
+    module_function
+
+    def configure
+      yield configuration
+    end
+
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    def call env
+      server.call env
+    end
+
+    def server
+      @server ||= Server.new
+    end
+
+    def start
+      @listeners = configuration.directories.map { |dir|
+        puts "[Clearwater::HotLoader] Monitoring #{dir}"
+        FileListener.new(dir) do |filename|
+          begin
+            puts "[Clearwater::HotLoader] Compiling #{filename}..."
+            code = server.compile_file(filename)
+            puts "[Clearwater::HotLoader] Hot-loading #{filename}..."
+
+            sockets.each do |ws|
+              ws.send code
+            end
+          rescue => e
+            puts "ONOES! #{e.class} - #{e.message}"
+          end
+        end
+      }
+      @listeners.each(&:start)
+      puts "[Clearwater::HotLoader] started."
+    end
+
+    def sockets
+      @sockets ||= Set.new
+    end
+
+    def add_socket socket
+      sockets << socket
+      self
+    end
+
+    def remove_socket socket
+      sockets.delete socket
+      self
+    end
+  end
+end
+
+Opal.append_path File.expand_path('../../../opal', __FILE__)

data/opal/clearwater/hot_loader.rb

@@ -0,0 +1,35 @@
+require 'bowser'
+require 'bowser/websocket'
+require 'clearwater'
+
+module Clearwater
+  class HotLoader
+    attr_reader :port, :path
+
+    def self.connect port=3000, path='/clearwater_hot_loader'
+      new(port, path).connect
+    end
+
+    def initialize port, path='/clearwater_hot_loader'
+      @port = port
+      @path = path
+    end
+
+    def connect
+      @socket = Bowser::WebSocket.new("ws://localhost:#{port}#{path}")
+
+      @socket.on :message do |msg|
+        %x{ eval(msg.native.data) }
+        Clearwater::Application.render
+      end
+
+      @socket.on :close do
+        Bowser.window.delay 1 do
+          connect
+        end
+      end
+
+      self
+    end
+  end
+end

metadata

@@ -0,0 +1,143 @@
+--- !ruby/object:Gem::Specification
+name: clearwater-hot_loader
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Jamie Gaskins
+autorequire: 
+bindir: exe
+cert_chain: []
+date: 2016-05-18 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: clearwater
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: listen
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: faye-websocket
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.10'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.10'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  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:
+- jgaskins@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".gitignore"
+- ".rspec"
+- ".travis.yml"
+- CODE_OF_CONDUCT.md
+- Gemfile
+- README.md
+- Rakefile
+- bin/console
+- bin/setup
+- clearwater-hot_loader.gemspec
+- lib/clearwater/hot_loader.rb
+- lib/clearwater/hot_loader/configuration.rb
+- lib/clearwater/hot_loader/file_listener.rb
+- lib/clearwater/hot_loader/server.rb
+- lib/clearwater/hot_loader/version.rb
+- opal/clearwater/hot_loader.rb
+homepage: https://github.com/clearwater-rb/clearwater-hot_loader
+licenses: []
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.5.1
+signing_key: 
+specification_version: 4
+summary: Reload your Clearwater app without refreshing the browser
+test_files: []