turbo-replay 0.1.0 → 0.1.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
checksums.yaml CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  SHA256:
3
- metadata.gz: d51efac005c1642592ebccb9753657e2be702141014bc0ebae2e7d4757aee362
4
- data.tar.gz: ae00e5f49f8f106ef525e5efa7f3f6abe01b2676553b64f2c8bbfe9f943e23f1
3
+ metadata.gz: abe7572c62c8e9b824b44428d238bb7fb99cc4efd69ba2515d931634a8db8e8c
4
+ data.tar.gz: 2b7701bddfb6941f3bd53aa877fd83d9788fc8a3681c773705f5ff8770ad9df6
5
5
  SHA512:
6
- metadata.gz: 6ff54759f20fdd6cbb6c6a23f926297d9f12eb5d86ae96617b212a98eb0c53d421d2c676020cf89778ef56795ef7cc8a2a213f8f12b710e5d198948995508e8a
7
- data.tar.gz: 1cd690000760467b1ded8d168d26621d69fd08c255ca1d688c5e83d43c8d0df12038cb0e41a94b4af45a47f84cd2663eced22f3edc1c6ca0129ba18c1e5a3343
6
+ metadata.gz: 1aaa04169166308ded72caee2f1c2903b0cfc57951d75755494346309ca387fa9c7bec50da051c203040ec57162b49f3acca76788b7f83976ca9b4b8db0dc945
7
+ data.tar.gz: 0472f0f884358bab6d623a2f107a473520a5e87032fc2cb6045c48b3b00364e8518ba429c84cf4e21698ce4d1392da74dd9c7c4f586ecb5906e3e6944a427edc
data/README.md CHANGED
@@ -1,28 +1,93 @@
1
- # Turbo::Replay
2
- Short description and motivation.
1
+ # turbo-replay
3
2
 
4
- ## Usage
5
- How to use my plugin.
3
+ **turbo-replay** assigns a sequence number to broadcasted messages and caches them. When a client
4
+ disconnects because of flaky network, we're able to resend (or replay, hence the name) missed
5
+ messages in the same order they were originally sent.
6
6
 
7
7
  ## Installation
