turbo-replay 0.1.0 → 0.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d51efac005c1642592ebccb9753657e2be702141014bc0ebae2e7d4757aee362
-  data.tar.gz: ae00e5f49f8f106ef525e5efa7f3f6abe01b2676553b64f2c8bbfe9f943e23f1
+  metadata.gz: abe7572c62c8e9b824b44428d238bb7fb99cc4efd69ba2515d931634a8db8e8c
+  data.tar.gz: 2b7701bddfb6941f3bd53aa877fd83d9788fc8a3681c773705f5ff8770ad9df6
 SHA512:
-  metadata.gz: 6ff54759f20fdd6cbb6c6a23f926297d9f12eb5d86ae96617b212a98eb0c53d421d2c676020cf89778ef56795ef7cc8a2a213f8f12b710e5d198948995508e8a
-  data.tar.gz: 1cd690000760467b1ded8d168d26621d69fd08c255ca1d688c5e83d43c8d0df12038cb0e41a94b4af45a47f84cd2663eced22f3edc1c6ca0129ba18c1e5a3343
+  metadata.gz: 1aaa04169166308ded72caee2f1c2903b0cfc57951d75755494346309ca387fa9c7bec50da051c203040ec57162b49f3acca76788b7f83976ca9b4b8db0dc945
+  data.tar.gz: 0472f0f884358bab6d623a2f107a473520a5e87032fc2cb6045c48b3b00364e8518ba429c84cf4e21698ce4d1392da74dd9c7c4f586ecb5906e3e6944a427edc

data/README.md

@@ -1,28 +1,93 @@
-# Turbo::Replay
-Short description and motivation.
+# turbo-replay
 
-## Usage
-How to use my plugin.
+**turbo-replay** assigns a sequence number to broadcasted messages and caches them. When a client 
+disconnects because of flaky network, we're able to resend (or replay, hence the name) missed
+messages in the same order they were originally sent.
 
 ## Installation
