vue_live 0.1.0

data/lib/vue_live/live_reload.rb

@@ -0,0 +1,135 @@
+# frozen_string_literal: true
+
+require 'json'
+
+module VueLive
+  # Development live reload: a Server-Sent Events stream at <prefix>/-/events that announces
+  # changed components, and a small client (<prefix>/-/reload.js) that reloads the page.
+  #
+  # The stream polls the component directory's mtimes (config.live_reload_interval seconds) from
+  # the request's own thread, so it works with any threaded Rack server (Puma, Falcon, WEBrick)
+  # without extra processes or websockets.  On Rack 3 it is a streaming body (`call(io)`), which
+  # servers write through unbuffered; on Rack 2 it is an `each` body.
+  class LiveReload
+    CLIENT = File.expand_path('assets/reload.js', __dir__)
+    HEARTBEAT = 5 # seconds between keep-alive comments (also how fast a gone client is noticed)
+
+    attr_reader :config
+
+    def initialize(config)
+      @config = config
+    end
+
+    def enabled?
+      config.live_reload?
+    end
+
+    # Rack response for the SSE stream.
+    def stream_response(_env = nil)
+      headers = {
+        'content-type' => 'text/event-stream; charset=utf-8',
+        'cache-control' => 'no-store',
+        'x-accel-buffering' => 'no' # nginx: do not buffer
+      }
+      body = LiveReload.rack3? ? StreamingBody.new(config, self) : Stream.new(config, self)
+      [200, headers, body]
+    end
+
+    def client_response
+      body = File.read(CLIENT)
+      [200, { 'content-type' => 'text/javascript; charset=utf-8', 'cache-control' => 'no-cache',
+              'content-length' => body.bytesize.to_s }, [body]]
+    end
+
+    # Snapshot of every servable file's mtime under the component root.
+    def snapshot
+      resolver = Resolver.new(config)
+      root = resolver.source_dir
+      resolver.files.each_with_object({}) do |rel, h|
+        h[rel] = File.mtime(File.join(root, rel)).to_f
+      rescue Errno::ENOENT
+        next
+      end
+    end
+
+    # Files whose mtime differs between two snapshots (added, removed or modified).
+    def self.diff(before, after)
+      (before.keys | after.keys).reject { |k| before[k] == after[k] }.sort
+    end
+
+    def self.rack3?
+      defined?(::Rack::RELEASE) && ::Rack::RELEASE.to_s.split('.').first.to_i >= 3
+    end
+
+    # Produces SSE frames until the consumer raises (client gone), +stop+ is called, or the
+    # stream reaches MAX_LIFETIME (the client reconnects at once; the cap keeps servers that join
+    # request threads on shutdown, such as WEBrick, from waiting on an idle tab forever).
+    class Frames
+      MAX_LIFETIME = 30 # seconds
+
+      def initialize(config, reloader)
+        @config = config
+        @reloader = reloader || LiveReload.new(config)
+        @stopped = false
+      end
+
+      def stop
+        @stopped = true
+      end
+
+      def each_frame
+        last = @reloader.snapshot # before the first frame, so nothing slips through the gap
+        yield "retry: 1000\n\n"
+        yield ": connected\n\n"
+        started = last_beat = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+        until @stopped
+          sleep @config.live_reload_interval
+          current = @reloader.snapshot
+          changed = LiveReload.diff(last, current)
+          unless changed.empty?
+            VueLive.store.clear if @config.reload? # make sure the next request recompiles
+            yield "event: change\ndata: #{JSON.generate(files: changed)}\n\n"
+            last = current
+          end
+          now = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+          break if now - started >= MAX_LIFETIME
+
+          if now - last_beat >= HEARTBEAT
+            yield ": ping\n\n"
+            last_beat = now
+          end
+        end
+      rescue Errno::EPIPE, Errno::ECONNRESET, Errno::ENOTCONN, IOError
+        nil # client went away
+      end
+    end
+
+    # Rack 2 style body: the server pulls frames with #each.
+    class Stream < Frames
+      def each(&block)
+        each_frame(&block)
+      end
+
+      def close
+        stop
+      end
+    end
+
+    # Rack 3 streaming body: the server hands us the connection and we push frames into it.
+    # Deliberately has no #each, otherwise servers would buffer it as an ordinary body.
+    class StreamingBody < Frames
+      def call(io)
+        each_frame do |frame|
+          io.write(frame)
+          io.flush if io.respond_to?(:flush)
+        end
+      ensure
+        begin
+          io.close if io.respond_to?(:close)
+        rescue IOError, SystemCallError
+          nil
+        end
+      end
+    end
+  end
+end

