actioncable 5.2.4.5 → 6.1.3.1

Sign up to get free protection for your applications and to get access to all the features.
Files changed (45) hide show
  1. checksums.yaml +4 -4
  2. data/CHANGELOG.md +31 -45
  3. data/MIT-LICENSE +1 -1
  4. data/README.md +3 -546
  5. data/app/assets/javascripts/action_cable.js +517 -0
  6. data/lib/action_cable.rb +15 -7
  7. data/lib/action_cable/channel.rb +1 -0
  8. data/lib/action_cable/channel/base.rb +10 -4
  9. data/lib/action_cable/channel/broadcasting.rb +18 -8
  10. data/lib/action_cable/channel/naming.rb +1 -1
  11. data/lib/action_cable/channel/streams.rb +30 -4
  12. data/lib/action_cable/channel/test_case.rb +310 -0
  13. data/lib/action_cable/connection.rb +1 -0
  14. data/lib/action_cable/connection/authorization.rb +1 -1
  15. data/lib/action_cable/connection/base.rb +13 -7
  16. data/lib/action_cable/connection/message_buffer.rb +1 -4
  17. data/lib/action_cable/connection/stream.rb +4 -2
  18. data/lib/action_cable/connection/subscriptions.rb +2 -5
  19. data/lib/action_cable/connection/test_case.rb +234 -0
  20. data/lib/action_cable/connection/web_socket.rb +1 -3
  21. data/lib/action_cable/engine.rb +1 -1
  22. data/lib/action_cable/gem_version.rb +4 -4
  23. data/lib/action_cable/helpers/action_cable_helper.rb +3 -3
  24. data/lib/action_cable/server.rb +0 -1
  25. data/lib/action_cable/server/base.rb +9 -4
  26. data/lib/action_cable/server/broadcasting.rb +1 -1
  27. data/lib/action_cable/server/worker.rb +6 -8
  28. data/lib/action_cable/subscription_adapter.rb +1 -0
  29. data/lib/action_cable/subscription_adapter/base.rb +4 -0
  30. data/lib/action_cable/subscription_adapter/postgresql.rb +28 -9
  31. data/lib/action_cable/subscription_adapter/redis.rb +4 -2
  32. data/lib/action_cable/subscription_adapter/test.rb +40 -0
  33. data/lib/action_cable/test_case.rb +11 -0
  34. data/lib/action_cable/test_helper.rb +133 -0
  35. data/lib/rails/generators/channel/USAGE +5 -6
  36. data/lib/rails/generators/channel/channel_generator.rb +6 -3
  37. data/lib/rails/generators/channel/templates/{assets → javascript}/channel.js.tt +6 -4
  38. data/lib/rails/generators/channel/templates/javascript/consumer.js.tt +6 -0
  39. data/lib/rails/generators/channel/templates/javascript/index.js.tt +5 -0
  40. data/lib/rails/generators/test_unit/channel_generator.rb +20 -0
  41. data/lib/rails/generators/test_unit/templates/channel_test.rb.tt +8 -0
  42. metadata +37 -13
  43. data/lib/assets/compiled/action_cable.js +0 -601
  44. data/lib/rails/generators/channel/templates/assets/cable.js.tt +0 -13
  45. data/lib/rails/generators/channel/templates/assets/channel.coffee.tt +0 -14
checksums.yaml CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  SHA256:
3
- metadata.gz: f366b8bcbabb55197e939cfaf6e55e3cb37d0c7ecbaaf775cfc2fe70392398ff
4
- data.tar.gz: e8f4fc6e8db710e9b405c28e1aba19e97c27c0a7c81a5b215d42431aaff5c01f
3
+ metadata.gz: 9e0e852bb8fa5267eff346a9aef794e6de1a2e9d0e62957453e6afdcfcea48d9
4
+ data.tar.gz: 406480de8ebdfe0532819a4a5a17bc93d896849c8ab0a47ea06077c69c3799fb
5
5
  SHA512:
