# turbo-replay

> Never miss a single websocket event.

Latest version **0.1.2** (published 2022-07-03) · 0 weekly downloads

## Install

```sh
npm install turbo-replay
pnpm add turbo-replay
yarn add turbo-replay
bun add turbo-replay
```

## Health

**Score 15/100 (F)** — status: abandoned.

Positive: esm support; no vulnerabilities.

Warnings: low downloads; no types; low quality score; pre 1.0.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 0.1.2 |
| Published | 2022-07-03 |
| First published | 2022-07-03 |
| Weekly downloads | 0 |
| TypeScript types | none |
| Module format | ESM + CommonJS |
| Dependencies | 2 |
| Unpacked size | 65.1 KB |
| Known vulnerabilities | 0 (+1 in 1 direct dependencies) |
| Install scripts | no |
| Maintainers | luizpvasc |

## Links

- npm: https://www.npmjs.com/package/turbo-replay
- npm.io page: https://npm.io/package/turbo-replay

## Dependencies (2)

- [@hotwired/turbo](https://npm.io/package/@hotwired/turbo.md) ^7.1.0
- [@rails/actioncable](https://npm.io/package/@rails/actioncable.md) ^7.0

## Recent versions

- 0.1.2 (latest) — 2022-07-03
- 0.1.1 — 2022-07-03
- 0.1.0 — 2022-07-03

## README

# turbo-replay

**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"
```

Execute the following commands to install the gem and generate an initializer:

```bash
$ bin/bundle install
$ bin/rails turbo-replay:install
```

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)
})
```

### 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).

---
_Source: https://npm.io/package/turbo-replay · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._