+
+> **Important**: Make sure you have installed [`hotwired/turbo-rails`](https://github.com/hotwired/turbo-rails) before using this gem!
+
 Add this line to your application's Gemfile:
 
 ```ruby
 gem "turbo-replay"
 ```
 
-And then execute:
+Execute the following commands to install the gem and generate an initializer:
+
 ```bash
-$ bundle
+$ bin/bundle install
+$ bin/rails turbo-replay:install
 ```
 
-Or install it yourself as:
-```bash
-$ gem install turbo-replay
+Replace the import for `@hotwired/turbo-rails` in your application.js
+
+```diff
+- import "@hotwired/turbo-rails"
++ import "turbo-replay"
+```
+
+Now reload your server - and that's it!
+
+### Javascript events
+
+```javascript
+// The user connected for the first time to a channel.
+window.addEventListener('turbo-replay:connected', (ev) => {
+  console.log('connected', ev.detail.channel)
+})
+
+// The user disconnected from a channel and we're retrying to reconnect.
+// It's good to show some 'reconnecting...' indication here.
+window.addEventListener('turbo-replay:disconnected', (ev) => {
+  console.log('disconnected', ev.detail.channel)
+})
+
+// The user reconnected after being offline a little bit.
+// Hide the 'reconnecting...' indicationk here.
+window.addEventListener('turbo-replay:reconnected', (ev) => {
+  console.log('reconnected', ev.detail.channel)
+})
+
+// The user reconnected, but the latest received message was older
+// than the oldest message in the cache. There's nothing we can do
+// here to recover the state. You can reload the whole application
+// or show some indication asking the user to reload.
+window.addEventListener('turbo-replay:unrecoverable', (ev) => {
+  console.log('unrecoverable', ev.detail.channel)
+})
 ```
 
-## Contributing
-Contribution directions go here.
+### How does it work?
+
+**turbo-replay** stores broadcasted messages in a cache. Each message is assigned a sequence number.
+
+Because the sequence number is sequential, clients know what the next value is expected to be.
+If an arrived `sequence_number` doesn't match the expected value, it means the client missed a message.
+
+> The sequence number ensures clients can detect missed messages even without a disconnect event.
+
+When the client notices they missed an event, they ask the server to resend messages after the last known
+sequence number.
+
+### I like to broadcast lots of stuff, isn't the cache too much overhead?
+
+Maybe, it depends on your use case. Take a look at `config/initializers/turbo_replay.rb` in your
+application to tweak the cache's retention policy.
+
+### What if the client stays offline too long?
+
+There's nothing we can do if the client's latest received message is older than the oldest message in the cache.
+
+Suggestion: handle the `turbo-replay:unrecoverable` event and display a message asking the user
+to reload the app. For example:
+
+```js
+window.addEventListener('turbo-replay:unrecoverable', () => {
+  window.alert("You're offline for too long. Please reload the page.")
+})
+```
 
 ## License
 The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -1,3 +1,16 @@
 require "bundler/setup"
 require "bundler/gem_tasks"
+require "rake/testtask"
 require "standard/rake"
+
+APP_RAKEFILE = File.expand_path("test/dummy/Rakefile", __dir__)
+load "rails/tasks/engine.rake"
+load "rails/tasks/statistics.rake"
+
+Rake::TestTask.new do |test|
+  test.libs << "test"
+  test.test_files = FileList["test/**/*_test.rb"]
+  test.warning = false
+end
+
+task default: :test

data/app/javascript/turbo-replay/cable.js

@@ -0,0 +1,19 @@
+let consumer
+
+export async function getConsumer() {
+  return consumer || setConsumer(createConsumer().then(setConsumer))
+}
+
+export function setConsumer(newConsumer) {
+  return consumer = newConsumer
+}
+
+export async function createConsumer() {
+  const { createConsumer } = await import(/* webpackChunkName: "actioncable" */ "@rails/actioncable/src")
+  return createConsumer()
+}
+
+export async function subscribeTo(channel, mixin) {
+  const { subscriptions } = await getConsumer()
+  return subscriptions.create(channel, mixin)
+}

data/app/javascript/turbo-replay/cable_stream_source_element.js

@@ -0,0 +1,114 @@
+import { connectStreamSource, disconnectStreamSource } from "@hotwired/turbo"
+import { subscribeTo } from "./cable"
+import snakeize from "./snakeize"
+
+const UNRECOVERABLE_RESULT = "unrecoverable"
+
+class TurboCableStreamSourceElement extends HTMLElement {
+  async connectedCallback() {
+    connectStreamSource(this)
+
+    this.subscription = await subscribeTo(this.channel, {
+      connected: this.handleConnected.bind(this),
+      disconnected: this.handleDisconnected.bind(this),
+      received: this.handleMessage.bind(this)
+    })
+  }
+
+  disconnectedCallback() {
+    disconnectStreamSource(this)
+    if (this.subscription) this.subscription.unsubscribe()
+  }
+
+  handleConnected(ev) {
+    this.dispatchConnectionEvent(this.connectedOnce ? "turbo-replay:reconnected" : "turbo-replay:connected")
+
+    if (this.sequenceNumber && this.connectedOnce !== undefined) {
+      this.replayMissedMessages()
+      return
+    }
+
+    this.subscription.send({cmd: "get_current_sequence_number"})
+  }
+
+  handleDisconnected(ev) {
+    this.dispatchConnectionEvent("turbo-replay:disconnected")
+  }
+
+  replayMissedMessages() {
+    this.subscription.send({
+      cmd: "get_messages_after_sequence_number",
+      sequence_number: this.sequenceNumber
+    })
+  }
+
+  handleMessage(data) {
+    if (data.get_current_sequence_number !== undefined) {
+      return this.handleGetCurrentSequenceNumber(data)
+    }
+
+    if (data.get_messages_after_sequence_number !== undefined) {
+      return this.handleGetMessagesAfterSequenceNumber(data)
+    }
+
+    if (data.sequence_number !== undefined) {
+      return this.handleMessageBroadcast(data)
+    }
+  }
+
+  handleGetCurrentSequenceNumber(data) {
+    this.connectedOnce = true
+    this.sequenceNumber = data.get_current_sequence_number
+  }
+
+  handleGetMessagesAfterSequenceNumber(data) {
+    const result =
+      data.get_messages_after_sequence_number
+
+    if (Array.isArray(result)) {
+      return result.forEach(this.dispatchMessageEvent.bind(this))
+    }
+
+    if (result  === UNRECOVERABLE_RESULT) {
+      return this.dispatchConnectionEvent("turbo-replay:unrecoverable")
+    }
+
+    throw new Error(`Unexpected result from get_messages_after_sequence_number: ${result}`)
+  }
+
+  handleMessageBroadcast(data) {
+    const sequenceNumberDoesNotMatchExpectedValue =
+      data.sequence_number !== 1 && data.sequence_number !== this.sequenceNumber + 1
+
+    if (sequenceNumberDoesNotMatchExpectedValue) {
+      this.replayMissedMessages()
+
+      return
+    }
+
+    this.dispatchMessageEvent(data)
+  }
+
+  dispatchMessageEvent(data) {
+    this.sequenceNumber =
+      data.sequence_number
+
+    return this.dispatchEvent(
+      new MessageEvent("message", { data: data.content })
+    )
+  }
+
+  dispatchConnectionEvent(eventName) {
+    return this.dispatchEvent(
+      new CustomEvent(eventName, {detail: {channel: this.channel}, bubbles: true})
+    )
+  }
+
+  get channel() {
+    const channel = this.getAttribute("channel")
+    const signed_stream_name = this.getAttribute("signed-stream-name")
+    return { channel, signed_stream_name, ...snakeize({ ...this.dataset }) }
+  }
+}
+
+customElements.define("turbo-cable-stream-source", TurboCableStreamSourceElement)

data/app/javascript/turbo-replay/form_submissions.js

@@ -0,0 +1,5 @@
+export function overrideMethodWithFormmethod({ detail: { formSubmission: { fetchRequest, submitter } } }) {
+  if (submitter && submitter.formMethod && fetchRequest.body.has("_method")) {
+    fetchRequest.body.set("_method", submitter.formMethod)
+  }
+}

data/app/javascript/turbo-replay/index.js

@@ -0,0 +1,10 @@
+import "./cable_stream_source_element"
+import { overrideMethodWithFormmethod } from "./form_submissions"
+
+import * as Turbo from "@hotwired/turbo"
+export { Turbo }
+
+import * as cable from "./cable"
+export { cable }
+
+addEventListener("turbo:submit-start", overrideMethodWithFormmethod)

data/app/javascript/turbo-replay/snakeize.js

@@ -0,0 +1,31 @@
+// Based on https://github.com/nathan7/snakeize
+//
+// This software is released under the 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.
+export default function walk (obj) {
+    if (!obj || typeof obj !== 'object') return obj;
+    if (obj instanceof Date || obj instanceof RegExp) return obj;
+    if (Array.isArray(obj)) return obj.map(walk);
+    return Object.keys(obj).reduce(function (acc, key) {
+        var camel = key[0].toLowerCase() + key.slice(1).replace(/([A-Z]+)/g, function (m, x) {
+            return '_' + x.toLowerCase();
+        });
+        acc[camel] = walk(obj[key]);
+        return acc;
+    }, {});
+};

data/lib/tasks/turbo/install/task.rb

@@ -0,0 +1,21 @@
+say "Installing Javascript library"
+run "yarn add turbo-replay"
+
+say "Creating initializer"
+
+initializer "turbo_replay.rb", <<-CODE
+  require 'turbo/replay'
+
+  Turbo::Replay.configure do |config|
+    redis_client = Redis.new(
+      host: ENV['REDIS_HOST'],
+      port: ENV['REDIS_PORT']
+    )
+
+    # Store for broadcasted messages
+    config.repo = Turbo::Replay::Repo::Redis.new(client: redis_client)
+
+    # Retention policy
+    config.retention = Turbo::Replay::Retention.new(ttl: 60.minutes, size: 50)
+  end
+CODE

data/lib/tasks/turbo/replay_tasks.rake

@@ -1,4 +1,5 @@
-# desc "Explaining what the task does"
-# task :turbo_replay do
-#   # Task goes here
-# end
+namespace :"turbo-replay" do
+  task :install do
+    system "#{RbConfig.ruby} ./bin/rails app:template LOCATION=#{File.expand_path("./install/task.rb", __dir__)}"
+  end
+end

data/lib/turbo/replay/engine.rb

@@ -0,0 +1,15 @@
+require "rails/engine"
+require "turbo-rails"
+
+module Turbo::Replay
+  class Engine < ::Rails::Engine
+    isolate_namespace Turbo::Replay
+
+    initializer "turbo-replay.overrides" do
+      Turbo::StreamsChannel.tap do |channel|
+        channel.extend(Overrides::StreamsChannelBroadcast)
+        channel.include(Overrides::StreamsChannelReceive)
+      end
+    end
+  end
+end

data/lib/turbo/replay/message.rb

@@ -7,6 +7,8 @@ module Turbo::Replay
     end
 
     def get_after_sequence_number(broadcasting:, sequence_number:)
+      return [] if sequence_number.nil?
+
       messages =
         Turbo::Replay.configuration.repo
           .get_all_messages(broadcasting: broadcasting)

data/lib/turbo/replay/overrides/streams_channel_broadcast.rb

@@ -0,0 +1,18 @@
+module Turbo::Replay
+  module Overrides
+    module StreamsChannelBroadcast
+      def broadcast_stream_to(*streamables, content:)
+        broadcasting =
+          stream_name_from(streamables)
+
+        content_with_sequence_number =
+          Turbo::Replay::Message.insert(
+            broadcasting: broadcasting,
+            content: content
+          )
+
+        ::ActionCable.server.broadcast(broadcasting, content_with_sequence_number)
+      end
+    end
+  end
+end

data/lib/turbo/replay/overrides/streams_channel_receive.rb

@@ -0,0 +1,39 @@
+module Turbo::Replay
+  module Overrides
+    module StreamsChannelReceive
+      GetCurrentSequenceNumber =
+        lambda do |broadcasting, _params|
+          sequence_number =
+            Message.get_current_sequence_number(broadcasting: broadcasting)
+
+          {get_current_sequence_number: sequence_number}
+        end
+
+      GetMessagesAfterSequenceNumber =
+        lambda do |broadcasting, params|
+          messages =
+            Message.get_after_sequence_number(
+              broadcasting: broadcasting,
+              sequence_number: params["sequence_number"]&.to_i
+            )
+
+          {get_messages_after_sequence_number: messages}
+        end
+
+      CMD_HANDLERS = {
+        "get_current_sequence_number" => GetCurrentSequenceNumber,
+        "get_messages_after_sequence_number" => GetMessagesAfterSequenceNumber
+      }.freeze
+
+      def receive(data)
+        cmd_handler =
+          CMD_HANDLERS[data["cmd"]]
+
+        broadcasting =
+          self.class.verified_stream_name(params[:signed_stream_name])
+
+        transmit(cmd_handler.call(broadcasting, data)) if cmd_handler.present?
+      end
+    end
+  end
+end

data/lib/turbo/replay/version.rb

@@ -1,5 +1,5 @@
 module Turbo
   module Replay
-    VERSION = "0.1.0"
+    VERSION = "0.1.1"
   end
 end

data/lib/turbo/replay.rb

@@ -1,11 +1,16 @@
-require "turbo/replay/version"
-require "turbo/replay/railtie"
-
-require_relative "./replay/retention"
-require_relative "./replay/message"
-require_relative "./replay/repo/base"
-require_relative "./replay/repo/memory"
-require_relative "./replay/repo/redis"
+%w[
+  version
+  engine
+  retention
+  message
+  overrides/streams_channel_broadcast
+  overrides/streams_channel_receive
+  repo/base
+  repo/memory
+  repo/redis
+].each do |dependency|
+  require "turbo/replay/#{dependency}"
+end
 
 module Turbo
   module Replay
@@ -18,6 +23,8 @@ module Turbo
     mattr_accessor :configuration
     self.configuration = Configuration.new
 
-    def self.configure = yield(configuration)
+    def self.configure
+      yield(configuration)
+    end
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: turbo-replay
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.1.1
 platform: ruby
 authors:
 - Luiz Vasconcellos
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2022-07-02 00:00:00.000000000 Z
+date: 2022-07-03 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -24,6 +24,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: 6.0.0
+- !ruby/object:Gem::Dependency
+  name: turbo-rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0.5'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0.5'
 - !ruby/object:Gem::Dependency
   name: standard
   requirement: !ruby/object:Gem::Requirement
@@ -77,10 +91,18 @@ files:
 - MIT-LICENSE
 - README.md
 - Rakefile
+- app/javascript/turbo-replay/cable.js
+- app/javascript/turbo-replay/cable_stream_source_element.js
+- app/javascript/turbo-replay/form_submissions.js
+- app/javascript/turbo-replay/index.js
+- app/javascript/turbo-replay/snakeize.js
+- lib/tasks/turbo/install/task.rb
 - lib/tasks/turbo/replay_tasks.rake
 - lib/turbo/replay.rb
+- lib/turbo/replay/engine.rb
 - lib/turbo/replay/message.rb
-- lib/turbo/replay/railtie.rb
+- lib/turbo/replay/overrides/streams_channel_broadcast.rb
+- lib/turbo/replay/overrides/streams_channel_receive.rb
 - lib/turbo/replay/repo/base.rb
 - lib/turbo/replay/repo/memory.rb
 - lib/turbo/replay/repo/redis.rb

data/lib/turbo/replay/railtie.rb

@@ -1,7 +0,0 @@
-# Is this needed?
-module Turbo
-  module Replay
-    class Railtie < ::Rails::Railtie
-    end
-  end
-end