6
- metadata.gz: b6bbc37a40d11aeee93c3a4910289cf3ed0c961000fdc444b85c29fe6e1b7689157cdfa4da903b339d696f0b35fe1d7c7ad7a1d4142d1cdfb99f0979efc8ac07
7
- data.tar.gz: 21f6b8d97132ffe78357338a114ffe405945ade59bdbb605f16c695cb951a1a89ed6711052e86450d258a4a926717e38d6f3f492a689cd0ee0fd75db6e258025
6
+ metadata.gz: e76c5c926ec4c818018968ba2b7d6f9464a020c1306efe66e18565f599233230f3a4766587c4274744d6e123c5f031c82b1000e820d762467b7522cc11ef6201
7
+ data.tar.gz: c0bb3bf3b2327a68c493d4f7b4369878770439c4bfdfd85499b7caa86dcafc480021ee44e96c82caf96c62ecfebec1b052ec4f88707bad30eeb1487be88b74e4
data/CHANGELOG.md CHANGED
@@ -1,79 +1,65 @@
1
- ## Rails 5.2.4.5 (February 10, 2021) ##
1
+ ## Rails 6.1.3.1 (March 26, 2021) ##
2
2
 
3
3
  * No changes.
4
4
 
5
5
 
6
- ## Rails 5.2.4.4 (September 09, 2020) ##
6
+ ## Rails 6.1.3 (February 17, 2021) ##
7
7
 
8
8
  * No changes.
9
9
 
10
10
 
11
- ## Rails 5.2.4.3 (May 18, 2020) ##
11
+ ## Rails 6.1.2.1 (February 10, 2021) ##
12
12
 
13
13
  * No changes.
14
14
 
15
15
 
16
- ## Rails 5.2.4.1 (December 18, 2019) ##
16
+ ## Rails 6.1.2 (February 09, 2021) ##
17
17
 
18
18
  * No changes.
19
19
 
20
20
 
21
- ## Rails 5.2.4 (November 27, 2019) ##
21
+ ## Rails 6.1.1 (January 07, 2021) ##
22
22
 
23
23
  * No changes.
24
24
 
25
25
 
26
- ## Rails 5.2.3 (March 27, 2019) ##
27
-
28
- * No changes.
29
-
30
-
31
- ## Rails 5.2.2.1 (March 11, 2019) ##
32
-
33
- * No changes.
34
-
35
-
36
- ## Rails 5.2.2 (December 04, 2018) ##
37
-
38
- * No changes.
39
-
40
-
41
- ## Rails 5.2.1.1 (November 27, 2018) ##
42
-
43
- * No changes.
44
-
45
-
46
- ## Rails 5.2.1 (August 07, 2018) ##
47
-
48
- * No changes.
26
+ ## Rails 6.1.0 (December 09, 2020) ##
49
27
 
28
+ * `ActionCable::Connection::Base` now allows intercepting unhandled exceptions
29
+ with `rescue_from` before they are logged, which is useful for error reporting
30
+ tools and other integrations.
50
31
 
51
- ## Rails 5.2.0 (April 09, 2018) ##
32
+ *Justin Talbott*
52
33
 
53
- * Removed deprecated evented redis adapter.
34
+ * Add `ActionCable::Channel#stream_or_reject_for` to stream if record is present, otherwise reject the connection
54
35
 
55
- *Rafael Mendonça França*
36
+ *Atul Bhosale*
56
37
 
57
- * Support redis-rb 4.0.
38
+ * Add `ActionCable::Channel#stop_stream_from` and `#stop_stream_for` to unsubscribe from a specific stream.
58
39
 
59
- *Jeremy Daer*
40
+ *Zhang Kang*
60
41
 
61
- * Hash long stream identifiers when using PostgreSQL adapter.
42
+ * Add PostgreSQL subscription connection identificator.
62
43
 