data/lib/vue_live/middleware.rb

@@ -0,0 +1,186 @@
+# frozen_string_literal: true
+
+require 'time'
+
+module VueLive
+  # Rack middleware answering requests under the configured prefix (default "/vue"):
+  #
+  #   GET /vue/App.vue            -> compiled ES module (also at /vue/App.vue.js)
+  #   GET /vue/components/x.js    -> any other allowed file under the component root, as-is
+  #   GET /vue/-/vue.esm-browser.js -> a local copy of Vue when the project has one
+  #   GET /vue/-/reload.js, /vue/-/events -> development live reload (client + SSE stream)
+  #
+  # Everything else is passed to the next app, so it can sit in front of Sprockets, Propshaft,
+  # Webpacker or ActionDispatch::Static without interfering with them.
+  #
+  #   use VueLive::Middleware                      # uses VueLive.config
+  #   use VueLive::Middleware, prefix: '/components', source_path: 'lib/vue'
+  class Middleware
+    MIME = {
+      '.vue' => 'text/javascript; charset=utf-8',
+      '.js' => 'text/javascript; charset=utf-8',
+      '.mjs' => 'text/javascript; charset=utf-8',
+      '.css' => 'text/css; charset=utf-8',
+      '.json' => 'application/json; charset=utf-8',
+      '.svg' => 'image/svg+xml',
+      '.png' => 'image/png',
+      '.jpg' => 'image/jpeg',
+      '.jpeg' => 'image/jpeg',
+      '.gif' => 'image/gif',
+      '.webp' => 'image/webp',
+      '.avif' => 'image/avif',
+      '.ico' => 'image/x-icon',
+      '.woff' => 'font/woff',
+      '.woff2' => 'font/woff2',
+      '.ttf' => 'font/ttf',
+      '.otf' => 'font/otf'
+    }.freeze
+
+    attr_reader :config
+
+    def initialize(app, options = {})
+      @app = app
+      options = options.dup
+      @config = if (cfg = options.delete(:config))
+                  cfg
+                elsif options.empty?
+                  VueLive.config
+                else
+                  VueLive.config.dup.apply(options)
+                end
+      # Share the global store when running on the global config so VueLive.store.clear works.
+      @store = @config.equal?(VueLive.config) ? nil : Store.new(@config)
+    end
+
+    def store
+      @store || VueLive.store
+    end
+
+    def call(env)
+      path = env['PATH_INFO'].to_s
+      prefix = config.normalized_prefix
+      return @app.call(env) unless path.start_with?("#{prefix}/")
+      return method_not_allowed unless %w[GET HEAD].include?(env['REQUEST_METHOD'])
+
+      rest = path[(prefix.length + 1)..]
+      return serve_internal(env, rest) if rest.start_with?('-/')
+
+      target = store.resolver.resolve(rest)
+      return @app.call(env) unless target
+
+      target.vue? ? serve_component(env, target) : serve_file(env, target)
+    end
+
+    private
+
+    def serve_component(env, target)
+      compiled = store.fetch(target.relative_path)
+      return not_modified if fresh?(env, compiled.etag)
+
+      headers = {
+        'content-type' => MIME['.vue'],
+        'etag' => compiled.etag,
+        'cache-control' => cache_control(env, compiled.digest),
+        'x-vue-live' => compiled.backend.to_s
+      }
+      respond(env, 200, headers, compiled.code)
+    rescue CompileError => e
+      config.logger.error("[vue_live] #{e.message}")
+      if config.production?
+        respond(env, 500, { 'content-type' => 'text/plain; charset=utf-8', 'cache-control' => 'no-store' },
+                "vue_live: failed to compile #{target.relative_path}\n")
+      else
+        respond(env, 200, { 'content-type' => MIME['.vue'], 'cache-control' => 'no-store' }, error_module(e))
+      end
+    end
+
+    def serve_file(env, target)
+      stat = File.stat(target.absolute_path)
+      etag = %("#{Store.file_etag(stat)}")
+      return not_modified if fresh?(env, etag)
+
+      ext = File.extname(target.relative_path).downcase
+      headers = {
+        'content-type' => MIME.fetch(ext, 'application/octet-stream'),
+        'etag' => etag,
+        'last-modified' => stat.mtime.httpdate,
+        'cache-control' => cache_control(env, etag.delete('"'))
+      }
+      respond(env, 200, headers, File.binread(target.absolute_path))
+    end
+
+    # Internal endpoints under <prefix>/-/.
+    def serve_internal(env, rest)
+      case rest
+      when '-/vue.esm-browser.js' then serve_vendor(env)
+      when '-/reload.js' then live_reload.enabled? ? live_reload.client_response : @app.call(env)
+      when '-/events' then live_reload.enabled? ? live_reload.stream_response(env) : @app.call(env)
+      else @app.call(env)
+      end
+    end
+
+    def live_reload
+      @live_reload ||= LiveReload.new(config)
+    end
+
+    # /vue/-/vue.esm-browser.js : serve the project's own copy of Vue when there is one.
+    def serve_vendor(env)
+      return @app.call(env) unless (file = config.local_vue_file)
+
+      stat = File.stat(file)
+      etag = %("vue-#{stat.size.to_s(16)}-#{stat.mtime.to_i.to_s(16)}")
+      return not_modified if fresh?(env, etag)
+
+      headers = { 'content-type' => MIME['.js'], 'etag' => etag, 'cache-control' => cache_control(env, etag.delete('"')) }
+      respond(env, 200, headers, File.binread(file))
+    end
+
+    # Digested URLs (?v=<digest>) are immutable; plain URLs must revalidate.
+    def cache_control(env, digest)
+      query = env['QUERY_STRING'].to_s
+      if query.match?(/(?:\A|&)v=#{Regexp.escape(digest)}(?:&|\z)/) && !config.reload?
+        'public, max-age=31536000, immutable'
+      else
+        'no-cache'
+      end
+    end
+
+    def fresh?(env, etag)
+      inm = env['HTTP_IF_NONE_MATCH']
+      inm && inm.split(',').map(&:strip).include?(etag)
+    end
+
+    def not_modified
+      [304, { 'cache-control' => 'no-cache' }, []]
+    end
+
+    def method_not_allowed
+      [405, { 'content-type' => 'text/plain', 'allow' => 'GET, HEAD' }, ['Method Not Allowed']]
+    end
+
+    def respond(env, status, headers, body)
+      body = body.to_s
+      headers['content-length'] = body.bytesize.to_s
+      [status, headers, env['REQUEST_METHOD'] == 'HEAD' ? [] : [body]]
+    end
+
+    # In development a broken component becomes a module that throws a readable error, so the
+    # failure shows up in the browser console (and in Vue's error overlay if any) instead of a
+    # bare network error.
+    def error_module(error)
+      message = Emitter.js_string("[vue_live] #{error.message}")
+      <<~JS
+        const message = #{message}
+        console.error(message)
+        if (typeof document !== 'undefined') {
+          const pre = document.createElement('pre')
+          pre.setAttribute('data-vue-live-error', '')
+          pre.style.cssText = 'position:fixed;left:0;right:0;bottom:0;margin:0;padding:16px;max-height:50vh;overflow:auto;z-index:2147483647;background:#300;color:#fdd;font:13px/1.4 monospace;white-space:pre-wrap;'
+          pre.textContent = message
+          document.body ? document.body.appendChild(pre) : document.addEventListener('DOMContentLoaded', () => document.body.appendChild(pre))
+        }
+        throw new Error(message)
+      JS
+    end
+  end
+end

data/lib/vue_live/node_tools.rb

@@ -0,0 +1,114 @@
+# frozen_string_literal: true
+
+require 'open3'
+require 'json'
+
+module VueLive
+  # Optional Node.js plumbing for the :node compiler backend.
+  #
+  # When the webpacker_cli gem is available its conventions are reused (package manager detection,
+  # project layout); otherwise a yarn.lock / package-lock.json sniff decides between yarn and npm.
+  module NodeTools
+    PACKAGES = ['@vue/compiler-sfc', 'vue'].freeze
+    # Node.js versions from here on strip TypeScript types themselves (node:module#stripTypeScriptTypes).
+    TYPE_STRIPPING_NODE = [22, 13].freeze
+    # npm packages compile.js can strip TypeScript with, when Node cannot.
+    TS_TRANSPILERS = %w[sucrase esbuild typescript @babel/core].freeze
+    DEFAULT_TS_TRANSPILER = 'sucrase'
+
+    module_function
+
+    def webpacker_cli?
+      return true if defined?(::WebpackerCli)
+
+      require 'webpacker_cli'
+      true
+    rescue LoadError
+      false
+    end
+
+    def node_version(config = VueLive.config)
+      out, status = Open3.capture2e(config.node_bin, '--version')
+      status.success? ? out.strip : nil
+    rescue Errno::ENOENT
+      nil
+    end
+
+    # true when the installed Node strips TypeScript on its own (>= 22.13).
+    def node_strips_types?(config = VueLive.config)
+      version = node_version(config)
+      return false unless version
+
+      major, minor = version.delete_prefix('v').split('.').map(&:to_i)
+      major > TYPE_STRIPPING_NODE[0] || (major == TYPE_STRIPPING_NODE[0] && minor >= TYPE_STRIPPING_NODE[1])
+    end
+
+    # The TypeScript transpiler packages installed under +root+.
+    def installed_ts_transpilers(root = VueLive.config.root)
+      TS_TRANSPILERS.select { |pkg| File.directory?(File.join(root, 'node_modules', *pkg.split('/'))) }
+    end
+
+    def package_manager(root = VueLive.config.root)
+      return ::WebpackerCli.package_manager(root) if webpacker_cli?
+      return 'npm' if File.exist?(File.join(root, 'package-lock.json')) && !File.exist?(File.join(root, 'yarn.lock'))
+      return 'yarn' if File.exist?(File.join(root, 'yarn.lock')) || which('yarn')
+
+      'npm'
+    end
+
+    def compiler_sfc_version(root = VueLive.config.root)
+      JSON.parse(File.read(File.join(root, 'node_modules', '@vue', 'compiler-sfc', 'package.json')))['version']
+    rescue StandardError
+      nil
+    end
+
+    def vue_version(root = VueLive.config.root)
+      JSON.parse(File.read(File.join(root, 'node_modules', 'vue', 'package.json')))['version']
+    rescue StandardError
+      nil
+    end
+
+    # Install @vue/compiler-sfc (and vue, for a local copy of the browser build) into the project.
+    def setup(root = VueLive.config.root, packages: PACKAGES, dev: true)
+      raise Error, 'Node.js was not found in PATH; install it to use the :node compiler' unless node_version
+
+      pkg_json = File.join(root, 'package.json')
+      File.write(pkg_json, JSON.pretty_generate('name' => File.basename(root), 'private' => true)) unless File.exist?(pkg_json)
+      manager = package_manager(root)
+      cmd = if manager == 'yarn'
+              ['yarn', 'add', *(dev ? ['--dev'] : []), *packages]
+            else
+              ['npm', 'install', *(dev ? ['--save-dev'] : []), *packages]
+            end
+      puts "  run    #{cmd.join(' ')}"
+      success = system(*cmd, chdir: root)
+      raise Error, "#{manager} failed to install #{packages.join(', ')}" unless success
+
+      Compiler::Node.reset!
+      true
+    end
+
+    # Human-readable status for `vue-live check`.
+    def problems(config = VueLive.config)
+      problems = []
+      problems << "component directory does not exist: #{config.source_dir}" unless File.directory?(config.source_dir)
+      if %i[node].include?(config.compiler.to_sym)
+        problems << 'Node.js was not found in PATH (required by compiler: node)' unless node_version(config)
+        problems << '@vue/compiler-sfc is not installed (run `vue-live node-setup`)' unless compiler_sfc_version(config.root)
+      end
+      if %i[node auto].include?(config.compiler.to_sym) && node_version(config) && !node_strips_types?(config) &&
+         installed_ts_transpilers(config.root).empty?
+        problems << "Node.js #{node_version(config)} cannot strip TypeScript and no transpiler is installed; " \
+                    '<script lang="ts"> components will fail (run `vue-live node-setup --with sucrase`)'
+      end
+      problems
+    end
+
+    def which(cmd)
+      ENV['PATH'].to_s.split(File::PATH_SEPARATOR).any? do |p|
+        f = File.join(p, cmd)
+        File.executable?(f) && !File.directory?(f)
+      end
+    end
+  end
+end

data/lib/vue_live/precompiler.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+require 'fileutils'
+require 'json'
+
+module VueLive
+  # Writes every component as a static `.vue.js` module (plus sibling assets and a manifest) so
+  # a CDN or plain file server can serve them.  Optional: the middleware is the normal path.
+  #
+  #   VueLive::Precompiler.new.run            #=> public/vue/App.vue.js, public/vue/manifest.json
+  #
+  # The manifest maps "App.vue" => "/vue/App.vue.js?v=<digest>" and is used by vue_live_path when
+  # config.use_manifest? is true.
+  class Precompiler
+    attr_reader :config, :store, :errors
+
+    def initialize(config = VueLive.config, store: nil)
+      @config = config
+      @store = store || Store.new(config)
+    end
+
+    # Compiles everything it can.  Components that fail are reported (and collected in #errors);
+    # pass strict: true to raise on the first failure instead.
+    def run(output: config.precompile_dir, quiet: false, strict: false, out: $stdout)
+      FileUtils.mkdir_p(output)
+      manifest = {}
+      @errors = errors = []
+      prefix = config.normalized_prefix
+
+      store.resolver.files.each do |rel|
+        src = File.join(store.resolver.source_dir, rel)
+        if rel.end_with?('.vue')
+          begin
+            compiled = store.fetch(rel)
+          rescue Error => e
+            errors << e
+            out.puts "  FAIL   #{rel}: #{e.message}" unless quiet
+            next
+          end
+          dest = File.join(output, "#{rel}.js")
+          write(dest, compiled.code)
+          manifest[rel] = "#{prefix}/#{rel}.js?v=#{compiled.digest}"
+        else
+          dest = File.join(output, rel)
+          FileUtils.mkdir_p(File.dirname(dest))
+          FileUtils.cp(src, dest)
+          manifest[rel] = "#{prefix}/#{rel}"
+        end
+        out.puts "  write  #{dest}" unless quiet
+      end
+
+      if (vue = config.local_vue_file)
+        dest = File.join(output, '-', 'vue.esm-browser.js')
+        FileUtils.mkdir_p(File.dirname(dest))
+        FileUtils.cp(vue, dest)
+        out.puts "  write  #{dest}" unless quiet
+      end
+
+      write(File.join(output, 'manifest.json'), JSON.pretty_generate(manifest))
+      raise errors.first if strict && errors.any?
+
+      manifest
+    end
+
+    def clobber(output: config.precompile_dir)
+      FileUtils.rm_rf(output)
+    end
+
+    def self.manifest(config = VueLive.config)
+      @manifests ||= {}
+      path = config.manifest_path
+      return @manifests[path] if @manifests[path] && !config.reload?
+
+      @manifests[path] = File.file?(path) ? JSON.parse(File.read(path)) : {}
+    end
+
+    def self.reset!
+      @manifests = {}
+    end
+
+    private
+
+    def write(dest, content)
+      FileUtils.mkdir_p(File.dirname(dest))
+      File.write(dest, content)
+    end
+  end
+end

data/lib/vue_live/rails/helper.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module VueLive
+  module Rails
+    # ActionView flavour of VueLive::Helpers: html_safe output, automatic CSP nonces and
+    # cooperation with importmap-rails (browsers honour only one import map per page).
+    module Helper
+      include VueLive::Helpers
+
+      def vue_live_import_map_tag(imports: {}, nonce: nil)
+        super(imports: imports, nonce: nonce || vue_live_csp_nonce).html_safe
+      end
+
+      def vue_live_mount_tag(component, selector = '#app', nonce: nil, **options)
+        super(component, selector, nonce: nonce || vue_live_csp_nonce, **options).html_safe
+      end
+
+      def vue_live_module_tag(javascript, nonce: nil)
+        super(javascript, nonce: nonce || vue_live_csp_nonce).html_safe
+      end
+
+      def vue_live_tags(component, selector = '#app', **options)
+        super.html_safe
+      end
+
+      def vue_live_reload_tag(nonce: nil)
+        super(nonce: nonce || vue_live_csp_nonce).html_safe
+      end
+
+      private
+
+      def vue_live_csp_nonce
+        respond_to?(:content_security_policy_nonce, true) ? content_security_policy_nonce : nil
+      end
+
+      # importmap-rails owns the page's import map; the Railtie pins `vue` into it instead.
+      # Set config.vue_live.importmap_pin = false to keep the two separate.
+      def vue_live_external_importmap?
+        defined?(::Importmap::Map) && VueLive.config.importmap_pin ? true : false
+      end
+    end
+  end
+end

data/lib/vue_live/railtie.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+require 'rails/railtie'
+require_relative '../vue_live'
+require_relative 'rails/helper'
+
+module VueLive
+  # Wires vue_live into a Rails application with no configuration:
+  #
+  #   * `config.vue_live` exposes every Configuration option (config.vue_live.prefix = '/components')
+  #   * config/vue_live.yml is read when present (`rails g vue_live:install` writes one)
+  #   * the middleware is mounted ahead of the asset pipeline's static file server, answering
+  #     only `/vue/...`, so Sprockets, Propshaft, Webpacker and jsbundling keep their own paths
+  #   * view helpers are added to ActionView
+  #   * when importmap-rails is present, `vue` is pinned into the app's import map
+  #   * rake tasks: vue_live:precompile, vue_live:clobber, vue_live:check, vue_live:node_setup
+  class Railtie < ::Rails::Railtie
+    config.vue_live = ActiveSupport::OrderedOptions.new
+
+    # Make `Rails.root`, `Rails.env` and `Rails.logger` the source of truth before anything reads them.
+    initializer 'vue_live.configure', before: :load_environment_config do |app|
+      VueLive.config.root = app.root.to_s
+      VueLive.config.env = ::Rails.env.to_s
+      VueLive.config.logger = ::Rails.logger if ::Rails.logger
+    end
+
+    initializer 'vue_live.apply_configuration', after: :load_environment_config do |app|
+      VueLive.config.root = app.root.to_s
+      VueLive.config.env = ::Rails.env.to_s
+      VueLive.load_config_file
+      VueLive.config.apply(app.config.vue_live.to_h)
+      VueLive.reset_store!
+    end
+
+    initializer 'vue_live.middleware' do |app|
+      app.config.after_initialize do
+        VueLive.config.logger ||= ::Rails.logger
+      end
+      next unless app.config.vue_live.fetch(:middleware, true)
+
+      if defined?(::ActionDispatch::Static) && app.middleware.respond_to?(:insert_before)
+        begin
+          app.middleware.insert_before ::ActionDispatch::Static, VueLive::Middleware
+        rescue StandardError
+          app.middleware.use VueLive::Middleware
+        end
+      else
+        app.middleware.use VueLive::Middleware
+      end
+    end
+
+    initializer 'vue_live.helpers' do
+      ActiveSupport.on_load(:action_view) { include VueLive::Rails::Helper }
+    end
+
+    initializer 'vue_live.importmap', after: 'importmap' do |app|
+      next unless defined?(::Importmap) && app.respond_to?(:importmap)
+
+      app.config.after_initialize do
+        next unless VueLive.config.importmap_pin
+
+        map = app.importmap
+        next if map.packages.key?('vue')
+
+        map.draw { pin 'vue', to: VueLive.config.resolved_vue_url, preload: true }
+      end
+    end
+
+    rake_tasks do
+      load File.expand_path('tasks.rake', __dir__)
+    end
+
+    generators do
+      require_relative '../generators/vue_live/install/install_generator'
+    end
+  end
+end