turbo-train 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 49c31938503f032280b36b7c2cb38d021a9a1fd9c14b685fbe37b59d3a03fc76
+  data.tar.gz: 12da15ef47ca0a4848fe247fe5e5529704583bb68a66868c21981a0e29b43535
+SHA512:
+  metadata.gz: 7327f19a04e59f9877deea564bd9be9e6f2573e78ee2a3a8ff47857a39da613582fa5a6b2d4caeaf53ef3b487aa3995c9e3b022cd9a54b49a8dae5415d7d093b
+  data.tar.gz: dc36a1d51ab9463efd671f8b6f8dcf1dcb2a2a432fa00ac96fc184d9efa3566669f0ab5c863d833af8899a04b07e71c43ea735b2f230c420ea2308a4728fb221

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright 2022 goodsign
+
+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,107 @@
+![Build Status](https://github.com/Uscreen-video/turbo-train/actions/workflows/main.yml/badge.svg)
+
+# Turbo::Train
+
+<img align="right" width="160" title="Turbo::Train logo"
+     src="./logo.svg">
+
+Real-time page updates for your Rails app over SSE with [Mercure](https://mercure.rocks) and [Hotwire Turbo](https://turbo.hotwired.dev/handbook/streams#integration-with-server-side-frameworks).
+
+* **Uses [SSE](https://html.spec.whatwg.org/multipage/server-sent-events.html)**. No more websockets, client libraries, JS code and handling reconnects. Just an HTTP connection. Let the [browser](https://caniuse.com/eventsource) do the work.
+* **Seamless Hotwire integration.** Use it exactly like [ActionCable](https://github.com/hotwired/turbo-rails#come-alive-with-turbo-streams). Drop-in replacement for `broadcast_action_to` and usual helpers.
+* **Simple.** Get running in minutes, scale easily in production 🚀 
+
+## Before your proceed
+
+Using this gem requires some knowledge of ActionCable and broadcasting turbo streams. Turbo::Train is designed to mimic those, so it is highly recommended to first try the original to understand the concept.
+
+You can start [here](https://hotwired.dev/) and proceed with the [Turbo Handbook](https://turbo.hotwired.dev/handbook/introduction). One of its chapters will be covering [Turbo Streams](https://turbo.hotwired.dev/handbook/streams). Specifically [this section](https://turbo.hotwired.dev/handbook/streams#integration-with-server-side-frameworks) would be the main prerequisite to understanding what this gem is about: it covers [Broadcastable](https://github.com/hotwired/turbo-rails/blob/main/app/models/concerns/turbo/broadcastable.rb) and the overall idea of working with Mercure.
+
+## Prerequisites
+
+1. Rails 7+
+2. Mercure server (setup instructions below)
+
+This should also work for Rails 6, but you will also need to install [turbo-rails](https://github.com/hotwired/turbo-rails#installation) manually before this gem.
+
+## Installation
+
+### Step 1. Turbo::Train
+
+Instructions for Rails 7+
+
+1. Add the turbo-train gem to your Gemfile: `gem 'turbo-train'`
+2. Run `bundle install`
+3. Run `rails turbo_train:install`
+
+Instructions for Rails 6
+
+1. Install [turbo-rails](https://github.com/hotwired/turbo-rails#installation)
+2. Repeat steps for Rails 7 above
+
+### Step 2. Mercure
+
+Mercure is installed as a plugin to [Caddy](https://github.com/caddyserver/caddy) server. For mac users everything is pretty easy:
+
+```
+brew install caddy
+```
+
+```
+caddy add-package github.com/dunglas/mercure/caddy
+```
+
+Now you are ready to run 🚀
+
+```
+caddy run
+```
+
+
+## Usage
+
+If you are familiar with broadcasting from ActionCable, usage would be extremely familiar:
+
+```
+<%# app/views/chat_messages/index.html.erb %>
+<%= turbo_train_from "chat_messages" %>
+
+<div id="append_new_messages_here"></div>
+```
+
+And then you can send portions of HTML from your Rails backend to deliver live to all currently open browsers:
+
+```
+Turbo::Train.broadcast_action_to('chat_messages', action: :append, target:'append_new_messages_here', html: '<span>Test!</span>')
+```
+
+or in real world you'd probably have something like
+
+```
+# app/models/chat_message.rb
+after_create_commit { Turbo::Train.broadcast_action_to('chat_messages', action: :append, target:'append_new_messages_here', partial: 'somepath/message') }
+```
+
+You have the same options as original Rails Turbo helpers: rendering partials, pure html, [same actions](https://turbo.hotwired.dev/reference/streams).
+
+## Configuration
+
+To specify different Mercure server settings, please adjust the generated `config/initializers/turbo_train.rb` file:
+
+```
+Turbo::Train.configure do |config|
+  config.mercure_domain = ...
+  config.publisher_key = ...
+  config.subscriber_key = ...
+end
+```
+
+* Your SSE will connect to `https://#{configuration.mercure_domain}/.well-known`. 
+* The publisher/subscriber key correspond to the [configuration](https://mercure.rocks/docs/hub/config) or your Mercure server.
+
+By default, these are set to `localhost`/`test`/`testing` to match the configuration of the local development server from the installation instructions above.
+
+***
+
+## License
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,8 @@
+require "bundler/setup"
+
+APP_RAKEFILE = File.expand_path("test/dummy/Rakefile", __dir__)
+load "rails/tasks/engine.rake"
+
+load "rails/tasks/statistics.rake"
+
+require "bundler/gem_tasks"

data/app/assets/javascripts/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "@uscreentv/turbo-train",
+  "version": "0.0.2",
+  "description": "",
+  "main": "turbo-train.js",
+  "type": "module",
+  "exports": {
+    ".": {
+      "import": "./turbo-train.js"
+    }
+  },
+  "scripts": {
+    "test": "echo \"Error: no test specified\" && exit 1"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Uscreen-video/turbo-train.git"
+  },
+  "author": "",
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/Uscreen-video/turbo-train/issues"
+  },
+  "homepage": "https://github.com/Uscreen-video/turbo-train#readme",
+  "peerDependencies": {
+    "@hotwired/turbo-rails": ">=7.0.0"
+  }
+}

data/app/assets/javascripts/turbo-train.js

@@ -0,0 +1,39 @@
+import { Turbo } from "@hotwired/turbo-rails"
+
+export default class TurboTrain extends HTMLElement {
+  static get observedAttributes() {
+    return [ 'href', 'session', 'name' ];
+  }
+
+  constructor() {
+    super();
+  }
+
+  connectedCallback() {
+    this.eventSource = new EventSource(`${this.href}/mercure?topic=${this.name}&authorization=${this.session}`);
+    Turbo.connectStreamSource(this.eventSource);
+  }
+
+  disconnectedCallback() {
+    Turbo.disconnectStreamSource(this.eventSource);
+  }
+
+  get href() {
+    return this.getAttribute('href');
+  }
+
+  get session() {
+    return this.getAttribute('session');
+  }
+
+  get name() {
+    return this.getAttribute('name');
+  }
+}
+
+if (
+  typeof window !== 'undefined' &&
+  !window.customElements.get('turbo-train-stream-source')
+) {
+  window.customElements.define('turbo-train-stream-source', TurboTrain)
+}

data/app/assets/javascripts/turbo-train.min.js

@@ -0,0 +1 @@
+import{Turbo as e}from"@hotwired/turbo-rails";export default class t extends HTMLElement{static get observedAttributes(){return["href","session","name"]}constructor(){super()}connectedCallback(){this.eventSource=new EventSource(`${this.href}/mercure?topic=${this.name}&authorization=${this.session}`),e.connectStreamSource(this.eventSource)}disconnectedCallback(){e.disconnectStreamSource(this.eventSource)}get href(){return this.getAttribute("href")}get session(){return this.getAttribute("session")}get name(){return this.getAttribute("name")}};"undefined"==typeof window||window.customElements.get("turbo-train-stream-source")||window.customElements.define("turbo-train-stream-source",t);

data/app/controllers/turbo/train/test/application_controller.rb

@@ -0,0 +1,8 @@
+module Turbo
+  module Train
+    module Test
+      class ApplicationController < ActionController::Base
+      end
+    end
+  end
+end

data/app/helpers/turbo/train/streams_helper.rb

@@ -0,0 +1,8 @@
+module Turbo::Train::StreamsHelper
+  def turbo_train_from(*streamables, **attributes)
+    attributes[:name] = Turbo::Train.signed_stream_name(streamables)
+    attributes[:session] = Turbo::Train.encode({ platform: "web" })
+    attributes[:href] = Turbo::Train.url
+    tag.turbo_train_stream_source(**attributes)
+  end
+end

data/app/jobs/turbo/train/test/application_job.rb

@@ -0,0 +1,8 @@
+module Turbo
+  module Train
+    module Test
+      class ApplicationJob < ActiveJob::Base
+      end
+    end
+  end
+end

data/app/mailers/turbo/train/test/application_mailer.rb

@@ -0,0 +1,10 @@
+module Turbo
+  module Train
+    module Test
+      class ApplicationMailer < ActionMailer::Base
+        default from: "from@example.com"
+        layout "mailer"
+      end
+    end
+  end
+end

data/app/models/turbo/train/test/application_record.rb

@@ -0,0 +1,9 @@
+module Turbo
+  module Train
+    module Test
+      class ApplicationRecord < ActiveRecord::Base
+        self.abstract_class = true
+      end
+    end
+  end
+end

data/app/views/layouts/turbo/train/test/application.html.erb

@@ -0,0 +1,15 @@
+<!DOCTYPE html>
+<html>
+<head>
+  <title>Turbo train test</title>
+  <%= csrf_meta_tags %>
+  <%= csp_meta_tag %>
+
+  <%= stylesheet_link_tag    "turbo/train/application", media: "all" %>
+</head>
+<body>
+
+<%= yield %>
+
+</body>
+</html>

data/config/routes.rb

@@ -0,0 +1,2 @@
+Turbo::Train::Engine.routes.draw do
+end

data/lib/install/create_caddyfile.rb

@@ -0,0 +1,16 @@
+say "Creating Caddyfile"
+create_file Rails.root.join("Caddyfile") do
+  %{
+localhost
+
+route {
+    mercure {
+        publisher_jwt testing
+        subscriber_jwt test
+        cors_origins "*"
+    }
+
+    respond "Not Found" 404
+}
+  }
+end

data/lib/install/create_initializer.rb

@@ -0,0 +1,11 @@
+say "Creating initializer"
+create_file Rails.root.join("config/initializers/turbo_train.rb") do
+  %{
+Turbo::Train.configure do |config|
+  config.mercure_domain = 'localhost'
+  config.publisher_key = 'testing'
+  config.subscriber_key = 'test'
+  config.skip_ssl_verification = true # Development only; don't do this in production
+end
+  }
+end

data/lib/install/install_importmap.rb

@@ -0,0 +1,5 @@
+say "Import Turbo"
+append_to_file "app/javascript/application.js", %(import "@uscreentv/turbo-train"\n)
+
+say "Pin Turbo"
+append_to_file "config/importmap.rb", %(pin "@uscreentv/turbo-train", to: "turbo-train.min.js", preload: true\n)

data/lib/install/install_node.rb

@@ -0,0 +1,21 @@
+if Rails.root.join("yarn.lock").exist?
+  say "Detected yarn.lock. Installing Turbo Train with yarn"
+  run "yarn add @uscreentv/turbo-train"
+elsif Rails.root.join("pnpm-lock.yaml").exist?
+  say "Detected pnpm-lock.yaml. Installing Turbo Train with pnpm"
+  run "pnpm add @uscreentv/turbo-train -w"
+elsif Rails.root.join("package-lock.json").exist?
+  say "Detected package-lock.json. Installing Turbo Train with npm"
+  run "npm add @uscreentv/turbo-train"
+else
+  say "We could not automatically install the @uscreentv/turbo-train JS library", :red
+  say "  -> You must manually install the @uscreentv/turbo-train JS package.", :red
+end
+
+if (js_entrypoint_path = Rails.root.join("app/javascript/application.js")).exist?
+  say "Importing Turbo Train"
+  append_to_file "app/javascript/application.js", %(import "@uscreentv/turbo-train"\n)
+else
+  say "We could not automatically detect your JS entrypoint (such as app/javascript/application.js)", :red
+  say "  -> You must manually import @uscreentv/turbo-train in your JavaScript entrypoint file.", :red
+end

data/lib/tasks/install_tasks.rake

@@ -0,0 +1,32 @@
+def run_install_template(path)
+  system "#{RbConfig.ruby} ./bin/rails app:template LOCATION=#{File.expand_path("../install/#{path}.rb", __dir__)}"
+end
+
+namespace :turbo_train do
+  desc "Install Turbo::Train into the app"
+  task :install do
+    run_install_template 'create_initializer'
+    run_install_template 'create_caddyfile'
+
+    if Rails.root.join("config/importmap.rb").exist?
+      Rake::Task["turbo_train:install:importmap"].invoke
+    elsif Rails.root.join("package.json").exist?
+      Rake::Task["turbo_train:install:node"].invoke
+    else
+      puts "We can't detect neither (package.json) nor importmap-rails (config/importmap.rb) 🙁"
+      puts "Please refer to https://github.com/Uscreen-video/turbo-train/blob/main/README.md#installation for manual installation instructions."
+    end
+  end
+
+  namespace :install do
+    desc "Install Turbo::Train into the app with asset pipeline"
+    task :importmap do
+      run_install_template "install_importmap"
+    end
+
+    desc "Install Turbo::Train into the app with webpacker"
+    task :node do
+      run_install_template "install_node"
+    end
+  end
+end

data/lib/turbo/train/config.rb

@@ -0,0 +1,23 @@
+module Turbo
+  module Train
+    class Configuration
+      attr_accessor :mercure_domain, :publisher_key, :subscriber_key, :skip_ssl_verification
+
+      def initialize
+        @mercure_domain = 'localhost'
+        @publisher_key = 'test'
+        @subscriber_key = 'testing'
+        @skip_ssl_verification = Rails.env.development? || Rails.env.test?
+      end
+    end
+
+    class << self
+      attr_accessor :configuration
+
+      def configure
+        self.configuration ||= Configuration.new
+        yield(configuration)
+      end
+    end
+  end
+end

data/lib/turbo/train/engine.rb

@@ -0,0 +1,29 @@
+require 'turbo-rails'
+
+module Turbo
+  module Train
+    class Engine < ::Rails::Engine
+      isolate_namespace Turbo::Train
+
+      PRECOMPILE_ASSETS = %w( turbo-train.js turbo-train.min.js )
+
+      initializer "turbotrain.assets" do
+        if Rails.application.config.respond_to?(:assets)
+          Rails.application.config.assets.precompile += PRECOMPILE_ASSETS
+        end
+      end
+
+      initializer "turbotrain.helpers", before: :load_config_initializers do
+        ActiveSupport.on_load(:action_controller_base) do
+          helper Turbo::Train::StreamsHelper
+        end
+      end
+
+      initializer "turbotrain.load" do
+        ActiveSupport.on_load(:active_record) do
+          require_relative 'train'
+        end
+      end
+    end
+  end
+end

data/lib/turbo/train/train.rb

@@ -0,0 +1,114 @@
+require 'jwt'
+require 'net/http'
+
+module Turbo
+  module Train
+    extend Turbo::Streams::ActionHelper
+
+    ALGORITHM = "HS256"
+
+    class << self
+      def url
+        "https://#{configuration.mercure_domain}/.well-known"
+      end
+
+      def encode(payload)
+        structured_payload = { mercure: { payload: payload } }
+        JWT.encode structured_payload, configuration.subscriber_key, ALGORITHM
+      end
+
+      def signed_stream_name(streamables)
+        Turbo.signed_stream_verifier.generate stream_name_from(streamables)
+      end
+
+      def broadcast_action_to(*streamables, action:, target: nil, targets: nil, **rendering)
+        broadcast(streamables, content: turbo_stream_action_tag(action, target: target, targets: targets, template:
+          rendering.delete(:content) || rendering.delete(:html) || (rendering.any? ? render_format(:html, **rendering) : nil)
+        ))
+      end
+
+      def broadcast_render_to(*streamables, **rendering)
+        broadcast(*streamables, content: render_format(:turbo_stream, **rendering))
+      end
+
+      def broadcast_remove_to(*streamables, **opts)
+        broadcast_action_to(*streamables, action: :remove, **opts)
+      end
+
+      def broadcast_replace_to(*streamables, **opts)
+        broadcast_action_to(*streamables, action: :replace, **opts)
+      end
+
+      def broadcast_update_to(*streamables, **opts)
+        broadcast_action_to(*streamables, action: :update, **opts)
+      end
+
+      def broadcast_before_to(*streamables, **opts)
+        broadcast_action_to(*streamables, action: :before, **opts)
+      end
+
+      def broadcast_after_to(*streamables, **opts)
+        broadcast_action_to(*streamables, action: :after, **opts)
+      end
+
+      def broadcast_append_to(*streamables, **opts)
+        broadcast_action_to(*streamables, action: :append, **opts)
+      end
+
+      def broadcast_prepend_to(*streamables, **opts)
+        broadcast_action_to(*streamables, action: :prepend, **opts)
+      end
+
+      private
+
+      def domain
+        Rails.configuration.turbo_train.mercure_domain
+      end
+
+      def render_format(format, **rendering)
+        ApplicationController.render(formats: [ format ], **rendering)
+      end
+
+      def broadcast(streamables, content:)
+        topics = if streamables.is_a?(Array)
+          streamables.map { |s| signed_stream_name(s) }
+        else
+          [signed_stream_name(streamables)]
+        end
+
+        data = {
+          topic: topics,
+          data: content
+        }
+        payload = { mercure: { publish: topics } }
+        token = JWT.encode payload, configuration.publisher_key, ALGORITHM
+
+        uri = URI("#{url}/mercure")
+
+        req = Net::HTTP::Post.new(uri)
+        req['Content-Type'] = 'application/x-www-form-urlencoded'
+        req['Authorization'] = "Bearer #{token}"
+        req.body = URI.encode_www_form(data)
+        opts = {
+          use_ssl: uri.scheme == 'https'
+        }
+
+        if configuration.skip_ssl_verification
+          opts[:verify_mode] = OpenSSL::SSL::VERIFY_NONE
+        end
+
+        Net::HTTP.start(uri.host, uri.port, opts) do |http|
+          http.request(req)
+        end
+      end
+
+      def stream_name_from(streamables)
+        if streamables.is_a?(Array)
+          streamables.map  { |streamable| stream_name_from(streamable) }.join(":")
+        else
+          streamables.then { |streamable| streamable.try(:to_gid_param) || streamable.to_param }
+        end
+      end
+    end
+  end
+end

data/lib/turbo/train/version.rb

@@ -0,0 +1,5 @@
+module Turbo
+  module Train
+    VERSION = "0.0.1"
+  end
+end

data/lib/turbo/train.rb

@@ -0,0 +1,3 @@
+require "turbo/train/version"
+require "turbo/train/config"
+require "turbo/train/engine"

metadata

@@ -0,0 +1,114 @@
+--- !ruby/object:Gem::Specification
+name: turbo-train
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+platform: ruby
+authors:
+- Nick Savrov
+- Dima Bondarenko
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2022-12-14 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.1'
+- !ruby/object:Gem::Dependency
+  name: turbo-rails
+  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: jwt
+  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'
+description: 
+email:
+- nick@uscreen.tv
+- dmitry@uscreen.tv
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- MIT-LICENSE
+- README.md
+- Rakefile
+- app/assets/config/turbo_train_test_manifest.js
+- app/assets/javascripts/package.json
+- app/assets/javascripts/turbo-train.js
+- app/assets/javascripts/turbo-train.min.js
+- app/controllers/turbo/train/test/application_controller.rb
+- app/helpers/turbo/train/streams_helper.rb
+- app/jobs/turbo/train/test/application_job.rb
+- app/mailers/turbo/train/test/application_mailer.rb
+- app/models/turbo/train/test/application_record.rb
+- app/views/layouts/turbo/train/test/application.html.erb
+- config/routes.rb
+- lib/install/create_caddyfile.rb
+- lib/install/create_initializer.rb
+- lib/install/install_importmap.rb
+- lib/install/install_node.rb
+- lib/tasks/install_tasks.rake
+- lib/turbo/train.rb
+- lib/turbo/train/config.rb
+- lib/turbo/train/engine.rb
+- lib/turbo/train/train.rb
+- lib/turbo/train/version.rb
+homepage: https://github.com/Uscreen-video/turbo-train
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/Uscreen-video/turbo-train
+  source_code_uri: https://github.com/goodsign/turbo-train-test
+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: []
+rubygems_version: 3.1.6
+signing_key: 
+specification_version: 4
+summary: Rails Turbo Stream broadcasting over SSE instead of WebSockets. Uses Mercure
+  server.
+test_files: []