63
- PostgreSQL has a limit on identifiers length (63 chars, [docs](https://www.postgresql.org/docs/current/static/sql-syntax-lexical.html#SQL-SYNTAX-IDENTIFIERS)).
64
- Provided fix minifies identifiers longer than 63 chars by hashing them with SHA1.
44
+ Now you can distinguish Action Cable PostgreSQL subscription connections among others.
45
+ Also, you can set custom `id` in `cable.yml` configuration.
65
46
 
66
- Fixes #28751.
47
+ ```sql
48
+ SELECT application_name FROM pg_stat_activity;
49
+ /*
50
+ application_name
51
+ ------------------------
52
+ psql
53
+ ActionCable-PID-42
54
+ (2 rows)
55
+ */
56
+ ```
67
57
 
68
- *Vladimir Dementyev*
58
+ *Sergey Ponomarev*
69
59
 
70
- * Action Cable's `redis` adapter allows for other common redis-rb options (`host`, `port`, `db`, `password`) in cable.yml.
60
+ * Subscription confirmations and rejections are now logged at the `DEBUG` level instead of `INFO`.
71
61
 
72
- Previously, it accepts only a [redis:// url](https://www.iana.org/assignments/uri-schemes/prov/redis) as an option.
73
- While we can add all of these options to the `url` itself, it is not explicitly documented. This alternative setup
74
- is shown as the first example in the [Redis rubygem](https://github.com/redis/redis-rb#getting-started), which
75
- makes this set of options as sensible as using just the `url`.
62
+ *DHH*
76
63
 
77
- *Marc Rendl Ignacio*
78
64
 
79
- Please check [5-1-stable](https://github.com/rails/rails/blob/5-1-stable/actioncable/CHANGELOG.md) for previous changes.
65
+ Please check [6-0-stable](https://github.com/rails/rails/blob/6-0-stable/actioncable/CHANGELOG.md) for previous changes.
data/MIT-LICENSE CHANGED
@@ -1,4 +1,4 @@
1
- Copyright (c) 2015-2018 Basecamp, LLC
1
+ Copyright (c) 2015-2020 Basecamp, LLC
2
2
 
3
3
  Permission is hereby granted, free of charge, to any person obtaining
4
4
  a copy of this software and associated documentation files (the
data/README.md CHANGED
@@ -7,556 +7,13 @@ and scalable. It's a full-stack offering that provides both a client-side
7
7
  JavaScript framework and a server-side Ruby framework. You have access to your full
8
8
  domain model written with Active Record or your ORM of choice.
9
9
 
10
- ## Terminology
11
-
12
- A single Action Cable server can handle multiple connection instances. It has one
13
- connection instance per WebSocket connection. A single user may have multiple
14
- WebSockets open to your application if they use multiple browser tabs or devices.
15
- The client of a WebSocket connection is called the consumer.
16
-
17
- Each consumer can in turn subscribe to multiple cable channels. Each channel encapsulates
18
- a logical unit of work, similar to what a controller does in a regular MVC setup. For example,
19
- you could have a `ChatChannel` and an `AppearancesChannel`, and a consumer could be subscribed to either
20
- or to both of these channels. At the very least, a consumer should be subscribed to one channel.
21
-
22
- When the consumer is subscribed to a channel, they act as a subscriber. The connection between
23
- the subscriber and the channel is, surprise-surprise, called a subscription. A consumer
24
- can act as a subscriber to a given channel any number of times. For example, a consumer
25
- could subscribe to multiple chat rooms at the same time. (And remember that a physical user may
26
- have multiple consumers, one per tab/device open to your connection).
27
-
28
- Each channel can then again be streaming zero or more broadcastings. A broadcasting is a
29
- pubsub link where anything transmitted by the broadcaster is sent directly to the channel
30
- subscribers who are streaming that named broadcasting.
31
-
32
- As you can see, this is a fairly deep architectural stack. There's a lot of new terminology
33
- to identify the new pieces, and on top of that, you're dealing with both client and server side
34
- reflections of each unit.
35
-
36
- ## Examples
37
-
38
- ### A full-stack example
39
-
40
- The first thing you must do is define your `ApplicationCable::Connection` class in Ruby. This
41
- is the place where you authorize the incoming connection, and proceed to establish it,
42
- if all is well. Here's the simplest example starting with the server-side connection class:
43
-
44
- ```ruby
45
- # app/channels/application_cable/connection.rb
46
- module ApplicationCable
47
- class Connection < ActionCable::Connection::Base
48
- identified_by :current_user
49
-
50
- def connect
51
- self.current_user = find_verified_user
52
- end
53
-
54
- private
55
- def find_verified_user
56
- if verified_user = User.find_by(id: cookies.encrypted[:user_id])
57
- verified_user
58
- else
59
- reject_unauthorized_connection
60
- end
61
- end
62
- end
63
- end
64
- ```
65
- Here `identified_by` is a connection identifier that can be used to find the specific connection again or later.
66
- Note that anything marked as an identifier will automatically create a delegate by the same name on any channel instances created off the connection.
67
-
68
- This relies on the fact that you will already have handled authentication of the user, and
69
- that a successful authentication sets a signed cookie with the `user_id`. This cookie is then
70
- automatically sent to the connection instance when a new connection is attempted, and you
71
- use that to set the `current_user`. By identifying the connection by this same current_user,
72
- you're also ensuring that you can later retrieve all open connections by a given user (and
73
- potentially disconnect them all if the user is deleted or deauthorized).
74
-
75
- Next, you should define your `ApplicationCable::Channel` class in Ruby. This is the place where you put
76
- shared logic between your channels.
77
-
78
- ```ruby
79
- # app/channels/application_cable/channel.rb
80
- module ApplicationCable
81
- class Channel < ActionCable::Channel::Base
82
- end
83
- end
84
- ```
85
-
86
- The client-side needs to setup a consumer instance of this connection. That's done like so:
87
-
88
- ```js
89
- // app/assets/javascripts/cable.js
90
- //= require action_cable
91
- //= require_self
92
- //= require_tree ./channels
93
-
94
- (function() {
95
- this.App || (this.App = {});
96
-
97
- App.cable = ActionCable.createConsumer("ws://cable.example.com");
98
- }).call(this);
99
- ```
100
-
101
- The `ws://cable.example.com` address must point to your Action Cable server(s), and it
102
- must share a cookie namespace with the rest of the application (which may live under http://example.com).
103
- This ensures that the signed cookie will be correctly sent.
104
-
105
- That's all you need to establish the connection! But of course, this isn't very useful in
106
- itself. This just gives you the plumbing. To make stuff happen, you need content. That content
107
- is defined by declaring channels on the server and allowing the consumer to subscribe to them.
108
-
109
-
110
- ### Channel example 1: User appearances
111
-
112
- Here's a simple example of a channel that tracks whether a user is online or not, and also what page they are currently on.
113
- (This is useful for creating presence features like showing a green dot next to a user's name if they're online).
114
-
115
- First you declare the server-side channel:
116
-
117
- ```ruby
118
- # app/channels/appearance_channel.rb
119
- class AppearanceChannel < ApplicationCable::Channel
120
- def subscribed
121
- current_user.appear
122
- end
123
-
124
- def unsubscribed
125
- current_user.disappear
126
- end
127
-
128
- def appear(data)
129
- current_user.appear on: data['appearing_on']
130
- end
131
-
132
- def away
133
- current_user.away
134
- end
135
- end
136
- ```
137
-
138
- The `#subscribed` callback is invoked when, as we'll show below, a client-side subscription is initiated. In this case,
139
- we take that opportunity to say "the current user has indeed appeared". That appear/disappear API could be backed by
140
- Redis or a database or whatever else. Here's what the client-side of that looks like:
141
-
142
- ```coffeescript
143
- # app/assets/javascripts/cable/subscriptions/appearance.coffee
144
- App.cable.subscriptions.create "AppearanceChannel",
145
- # Called when the subscription is ready for use on the server
146
- connected: ->
147
- @install()
148
- @appear()
149
-
150
- # Called when the WebSocket connection is closed
151
- disconnected: ->
152
- @uninstall()
153
-
154
- # Called when the subscription is rejected by the server
155
- rejected: ->
156
- @uninstall()
157
-
158
- appear: ->
159
- # Calls `AppearanceChannel#appear(data)` on the server
160
- @perform("appear", appearing_on: $("main").data("appearing-on"))
161
-
162
- away: ->
163
- # Calls `AppearanceChannel#away` on the server
164
- @perform("away")
165
-
166
-
167
- buttonSelector = "[data-behavior~=appear_away]"
168
-
169
- install: ->
170
- $(document).on "turbolinks:load.appearance", =>
171
- @appear()
172
-
173
- $(document).on "click.appearance", buttonSelector, =>
174
- @away()
175
- false
176
-
177
- $(buttonSelector).show()
178
-
179
- uninstall: ->
180
- $(document).off(".appearance")
181
- $(buttonSelector).hide()
182
- ```
183
-
184
- Simply calling `App.cable.subscriptions.create` will setup the subscription, which will call `AppearanceChannel#subscribed`,
185
- which in turn is linked to the original `App.cable` -> `ApplicationCable::Connection` instances.
186
-
187
- Next, we link the client-side `appear` method to `AppearanceChannel#appear(data)`. This is possible because the server-side
188
- channel instance will automatically expose the public methods declared on the class (minus the callbacks), so that these
189
- can be reached as remote procedure calls via a subscription's `perform` method.
190
-
191
- ### Channel example 2: Receiving new web notifications
192
-
193
- The appearance example was all about exposing server functionality to client-side invocation over the WebSocket connection.
194
- But the great thing about WebSockets is that it's a two-way street. So now let's show an example where the server invokes
195
- an action on the client.
196
-
197
- This is a web notification channel that allows you to trigger client-side web notifications when you broadcast to the right
198
- streams:
199
-
200
- ```ruby
201
- # app/channels/web_notifications_channel.rb
202
- class WebNotificationsChannel < ApplicationCable::Channel
203
- def subscribed
204
- stream_from "web_notifications_#{current_user.id}"
205
- end
206
- end
207
- ```
208
-
209
- ```coffeescript
210
- # Client-side, which assumes you've already requested the right to send web notifications
211
- App.cable.subscriptions.create "WebNotificationsChannel",
212
- received: (data) ->
213
- new Notification data["title"], body: data["body"]
214
- ```
215
-
216
- ```ruby
217
- # Somewhere in your app this is called, perhaps from a NewCommentJob
218
- ActionCable.server.broadcast \
219
- "web_notifications_#{current_user.id}", { title: 'New things!', body: 'All the news that is fit to print' }
220
- ```
221
-
222
- The `ActionCable.server.broadcast` call places a message in the Action Cable pubsub queue under a separate broadcasting name for each user. For a user with an ID of 1, the broadcasting name would be `web_notifications_1`.
223
- The channel has been instructed to stream everything that arrives at `web_notifications_1` directly to the client by invoking the
224
- `#received(data)` callback. The data is the hash sent as the second parameter to the server-side broadcast call, JSON encoded for the trip
225
- across the wire, and unpacked for the data argument arriving to `#received`.
226
-
227
-
228
- ### Passing Parameters to Channel
229
-
230
- You can pass parameters from the client side to the server side when creating a subscription. For example:
231
-
232
- ```ruby
233
- # app/channels/chat_channel.rb
234
- class ChatChannel < ApplicationCable::Channel
235
- def subscribed
236
- stream_from "chat_#{params[:room]}"
237
- end
238
- end
239
- ```
240
-
241
- If you pass an object as the first argument to `subscriptions.create`, that object will become the params hash in your cable channel. The keyword `channel` is required.
242
-
243
- ```coffeescript
244
- # Client-side, which assumes you've already requested the right to send web notifications
245
- App.cable.subscriptions.create { channel: "ChatChannel", room: "Best Room" },
246
- received: (data) ->
247
- @appendLine(data)
248
-
249
- appendLine: (data) ->
250
- html = @createLine(data)
251
- $("[data-chat-room='Best Room']").append(html)
252
-
253
- createLine: (data) ->
254
- """
255
- <article class="chat-line">
256
- <span class="speaker">#{data["sent_by"]}</span>
257
- <span class="body">#{data["body"]}</span>
258
- </article>
259
- """
260
- ```
261
-
262
- ```ruby
263
- # Somewhere in your app this is called, perhaps from a NewCommentJob
264
- ActionCable.server.broadcast \
265
- "chat_#{room}", { sent_by: 'Paul', body: 'This is a cool chat app.' }
266
- ```
267
-
268
-
269
- ### Rebroadcasting message
270
-
271
- A common use case is to rebroadcast a message sent by one client to any other connected clients.
272
-
273
- ```ruby
274
- # app/channels/chat_channel.rb
275
- class ChatChannel < ApplicationCable::Channel
276
- def subscribed
277
- stream_from "chat_#{params[:room]}"
278
- end
279
-
280
- def receive(data)
281
- ActionCable.server.broadcast "chat_#{params[:room]}", data
282
- end
283
- end
284
- ```
285
-
286
- ```coffeescript
287
- # Client-side, which assumes you've already requested the right to send web notifications
288
- App.chatChannel = App.cable.subscriptions.create { channel: "ChatChannel", room: "Best Room" },
289
- received: (data) ->
290
- # data => { sent_by: "Paul", body: "This is a cool chat app." }
291
-
292
- App.chatChannel.send({ sent_by: "Paul", body: "This is a cool chat app." })
293
- ```
294
-
295
- The rebroadcast will be received by all connected clients, _including_ the client that sent the message. Note that params are the same as they were when you subscribed to the channel.
296
-
297
-
298
- ### More complete examples
299
-
300
- See the [rails/actioncable-examples](https://github.com/rails/actioncable-examples) repository for a full example of how to setup Action Cable in a Rails app, and how to add channels.
301
-
302
- ## Configuration
303
-
304
- Action Cable has three required configurations: a subscription adapter, allowed request origins, and the cable server URL (which can optionally be set on the client side).
305
-
306
- ### Redis
307
-
308
- By default, `ActionCable::Server::Base` will look for a configuration file in `Rails.root.join('config/cable.yml')`.
309
- This file must specify an adapter and a URL for each Rails environment. It may use the following format:
310
-
311
- ```yaml
312
- production: &production
313
- adapter: redis
314
- url: redis://10.10.3.153:6381
315
- development: &development
316
- adapter: redis
317
- url: redis://localhost:6379
318
- test: *development
319
- ```
320
-
321
- You can also change the location of the Action Cable config file in a Rails initializer with something like:
322
-
323
- ```ruby
324
- Rails.application.paths.add "config/cable", with: "somewhere/else/cable.yml"
325
- ```
326
-
327
- ### Allowed Request Origins
328
-
329
- Action Cable will only accept requests from specific origins.
330
-
331
- By default, only an origin matching the cable server itself will be permitted.
332
- Additional origins can be specified using strings or regular expressions, provided in an array.
333
-
334
- ```ruby
335
- Rails.application.config.action_cable.allowed_request_origins = ['http://rubyonrails.com', /http:\/\/ruby.*/]
336
- ```
337
-
338
- When running in the development environment, this defaults to "http://localhost:3000".
339
-
340
- To disable protection and allow requests from any origin:
341
-
342
- ```ruby
343
- Rails.application.config.action_cable.disable_request_forgery_protection = true
344
- ```
345
-
346
- To disable automatic access for same-origin requests, and strictly allow
347
- only the configured origins:
348
-
349
- ```ruby
350
- Rails.application.config.action_cable.allow_same_origin_as_host = false
351
- ```
352
-
353
- ### Consumer Configuration
354
-
355
- Once you have decided how to run your cable server (see below), you must provide the server URL (or path) to your client-side setup.
356
- There are two ways you can do this.
357
-
358
- The first is to simply pass it in when creating your consumer. For a standalone server,
359
- this would be something like: `App.cable = ActionCable.createConsumer("ws://example.com:28080")`, and for an in-app server,
360
- something like: `App.cable = ActionCable.createConsumer("/cable")`.
361
-
362
- The second option is to pass the server URL through the `action_cable_meta_tag` in your layout.
363
- This uses a URL or path typically set via `config.action_cable.url` in the environment configuration files, or defaults to "/cable".
364
-
365
- This method is especially useful if your WebSocket URL might change between environments. If you host your production server via https, you will need to use the wss scheme
366
- for your Action Cable server, but development might remain http and use the ws scheme. You might use localhost in development and your
367
- domain in production.
368
-
369
- In any case, to vary the WebSocket URL between environments, add the following configuration to each environment:
370
-
371
- ```ruby
372
- config.action_cable.url = "ws://example.com:28080"
373
- ```
374
-
375
- Then add the following line to your layout before your JavaScript tag:
376
-
377
- ```erb
378
- <%= action_cable_meta_tag %>
379
- ```
380
-
381
- And finally, create your consumer like so:
382
-
383
- ```coffeescript
384
- App.cable = ActionCable.createConsumer()
385
- ```
386
-
387
- ### Other Configurations
388
-
389
- The other common option to configure is the log tags applied to the per-connection logger. Here's an example that uses the user account id if available, else "no-account" while tagging:
390
-
391
- ```ruby
392
- config.action_cable.log_tags = [
393
- -> request { request.env['user_account_id'] || "no-account" },
394
- :action_cable,
395
- -> request { request.uuid }
396
- ]
397
- ```
398
-
399
- For a full list of all configuration options, see the `ActionCable::Server::Configuration` class.
400
-
401
- Also note that your server must provide at least the same number of database connections as you have workers. The default worker pool is set to 4, so that means you have to make at least that available. You can change that in `config/database.yml` through the `pool` attribute.
402
-
403
-
404
- ## Running the cable server
405
-
406
- ### Standalone
407
- The cable server(s) is separated from your normal application server. It's still a Rack application, but it is its own Rack
408
- application. The recommended basic setup is as follows:
409
-
410
- ```ruby
411
- # cable/config.ru
412
- require_relative '../config/environment'
413
- Rails.application.eager_load!
414
-
415
- run ActionCable.server
416
- ```
417
-
418
- Then you start the server using a binstub in bin/cable ala:
419
- ```sh
420
- #!/bin/bash
421
- bundle exec puma -p 28080 cable/config.ru
422
- ```
423
-
424
- The above will start a cable server on port 28080.
425
-
426
- ### In app
427
-
428
- If you are using a server that supports the [Rack socket hijacking API](http://www.rubydoc.info/github/rack/rack/file/SPEC#Hijacking), Action Cable can run alongside your Rails application. For example, to listen for WebSocket requests on `/websocket`, specify that path to `config.action_cable.mount_path`:
429
-
430
- ```ruby
431
- # config/application.rb
432
- class Application < Rails::Application
433
- config.action_cable.mount_path = '/websocket'
434
- end
435
- ```
436
-
437
- For every instance of your server you create and for every worker your server spawns, you will also have a new instance of Action Cable, but the use of Redis keeps messages synced across connections.
438
-
439
- ### Notes
440
-
441
- Beware that currently, the cable server will _not_ auto-reload any changes in the framework. As we've discussed, long-running cable connections mean long-running objects. We don't yet have a way of reloading the classes of those objects in a safe manner. So when you change your channels, or the model your channels use, you must restart the cable server.
442
-
443
- We'll get all this abstracted properly when the framework is integrated into Rails.
444
-
445
- The WebSocket server doesn't have access to the session, but it has access to the cookies. This can be used when you need to handle authentication. You can see one way of doing that with Devise in this [article](http://www.rubytutorial.io/actioncable-devise-authentication).
446
-
447
- ## Dependencies
448
-
449
- Action Cable provides a subscription adapter interface to process its pubsub internals. By default, asynchronous, inline, PostgreSQL, and Redis adapters are included. The default adapter in new Rails applications is the asynchronous (`async`) adapter. To create your own adapter, you can look at `ActionCable::SubscriptionAdapter::Base` for all methods that must be implemented, and any of the adapters included within Action Cable as example implementations.
450
-
451
- The Ruby side of things is built on top of [websocket-driver](https://github.com/faye/websocket-driver-ruby), [nio4r](https://github.com/celluloid/nio4r), and [concurrent-ruby](https://github.com/ruby-concurrency/concurrent-ruby).
452
-
453
-
454
- ## Deployment
455
-
456
- Action Cable is powered by a combination of WebSockets and threads. All of the
457
- connection management is handled internally by utilizing Ruby's native thread
458
- support, which means you can use all your regular Rails models with no problems
459
- as long as you haven't committed any thread-safety sins.
460
-
461
- The Action Cable server does _not_ need to be a multi-threaded application server.
462
- This is because Action Cable uses the [Rack socket hijacking API](http://www.rubydoc.info/github/rack/rack/file/SPEC#Hijacking)
463
- to take over control of connections from the application server. Action Cable
464
- then manages connections internally, in a multithreaded manner, regardless of
465
- whether the application server is multi-threaded or not. So Action Cable works
466
- with all the popular application servers -- Unicorn, Puma and Passenger.
467
-
468
- Action Cable does not work with WEBrick, because WEBrick does not support the
469
- Rack socket hijacking API.
470
-
471
- ## Frontend assets
472
-
473
- Action Cable's frontend assets are distributed through two channels: the
474
- official gem and npm package, both titled `actioncable`.
475
-
476
- ### Gem usage
477
-
478
- Through the `actioncable` gem, Action Cable's frontend assets are
479
- available through the Rails Asset Pipeline. Create a `cable.js` or
480
- `cable.coffee` file (this is automatically done for you with Rails
481
- generators), and then simply require the assets:
482
-
483
- In JavaScript...
484
-
485
- ```javascript
486
- //= require action_cable
487
- ```
488
-
489
- ... and in CoffeeScript:
490
-
491
- ```coffeescript
492
- #= require action_cable
493
- ```
494
-
495
- ### npm usage
496
-
497
- In addition to being available through the `actioncable` gem, Action Cable's
498
- frontend JS assets are also bundled in an officially supported npm module,
499
- intended for usage in standalone frontend applications that communicate with a
500
- Rails application. A common use case for this could be if you have a decoupled
501
- frontend application written in React, Ember.js, etc. and want to add real-time
502
- WebSocket functionality.
503
-
504
- ### Installation
505
-
506
- ```
507
- npm install actioncable --save
508
- ```
509
-
510
- ### Usage
511
-
512
- The `ActionCable` constant is available as a `require`-able module, so
513
- you only have to require the package to gain access to the API that is
514
- provided.
515
-
516
- In JavaScript...
517
-
518
- ```javascript
519
- ActionCable = require('actioncable')
520
-
521
- var cable = ActionCable.createConsumer('wss://RAILS-API-PATH.com/cable')
522
-
523
- cable.subscriptions.create('AppearanceChannel', {
524
- // normal channel code goes here...
525
- });
526
- ```
527
-
528
- and in CoffeeScript...
529
-
530
- ```coffeescript
531
- ActionCable = require('actioncable')
532
-
533
- cable = ActionCable.createConsumer('wss://RAILS-API-PATH.com/cable')
534
-
535
- cable.subscriptions.create 'AppearanceChannel',
536
- # normal channel code goes here...
537
- ```
538
-
539
- ## Download and Installation
540
-
541
- The latest version of Action Cable can be installed with [RubyGems](#gem-usage),
542
- or with [npm](#npm-usage).
543
-
544
- Source code can be downloaded as part of the Rails project on GitHub
545
-
546
- * https://github.com/rails/rails/tree/5-2-stable/actioncable
547
-
548
- ## License
549
-
550
- Action Cable is released under the MIT license:
551
-
552
- * https://opensource.org/licenses/MIT
553
-
10
+ You can read more about Action Cable in the [Action Cable Overview](https://edgeguides.rubyonrails.org/action_cable_overview.html) guide.
554
11
 
555
12
  ## Support
556
13
 
557
14
  API documentation is at:
558
15
 
559
- * http://api.rubyonrails.org
16
+ * https://api.rubyonrails.org
560
17
 
561
18
  Bug reports for the Ruby on Rails project can be filed here:
562
19
 
@@ -564,4 +21,4 @@ Bug reports for the Ruby on Rails project can be filed here:
564
21
 
565
22
  Feature requests should be discussed on the rails-core mailing list here:
566
23
 
567
- * https://groups.google.com/forum/?fromgroups#!forum/rubyonrails-core
24
+ * https://discuss.rubyonrails.org/c/rubyonrails-core