8
+
9
+ > **Important**: Make sure you have installed [`hotwired/turbo-rails`](https://github.com/hotwired/turbo-rails) before using this gem!
10
+
8
11
  Add this line to your application's Gemfile:
9
12
 
10
13
  ```ruby
11
14
  gem "turbo-replay"
12
15
  ```
13
16
 
14
- And then execute:
17
+ Execute the following commands to install the gem and generate an initializer:
18
+
15
19
  ```bash
16
- $ bundle
20
+ $ bin/bundle install
21
+ $ bin/rails turbo-replay:install
17
22
  ```
18
23
 
19
- Or install it yourself as:
20
- ```bash
21
- $ gem install turbo-replay
24
+ Replace the import for `@hotwired/turbo-rails` in your application.js
25
+
26
+ ```diff
27
+ - import "@hotwired/turbo-rails"
28
+ + import "turbo-replay"
29
+ ```
30
+
31
+ Now reload your server - and that's it!
32
+
33
+ ### Javascript events
34
+
35
+ ```javascript
36
+ // The user connected for the first time to a channel.
37
+ window.addEventListener('turbo-replay:connected', (ev) => {
38
+ console.log('connected', ev.detail.channel)
39
+ })
40
+
41
+ // The user disconnected from a channel and we're retrying to reconnect.
42
+ // It's good to show some 'reconnecting...' indication here.
43
+ window.addEventListener('turbo-replay:disconnected', (ev) => {
44
+ console.log('disconnected', ev.detail.channel)
45
+ })
46
+
47
+ // The user reconnected after being offline a little bit.
48
+ // Hide the 'reconnecting...' indicationk here.
49
+ window.addEventListener('turbo-replay:reconnected', (ev) => {
50
+ console.log('reconnected', ev.detail.channel)
51
+ })
52
+
53
+ // The user reconnected, but the latest received message was older
54
+ // than the oldest message in the cache. There's nothing we can do
55
+ // here to recover the state. You can reload the whole application
56
+ // or show some indication asking the user to reload.
57
+ window.addEventListener('turbo-replay:unrecoverable', (ev) => {
58
+ console.log('unrecoverable', ev.detail.channel)
59
+ })
22
60
  ```
23
61
 
24
- ## Contributing
25
- Contribution directions go here.
62
+ ### How does it work?
63
+
64
+ **turbo-replay** stores broadcasted messages in a cache. Each message is assigned a sequence number.
65
+
66
+ Because the sequence number is sequential, clients know what the next value is expected to be.
67
+ If an arrived `sequence_number` doesn't match the expected value, it means the client missed a message.
68
+
69
+ > The sequence number ensures clients can detect missed messages even without a disconnect event.
70
+
71
+ When the client notices they missed an event, they ask the server to resend messages after the last known
72
+ sequence number.
73
+
74
+ ### I like to broadcast lots of stuff, isn't the cache too much overhead?
75
+
76
+ Maybe, it depends on your use case. Take a look at `config/initializers/turbo_replay.rb` in your
77
+ application to tweak the cache's retention policy.
78
+
79
+ ### What if the client stays offline too long?
80
+
81
+ There's nothing we can do if the client's latest received message is older than the oldest message in the cache.
82
+
83
+ Suggestion: handle the `turbo-replay:unrecoverable` event and display a message asking the user
84
+ to reload the app. For example:
85
+
86
+ ```js
87
+ window.addEventListener('turbo-replay:unrecoverable', () => {
88
+ window.alert("You're offline for too long. Please reload the page.")
89
+ })
90
+ ```
26
91
 
27
92
  ## License
28
93
  The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
data/Rakefile CHANGED
@@ -1,3 +1,16 @@
1
1
  require "bundler/setup"
2
2
  require "bundler/gem_tasks"
3
+ require "rake/testtask"
3
4
  require "standard/rake"
5
+
6
+ APP_RAKEFILE = File.expand_path("test/dummy/Rakefile", __dir__)
7
+ load "rails/tasks/engine.rake"
8
+ load "rails/tasks/statistics.rake"
9
+
10
+ Rake::TestTask.new do |test|
11
+ test.libs << "test"
12
+ test.test_files = FileList["test/**/*_test.rb"]
13
+ test.warning = false
14
+ end
15
+
16
+ task default: :test
@@ -0,0 +1,19 @@
1
+ let consumer
2
+
3
+ export async function getConsumer() {
4
+ return consumer || setConsumer(createConsumer().then(setConsumer))
5
+ }
6
+
7
+ export function setConsumer(newConsumer) {
8
+ return consumer = newConsumer
9
+ }
10
+
11
+ export async function createConsumer() {
12
+ const { createConsumer } = await import(/* webpackChunkName: "actioncable" */ "@rails/actioncable/src")
13
+ return createConsumer()
14
+ }
15
+
16
+ export async function subscribeTo(channel, mixin) {
17
+ const { subscriptions } = await getConsumer()
18
+ return subscriptions.create(channel, mixin)
19
+ }
@@ -0,0 +1,114 @@
1
+ import { connectStreamSource, disconnectStreamSource } from "@hotwired/turbo"
2
+ import { subscribeTo } from "./cable"
3
+ import snakeize from "./snakeize"
4
+
5
+ const UNRECOVERABLE_RESULT = "unrecoverable"
6
+
7
+ class TurboCableStreamSourceElement extends HTMLElement {
8
+ async connectedCallback() {
9
+ connectStreamSource(this)
10
+
11
+ this.subscription = await subscribeTo(this.channel, {
12
+ connected: this.handleConnected.bind(this),
13
+ disconnected: this.handleDisconnected.bind(this),
14
+ received: this.handleMessage.bind(this)
15
+ })
16
+ }
17
+
18
+ disconnectedCallback() {
19
+ disconnectStreamSource(this)
20
+ if (this.subscription) this.subscription.unsubscribe()
21
+ }
22
+
23
+ handleConnected(ev) {
24
+ this.dispatchConnectionEvent(this.connectedOnce ? "turbo-replay:reconnected" : "turbo-replay:connected")
25
+
26
+ if (this.sequenceNumber && this.connectedOnce !== undefined) {
27
+ this.replayMissedMessages()
28
+ return
29
+ }
30
+
31
+ this.subscription.send({cmd: "get_current_sequence_number"})
32
+ }
33
+
34
+ handleDisconnected(ev) {
35
+ this.dispatchConnectionEvent("turbo-replay:disconnected")
36
+ }
37
+
38
+ replayMissedMessages() {
39
+ this.subscription.send({
40
+ cmd: "get_messages_after_sequence_number",
41
+ sequence_number: this.sequenceNumber
42
+ })
43
+ }
44
+
45
+ handleMessage(data) {
46
+ if (data.get_current_sequence_number !== undefined) {
47
+ return this.handleGetCurrentSequenceNumber(data)
48
+ }
49
+
50
+ if (data.get_messages_after_sequence_number !== undefined) {
51
+ return this.handleGetMessagesAfterSequenceNumber(data)
52
+ }
53
+
54
+ if (data.sequence_number !== undefined) {
55
+ return this.handleMessageBroadcast(data)
56
+ }
57
+ }
58
+
59
+ handleGetCurrentSequenceNumber(data) {
60
+ this.connectedOnce = true
61
+ this.sequenceNumber = data.get_current_sequence_number
62
+ }
63
+
64
+ handleGetMessagesAfterSequenceNumber(data) {
65
+ const result =
66
+ data.get_messages_after_sequence_number
67
+
68
+ if (Array.isArray(result)) {
69
+ return result.forEach(this.dispatchMessageEvent.bind(this))
70
+ }
71
+
72
+ if (result === UNRECOVERABLE_RESULT) {
73
+ return this.dispatchConnectionEvent("turbo-replay:unrecoverable")
74
+ }
75
+
76
+ throw new Error(`Unexpected result from get_messages_after_sequence_number: ${result}`)
77
+ }
78
+
79
+ handleMessageBroadcast(data) {
80
+ const sequenceNumberDoesNotMatchExpectedValue =
81
+ data.sequence_number !== 1 && data.sequence_number !== this.sequenceNumber + 1
82
+
83
+ if (sequenceNumberDoesNotMatchExpectedValue) {
84
+ this.replayMissedMessages()
85
+
86
+ return
87
+ }
88
+
89
+ this.dispatchMessageEvent(data)
90
+ }
91
+
92
+ dispatchMessageEvent(data) {
93
+ this.sequenceNumber =
94
+ data.sequence_number
95
+
96
+ return this.dispatchEvent(
97
+ new MessageEvent("message", { data: data.content })
98
+ )
99
+ }
100
+
101
+ dispatchConnectionEvent(eventName) {
102
+ return this.dispatchEvent(
103
+ new CustomEvent(eventName, {detail: {channel: this.channel}, bubbles: true})
104
+ )
105
+ }
106
+
107
+ get channel() {
108
+ const channel = this.getAttribute("channel")
109
+ const signed_stream_name = this.getAttribute("signed-stream-name")
110
+ return { channel, signed_stream_name, ...snakeize({ ...this.dataset }) }
111
+ }
112
+ }
113
+
114
+ customElements.define("turbo-cable-stream-source", TurboCableStreamSourceElement)
@@ -0,0 +1,5 @@
1
+ export function overrideMethodWithFormmethod({ detail: { formSubmission: { fetchRequest, submitter } } }) {
2
+ if (submitter && submitter.formMethod && fetchRequest.body.has("_method")) {
3
+ fetchRequest.body.set("_method", submitter.formMethod)
4
+ }
5
+ }
@@ -0,0 +1,10 @@
1
+ import "./cable_stream_source_element"
2
+ import { overrideMethodWithFormmethod } from "./form_submissions"
3
+
4
+ import * as Turbo from "@hotwired/turbo"
5
+ export { Turbo }
6
+
7
+ import * as cable from "./cable"
8
+ export { cable }
9
+
10
+ addEventListener("turbo:submit-start", overrideMethodWithFormmethod)
@@ -0,0 +1,31 @@
1
+ // Based on https://github.com/nathan7/snakeize
2
+ //
3
+ // This software is released under the MIT license:
4
+ // Permission is hereby granted, free of charge, to any person obtaining a copy of
5
+ // this software and associated documentation files (the "Software"), to deal in
6
+ // the Software without restriction, including without limitation the rights to
7
+ // use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
8
+ // the Software, and to permit persons to whom the Software is furnished to do so,
9
+ // subject to the following conditions:
10
+
11
+ // The above copyright notice and this permission notice shall be included in all
12
+ // copies or substantial portions of the Software.
13
+
14
+ // THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
15
+ // IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
16
+ // FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
17
+ // COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
18
+ // IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
19
+ // CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
20
+ export default function walk (obj) {
21
+ if (!obj || typeof obj !== 'object') return obj;
22
+ if (obj instanceof Date || obj instanceof RegExp) return obj;
23
+ if (Array.isArray(obj)) return obj.map(walk);
24
+ return Object.keys(obj).reduce(function (acc, key) {
25
+ var camel = key[0].toLowerCase() + key.slice(1).replace(/([A-Z]+)/g, function (m, x) {
26
+ return '_' + x.toLowerCase();
27
+ });
28
+ acc[camel] = walk(obj[key]);
29
+ return acc;
30
+ }, {});
31
+ };
@@ -0,0 +1,21 @@
1
+ say "Installing Javascript library"
2
+ run "yarn add turbo-replay"
3
+
4
+ say "Creating initializer"
5
+
6
+ initializer "turbo_replay.rb", <<-CODE
7
+ require 'turbo/replay'
8
+
9
+ Turbo::Replay.configure do |config|
10
+ redis_client = Redis.new(
11
+ host: ENV['REDIS_HOST'],
12
+ port: ENV['REDIS_PORT']
13
+ )
14
+
15
+ # Store for broadcasted messages
16
+ config.repo = Turbo::Replay::Repo::Redis.new(client: redis_client)
17
+
18
+ # Retention policy
19
+ config.retention = Turbo::Replay::Retention.new(ttl: 60.minutes, size: 50)
20
+ end
21
+ CODE
@@ -1,4 +1,5 @@
1
- # desc "Explaining what the task does"
2
- # task :turbo_replay do
3
- # # Task goes here
4
- # end
1
+ namespace :"turbo-replay" do
2
+ task :install do
3
+ system "#{RbConfig.ruby} ./bin/rails app:template LOCATION=#{File.expand_path("./install/task.rb", __dir__)}"
4
+ end
5
+ end
@@ -0,0 +1,15 @@
1
+ require "rails/engine"
2
+ require "turbo-rails"
3
+
4
+ module Turbo::Replay
5
+ class Engine < ::Rails::Engine
6
+ isolate_namespace Turbo::Replay
7
+
8
+ initializer "turbo-replay.overrides" do
9
+ Turbo::StreamsChannel.tap do |channel|
10
+ channel.extend(Overrides::StreamsChannelBroadcast)
11
+ channel.include(Overrides::StreamsChannelReceive)
12
+ end
13
+ end
14
+ end
15
+ end
@@ -7,6 +7,8 @@ module Turbo::Replay
7
7
  end
8
8
 
9
9
  def get_after_sequence_number(broadcasting:, sequence_number:)
10
+ return [] if sequence_number.nil?
11
+
10
12
  messages =
11
13
  Turbo::Replay.configuration.repo
12
14
  .get_all_messages(broadcasting: broadcasting)
@@ -0,0 +1,18 @@
1
+ module Turbo::Replay
2
+ module Overrides
3
+ module StreamsChannelBroadcast
4
+ def broadcast_stream_to(*streamables, content:)
5
+ broadcasting =
6
+ stream_name_from(streamables)
7
+
8
+ content_with_sequence_number =
9
+ Turbo::Replay::Message.insert(
10
+ broadcasting: broadcasting,
11
+ content: content
12
+ )
13
+
14
+ ::ActionCable.server.broadcast(broadcasting, content_with_sequence_number)
15
+ end
16
+ end
17
+ end
18
+ end
@@ -0,0 +1,39 @@
1
+ module Turbo::Replay
2
+ module Overrides
3
+ module StreamsChannelReceive
4
+ GetCurrentSequenceNumber =
5
+ lambda do |broadcasting, _params|
6
+ sequence_number =
7
+ Message.get_current_sequence_number(broadcasting: broadcasting)
8
+
9
+ {get_current_sequence_number: sequence_number}
10
+ end
11
+
12
+ GetMessagesAfterSequenceNumber =
13
+ lambda do |broadcasting, params|
14
+ messages =
15
+ Message.get_after_sequence_number(
16
+ broadcasting: broadcasting,
17
+ sequence_number: params["sequence_number"]&.to_i
18
+ )
19
+
20
+ {get_messages_after_sequence_number: messages}
21
+ end
22
+
23
+ CMD_HANDLERS = {
24
+ "get_current_sequence_number" => GetCurrentSequenceNumber,
25
+ "get_messages_after_sequence_number" => GetMessagesAfterSequenceNumber
26
+ }.freeze
27
+
28
+ def receive(data)
29
+ cmd_handler =
30
+ CMD_HANDLERS[data["cmd"]]
31
+
32
+ broadcasting =
33
+ self.class.verified_stream_name(params[:signed_stream_name])
34
+
35
+ transmit(cmd_handler.call(broadcasting, data)) if cmd_handler.present?
36
+ end
37
+ end
38
+ end
39
+ end
@@ -1,5 +1,5 @@
1
1
  module Turbo
2
2
  module Replay
3
- VERSION = "0.1.0"
3
+ VERSION = "0.1.1"
4
4
  end
5
5
  end
data/lib/turbo/replay.rb CHANGED
@@ -1,11 +1,16 @@
1
- require "turbo/replay/version"
2
- require "turbo/replay/railtie"
3
-
4
- require_relative "./replay/retention"
5
- require_relative "./replay/message"
6
- require_relative "./replay/repo/base"
7
- require_relative "./replay/repo/memory"
8
- require_relative "./replay/repo/redis"
1
+ %w[
2
+ version
3
+ engine
4
+ retention
5
+ message
6
+ overrides/streams_channel_broadcast
7
+ overrides/streams_channel_receive
8
+ repo/base
9
+ repo/memory
10
+ repo/redis
11
+ ].each do |dependency|
12
+ require "turbo/replay/#{dependency}"
13
+ end
9
14
 
10
15
  module Turbo
11
16
  module Replay
@@ -18,6 +23,8 @@ module Turbo
18
23
  mattr_accessor :configuration
19
24
  self.configuration = Configuration.new
20
25
 
21
- def self.configure = yield(configuration)
26
+ def self.configure
27
+ yield(configuration)
28
+ end
22
29
  end
23
30
  end
metadata CHANGED
@@ -1,14 +1,14 @@
1
1
  --- !ruby/object:Gem::Specification
2
2
  name: turbo-replay
3
3
  version: !ruby/object:Gem::Version
4
- version: 0.1.0
4
+ version: 0.1.1
5
5
  platform: ruby
6
6
  authors:
7
7
  - Luiz Vasconcellos
8
8
  autorequire:
9
9
  bindir: bin
10
10
  cert_chain: []
11
- date: 2022-07-02 00:00:00.000000000 Z
11
+ date: 2022-07-03 00:00:00.000000000 Z
12
12
  dependencies:
13
13
  - !ruby/object:Gem::Dependency
14
14
  name: rails
@@ -24,6 +24,20 @@ dependencies:
24
24
  - - ">="
25
25
  - !ruby/object:Gem::Version
26
26
  version: 6.0.0
27
+ - !ruby/object:Gem::Dependency
28
+ name: turbo-rails
29
+ requirement: !ruby/object:Gem::Requirement
30
+ requirements:
31
+ - - ">="
32
+ - !ruby/object:Gem::Version
33
+ version: '0.5'
34
+ type: :runtime
35
+ prerelease: false
36
+ version_requirements: !ruby/object:Gem::Requirement
37
+ requirements:
38
+ - - ">="
39
+ - !ruby/object:Gem::Version
40
+ version: '0.5'
27
41
  - !ruby/object:Gem::Dependency
28
42
  name: standard
29
43
  requirement: !ruby/object:Gem::Requirement
@@ -77,10 +91,18 @@ files:
77
91
  - MIT-LICENSE
78
92
  - README.md
79
93
  - Rakefile
94
+ - app/javascript/turbo-replay/cable.js
95
+ - app/javascript/turbo-replay/cable_stream_source_element.js
96
+ - app/javascript/turbo-replay/form_submissions.js
97
+ - app/javascript/turbo-replay/index.js
98
+ - app/javascript/turbo-replay/snakeize.js
99
+ - lib/tasks/turbo/install/task.rb
80
100
  - lib/tasks/turbo/replay_tasks.rake
81
101
  - lib/turbo/replay.rb
102
+ - lib/turbo/replay/engine.rb
82
103
  - lib/turbo/replay/message.rb
83
- - lib/turbo/replay/railtie.rb
104
+ - lib/turbo/replay/overrides/streams_channel_broadcast.rb
105
+ - lib/turbo/replay/overrides/streams_channel_receive.rb
84
106
  - lib/turbo/replay/repo/base.rb
85
107
  - lib/turbo/replay/repo/memory.rb
86
108
  - lib/turbo/replay/repo/redis.rb
@@ -1,7 +0,0 @@
1
- # Is this needed?
2
- module Turbo
3
- module Replay
4
- class Railtie < ::Rails::Railtie
5
- end
6
- end
7
- end